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

[Alejandro Colomar]

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


After running those 4, and inspecting the changes to make sure they look good 
(and they do), I have a quite small amount of references that my scripts didn't 
catch.  Some of them, just need a ffix before running the scripts again, some 
others need a manual migration, but nothing too difficult.


alx@asus5775:~/src/linux/man-pages/man-pages/MR$ grep -rn '^\.RB .* 
.\?([1-9]\w*)'
man2/mremap.2:324:.RB ( mmap "(2) " MAP_PRIVATE ),
man2/perf_event_open.2:35:.RB ( read "(2), " mmap "(2), " prctl "(2), " fcntl 
"(2), etc.)."
man2/open.2:86:.RB ( read "(2), " write "(2), " lseek "(2), " fcntl (2),
man3type/div_t.3type:43:.RB [[ l ] l ] div (3)
man3/fts.3:189:.RB [ l ] stat (2)
man3/fts.3:200:.RB [ l ] stat (2)
man3/fts.3:331:.RB [ l ] stat (2)
man3/fts.3:745:.RB [ l ] stat (2).
man5/proc.5:3426:.RB ( flock "(2) and " fcntl (2))
man7/pty.7:125:.RB ( ssh "(1), " rlogin "(1), " telnet (1)),
alx@asus5775:~/src/linux/man-pages/man-pages/MR$ grep -rn '^\.BR .* 
.\?([1-9]\w*)'
man1/getent.1:346:.BR ahosts / getaddrinfo (3)
man2/ioprio_set.2:278:.BR IOPRIO_CLASS_RT " (1)"
man2/ioprio_set.2:293:.BR IOPRIO_CLASS_BE " (2)"
man2/ioprio_set.2:306:.BR IOPRIO_CLASS_IDLE " (3)"
man2/keyctl.2:985:.BR  execve (2).
man2/ioctl_iflags.2:63:.BR mount  (2)
man2/memfd_create.2:232:.BR  open (2)
man2/syslog.2:77:.BR SYSLOG_ACTION_OPEN " (1)"
man2/syslog.2:81:.BR SYSLOG_ACTION_READ " (2)"
man2/syslog.2:93:.BR SYSLOG_ACTION_READ_ALL " (3)"
man2/syslog.2:103:.BR SYSLOG_ACTION_READ_CLEAR " (4)"
man2/syslog.2:109:.BR SYSLOG_ACTION_CLEAR " (5)"
man2/syslog.2:128:.BR SYSLOG_ACTION_CONSOLE_OFF " (6)"
man2/syslog.2:152:.BR SYSLOG_ACTION_CONSOLE_ON " (7)"
man2/syslog.2:175:.BR SYSLOG_ACTION_CONSOLE_LEVEL " (8)"
man2/syslog.2:192:.BR SYSLOG_ACTION_SIZE_UNREAD " (9) (since Linux 2.4.10)"
man2/syslog.2:203:.BR SYSLOG_ACTION_SIZE_BUFFER " (10) (since Linux 2.6.6)"
man2/sigreturn.2:42:.BR sigaltstack "(2))\(emin"
man2/timerfd_create.2:320:.BR poll "(2), " select "(2) (and similar)"
man2/eventfd.2:144:.BR poll "(2), " select "(2) (and similar)"
man2/signalfd.2:134:.BR poll "(2), " select "(2) (and similar)"
man3/duplocale.3:99:.BR  freelocale (3).
man7/spufs.7:122:.BR read "(2), " pread "(2), " write "(2), " pwrite "(2), " 
lseek (2)
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))


Cheers,

Alex

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

OpenPGP_signature
Description: OpenPGP digital signature