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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxx>
To: G. Branden Robinson <g.branden.robinson@xxxxxxxxx>
CC: Ingo Schwarze <schwarze@xxxxxxx>, linux-man@xxxxxxxxxxxxxxx

[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: OpenPGP_signature
Description: OpenPGP digital signature


[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux