Re: style: .MR

[G. Branden Robinson]

Hi Alex!

At 2022-02-07T18:34:15+0100, Alejandro Colomar (man-pages) wrote:
> Hi Branden,
> 
> How would you use .MR on non-man[23] (e.g., man1) pages to refer to
> the same topic of the manual page?  I mean, how would you refer to
> groff(1) from within groff.1?
> 
> .MR groff
> .MR groff 1
> 
> ?

It's an open question, and there is an unresolved difference of opinion
between me and Ingo Schwarze (mandoc maintainer) about a somewhat
broader issue.

Here's the background from last August[1].  Reading all 3 messages in
the thread is recommended.

In summary, I see man(7)'s new `MR` as roughly analogous to mdoc(7)'s
`Xr`.

However, by accident (apparently), groff's mdoc(7) implementation
supports single-argument calls of `Xr`.  mandoc(1) complains about this.
Ingo says that an mdoc(7) page making a self-reference should use `Nm`
for this purpose, and I see no reason to argue.

At the same time, man(7) has no counterpart to `Nm` and in my opinion,
introducing one for this purpose would not "pay its freight".  My ideas
about a general semantic tag system for man(7) are starting to take
shape, and I'm inclined to share them soon, but I'm more inclined to get
a groff-1.23.0-rc2 out.  Long story short, if something like what I have
in mind for semantic tags takes shape, it will take only two new macros
at most, and most man(7) pages in sections 1, 6,  or 8 (commands)
wanting to follow groff pages' practices will need only one of those.

> If you omit the number, you get empty parentheses, which for man[23]
> pages looks good (they are functions, and that syntax looks good for
> them),

Yes, I think this something like what mathematicians call an abuse of
notation.  That parentheses are both commonly used as a function
invocation operator and to set off man page section numbers from titles
is a typographical accident.  And not one without cost...let me quote
the forthcoming groff 1.23.0 NEWS file.

  [`MR`'s] purpose is to ameliorate several long-standing problems with
  man page cross references: [...] (2) false-positive identification of
  strings resembling man page cross references (as can happen with
  "exit(1)", "while(1)", "sleep(5)", "time(0)" and others) by terminal
  emulators and other programs; [...]

Right now the second argument to `MR` is mandatory (did I forget to put
in a style warning?--no, I didn't).  If I were to loosen the syntax to
permit an empty second argument, I would have the macro _not_ supply any
parentheses, and if you wanted abutting punctuation, I would require the
man(7) writer to put `\c` at the end of the first argument.  So the new
`MR` synopsis would be as follows.

  .MR page-title [page-section [trailing-punct]]

Thus if you wanted to talk in a section 2 or 3 page about some C
function name that has a man page to which you'd already referred, you
would write, for example.

  The
  .MR gmtime\c
  () function converts the calendar time
  .I timep
  to broken-down time representation,

Omission of a second argument would also necessarily suppress hyperlink
generation.

Maybe there's even an upside to this; if consistently applied, function
call references that _weren't_ man page cross references would become
extremely easy to locate with grep.  '^()' ought to do it.

> but for commands, it looks weird.

Oh, definitely.

> And if you specify the section, you're a bit repetitive (but that's
> better than nothing).

Yes.  This doesn't seem to worry Ingo much, but I'm a bit more
sympathetic to the "writerly" concern of avoiding excess repetition.
(That said, I frequently use parallel constructions in man(7) documents
rigidly and without shame, to make it clear to the reader that parallel
semantics or behavior are to be inferred--and also because man pages are
so frequently not read in linear sequence, but full-text searched and
the least possible amount of material absorbed to resolve the immediate
concern.)

> And then there's the option of using .B, or .I, but as we know,
> there's no consensus on which of them should be used.

Right.  I don't see any solutions for this apart from making `MR` more
permissive, supporting "semantic tag classes" (my pie-in-the-sky idea
above), or bloating the macro name space for a something of limited and
specialized function, and the last is my least favorite by a long shot.

If someone else has a better imagination, please speak up.

At intervals over the past few days I've been drafting an email in my
head about my further man(7) reforms; there are three.  One is above.
The other two involve the lack of a macro for quotation and the lack of
a non-deprecated, non-tbl(1) way to eliminate the space between
paragraphs in lists.

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2021-08/msg00035.html

signature.asc
Description: PGP signature