Re: mdoc: single-argument .Xr

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Wed, Aug 11, 2021 at 12:23:10AM +1000:
> At 2021-08-04T15:54:20+0200, Ingo Schwarze wrote:

>> 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:)

In that case, it it's arguably even worse: it can then be confused
with a placeholder, file name, or stress emphasis.  Seeing text that
is merely italic certainly doen't tell you it's refering to a manual
page.


>> G. Branden Robinson wrote on Tue, Dec 22, 2020 at 04:13:30PM +1100:

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

It seems doubtful to me whether leaving out the section number from
the link text benefits the reader.  Whether a link is easily
recognizable as a link may depend on the CSS being used (no doubt,
good CSS should make links easily recognizable).  Even it the link
is easy to spot as a link, making it obvious to the reader that
it's a link *to a manual page* is even better, no less in HTML than
at the terminal, without hovering your mouse over it.  Seeing foo(1)
tells you instantly that "foo" is a command, and seeing bar(3) that
"bar()" is a function.  Besides, i was trying to point out that the
formatter may have a hard time formatting the *URI* if the section
number is missing from the .Xr macro.

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

No, absolutely not.  With .Nm.  Always.

Yours,
  Ingo