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

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

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 5133 bytes --]

* Set `TH` page title in lowercase.
* In synopses, set ellipses as separate "operands" to better suggest
  argument separation by white space.
* 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>
---
 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
 .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.
 .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.
-- 
2.30.2


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

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

[Alejandro Colomar]

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

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

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 4963 bytes --]

Hi Alex,

At 2023-01-04T19:50:01+0100, Alejandro Colomar wrote:
> On 1/4/23 08:38, G. Branden Robinson wrote:
> > * 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?

It is hard to locate examples of where I think elision of white space
before an ellipsis in a command summary would be correct, so I have to
contrive one.

Consider some super-complicated but traditionally-syntaxed form of the
tar(1) command.

tar cfv... archive member ...

There might be a _bunch_ of flag letters in the first argument, and a
terse or lazy man page might not present them all in the synopsis.  It
would be wrong to have white space as in "cfv ..." because once that
first argument is finished, the command is looking for an archive file
name (or "-", traditionally).  By contrast, each member of the archive
one wants to extract _must_ be separated by white space.

I acknowledge that the GNU tar(1) man page is not written in the style I
prescribe or presented above.  It appears to hew closely to Texinfo
conventions even where it need not, as with the shouting full capitals.
(Still, the page is a big improvement over the form it had 20 years or
so ago, when IIRC it was one of the many that told you to read info
files or pound sand.)

Official GNU resistance to man pages is broad and deep, but not
universal.

> > * In synopses, prevent breaks within option brackets.

We would more prefer the synopsis to break like this:

  /sbin/ldconfig [-nNvX] [-C cache] [-f conf]
  [-r root] directory ...

...than this.

  /sbin/ldconfig [-nNvX] [-C cache] [-f conf] [-r
  root] directory ...

If we use SY/YS and employ \~ judiciously, we'll even get this.

  /sbin/ldconfig [-nNvX] [-C cache] [-f conf]
                 [-r root] directory ...

Magnifique!  <chef's kiss>

> > * 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).

Okay, for v3 I'll split the "style" change into ffix, tfix, wfix, and
the lexical arrangement of the argumentful options to ldconfig(8).

> > -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?

Sure.  Consider the sentence:

I ate pizza yesterday.

We can insert the modifier "only" in _five_ different places in this
sentence, producing five distinct meanings.  For additional English
language fun, these are not the only possible interpretations; but all
are plausible.

Only I ate pizza yesterday.  ->  Other people ate something else.
I only ate pizza yesterday.  ->  I didn't _make_ the pizza.
I ate only pizza yesterday.  ->  I didn't eat anything else.
I ate pizza only yesterday.  ->  It hasn't been long since I ate pizza.
I ate pizza yesterday only.  ->  I usually don't, but fell off the wagon.

> > -will only look at files that are named
> > +will look only at files that are named

Here, the restriction applies to the set of possible files "looked at".
At the same time, files are not simply "looked at"; ldconfig(8) may
replace them by rewriting the target of a symbolic link.  So it is not
correct to suggest that files are "only looked at".

> > -Intended for use by experts only.
[...]
> > +Intended for use only by experts.
> 
> Same here.

There's no significant difference in meaning here, to my eyes; the
latter reads more like idiomatic English to me.

Regards,
Branden

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

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

[Alejandro Colomar]

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

Hi Branden,

On 1/4/23 21:04, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-01-04T19:50:01+0100, Alejandro Colomar wrote:
>> On 1/4/23 08:38, G. Branden Robinson wrote:
>>> * 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?
> 
> It is hard to locate examples of where I think elision of white space
> before an ellipsis in a command summary would be correct, so I have to
> contrive one.
> 
> Consider some super-complicated but traditionally-syntaxed form of the
> tar(1) command.
> 
> tar cfv... archive member ...
> 
> There might be a _bunch_ of flag letters in the first argument, and a
> terse or lazy man page might not present them all in the synopsis.  It
> would be wrong to have white space as in "cfv ..." because once that

Ahh, yes, we don't want that.

> first argument is finished, the command is looking for an archive file
> name (or "-", traditionally).  By contrast, each member of the archive
> one wants to extract _must_ be separated by white space.
> 
> I acknowledge that the GNU tar(1) man page is not written in the style I
> prescribe or presented above.  It appears to hew closely to Texinfo
> conventions even where it need not, as with the shouting full capitals.
> (Still, the page is a big improvement over the form it had 20 years or
> so ago, when IIRC it was one of the many that told you to read info
> files or pound sand.)
> 
> Official GNU resistance to man pages is broad and deep, but not
> universal.

Is there still resistance apart from written?  Most contributors to GNU today 
seem to use man pages.  There are still a few projects, like make(1) which would 
be better with manual pages documenting the language, but most have useful 
manual pages, don't they?  Maybe Debian helped get there.

> 
>>> * In synopses, prevent breaks within option brackets.
> 
> We would more prefer the synopsis to break like this:
> 
>    /sbin/ldconfig [-nNvX] [-C cache] [-f conf]
>    [-r root] directory ...
> 
> ...than this.
> 
>    /sbin/ldconfig [-nNvX] [-C cache] [-f conf] [-r
>    root] directory ...
> 
> If we use SY/YS and employ \~ judiciously, we'll even get this.
> 
>    /sbin/ldconfig [-nNvX] [-C cache] [-f conf]
>                   [-r root] directory ...

Hmmm, looks very good.

> 
> Magnifique!  <chef's kiss>
> 
>>> * 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).
> 
> Okay, for v3 I'll split the "style" change into ffix, tfix, wfix, and
> the lexical arrangement of the argumentful options to ldconfig(8).
> 
>>> -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?
> 
> Sure.  Consider the sentence:
> 
> I ate pizza yesterday.
> 
> We can insert the modifier "only" in _five_ different places in this
> sentence, producing five distinct meanings.  For additional English
> language fun, these are not the only possible interpretations; but all
> are plausible.
> 
> Only I ate pizza yesterday.  ->  Other people ate something else.
> I only ate pizza yesterday.  ->  I didn't _make_ the pizza.
> I ate only pizza yesterday.  ->  I didn't eat anything else.
> I ate pizza only yesterday.  ->  It hasn't been long since I ate pizza.
> I ate pizza yesterday only.  ->  I usually don't, but fell off the wagon.

Hmmm, pizza!  Nice examples.  Thanks!

> 
>>> -will only look at files that are named
>>> +will look only at files that are named
> 
> Here, the restriction applies to the set of possible files "looked at".
> At the same time, files are not simply "looked at"; ldconfig(8) may
> replace them by rewriting the target of a symbolic link.  So it is not
> correct to suggest that files are "only looked at".

Makes sense.

> 
>>> -Intended for use by experts only.
> [...]
>>> +Intended for use only by experts.
>>
>> Same here.
> 
> There's no significant difference in meaning here, to my eyes; the
> latter reads more like idiomatic English to me.

Okay.

> 
> Regards,
> Branden

Cheers,
Alex

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

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

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

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1823 bytes --]

Hi Alex,

At 2023-01-05T13:03:01+0100, Alejandro Colomar wrote:
> On 1/4/23 21:04, G. Branden Robinson wrote:
> > Official GNU resistance to man pages is broad and deep, but not
> > universal.
> 
> Is there still resistance apart from written?

This is hard to me to judge, but I also interpret unorthodox man page
typography as constitutive of resistance.  I credit Albert Cahalan with
giving me a formative experience in reading a man page that was written
with resentment.[1]  Countless thousands of Debian ps(1) page readers,
often under stress trying to figure out how to identify and kill a rogue
process, attempted self-help and found themselves served a dinner plate
of steaming documentary hostility, innocent bystanders caught up in a
pointless vendetta against a text formatting language.

When Mr. Cahalan passes, I hope his family has the funds to engrave the
first comment block from his ps(1) rewrite on his headstone.

> Most contributors to GNU today seem to use man pages.  There are still
> a few projects, like make(1) which would be better with manual pages
> documenting the language, but most have useful manual pages, don't
> they?

GNU programs whose manuals have Invariant Sections or Cover Texts under
the FDL tend also to lack freely-licensed man pages.

Fortunately groff doesn't have this problem, because it's all
dual-licensed GPL.

> Maybe Debian helped get there.

I'd like to think so.  I was around when Debian still took a lot of crap
for adopting that stance.  Now it has users who weren't born yet when
that policy decision was made.

If you don't have further comments on v2 I'll make a few more changes to
v3 and submit it.

Regards,
Branden

[1] https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1

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

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

[Alejandro Colomar]

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

Hi Branden,

On 1/5/23 13:35, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-01-05T13:03:01+0100, Alejandro Colomar wrote:
>> On 1/4/23 21:04, G. Branden Robinson wrote:
>>> Official GNU resistance to man pages is broad and deep, but not
>>> universal.
>>
>> Is there still resistance apart from written?
> 
> This is hard to me to judge, but I also interpret unorthodox man page
> typography as constitutive of resistance.  I credit Albert Cahalan with
> giving me a formative experience in reading a man page that was written
> with resentment.[1]

Heh!  That one definitely counts as resistance.

>  Countless thousands of Debian ps(1) page readers,
> often under stress trying to figure out how to identify and kill a rogue
> process, attempted self-help and found themselves served a dinner plate
> of steaming documentary hostility, innocent bystanders caught up in a
> pointless vendetta against a text formatting language.

Thew current page is better, but the command is so huge that I'll die before 
knowing how to use it more than the couple of options I normally use.

> 
> When Mr. Cahalan passes, I hope his family has the funds to engrave the
> first comment block from his ps(1) rewrite on his headstone.

It would be ironic if they indented anything in his headstone :)

