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

[Alejandro Colomar]

On 11/10/22 20:37, Alejandro Colomar wrote:
> Hi Branden,
>
> On 11/10/22 19:04, Alejandro Colomar wrote:
> > Of course I forgot to rename the title, and to agg groff@.  Nice.
> >
> > -------- Forwarded Message --------
> > Subject: Re: [PATCH] Various pages: SYNOPSIS: Use VLA syntax in function 
> > parameters
> > Date: Thu, 10 Nov 2022 18:47:38 +0100
> > From: Alejandro Colomar <alx.manpages@gmail.com>
> > To: G. Branden Robinson <g.branden.robinson@gmail.com>
> > CC: Ingo Schwarze <schwarze@usta.de>, linux-man@vger.kernel.org
> >
> > [removed gcc@ and other uninterested people; added groff@]
> >
> > Hi Branden!
> >
> > On 11/10/22 11:59, Alejandro Colomar wrote:
> >  >> Also, as soon as Bertrand and I can get groff 1.23 out[1], I am hoping
> >  >> you will, shortly thereafter, migrate to the new `MR` macro.
> >  >
> >  > Not as soon as it gets released, because I expect (at least a decent amount 
> > of)
> >  > contributors to be able to read the pages to which they contribute to, but as
> >  > soon as it makes it into Debian stable, yes, that's in my plans.  So, if you
> >  > make it before the freeze, that means around a couple of months from now.
> >
> > 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.
> >
> > 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?
>
> To document and discuss the way I'm migrating, I'll share here the scripts:
>
> The simplest case: a single man page reference with no other stuff around it:
>
> $ find man* -type f \
>    | xargs sed -i 's/^\.BR \([^ ]*\) (\([1-9]\w*\))$/.MR \1 \2/'
>
> Second simplest case: a single man page reference with only trailing stuff:
>
> $ find man* -type f \
>    | xargs sed -i 's/^\.BR \([^ ]*\) (\([1-9]\w*\))/.MR \1 \2 /'
>
>
> And here I continue with hypothetical syntax not yet allowed by groff.
>
> A single man page reference with only leading stuff:
>
> $ find man* -type f \
>    | xargs sed -i 's/^\.RB \([^ ]*\) \([^ ]*\) (\([1-9]\w*\))$/.MR \2 \3 "" \1/'
>
> A single man page reference with both leading and trailing stuff (thank $DEITY 
> for not having comments in any of those, so I can just run the script):
>
> $ find man* -type f \
>    | xargs sed -i 's/^\.RB \([^ ]*\) \([^ ]*\) (\([1-9]\w*\))\(.*\)/.MR \2 \3 \4 
> \1/'

And a few more, to cover same-page references.  As Ingo recommended, I'm adding 
the section for consistency.  Redundancy is not a big issue here.

Man references in the same page, with no stuff around them:

$ find man2 -type f \
  | xargs sed -i 's/^\.BR \([^ ]*\) ()$/.MR \1 2/'

$ find man3 -type f \
  | xargs sed -i 's/^\.BR \([^ ]*\) ()$/.MR \1 3/'


Man references in the same page, with trailing stuff:

$ find man2 -type f \
  | xargs sed -i 's/^\.BR \([^ ]*\) ()/.MR \1 2 /'

$ find man3 -type f \
  | xargs sed -i 's/^\.BR \([^ ]*\) ()/.MR \1 3 /'


Man references in the same page, with only leading stuff:

$ find man2 -type f \
  | xargs sed -i 's/^\.RB \([^ ]*\) \([^ ]*\) ()$/.MR \2 2 "" \1/'

$ find man3 -type f \
  | xargs sed -i 's/^\.RB \([^ ]*\) \([^ ]*\) ()$/.MR \2 3 "" \1/'


And finally, man references in the same page, with both leading and trailing 
stuff (again, I was lucky, and there were no comments):

$ find man2 -type f \
  | xargs sed -i 's/^\.RB \([^ ]*\) \([^ ]*\) ()\(.*\)/.MR \2 2 \3 \1/'

$ find man3 -type f \
  | xargs sed -i 's/^\.RB \([^ ]*\) \([^ ]*\) ()\(.*\)/.MR \2 3 \3 \1/'

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

OpenPGP_signature
Description: OpenPGP digital signature