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

[Alejandro Colomar <alx.manpages@gmail.com>]

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

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]