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

Alejandro Colomar
2022-11-10T23:55:35Z

[-- Attachment #1.1: Type: text/plain, Size: 7194 bytes --]

Hi Branden,

On 11/10/22 23:55, G. Branden Robinson wrote:
> 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. :)

:)

[...]

>> 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).

Hmm, will need to parse that. Anyway, I think now that I have the MR with 4
arguments, moving the 4th to the previous line with sed and N should not be that
difficult.

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

Well, being a compatible extension to the others is not that bad. How does
mdoc(7) solve it with Xr?

>
> (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.

One of the biggest issues with this is that it breaks what would otherwise
represent a single entity, into two lines, so it hurts readability. See as an
extreme example the following change I did with my scripts (from posix_spawn(3),
if you're curious):

@@ -129,7 +129,7 @@ .SH DESCRIPTION
Below, the functions are described in terms of a three-step process: the
.MR fork 3
step, the
-.RB pre- exec ()
+.MR exec 3 "" pre-
step (executed in the child),
and the
.MR exec 3

Having 'pre-' as the last part of some random line, separates it from the other
part of the word. The \c alternative would be:

step, the pre-
.MR exec 3
step ...

Not terrible, but I'm not in love with it.

>
> `\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.)

I hope I can come up with something, but yes, if not, I'll call you ;)

BTW, so far I've never found a case where I had to use the hold space. I wonder
if I may meet a case where I need it in my life. This week I came up with some
script for inserting an element into a JSON array at a specified position, but N
is all that was needed:
<http://www.alejandro-colomar.es/src/alx/nginx/unitcli.git/tree/bin/setup-unit#n969>.
I've met a few more-complex cases, but not really that much. I always come up
with some combination of filters that allows me to avoid the hold space.
Sometimes, two scripts run consecutively also helps keep it simple :)

Cheers,

Alex

>
> Regards,
> Branden