Re: [PATCH v2] man*/: srcfix

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

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

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.

The above scenario is "snaggable" with an additional case in MR.sed.

# 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
+.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(-)

...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".

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.

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