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

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

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