Re: MR macro 4th argument (was: [PATCH] Various pages: SYNOPSIS: Use VLA syntax in function parameters)

[G. Branden Robinson]

Hi Alex,

At 2022-11-10T19:04:46+0100, Alejandro Colomar wrote:
> Of course I forgot to rename the title, and to agg groff@.  Nice.

It gave me time to reply to this one.  :)

> On 11/10/22 11:59, Alejandro Colomar wrote:
> I won't be applying the patch now, to avoid contributors seeing people
> suddenly not seeing man page references while preparing patches.  But
> I'll start preparing the patch, to see where are the most difficult
> parts.  And maybe report some issues with the usability.
> 
> My first thing was to run:
> 
> $ grep -rn '^\.BR .* ([1-9]\w*)'
> 
> I'm surprised for good that it seems that there are no false
> positives.  I didn't expect that.  But since things like exit(1) are
> code, they are probably either not highlighted at all, or maybe are
> italicized (as code is).  So that's a good thing.
> 
> It showed a few lines that might be problematic, but that's actually
> bad code, which I need to fix:
> 
> man7/credentials.7:270:.BR setuid "(2) (" setgid (2))
> man7/credentials.7:274:.BR seteuid "(2) (" setegid (2))
> man7/credentials.7:277:.BR setfsuid "(2) (" setfsgid (2))
> man7/credentials.7:280:.BR setreuid "(2) (" setregid (2))
> man7/credentials.7:284:.BR setresuid "(2) (" setresgid (2))
> 
> Those are asking for a 2-line thing, where the second line is RB instead of
> BR. Which reminds me to check RB:
> 
> $ grep -rn '^\.RB .* ([1-9]\w*)'
> 
> There are much less cases, and also seem to be fine to script, with a few
> minor ffixes too.
> 
> The big issue is that your MR doesn't support leading text:
> 
>         .MR page‐title manual‐section [trailing‐text]
> 
> I remember we had this discussion about what to do with it.  A 4th
> argument?  There's also conflict with a hypothetical link that we
> might want to add later.
> 
> My opinion is that the 4th argument should be the leading text.
> Asking to use the escape (was it \c?) sequence to workaround that
> limitation is not very nice.   Especially for scripting the change.

Here's what I did for groff.

commit 2ab0dacb95863a2e347d06cf970676c74c784ce2
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Fri Oct 8 00:46:41 2021 +1100

    [man pages]: Migrate man(7) cross refs to `MR`.

     # Handle simplest case: ".IR foo (1)".
    s/^.[BI]R \(\\%\)*\([@_[:alnum:]\\-]\+\) (\(@MAN[157]EXT@\))$/.MR \2 \3/
    s/^.[BI]R \(\\%\)*\([@_[:alnum:]\\-]\+\) (\([1-8a-z]\+\))$/.MR \2 \3/
     # Handle case: trailing puncutation, e.g., ".IR foo (1),".
    s/^.[BI]R \(\\%\)*\([@_[:alnum:]\\-]\+\) 
(\(@MAN[157]EXT@\))\([^[:space:]]\+\)/.MR \2 \3 \4/
    s/^.[BI]R \(\\%\)*\([@_[:alnum:]\\-]\+\) 
(\([1-8a-z]\+\))\([^[:space:]]\+\)/.MR \2 \3 \4/
     # Handle case: 3rd+ arguments or trailing comments.  This case is rare
     # and will require manual fixup if there are 4+ arguments to MR.  Use
     # groff -man -rCHECKSTYLE=1 to have them automatically reported.
    s/^.[BI]R \(\\%\)*\([@_[:alnum:]\\-]\+\) (\(@MAN[157]EXT@\))\( .*\)/.MR \2 
\3\4/
    s/^.[BI]R \(\\%\)*\([@_[:alnum:]\\-]\+\) (\([1-8a-z]\+\))\( .*\)/.MR \2 
\3\4/

You can ignore the 'MAN[157]EXT' lines; they are relevant only to
within-groff pages (because all of our man pages undergo sed-processing
to be prepared for installation).

> If you want a 5th argument for a URI, you can specify the leading text
> as "", which is not much of an issue.  And you keep the trailing text
> and the leading one together.
> 
> What are your thoughts?  What should we do?

I am reluctant to extend the interface of `MR` at this point because as
it is it has two nice properties: it aligns with mdoc(7)'s `Xr` macro
and with Plan 9 from User Space troff's `MR`, which did it first.

(Admittedly, P9US troff's `MR` macro doesn't supply the parentheses.  I
don't know if they intend to change that.  I'm willing to supply a patch
to change their implementation and their man pages to align with what I
did in groff.  As shown above, I believe my sed-fu is in order.)

I think man page authors should learn when the `\c` escape sequence is
appropriate and use it when warranted, and recast their sentences
otherwise.  That is why I provided an explicit example in the
groff_man_style(7) page.

    .MR page-title manual-section [trailing-text]
        (since groff 1.23) Set a man page cross reference as "page-
        title(manual-section)".  If trailing-text (typically
        punctuation) is specified, it follows the closing parenthesis
        without intervening space.  Hyphenation is disabled while the
        cross reference is set.  page-title is set in the font specified
        by the MF string.  The cross reference hyperlinks to a URI of
        the form "man:page-title(manual-section)".

            The output driver
            .MR grops 1
            produces PostScript from
            .I troff
            output.
            .
            The Ghostscript program (\c
            .MR gs 1 )
            interprets PostScript and PDF.

`\c` solves problems that are complicated to solve any other way.  As
far as I have seen, you don't ever need it in mdoc(7) pages, for
example...but you pay a price.  You must learn which of mdoc's several
dozen macros are "parsed" versus "callable" (and what the heck the
package even _means_ by those words); you must learn that `Pf` and `Ns`
exist and when to use them; you must learn that certain two-letter words
will not behave as you expect; and if you thought using mdoc(7) meant
you wouldn't have to type any groff escape sequences, think
again--you'll be putting `\&` all over the place.

People can use mdoc(7) if they want to (and now that I'm learning it
better, I will consult as I am able), but its reputation in some circles
as a superior solution to man(7) on all fronts that should have kicked
its predecessor into the grave long ago is due solely to irresponsible
hype from its exponents.

If you need help automating a change to adapt some Linux man-pages
documents to use `\c` before an `MR` call on the next line (where you
were using `RB` before, for instance), just let know.  I am nearly
certain that a sed script utilizing its hold space feature can get the
job done.  (I've used the hold space profitably before, but occasions
for it come up seldom enough that I have to review my past solutions
before the knowledge comes back.  Or maybe it's creeping senescence.)

Regards,
Branden

signature.asc
Description: PGP signature