Re: [PATCH 2/9] ldconfig.8: Fix style nits

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

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



On 1/4/23 08:38, G. Branden Robinson wrote:> * Set `TH` page title in 
lowercase.> * In synopses, set ellipses as separate "operands" to better 
suggest>    argument separation by white space.
Please explain this better to me.  Maybe an example difference?

> * In synopses, prevent breaks within option brackets.
> * Typeset ellipses more attractively on troff devices.
> * Sort option flags in English lexicographic order.
> * De-parenthesize content that seems important.
> * Perform a Kemper notectomy.  That is, stop saying "note that"
>    followed by some declarative statement.  This trope is all over Unix
>    documentation and I even see it in ISO standards.  The latter doesn't
>    serve to recommend it; as Dave Kemper has pointed out, everything we
>    put in technical documentation should be worthy of note unless placed
>    in a footnote, marked as "unnecessary on a first reading", or similar.
>    It is the exception, not the rule.  If you feel the need to say "note
>    that", consider what adjacent material you shouldn't be saying at all.
> * Say "symbolic link" instead of "symlink".
> * When one sentence explains the previous, use a semicolon.
> * Set literals used as arguments to `-c` option in bold, not italics.
> * Place the modifier "only" more carefully.
> * Recast option descriptions to be in the imperative mood.
> * Recast file descriptions to use the paragraph tag as the subject of
>    the first sentence.
> 
> Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>


Please break this further into ffix, wfix, and tfix, if/where it makes sense. 
Moving code around also usually goes in a separate commit, with no other code 
changes (that would be for the sorting).

> ---
>   man8/ldconfig.8 | 54 ++++++++++++++++++++++++-------------------------
>   1 file changed, 27 insertions(+), 27 deletions(-)
> 
> diff --git a/man8/ldconfig.8 b/man8/ldconfig.8
> index 0e74c1791..2e54cfad4 100644
> --- a/man8/ldconfig.8
> +++ b/man8/ldconfig.8
> @@ -5,7 +5,7 @@
>   .\"
>   .\" Modified, 6 May 2002, Michael Kerrisk, <mtk.manpages@gmail.com>
>   .\"   Change listed order of /usr/lib and /lib
> -.TH LDCONFIG 8 (date) "Linux man-pages (unreleased)"
> +.TH ldconfig 8 (date) "Linux man-pages (unreleased)"
>   .SH NAME
>   ldconfig \- configure dynamic linker run-time bindings
>   .SH SYNOPSIS
> @@ -14,18 +14,18 @@ ldconfig \- configure dynamic linker run-time bindings
>   .\" --verbose, -V, --version, -?, --help, --usage
>   .B /sbin/ldconfig
>   .RB [ \-nNvXV ]
> -.RB [ \-f
> -.IR conf ]
> -.RB [ \-C
> +.RB [ \-C\~\c
>   .IR cache ]
> -.RB [ \-r
> +.RB [ \-f\~\c
> +.IR conf ]
> +.RB [ \-r\~\c
>   .IR root ]
> -.IR directory ...
> +.IR directory \~.\|.\|.
>   .PP
>   .B /sbin/ldconfig
>   .B \-l
>   .RB [ \-v ]
> -.IR library ...
> +.IR library \~.\|.\|.
>   .PP
>   .B /sbin/ldconfig
>   .B \-p
> @@ -39,8 +39,8 @@ in the file
>   and in the trusted directories,
>   .I /lib
>   and
> -.I /usr/lib
> -(on some 64-bit architectures such as x86-64,
> +.IR /usr/lib .
> +On some 64-bit architectures such as x86-64,
>   .I /lib
>   and
>   .I /usr/lib
> @@ -49,7 +49,7 @@ while
>   .I /lib64
>   and
>   .I /usr/lib64
> -are used for 64-bit libraries).
> +are used for 64-bit libraries.
>   .PP
>   The cache is used by the run-time linker,
>   .I ld.so
> @@ -96,9 +96,8 @@ option.
>   should normally be run by the superuser as it may require write
>   permission on some root owned directories and files.
>   .PP
> -Note that
>   .B \%ldconfig
> -will only look at files that are named
> +will look only at files that are named

Would you mind explaining the difference to a non-native speaker?

>   .I lib*.so*
>   (for regular shared objects) or
>   .I ld\-*.so*
> @@ -106,7 +105,7 @@ will only look at files that are named
>   Other files will be ignored.
>   Also,
>   .B \%ldconfig
> -expects a certain pattern to how the symlinks are set up,
> +expects a certain pattern to how the symbolic links are set up,
>   like this example,
>   where the middle file
>   .RB ( libfoo.so.1
> @@ -127,18 +126,20 @@ after an upgrade.
>   .BI \-\-format= fmt
>   (Since glibc 2.2)
>   .\" commit 45eca4d141c047950db48c69c8941163d0a61fcd
> -Cache format to use:
> -.IR old ,
> -.IR new ,
> +Use cache format
> +.IR fmt ,
> +which is one of
> +.BR old ,
> +.BR new ,
>   or
> -.IR \%compat .
> +.BR \%compat .
>   Since glibc 2.32,
>   the default is
> -.IR new .
> +.BR new .
>   .\" commit cad64f778aced84efdaa04ae64f8737b86f063ab
>   Before that,
>   it was
> -.IR \%compat .
> +.BR \%compat .
>   .TP
>   .BI \-C\~ cache
>   Use
> @@ -161,13 +162,12 @@ Ignore auxiliary cache file.
>   .TP
>   .B \-l
>   (Since glibc 2.2)
> -Library mode.
> -Manually link individual libraries.
> -Intended for use by experts only.
> +Interpret each operand as a libary name and configure its links.
> +Intended for use only by experts.

Same here.

Cheers,

Alex

>   .TP
>   .B \-n
> -Process only the directories specified on the command line.
> -Don't process the trusted directories,
> +Process only the directories specified on the command line;
> +don't process the trusted directories,
>   nor those specified in
>   .IR /etc/ld.so.conf .
>   Implies
> @@ -218,15 +218,15 @@ the cache is still rebuilt.
>   .PD 0
>   .TP
>   .I /lib/ld.so
> -Run-time linker/loader.
> +is the run-time linker/loader.
>   .TP
>   .I /etc/ld.so.conf
> -File containing a list of directories,
> +contains a list of directories,
>   one per line,
>   in which to search for libraries.
>   .TP
>   .I /etc/ld.so.cache
> -File containing an ordered list of libraries found in the directories
> +contains an ordered list of libraries found in the directories
>   specified in
>   .IR /etc/ld.so.conf ,
>   as well as those found in the trusted directories.

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

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