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

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

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