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
