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

[Benno Schulenberg]

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...

> > -      --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.


> > -                           -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.

Regards,

Benno

-- 
http://www.fastmail.fm - mmm... Fastmail...