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

[Pádraig Brady]

On 08/01/2013 08:56 PM, Benno Schulenberg wrote:
> 
> Hello Pádraig,
> 
> On Mon, Jul 29, 2013, at 19:02, Pádraig Brady wrote:
>> On 07/28/2013 08:27 PM, Benno Schulenberg wrote:
>>> Attached patch replaces in several usage texts some periods with
>>> semicolons, removes from them several inconsistent final periods,
>>> properly double-indents continuation lines, and rephrases two or
>>> three sentences a little for increased clarity.
> 
> 
>>> -  -m                         fill width with a comma separated list of 
>>> entries\
>>> +  -m                         fill width with a comma-separated list of 
>>> entries\
>>
>> -1 This doesn't seem warranted.
>> Also all other mentions in usage() it various utilities use the non 
>> hyphenated version
> 
> Okay, I'll propose a patch to change all of those later.
> 
> 
>>> -      --suffix=SUFF   append SUFF to TEMPLATE.  SUFF must not contain 
>>> slash.\n\
>>> -                        This option is implied if TEMPLATE does not end in 
>>> X.\n\
>>> +      --suffix=SUFF   append SUFF to TEMPLATE; SUFF must not contain a 
>>> slash;\n\
>>> +                        this option is implied if TEMPLATE does not end in 
>>> X\n\
>>
>> -1 First ; OK, second doesn't seem right.
> 
> Well, the thing is: option descriptions never end with a period, which means
> they are not proper sentences, so should not start with a capital letter 
> either.
> When part of the description _does start with a capital, then it attempts to
> be a sentence and must thus end in a period -- which is not done, so...

Heh fair point. I see "\. [A-Z]" as sentence separators in this context.
I slightly prefer that, over artificially lengthened "sentences".
This is another reason to aim for short precise descriptions,
and more generally options that can be described in that manner.

>>> -      --tmpdir[=DIR]  interpret TEMPLATE relative to DIR.  If DIR is not\n\
>>> -                        specified, use $TMPDIR if set, else /tmp.  With\n\
>>> -                        this option, TEMPLATE must not be an absolute 
>>> name.\n\
>>> -                        Unlike with -t, TEMPLATE may contain slashes, 
>>> but\n\
>>> +      --tmpdir[=DIR]  interpret TEMPLATE relative to DIR; if DIR is not\n\
>>> +                        specified, use $TMPDIR if set, else /tmp; with\n\
>>> +                        this option, TEMPLATE must not be an absolute 
>>> name;\n\
>>> +                        unlike with -t, TEMPLATE may contain slashes, 
>>> but\n\
>>>                          mktemp creates only the final component\n\
>>
>> -1 The second ; doesn't seem right. Best to have 2 sentences here?
> 
> A semicolon is a sentence separator too; it just avoids the need for
> a capital starter letter and a finishing period.

Well generally there should be some tenuous relationship
between the ; delimited "sentences"
(like an elided continuation wored (that is not "and")).

>>> -                           -f, --follow, and --follow=descriptor are\n\
>>> -                           equivalent\n\
>>> +                             --follow equals --follow=descriptor\n\
>>
>> +1
> 
> Ah, you plussed-one this change, but the actual line you put in is:
> 
>         -f and --follow[=descriptor] are equivalent\n\
> 
> Which to me is kind of puzzling, because it is already known that
> -f and --follow are equivalent.  What the added sentence tries to
> say is that 'descriptor' is the default option argument when none
> is provided.  I think my version says that more clearly, but maybe
> a still better phrasing can be found.

I wanted to add -f in explicitly as that's the common usage.
It's a tradeoff between space/layout and grammar which is
always awkward.  I'll think about improvements.

thanks,
Pádraig.