[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#14976: [patch] use semicolons in option descriptions, not periods
From: |
Benno Schulenberg |
Subject: |
bug#14976: [patch] use semicolons in option descriptions, not periods |
Date: |
Thu, 01 Aug 2013 21:56:31 +0200 |
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...
- bug#14976: [patch] use semicolons in option descriptions, not periods,
Benno Schulenberg <=
- bug#14976: [patch] use semicolons in option descriptions, not periods, Pádraig Brady, 2013/08/02
- bug#14976: [patch] use semicolons in option descriptions, not periods, Benno Schulenberg, 2013/08/03
- bug#14976: [patch] use semicolons in option descriptions, not periods, Pádraig Brady, 2013/08/03
- bug#14976: [patch] use semicolons in option descriptions, not periods, Benno Schulenberg, 2013/08/04
- bug#14976: [patch] use semicolons in option descriptions, not periods, Pádraig Brady, 2013/08/04
- bug#14976: [patch] use semicolons in option descriptions, not periods, Pádraig Brady, 2013/08/04
- bug#14976: [patch] use semicolons in option descriptions, not periods, Bernhard Voelker, 2013/08/04
- bug#14976: [patch] use semicolons in option descriptions, not periods, Benno Schulenberg, 2013/08/04
- bug#14976: [patch] use semicolons in option descriptions, not periods, Pádraig Brady, 2013/08/04
- bug#14976: [patch] use semicolons in option descriptions, not periods, Benno Schulenberg, 2013/08/04