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: 5503 bytes --]

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

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