Re: Plan 9 man added a new macro for man page references

[G. Branden Robinson]

Hi Humm,

Thanks for your very nice email.  After so long it's probably a good
time to loop back with Russ Cox as well.

At 2020-08-15T20:23:51-0400, Russ Cox wrote:
> On Sat, Aug 15, 2020 at 7:27 AM G. Branden Robinson
> <g.branden.robinson@gmail.com> wrote:
> >
> > Plan 9 went and did an interesting thing[1].  They implemented a
> > macro just for man page cross-references.
> 
> I am amazed you found that so quickly.
[...]
> > Here's what I would have done differently or in addition.
> >
> > * Named the macro MR ("manual reference") to give it even more
> >   semantic weight.  If "IM" is mnemonic for something, I haven't
> >   figured out what.
> 
> It was "italic manual reference", but I took your suggestion and
> changed it to MR.
> Thanks!
> 
> > * Implemented that string macro, and probably called it MF ("manref
> >   font") or "RF" (reference font).
> > * Broken the syntactical parallel with .IR, thus:
> >     .MR page-name section [hidden-page-anchor]
> 
> I broke the parallel with IR as well, but differently.
> $3 is the roman punctuation to follow (without spaces)
> after the manual reference (1). Like:
> 
> See
> .IR cat (1) .

The balance of opinion on the groff list lay in that direction as well;
no one was enthusiastic about the idea of having an "RM" macro to
present roman text immediately prior to the man page reference.
Instead, our groff_man_style(7) page shows the user how to employ the
`\c` escape sequence on the previous input line to achieve the desired
output.

Humm noticed that groff ended up diverging in another way: groff's MR
implementation does not require (and does not want) the section argument
to be parenthesized.  As I recall, when implementing it, my reasoning
was that since the macro is "semantic", it paralleled "TH" more closely
than any of the font macros, and further, the application of parentheses
to set off the section number from the man page title is itself a
stylistic choice, and not something that should be left up to the
document author (except arguably via some general style-tweaking knob,
but I doubt anyone foresees this detail of style ever changing).

What do you think?

For completeness I should point out that I also added to groff's man(7)
a new string, "MF", (mnemonic: "man ref[erence] font") enabling
configuration of the font used to render the man page title (and only
that--not the section).  The Linux man-pages project seems pretty wedded
to boldface for that purpose, but my partisan affiliation is with
italics.

> > * Added support for another string, perhaps 'MB' ("manref base"?),
> >   supplying a base URL which can be set at page-generation time.
> >   Embedding a full URL in man pages sources to an inherently
> >   relocatable page hierarchy is a bad idea.
> 
> For what it's worth, there is no full URL embedded in the sources.
> The references are all from other manual pages, so the refs inserted
> are just relative links like "../man1/cat.html".

groff went with URI/URLs of the form "man:title(section)"; these are
embedded in device control escape sequences so the output drivers can
interpret them however they choose.

At 2022-01-03T04:55:38+0000, Humm wrote:
> > I'm pleased to announce the addition, in discussion for over a
> > year[1], of a new semantic macro for the GNU implementation of
> > man(7), prompted by and compatible with Plan 9 troff, for man page
> > cross references: MR.
> 
> That’s nice, but s,Plan 9,plan9port,.

I am aware of the distinction but, really, does anyone _else_ maintain
Plan 9's troff?  It seems to me that the Plan 9 porters have adopted an
uncontested mantle of responsibility.  Does Vita Nuova work on it?

> > .MR ls 1 .
> 
> That’s nice and all, but still inconsistent with p9p -man.  There,
> you’d do
> 
>       .MR ls (1) .

Yes; the typing of parentheses seems to serve no purpose in a semantic
macro, as noted above.

Regards,
Branden

signature.asc
Description: PGP signature