Hi Branden, On 2023-07-31 13:42, G. Branden Robinson wrote: > Hi Alex, > > At 2023-07-30T22:29:36+0200, Alejandro Colomar wrote: >> On 2023-07-30 21:32, G. Branden Robinson wrote: >>> Clean up in preparation for "MR sed". >>> >>> Format only one man page cross reference per input line. > [...] >>> --- a/man5/proc.5 >>> +++ b/man5/proc.5 >>> @@ -3459,7 +3459,9 @@ .SS Files and directories >>> .TP >>> .I /proc/locks >>> This file shows current file locks >>> -.RB ( flock "(2) and " fcntl (2)) >>> +.RB ( flock (2) >> >> I guess you'll want a \c before flock(2). RM ain't no macro. :) > > Thanks! Another good catch. I was trying to get over the goal line > too quickly yesterday, to little effect since the diff "ball" was too > large for vger even gzip -9 compressed, and was somehow corrupted in the > copy I sent directly to you. Can I just omit the diff entirely when > re-submitting? I'll include the (vastly shorter) sed script in the > commit message; you said you prefer to run such scripts yourself anyway. Sure. If you want to include the first 1 or 2 pages, it might help others have a look at what the patch does without running your script, but for me, the script and the --stat (especially, the count of line modifications, to make sure the script was correctly applied) are enough. > > The above scenario is "snaggable" with an additional case in MR.sed. While you're probably the most appropriate one to decide that, I suggest to keep it simple, and handle these special cases as separate patches. But whatever you prefer. > > # 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/ > > To anticipate complaints: > > The *roff markup produced by this is a bit viscous, exercising two > escape sequences that man page authors often neglect to use, or use > incorrectly.[1] > > diff --git a/man1/localedef.1 b/man1/localedef.1 > index 183f08f58..77ab69c4f 100644 > --- a/man1/localedef.1 > +++ b/man1/localedef.1 > @@ -53,7 +53,8 @@ .SH DESCRIPTION > files, > compiles them to a binary form quickly usable by the > locale functions in the C library > -.RB ( setlocale (3), > +\%(\c Interesting. No problem. > +.MR setlocale 3 , > .MR localeconv 3 , > etc.), > and places the output in > > On the bright side, this is only about 1% of all uses--and of course the > decision to cast a man page cross reference at the beginning of a > parenthetical is always(?) at the discretion of the page author. > > And when I say "about 1%", I'm not waving my hands. Here is the > diffstat summary from application of my "MR.sed" script _without_ the > foregoing replacement. > > 1100 files changed, 15264 insertions(+), 15264 deletions(-) OMG > > ...and here's what results from the replacement shown above. > > 56 files changed, 320 insertions(+), 160 deletions(-) > > The other complaint that I foresee is that while `MR` prevents man page > names from being hyphenated, that practice gives the formatter less > flexibility when performing adjustment, which can make the text "gappy". I guess that's inevitable. It's either that or unusable man page references. Cheers, Alex > > Here's an example from my before-and-after diff. > > --- DUMP1 2023-07-31 06:15:47.059827045 -0500 > +++ DUMP2 2023-07-31 06:16:03.059756758 -0500 > @@ -2503,2 +2503,2 @@ > - This specifies the caller’s session‐specific keyring (ses‐ > - sion-keyring(7)). > + This specifies the caller’s session‐specific keyring > + (session-keyring(7)). > > But people who hate this often hate adjustment anyway, and that's what > another new groff 1.23.0 feature is for. > > groff_man(7): > > -dAD=adjustment‐mode > Set line adjustment to adjustment‐mode, which is typically “b” > for adjustment to both margins (the default), or “l” for left > alignment (ragged right margin). Any valid argument to groff’s > “.ad” request may be used. See groff(7) for less‐common > choices. > > man-db man(1) has also long supported an "--nj" option to do the same > thing. In its Git repository it now uses the foregoing means if groff > 1.23 or later is the formatter, as opposed to a rougher approach with > some side effects. > > This problem also will never arise with mandoc(1), since it refuses to > perform adjustment (or hyphenation) even if you _do_ want it. > > [1] For *roff non-experts, groff_man_style(7) says: > > \% Control hyphenation. The location of this escape sequence > within a word marks a hyphenation point, supplementing groff’s > automatic hyphenation patterns. At the beginning of a word, it > suppresses any hyphenation breaks within except those specified > with \%. > > \c End a text line without inserting space or attempting a break. > Normally, if filling is enabled, the end of a text line is > treated like a space; an output line may be broken there (if > not, an adjustable space is inserted); if filling is disabled, > the line will be broken there, as in .EX/.EE examples. The next > line is interpreted as usual and can include a macro call > (contrast with \newline). \c is useful when three font styles > are needed in a single word, as in a command synopsis. -- <http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
