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

[Ingo Schwarze]

Hi,

G. Branden Robinson wrote on Sat, Apr 29, 2017 at 07:26:15AM -0400:
> At 2017-04-27T17:37:15+0200, Ingo Schwarze wrote:

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

> Well, thanks.  This is what it looked like before I got to it:
> .TP
> .B \-scale \fIxfac[,yfac]\fP

That's indeed gross: using font escapes inside .B instead of
simply using .BI - which would still be wrong because the
punctuation should clearly not be in \fI.

> However, _I_ don't like either of the above.  I mentioned before that
> having this \fX stuff directly abutting words throws frustrates spell
> checkers.

I admit that spell checkers might complain less about \c than about
\fIxfac, but honestly, that's what deroff(1) is for.  That's
exactly why spell(1) uses deroff(1) by default.  Feeding roff(7)
source into a spell checker without piping it through deroff(1)
first makes very little sense to me.

address@hidden $ deroff
.B \-scale \fIxfac[,yfac]\fP
^D
 scale xfac[,yfac] 

address@hidden $ spell
.B \-scale \fIxfac[,yfac]\fP
^D
xfac
yfac

It just works, nothing to see here, move on...   --->>>

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

I fully agree with that, and also with your plan to (sparingly and
carefully) add advice to groff_man(7) about which low-level roff(7)
features are OK (and typically required) for which situations.
Right now, while the general idea of the "PORTABILITY AND TROFF
REQUESTS" section cited earlier is highly laudable, it is of limited
helpfulness to only say "try to avoid low-level roff stuff" while
we all know that completely avoiding it is impossible in man(7).
Some constructive advice would be more helpful.

As Ralph rightly observed, even to work with mdoc(7), you need to
know a number of things about roff(7).  That's exactly why the
DESCRIPTION in the mdoc(7) manual from the mandoc distribution
points to specific sectins of the roff(7) manual (admittedly very
shortly).  A man(7) manual would likely have to mention a few more
low-level roff features that are hard to avoid.


>> G. Branden Robinson wrote on Thu, Apr 27, 2017 at 09:46:27AM -0400:

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

My conjecture is that cargo cult is roughly propertional to the
number of planes you see.  So far, we have seen about a dozen pages
in 10000 with (arguably) legitimate use and about half a dozen
abuses.

Once you start actively promoting

.TP
.B -S \c
.IR var [= val ],

that means there will be more planes in the sky (unless your marketing
campaign utterly fails), so it's a plausible guess that more people
with partial to bad understanding may start randomly adding \c after
their .B macros.

And to measure the damage done by pages misformatting on old systems,
the number of pages using \c right now doesn't matter either, what
matters there is the number of pages that will be converted to avoid
\f after line-scope macros (like .TP) by using \c.  In portable
software, that is.

Also, i still don't understand how educating people that \c is OK -
which has relatively non-obvious functionality, and, for man pages,
was unfamiliar so far even to people like Doug - is any easier than
making it official that \f, which has much simpler functionality,
is sometimes needed, which many are already used to.  In particular
given that spell checking is a problem solved decades ago.


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

Several years ago, i once exchanged mail with Gunnar when he was
still active.  Not long after that, lamentably, he quit.  Still
later, more than one person tried contacting him, to politely ask
whether he would consider putting a pointer to the new site onto
his old site.  I don't think anything ever came of it.  :-(

It's sad and strange, because everybody i heard mentioning him
seemed to agree that he is a very nice and kind person.


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

Frankly, i have never searched for man(7) parsers, so i have no idea.

I came across a number of man(7) generators apart form pod2man(1),
pandoc(1), and mandoc -Tman, but that's the opposite direction;
unsorted examples, probably much more incomplete than the list of
roff(7) implementations i sent earlier:

 * http://docutils.sourceforge.net/rst.html
 * http://github.com/rtomayko/ronn
 * https://github.com/GostCrypt/libgcrypt/blob/master/doc/yat2m.c

Oh, and here is one in the direction you are asking for, but i have
no idea about the quality or relevance.  Judging from the size, it
is not likely to be very complete:

 * https://raw.githubusercontent.com/rofl0r/hardcore-utils/master/man.c


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

So do i, but i occasionally look even at commercial systems,
in particular those that are as archaic as Oracle Solaris,
not because i want to use them, because they are so unusual
that they make you find bugs you do not easily find elsewhere.

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

I'm able to test on Solaris 9, 10, and 11 and on Plan9,
but i don't have access to other systems either, and i cannot
hand out shell accounts.  If you are an official member of
the groff project, OpenCSW might grant you a shell account,
though:

  https://www.opencsw.org/extend-it/signup/to-upstream-maintainers/

Those are very nice people, just ask them if you need it.


Let's see:

address@hidden [unstable11s]:~ > uname -a
SunOS unstable11s 5.11 11.2 sun4u sparc SUNW,SPARC-Enterprise
address@hidden [unstable11s]:~ > nroff -man
.TH TEST 1 2017-04-30
.SH DESCRIPTION
initial text
.TP
.B -S \c
.IR var [= val ]
indented text
^D
User Commands                                             TEST(1)

DESCRIPTION
     initial text

     -S   var[=val] indented text

SunOS 5.11           Last change: 2017-04-30                    1


So yes, it does misformat.  The var=val ends up in the body.

address@hidden > sed -n '/de TP/,/^\.\./p' /usr/share/lib/tmac/an
.de TP
.if !"\\$1"" .nr )I \\$1n
.sp \\n()Pu
.in \\n()Ru
.nr )E 1
.ns
.it 1 }N
.di ]B
..
address@hidden > sed -n '/de }N/,/^\.\./p' /usr/share/lib/tmac/an
.de }N
.if \\n()E .br
.di
.if "\\n()E"0" .}f
.if "\\n()E"1" .}1
.if "\\n()E"2" .}2
.nr )E 0
..

Good luck getting that fixed before the first manned Mars landing.

address@hidden [unstable11s]:~ > nroff
.de mT
trap sprang!
..
.it 1 mT
line 1
line 2
^D
line 1 trap sprang!  line 2

address@hidden [unstable11s]:~ > nroff
.de mT
trap sprang!
..
.itc 1 mT
line 1 \c
line 2
line 3
^D
line 1 line 2 line 3

Macro names are limited to two bytes, and .itc doesn't exist.

Yours,
  Ingo