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

[G. Branden Robinson]

Thanks to a perfectly pleasant offline conversation with Ingo, I no
longer fear that he is hell-bent on man's destruction.  ;-)

But I figured I'd better address a few remaining points, and
particularly to offer some thanks where it's deserved.

At 2017-04-27T17:37:15+0200, Ingo Schwarze wrote:
> G. Branden Robinson wrote on Thu, Apr 27, 2017 at 09:46:27AM -0400:
> > If this were a matter of preserving compatibility, you'd argue that
> > breaking 14 man pages out of 7000 is too many.
> 
> Sorry, i don't follow.  Nobody suggested deleting \c from roff.

Good!  I didn't think anyone was, thought.

> All i said regarding portability is that implemeting your .TP .itc
> in groff, Heirloom, and mandoc and recommending use of \c after .TP
> means that *all* pages doing that misrender on all systems using
> either older versions of our formatters or legacy formatters.

The number of pages doing that is really small, hence this subthread.
It's important to me to know the impact of the changes I propose.

> If a significant language improvement would break 0.2% of existing
> manuals, i'd certainly consider going ahead with it and doing the
> handful of commits required / sending out the handful of patches
> required, but i don't see how that is related to the discussion.

Understood.  You and I disagree about whether letting people have
multiple input lines after what I crudely (mis)understand to be an
initial parse phase after invoking man(7) macros that use input traps.

> >> 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.
> 
> No, it is not, because you can find lots and lots of poorly written
> man(7) documents in the wild, even hand-written ones.  All it tells
> us is that \c is exceedingly rare in manual pages - both (arguable)
> legitimate uses and abuses.  That doesn't imply there aren't other
> common problems; in fact, there are.

Oh, heck yes, I agree with that.  Many dragons to be slain there.

> >> 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.
> 
> Admitted.  \f etc. is also low-level.  But it is simpler.

See below for why I hate \f so desperately, though I've mentioned one of
my reasons before.

> >> 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
> 
> Only if you don't count the about 3000 mdoc(7) manuals in a typical
> *BSD base system.  If you count those, \c is about 2% (abuse by
> docbook included), mdoc(7) is about 30%.

Fair point.  I was poking a stick at you with that one, and I have
nothing against the BSDs technologically.  In fact, I've long been
deeply envious of the quality of their man pages, and mdoc has a lot to
do with that.

> .TP
> \fB\-scale\fP \fIxfac\fP[,\fIyfac\fP]
> 
> is not bad markup, but decent quality man(7) code that i would
> recommend.

Well, thanks.  This is what it looked like before I got to it:

.TP
.B \-scale \fIxfac[,yfac]\fP

However, _I_ don't like either of the above.  I mentioned before that
having this \fX stuff directly abutting words throws frustrates spell
checkers.  The other reason I hate font escapes in man pages is because
that way "there's more than one way to do it".  As I said elsewhere, I
think to get people writing man pages competently, we need to keep the
"language" small.  Most of them are infrequent users of the language,
and they don't know which parts are the macro package which are "raw"
*roff.  Many of them are sharp enough to make some shrewd guesses but
I'd rather take the guesswork out.

> > and practically no one will see \c as a new toy to play with.
> 
> That might turn out to be true; it's also plausible conjecture,
> even though you already reported \c cargo culting right now.

True, but less than I feared.  Few enough that it's a tractable
operation to submit patches to fix that stuff.

> Here you probably have half a point.

<laugh>  Thanks.

> I should probably go ahead and change the mandoc documentation to
> recommend \(rs rather than \e for newly written manual pages.
> 
> Scouring the existing manuals is maybe not worth the substatial
> amount of work required, because there is no problem in practice:
> if someone uses .ec *in a manual page* (seriously?) they are already
> responsible for writing \ for \ after that, and "xe" for "x" if
> they said, for example, ".ec x".

Yeah, that's why \(rs vs. \e is not a high-priority windmill for my
tilting lance right now.  Anyone who uses .ec without putting it back
deserves whatever maelstrom of trash they get.

> For example, even groff(7) still says:
> 
>   Printable backslashes must be denoted as \e.  To be more
>   precise, \e represents the current escape character.
>   To get a backslash glyph, use \(rs or \[rs].
> 
> That has already been improved substantially, but it could maybe
> still be worded better.

Agreed.  I'm having trouble even thinking of use case for \e, outside of
scenarios where the escape character might be under some sort of
external control (.rd), or diagnostic messages inside a macro where .ec
is being used.

> > In any event, I checked out Heirloom troff.  Unfortunately its CVS
> > repository has not seen a commit in almost 6 years.
> 
> You must have looked in the wrong place.  Try
> 
>   http://n-t-roff.github.io/heirloom/doctools.html
>   https://github.com/n-t-roff/heirloom-doctools/
> 
> as linked from
> 
>   http://mdocml.bsd.lv/links.html

Sadly, Gunnar Ritter's Heirloom Doctools site is still the top hit on
Google.  That's what led me astray.  Thanks for the clue.

> > Are we sure that Heirloom is still maintained?
> 
> Absolutely.  Carsten Kunze maintains it.  He is also one of the
> most active groff committers and regularly follows this list.

Now's a good time for me to say thanks to Carsten for the batch of
recent commits.  Thanks, man!

> > Is there any other living troff on the planet?
> 
> There is
> 
>   https://swtch.com/plan9port/
[...]
>   http://www2.research.att.com/sw/download
[...]
>   https://github.com/n-t-roff/DWB3.3
[...]
>   http://repo.or.cz/w/neatroff.git = http://litcave.rudi.ir/
>   http://www.nesssoftware.com/home/mwc/source.php
[...]
> It looks like https://github.com/jgm/pandoc/ can only write,
> but not parse manual pages.

Thank you very much for all this!

> It is likely that there are more implementations than i know of,
> and some may well be alive.  Besides, i did not even try to list
> ad-hoc non-roff man(7) parsers.

This may warrant another thread, but how many of _those_ are still
alive?  I'm betting the language in groff_man(7) and man(7) [man-pages]
about portability and safe subsets hasn't been touched in years.  I also
suspect (without much evidence) that a lot of these non-roff man parsers
gave up the effort before achieving quality output with a significant,
representative sample of real-world man pages.

> > 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.
> 
> Did you test your proposed new syntax (.TP using \c to include
> two macro lines in the head) on
> 
>  - Oracle Solaris 9, 10, or 11
>  - illumos
>  - Plan9 (not sure whether that is still relevant)
>  - DWB (may well be irrelevant by now)
>  - Any other commercial system like HP-UX, AIX, etc.: i don't
>    have the slightest idea what those systems use today.

I sure did not.  I don't have access to any of those at present and I
have a half-strength RMS-style allergy to non-free software.

But I'm willing to use shell accounts to do regression tests.

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

docbook-to-man seems to poison everyone who touches it.  It was cast
over the wall by Oasis/OPEN in 1996, picked up by David Bolen in 1999,
and the only people to hack on since then are the Debian folks, and even
there the package has been orphaned multiple times, the latest since
2014.

Regards,
Branden

signature.asc
Description: PGP signature