Re: [PATCH v2] man*/: srcfix

[Alejandro Colomar <alx@kernel.org>]

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

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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]