mdoc: single-argument .Xr

[Ingo Schwarze]

Hi Branden,

sorry, this one fell through the cracks last year.  I assigned a new
Subject: because the old one was no longer fitting and keeping a thread
together is no longer relevant after so many months.

G. Branden Robinson wrote on Tue, Dec 22, 2020 at 04:13:30PM +1100:
> At 2020-12-20T17:16:38+0100, Ingo Schwarze wrote:
>> G. Branden Robinson wrote on Sun, Dec 20, 2020 at 03:38:54AM -0500:

>>> +.Xr mdoc

>> That's an mdoc(7) syntax error, .Xr requires two arguments.
>> I think this should be ".Xr mdoc 7".

> Hrm.  groff mdoc doesn't complain about it, and neither does my
> installed version of mandoc (1.14.4, Debian revision 1), not even in -T
> lint mode.

Current mandoc certainly does complain:

   $ echo .Xr mdoc | mandoc -mdoc -T lint
  mandoc: <stdin>:1:2: WARNING: missing section argument: Xr mdoc
  [...]

According to CVS logs, i added the warning in December 2016, but we
certainly considered single-argument .Xr wrong long before that.

> Before you race to implement a warning or error for this
> usage, permit me to lobby for its validity.
> 
> The trailing section number is often clear from context, for instance
> when an .Xr for the given page has already been seen in the document.
> Admittedly, cases like groff(1) and groff(7) will often be ambiguous.
> But many, perhaps most, man pages, do not appear by the same name in
> multiple sections.

That is true, but the section number serves double duty: not just
telling the reader which section the cross reference is pointing to,
but also making it clear that this is a cross reference in the first
place.  If you leave it out, it no longer stands out from surrounding
text, at least not on the terminal.

Manual pages are not poetry where you might try to avoid repeated
use of the same words or forms (except for special effect, say, in a
parallelism or chiasm).  In manual pages, being as explicit and
unambiguous as possible provides more value.

> Particularly when the cross-reference is presented as a hyperlink, the
> repeated section parenthetical does little work.

Especially when formatted as a hyperlink, the section number is usually
needed for constructing the URI, so omitting it is harming that case
even more than for terminal output.

> I've noticed that you're pretty disciplined about annotating program
> names with trailing section parentheticals in emails; I do this often,
> too, but with less diligence.

In emails, that's mostly a habit and personal preference, and i
certainly don't blame others for not doing that, or doing it less
consistently.

> In part this is to disambiguate the term "man", but also
> because I don't compose and revise emails with the same
> fanatical attention I devote to man pages or other technical
> documentation.  In more formal materials I would expect the discussion
> to develop in such a way that once a topic requiring a cross reference
> is raised, subsequent mentions will be unambiguous, reducing the section
> parenthetical to typographical clutter.

I think making it crystal clear that you are indeed refering to the
program or function you introduced earlier and not just using the same
word in a more general sense is more valuable than saving the three
characters.

Besides, forgetting the section number is a very common error.
That makes the warning quite valuable.  In the four years since it
exists, it even saved myself from accidentally forgetting section
numbers, multiple times.

> What would be required to properly support my intended use case?  The
> construction of an associative array for each first argument seen to
> .Xr?
> 
> Is there another away to get the presentational effect I seek?

I disagree with your goal.  Omitting the section number after the
first use, or when the author considers it obvious for other reasons,
is undesirable.  It is likely to be more obvious for the author than
for the reader, and how obvious it is may even differ for different
readers, and even when obvious for all of them, the three additional
characters do no harm.

Yours,
  Ingo