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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 





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@xxxxxxxxx>

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: OpenPGP_signature
Description: OpenPGP digital signature


[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux