Re: [PATCH 1/9] ldconfig.8: Fix markup nits

[Alejandro Colomar <alx.manpages@gmail.com>]

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

Hi Branden,

On 1/4/23 08:38, G. Branden Robinson wrote:
> * Drop stale FIXME annotation regarding commit ID for `-i` option.
> * Rewrite synopses to use man(7) font macros instead of *roff font
>    selection escape sequences.
> * Drop redundant `PD` macro calls.
> * Rewrite option list to use man(7) font macros instead of *roff font
>    selection escape sequences.
> * Use `TQ` macro to include multiple tags for options with long synonyms
>    instead of comma notation.
> * Break input lines after commas.
> * Set multi-word parentheticals on their own input lines.
> * Break input lines at phrase boundaries more often.
> * Protect literals from automatic hyphenation with `\%` escape sequence.
> * Use \~ escape sequence instead of quoted arguments at word
>    boundaries in option synopses.
> 
> Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

This patch looks good to me.  However, I didn't apply it, since I have a few 
comments below.
> ---
>   man8/ldconfig.8 | 109 +++++++++++++++++++++++++++++++-----------------
>   1 file changed, 71 insertions(+), 38 deletions(-)
> 
> diff --git a/man8/ldconfig.8 b/man8/ldconfig.8
> index d608aaf56..0e74c1791 100644
> --- a/man8/ldconfig.8
> +++ b/man8/ldconfig.8
> @@ -9,22 +9,29 @@
>   .SH NAME
>   ldconfig \- configure dynamic linker run-time bindings
>   .SH SYNOPSIS

We should wrap this in .nf/.fi

Although maybe this goes better in the style patch, since it's a formatting fix.

> -.BR /sbin/ldconfig " [" \-nNvXV "] [" \-f " \fIconf\fP] [" \-C " \fIcache\fP] [" \-r " \fIroot\fP]"
> -.IR directory \...
>   .PD 0
> +.\" TODO?: -c, --format, -i, --ignore-aux-cache, --print-cache,
> +.\" --verbose, -V, --version, -?, --help, --usage
> +.B /sbin/ldconfig
> +.RB [ \-nNvXV ]
> +.RB [ \-f
> +.IR conf ]
> +.RB [ \-C
> +.IR cache ]
> +.RB [ \-r
> +.IR root ]
> +.IR directory ...
>   .PP
> -.PD
>   .B /sbin/ldconfig
>   .B \-l
>   .RB [ \-v ]
> -.IR library \...
> -.PD 0
> +.IR library ...
>   .PP
> -.PD
>   .B /sbin/ldconfig
>   .B \-p
> +.PD
>   .SH DESCRIPTION
> -.B ldconfig
> +.B \%ldconfig

I will suggest again that I believe \% should be the default in manual pages. 
Count how many times you want to break highlighted stuff vs how many times you 
want to not break such stuff.

>   creates the necessary links and cache to the most recent shared
>   libraries found in the directories specified on the command line,
>   in the file
> @@ -37,7 +44,8 @@ and

[...]

> @@ -105,35 +122,41 @@ Failure to follow this pattern may result in compatibility issues
>   after an upgrade.
>   .SH OPTIONS
>   .TP
> -.BR \-c " \fIfmt\fP, " \-\-format=\fIfmt\fP
> +.BI \-c\~ fmt
> +.TQ
> +.BI \-\-format= fmt
>   (Since glibc 2.2)
> +.\" commit 45eca4d141c047950db48c69c8941163d0a61fcd
>   Cache format to use:
>   .IR old ,
>   .IR new ,
>   or
> -.IR compat .
> -Since glibc 2.32, the default is
> +.IR \%compat .
> +Since glibc 2.32,
> +the default is
>   .IR new .
>   .\" commit cad64f778aced84efdaa04ae64f8737b86f063ab
> -Before that, it was
> -.IR compat .
> +Before that,
> +it was
> +.IR \%compat .
>   .TP
> -.BI "\-C " cache
> +.BI \-C\~ cache
>   Use
>   .I cache
>   instead of
>   .IR /etc/ld.so.cache .
>   .TP
> -.BI "\-f " conf
> +.BI \-f\~ conf
>   Use
>   .I conf
>   instead of
>   .IR /etc/ld.so.conf .
> -.\" FIXME glibc 2.7 added -i

And this is why comments are harmful.  I fint it rather uncommon for comments to 
be up-to-date with the code :P

>   .TP
> -.BR \-i ", " \-\-ignore\-aux\-cache
> +.B \-i
> +.TQ
> +.B \-\-ignore\-aux\-cache
>   (Since glibc 2.7)
> -.\"             commit 27d9ffda17df4d2388687afd12897774fde39bcc
> +.\" commit 27d9ffda17df4d2388687afd12897774fde39bcc
>   Ignore auxiliary cache file.
>   .TP
>   .B \-l
> @@ -154,31 +177,40 @@ Implies

[...]


-- 
<http://www.alejandro-colomar.es/>

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