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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxx>

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: OpenPGP_signature
Description: OpenPGP digital signature


[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux