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

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

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



On 1/4/23 13:26, Alejandro Colomar wrote:
> 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.

BTW, this would qualify as a style change (in my book, a ffix).  No?

Cheers,

Alex

>> * 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 --]