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

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

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