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

Alejandro Colomar
2022-11-10T20:42:04Z

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