Re: [Groff] Nesting font macros in man pages

[Ingo Schwarze]

Hi John,

John Gardner wrote on Sun, Apr 30, 2017 at 10:50:23PM +1000:

> .de XR
> . Xr \\fB\\$1\\fP \\$2
> ..

That's a bad idea for three reasons.

 1. It already stands out by the (N), additional font change is not
    required.  Manuals tend to have so much font jumping anyway
    that they are often not very visually pleasing and look noisy.
    Where that is required to convey semantics, it can't be helped,
    but whereever additional markup is not required, it ought to
    be avoided.  Admittedly, so far, my argumenmt can be considered
    a matter of taste.

 2. The whole point of markup is that readers get used to what gets
    marked up in which way and can easily glean the semantics from
    the markup without thinking about it.  If you invent your own
    presentation for established semantic markup, you defeat the
    whole purpose of the exercise.
    Note that in this respect, mdoc(7) is much better than man(7)
    because it ensures a uniform presentation across all manuals.
    While man-pages(7) usefully suggests standard practices (most
    of which, though not all, conform to preveiously established
    practice), those are unfortunately not enforced by the language,
    so you do see wildly varying markup for the same semantics,
    hindering readers.

 3. By mixing low-level roff(7) syntax into your mdoc(7) document,
    like defining your own macros, you gratuitiously endanger
    portability.  Since nowadays, only groff, Heirloom, and mandoc
    are commonly used for mdoc(7) and those all handle .de, that
    argument has become less compelling, but it is still bad style
    and potentially harmful.  It is also harmful for *authors*
    because they can't edit your manual pages without learning your
    personal idiosyncrasies.
    On the one hand, people say editing mdoc(7) is too hard because
    it contains about three dozen macros and that's too much.  And
    then they go ahead and define their own macros on top of it.
    As if nobody else will ever have to read or edit their pages.

> Seeing manpage references without *bold*(1) just looks unnatural to me. ;-)

You are being selfish.  If you forcefully redefine standard macros,
the result will look unnatural to *everyone else*.  \fR for .Xr is
the standard at least since July 1990 and has been ever since.
It predates the first stable version of groff by more than a year.
Even the first ever public groff version, groff-0.3.1, was only
released in June 1990.  So the established practice you are throwing
overboard was already established at a time when Brian Kernighan's
device independent troff was still the predominant tool for formatting
manual pages.

Oh, and by the way, even when Cynthia made this decision in 1989
or 1990, it was not arbitrary.  The 4.3BSD manuals she was converting
already had the convention of \fR for cross references, and so had
the Version 7 AT&T UNIX manuals before them, and even Version 4
started using bold markup, but not for cross references.  So what
you are calling "unnatural" has been a firmly established UNIX
convention for more than four decades.

See, when developing mandoc, i don't unilaterally change practices
established by groff either, no matter to which degree i like them,
except in very rare cases (like some improvements to .Rs and .Dq
presentation recently) where i first make sure that there is
consensus across the *whole* community and *all* maintainers (groff,
Heirloom, and mandoc) accept the required patches in lock-step.
Examples exist where i delayed committing improvements to mandoc
for more than a year in order to allow sufficient time for consensus
to emerge in the groff community.

Yours,
  Ingo