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

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

[G. Branden Robinson]

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

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

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3450 bytes --]

Hi MR. sed,

On Sun, Jan 14, 2024 at 09:42:25AM -0600, G. Branden Robinson wrote:
> 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).


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

Recipe applied.  
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=d02c2e2a15b6b9f5c35d1bef150e23cff27372d0>

It's still not in master, so if you want to tweak the commit message,
feel free to suggest an edit.  I'll push tomorrow to master.

Since groff-1.23.0 is already available in most distributions (Gentoo,
Arch, Debian Sid --and Bookworm has backported support for MR--,
Fedora 39), I think it has come the time to apply it.

Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2428 bytes --]

Hi Branden,

On Sun, Jan 14, 2024 at 07:22:47PM +0100, Alejandro Colomar wrote:
> Hi MR. sed,
> 
> On Sun, Jan 14, 2024 at 09:42:25AM -0600, G. Branden Robinson wrote:
...
> > 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.
...
> > 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).
> 
> 
> > # 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/
> 
> Recipe applied.  
> <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=d02c2e2a15b6b9f5c35d1bef150e23cff27372d0>

I was checking the book script from Deri (Deri, could you simplify the
script now that we use MR?  So dropping support for old BR?), and
noticed about syscalls.2, which has man-page references inside a tbl.

That hasn't been migrated by the script.  I guess you'd want to also
migrate those, right, Branden?

Have a lovely night,,
Alex

> It's still not in master, so if you want to tweak the commit message,
> feel free to suggest an edit.  I'll push tomorrow to master.

BTW, I've amended now the author, which I forgot.
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib>

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2629 bytes --]

On Mon, Jan 15, 2024 at 01:10:45AM +0100, Alejandro Colomar wrote:
> Hi Branden,
> 
> On Sun, Jan 14, 2024 at 07:22:47PM +0100, Alejandro Colomar wrote:
> > Hi MR. sed,
> > 
> > On Sun, Jan 14, 2024 at 09:42:25AM -0600, G. Branden Robinson wrote:
> ...
> > > 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.
> ...
> > > 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).
> > 
> > 
> > > # 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/
> > 
> > Recipe applied.  
> > <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=d02c2e2a15b6b9f5c35d1bef150e23cff27372d0>
> 
> I was checking the book script from Deri (Deri, could you simplify the

(Forgot to send to Deri.)

> script now that we use MR?  So dropping support for old BR?), and
> noticed about syscalls.2, which has man-page references inside a tbl.
> 
> That hasn't been migrated by the script.  I guess you'd want to also
> migrate those, right, Branden?
> 
> Have a lovely night,,
> Alex
> 
> > It's still not in master, so if you want to tweak the commit message,
> > feel free to suggest an edit.  I'll push tomorrow to master.
> 
> BTW, I've amended now the author, which I forgot.
> <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib>

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

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

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1443 bytes --]

Hi Alex,

At 2024-01-15T01:10:45+0100, Alejandro Colomar wrote:
> I was checking the book script from Deri (Deri, could you simplify the
> script now that we use MR?  So dropping support for old BR?), and
> noticed about syscalls.2, which has man-page references inside a tbl.
> 
> That hasn't been migrated by the script.  I guess you'd want to also
> migrate those, right, Branden?

Yes.  This can be done by setting the cross references inside text
blocks "T{"/"T}", where they can call macros.  I'll test this, of
course--calling macros from within a text block can be a chancy thing.
I don't _expect_ problems here, since `MR` does not mess with the format
of the output line--it does not alter line length, indentation, or
vertical spacing.  I trust but will verify.

I also see several references that didn't get converted ca. line 850
because my sed script cowardly refused to rewrite lines with *roff
comments in them.  So I'll search for more stragglers like this.

I will therefore be back with a "RECIPE v2".  I do not promise that the
updated sed script will be any easier to look at.  :P

> BTW, I've amended now the author, which I forgot.
> <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib>

Thanks!  Better if I take the heat for this 15,000+-line change.  As
Ferris Bueller said to Cameron Frye, "you don't want this much heat."
;-)

Regards,
Branden

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

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1777 bytes --]

Hi Branden,

On Mon, Jan 15, 2024 at 06:05:20AM -0600, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2024-01-15T01:10:45+0100, Alejandro Colomar wrote:
> > I was checking the book script from Deri (Deri, could you simplify the
> > script now that we use MR?  So dropping support for old BR?), and
> > noticed about syscalls.2, which has man-page references inside a tbl.
> > 
> > That hasn't been migrated by the script.  I guess you'd want to also
> > migrate those, right, Branden?
> 
> Yes.  This can be done by setting the cross references inside text
> blocks "T{"/"T}", where they can call macros.  I'll test this, of
> course--calling macros from within a text block can be a chancy thing.
> I don't _expect_ problems here, since `MR` does not mess with the format
> of the output line--it does not alter line length, indentation, or
> vertical spacing.  I trust but will verify.
> 
> I also see several references that didn't get converted ca. line 850
> because my sed script cowardly refused to rewrite lines with *roff
> comments in them.  So I'll search for more stragglers like this.
> 
> I will therefore be back with a "RECIPE v2".  I do not promise that the
> updated sed script will be any easier to look at.  :P

Maybe some preparation patch can help with this?

> 
> > BTW, I've amended now the author, which I forgot.
> > <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib>
> 
> Thanks!  Better if I take the heat for this 15,000+-line change.  As
> Ferris Bueller said to Cameron Frye, "you don't want this much heat."
> ;-)

:-)

Cheers,
Alex

> 
> Regards,
> Branden



-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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