Hi Ingo! At 2020-12-20T17:16:38+0100, Ingo Schwarze wrote: > G. Branden Robinson wrote on Sun, Dec 20, 2020 at 03:38:54AM -0500: > > commit ca0dfa5ff724eaf21a8b79f4ee825979ef3294fc > > Author: G. Branden Robinson <g.branden.robin...@gmail.com> > > AuthorDate: Sun Dec 20 14:10:09 2020 +1100 > > > > groff_mdoc(7): Add link to mandoc project. [...] > Thanks, so now the mdoc(7) manual page in the mandoc package and the > groff_mdoc(7) manual page in the groff package point at each other. > I think that's good and may occasionally help users because different > people may like different styles of documentation and because some > particular details may be easier to understand in one page, some in > the other.
That was certainly part of my intent. I expect to continue to be an exponent of good man(7) authorship, but that doesn't mean I want to suppress awareness of the mandoc project or the mdoc language. > > +.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. 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. Particularly when the cross-reference is presented as a hyperlink, the repeated section parenthetical does little work. 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 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. 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? > > +language and a renderer that directly parses its markup as well as that > > +of > > +.Xr man . > > dto.: .Xr man 7 . Regards, Branden
signature.asc
Description: PGP signature
