Re: mdoc: single-argument .Xr

[G. Branden Robinson]

Hi, Ingo!

At 2021-08-04T15:54:20+0200, Ingo Schwarze wrote:
> 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.

No worries.

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

To which I must point out...it does if you set man page titles in
italics.  3:)

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

What I was getting at is that the link text could safely omit the
section number even if the hyperlink itself did not.

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

I've developed a tendency to do it for annoying page titles like me(7)
and man(7) (and mom(7), sorry Peter) that are confusable with plain
English words.

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

How should a man page refer to its own topic in mdoc?  With Xr?

Regards,
Branden

signature.asc
Description: PGP signature