groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: G. Branden Robinson
Subject: Re: [Groff] Applications of \c in man pages in the wild
Date: Thu, 27 Apr 2017 09:46:27 -0400
User-agent: NeoMutt/20170113 (1.7.2)

At 2017-04-27T14:30:33+0200, Ingo Schwarze wrote:
> Hi,
> 
> wow, you definitely demonstrate diligence in investigating existing
> usage.
[...]
> 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.

If this were a matter of preserving compatibility, you'd argue that
breaking 14 man pages out of 7000 is too many.

Let's review, from earlier in the thread:

BR> What I'm hearing is that you feel that man(7) is a lost cause:
BR>
BR> A.  It desparately needs improvement because of its presentational,
BR>     rather than semantic, focus.
BR> B.  Improvement will break portability.
BR>
BR> This basically amounts to doing nothing and letting man(7) die of its
BR> own accord.

IS> Exactly.

> 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.

Yet, somehow, you do not regard this as evidence of the quality of
man(7) nor of the people who write in it.

> 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

It's no lower-level than the escapes to which you've given your
blessing; see groff(7) and CSTR #54, where it has parity.

> that is so far virtually unused in the wild,

Hmm.  210 uses out of ~7,000 makes it about twice as popular as mdoc.

$ find man* -type f -and -not -type l | xargs zgrep '^\.Dd' | wc -l
103

> 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.

That's conjecture.  What I see is a propensity to cut-and-paste from
examples that are believed to be good.  If we provide good examples,
there's no reason to expect abuse to grow.

My expectations are modest: I think a few people will pick it up and use
it correctly, most will continue to live with bad markup, and
practically no one will see \c as a new toy to play with.  Because, you
see, it isn't new--it's very, very old.  Older than, say, mdoc.

> 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.

\e is a bad example; in man(7) pages, people use it expecting to it to
do the same thing as \(rs.  Which is fine until some clever wag
redefines the escape character.

Most of the time, \(rs is what people mean, because--in man
pages--they're discussing the backslash symbol outside of the context of
*roff itself.  Almost always, they're telling C and shell programmers
how to escape and quote things.

Regardless, \c obviously has a couple of indispensable use cases in the
man(7) domain.  We should be documenting them, not ignoring them in
hopes people will just throw up their hands and go use mdoc instead.

> It is now demonstrated in the wild that \c misses the last criterium,
> and it is plausible to assume that \! will also miss it.

I think you're indulging deeply in motivated reasoning in service of the
objective we established earlier.  You don't want people to write man(7)
pages well; you want them to write them badly, if they write them at
all, in the hope that the wretchedness of the result will lead them to
the true light of mdoc(7).

In any event, I checked out Heirloom troff.  Unfortunately its CVS
repository has not seen a commit in almost 6 years.  I tried to build it
using Heirloom devtools; that, unfortunately has not seen a commit in
almost 7 years.  Perhaps not surprisingly, when it came time to compile
a C++ file, the build failed.

Are we sure that Heirloom is still maintained?  Is there any other
living troff on the planet?

If not, then I have to conclude that GNU troff _is_ the standard by dint
of being the sole living implementation, and therefore I'm not too
worried about the impact of my proposal regarding TP, which Bjarni
developed independently back in 2014, and with greater generality to
boot.

Nevertheless, if someone can get Heirloom troff building on Debian
stretch, I'm willing to run A/B comparisons to see what, if anything,
breaks.

Out of those ~7000 pages, I haven't seen a single markup error that can
be unquestionably laid at the feet of Bjarni's and my proposal.

At least we can agree that docbook-to-man produces a true dog's
breakfast of output.  Pretty lamentable.

Regards,
Branden

Attachment: signature.asc
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]