[RECIPE] Pull the trigger on Mister Sed? (MR macro migration)

G. Branden Robinson
2024-01-14T15:42:29Z

[-- Attachment #1.1: Type: text/plain, Size: 1857 bytes --]

Hi Alex,

All past efforts at submitting a patch for this have met with vger's
wrath and rage--even a diffstat is too much for it tolerate. For those
who don't remember what this proposal is meant to achieve, here's a
backgrounder from October[0].

groff 1.23.0 has been out for over six months[1] and every major
GNU/Linux distribution, plus several non-major ones, is shipping it.[2]

I'm attaching two scripts, "MR-migrate.sh" and "MR.sed". Drop them in
the directory of your man-pages checkout, and run the first with a POSIX
shell.

The migration script doesn't just alter the pages; it also generates
"before.txt" and "after.txt" files containing the man page contents
rendered as (UTF-8) plain text to verify that no changes to page content
(apart from font style change to man page cross references attendant to
the use of a new macro, which is user-configurable[3]) occur.

I get the following output:
$ sh ./MR-migrate.sh
man4/console_codes.4:324: warning: table wider than line length minus indentation
man5/proc_pid_smaps.5:88: warning: table wider than line length minus indentation
troff:man7/ascii.7:28: warning: cannot select font 'CW'
man4/console_codes.4:324: warning: table wider than line length minus indentation
man5/proc_pid_smaps.5:88: warning: table wider than line length minus indentation
troff:man7/ascii.7:28: warning: cannot select font 'CW'
SAME

Thanks again to Brian Inglis for reminding me not to update externally
generated/sourced pages (bpf-helpers and Paul Eggert's tz project).

Signed-off-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>

Regards,
Branden

[0] https://lore.kernel.org/linux-man/20231025185341.mqvn7qlm3iby4zgm@illithid/
[1] https://lists.gnu.org/archive/html/info-gnu/2023-07/msg00001.html
[2] https://repology.org/project/groff/versions
[3] You can of course find out how in groff_man(7).

[-- Attachment #1.2: MR-migrate.sh --]
[-- Type: application/x-sh, Size: 353 bytes --]

[-- Attachment #1.3: MR.sed --]
[-- Type: text/plain, Size: 745 bytes --]

# Handle simplest cases: ".BR foo (1)" and ".IR foo (1)".
s/^.[BI]R \(\\%\)*\([.@_[:alnum:]\\-]\+\) (\([1-9a-z]\+\))$/.MR \2 \3/
# Handle case: trailing punctuation, as in ".IR foo (1),".
s/^.[BI]R \(\\%\)*\([.@_[:alnum:]\\-]\+\) (\([1-9a-z]\+\))\([^[:space:]]\+\)$/.MR \2 \3 \4/
# Handle case: leading punctuation, as in ".RI ( foo (1)".
s/^.R[BI] \(\\%\)*\([^[:space:]]\+\) \([.@_[:alnum:]\\-]\+\) (\([1-9a-z]\+\))\([^[:space:]]\+\)$/\\%\2\\c\n.MR \3 \4 \5/
# Handle case: 3rd+ arguments or trailing comments. This case is rare
# and will require manual fixup if there are 4+ arguments to MR. Use
# groff -man -rCHECKSTYLE=1 to have them automatically reported.
s/^.[BI]R \(\\%\)*\([.@_[:alnum:]\\-]\+\) (\([1-8a-z]\+\))\( .*\)/.MR \2 \3\4/