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
