groff
[Top][All Lists]
Advanced

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

Re: MR macro 4th argument (was: [PATCH] Various pages: SYNOPSIS: Use VLA


From: Alejandro Colomar
Subject: Re: MR macro 4th argument (was: [PATCH] Various pages: SYNOPSIS: Use VLA syntax in function parameters)
Date: Thu, 10 Nov 2022 21:41:41 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.4.1

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


reply via email to

[Prev in Thread] Current Thread [Next in Thread]