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.