> 
>> Most contributors to GNU today seem to use man pages.  There are still
>> a few projects, like make(1) which would be better with manual pages
>> documenting the language, but most have useful manual pages, don't
>> they?
> 
> GNU programs whose manuals have Invariant Sections or Cover Texts under
> the FDL tend also to lack freely-licensed man pages.
> 
> Fortunately groff doesn't have this problem, because it's all
> dual-licensed GPL.
> 
>> Maybe Debian helped get there.
> 
> I'd like to think so.  I was around when Debian still took a lot of crap
> for adopting that stance.  Now it has users who weren't born yet when
> that policy decision was made.
> 
> If you don't have further comments on v2 I'll make a few more changes to
> v3 and submit it.

Please submit it.  We'll see.

Cheers,

Alex

> 
> Regards,
> Branden
> 
> [1] https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1

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

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

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

[Alejandro Colomar]

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



On 1/5/23 13:03, Alejandro Colomar wrote:
> Hi Branden,
> 
> On 1/4/23 21:04, G. Branden Robinson wrote:
>> Hi Alex,
>>
>> At 2023-01-04T19:50:01+0100, Alejandro Colomar wrote:
>>> On 1/4/23 08:38, G. Branden Robinson wrote:
>>>> * 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?
>>
>> It is hard to locate examples of where I think elision of white space
>> before an ellipsis in a command summary would be correct, so I have to
>> contrive one.
>>
>> Consider some super-complicated but traditionally-syntaxed form of the
>> tar(1) command.
>>
>> tar cfv... archive member ...
>>
>> There might be a _bunch_ of flag letters in the first argument, and a
>> terse or lazy man page might not present them all in the synopsis.  It
>> would be wrong to have white space as in "cfv ..." because once that
> 
> Ahh, yes, we don't want that.
> 
>> first argument is finished, the command is looking for an archive file
>> name (or "-", traditionally).  By contrast, each member of the archive
>> one wants to extract _must_ be separated by white space.
>>

I missed this part.  After having checked a few manual pages from various 
projects (OpenBSD grep(1), GNU grep(1), GNU tail(1), grepc(1)), it seems that 
the only one that has the ellipses together with "FILE" are from GNU, and we 
know GNU pages are not the best examples of quality, so yes, I agree.

>> I acknowledge that the GNU tar(1) man page is not written in the style I
>> prescribe or presented above.  It appears to hew closely to Texinfo
>> conventions even where it need not, as with the shouting full capitals.
>> (Still, the page is a big improvement over the form it had 20 years or
>> so ago, when IIRC it was one of the many that told you to read info
>> files or pound sand.)
>>
>> Official GNU resistance to man pages is broad and deep, but not
>> universal.
> 
> Is there still resistance apart from written?  Most contributors to GNU today 
> seem to use man pages.  There are still a few projects, like make(1) which would 
> be better with manual pages documenting the language, but most have useful 
> manual pages, don't they?  Maybe Debian helped get there.
> 
>>
>>>> * In synopses, prevent breaks within option brackets.
>>
>> We would more prefer the synopsis to break like this:
>>
>>    /sbin/ldconfig [-nNvX] [-C cache] [-f conf]
>>    [-r root] directory ...
>>
>> ...than this.
>>
>>    /sbin/ldconfig [-nNvX] [-C cache] [-f conf] [-r
>>    root] directory ...
>>
>> If we use SY/YS and employ \~ judiciously, we'll even get this.
>>
>>    /sbin/ldconfig [-nNvX] [-C cache] [-f conf]
>>                   [-r root] directory ...
> 
> Hmmm, looks very good.
> 
>>
>> Magnifique!  <chef's kiss>
>>
>>>> * 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).
>>
>> Okay, for v3 I'll split the "style" change into ffix, tfix, wfix, and
>> the lexical arrangement of the argumentful options to ldconfig(8).
>>
>>>> -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?
>>
>> Sure.  Consider the sentence:
>>
>> I ate pizza yesterday.
>>
>> We can insert the modifier "only" in _five_ different places in this
>> sentence, producing five distinct meanings.  For additional English
>> language fun, these are not the only possible interpretations; but all
>> are plausible.
>>
>> Only I ate pizza yesterday.  ->  Other people ate something else.
>> I only ate pizza yesterday.  ->  I didn't _make_ the pizza.
>> I ate only pizza yesterday.  ->  I didn't eat anything else.
>> I ate pizza only yesterday.  ->  It hasn't been long since I ate pizza.
>> I ate pizza yesterday only.  ->  I usually don't, but fell off the wagon.
> 
> Hmmm, pizza!  Nice examples.  Thanks!
> 
>>
>>>> -will only look at files that are named
>>>> +will look only at files that are named
>>
>> Here, the restriction applies to the set of possible files "looked at".
>> At the same time, files are not simply "looked at"; ldconfig(8) may
>> replace them by rewriting the target of a symbolic link.  So it is not
>> correct to suggest that files are "only looked at".
> 
> Makes sense.
> 
>>
>>>> -Intended for use by experts only.
>> [...]
>>>> +Intended for use only by experts.
>>>
>>> Same here.
>>
>> There's no significant difference in meaning here, to my eyes; the
>> latter reads more like idiomatic English to me.
> 
> Okay.
> 
>>
>> Regards,
>> Branden
> 
> Cheers,
> Alex
> 

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

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