bug#14976: [patch] use semicolons in option descriptions, not periods

[Pádraig Brady]

On 08/04/2013 08:51 PM, Benno Schulenberg wrote:
> 
> On Sun, Aug 4, 2013, at 13:28, Pádraig Brady wrote:
>> The latest patch is attached,
>> with all the above discussed changes.
>> I'll wait for confirmation before pushing.
> 
> Ack.  The patch is fine, with the spello corrected.
> 
> Bernhard, in my opinion "can be" is better than the too «pressing»
> "is one of" or "must be" or "must be one of" -- it is more «friendly».
> The syntax shows that the argument is not optional.

I left that as is so.

Also I was thinking of doing:

-  -d, --directory            list directories themselves, not their contents\n\
+  -d, --directory            for directories, list themselves, not their 
contents\n\

to avoid any ambiguity that -d listed only directories.
This is along the same lines as the recent du::usage() change:
http://git.sv.gnu.org/gitweb/?p=coreutils.git;a=commitdiff;h=63eea60

Also with your changes, we've gone over 80 chars per line in various places.
That is enforced with `make syntax-check`.  Now the existing indenting is
too much really, so what I've done is rather than mangling the descriptions,
I've just removed 4 spaces in the indentation between --option and description.
In a couple of places I've wrapped the description onto the following line, 
like:

      --show-control-chars   show nongraphic characters as-is (the default,\n\
                               unless program is 'ls' and output is a 
terminal)\n\

to:
      --show-control-chars\n\
                         show nongraphic characters as-is (the default,\n\
                           unless program is 'ls' and output is a terminal)\n\

Now there is a caveat with doing that for multi line descriptions,
in that help2man will add a blank line after the first line of the description.
That happens in a few places already, and isn't that awkward to parse,
so I'm fine with that for now.

As a general way to handle indentation going forward we might
revive the auto --help alignment patch:
http://lists.gnu.org/archive/html/coreutils/2012-09/msg00034.html

Anyway latest patch attached.

cheers,
Pádraig.

0001-doc-more-semicolons-instead-of-periods-in-option-des.patch
Description: Text Data