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

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?

Cheers,

Alex

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

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