Re: [Groff] Applications of \c in man pages in the wild

[Ingo Schwarze]

Hi,

wow, you definitely demonstrate diligence in investigating existing
usage.  Let's have a look at the result.

The only use cases that are (arguably) legitimate are FONT_MACRO_C,
PRIVATE_FONT_MACRO_C, SMALL_C, and TILDE_C.  Not counting the groff
documentation itself (because that might be considered biased by
excessive insider cleverness), if i read your mail correctly, you
found 14 cases of FONT_MACRO_C, 1 additional PRIVATE_FONT_MACRO_C,
1 SMALL_C, and 0 TILDE_C - in just shy of 7000 manuals.

That is (arguably) legitimate use in 0.23% of manuals - or put
another way, almost half the uses are *in groff itself*.
There is on average about one SPURIOUS_C for every two (arguably)
legitimate uses outside groff.

The bulk of existing cases is docbook insanity.

That can be summarized as follows:  Legitimate hand-written use is
almost inexistent, even hand-written abuse is very rare, but unusually
frequent when expressed as a fraction of the instances of use.  The
dominant occurence is abuse by known-bad autogenerators.

Remeber that writing legacy man(7) documents is quite hard and
entices many people to try all kinds of (sometimes unavoidable,
sometimes ill-advised) trickery.  Even when analyzing the use of
easy-to-use languages in the wild, you usually find substantial (in
that case, needless) trickery.  So it is actually surprising that
you found so little.

So, if we would choose to promote \c use for the FONT_MACRO_C use
case, we would actually promote using a low-level feature that is
so far virtually unused in the wild, but where existing practice
in the wild already demonstrates that about 1 out of 3 users who
choose to use it freely get it wrong.  Officially encouraging use
is likely to cause an increase rather than a decrease of abuse.

I think your analysis reinforces the argument that we should refrain
from promoting the use of escape seqeunces in manual pages unless
they are unavoidable, well-established, *and* easy to understand.
Typical examples of escapes matching those criteria are \e, \&, \f.
It is now demonstrated in the wild that \c misses the last criterium,
and it is plausible to assume that \! will also miss it.

Yours,
  Ingo