Re: groff_mdoc(7): Add link to mandoc project.

[G. Branden Robinson]

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