Package: coreutils;
Reported by: Benno Schulenberg <bensberg <at> justemail.net>
Date: Sun, 28 Jul 2013 19:28:02 UTC
Severity: normal
Tags: patch
Done: Pádraig Brady <P <at> draigBrady.com>
Bug is archived. No further changes may be made.
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 14976 in the body.
You can then email your comments to 14976 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
View this report as an mbox folder, status mbox, maintainer mbox
bug-coreutils <at> gnu.org:bug#14976; Package coreutils.
(Sun, 28 Jul 2013 19:28:02 GMT) Full text and rfc822 format available.Benno Schulenberg <bensberg <at> justemail.net>:bug-coreutils <at> gnu.org.
(Sun, 28 Jul 2013 19:28:02 GMT) Full text and rfc822 format available.Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
From: Benno Schulenberg <bensberg <at> justemail.net> To: Coreutils <bug-coreutils <at> gnu.org> Subject: [patch] use semicolons in option descriptions, not periods Date: Sun, 28 Jul 2013 21:27:24 +0200
[Message part 1 (text/plain, inline)]
Hi,
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.
Regards,
Benno
--
http://www.fastmail.fm - Accessible with your email software
or over the web
[0001-textual-use-semicolon-instead-of-period-in-option-de.patch (text/x-patch, attachment)]
bug-coreutils <at> gnu.org:bug#14976; Package coreutils.
(Mon, 29 Jul 2013 17:03:02 GMT) Full text and rfc822 format available.Message #8 received at 14976 <at> debbugs.gnu.org (full text, mbox):
From: Pádraig Brady <P <at> draigBrady.com> To: Benno Schulenberg <bensberg <at> justemail.net> Cc: 14976 <at> debbugs.gnu.org Subject: Re: bug#14976: [patch] use semicolons in option descriptions, not periods Date: Mon, 29 Jul 2013 18:02:45 +0100
On 07/28/2013 08:27 PM, Benno Schulenberg wrote:
> Hi,
>
> 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.
>
> Regards,
>
> Benno
>
> -- http://www.fastmail.fm - Accessible with your email software or over the web
>
>
> 0001-textual-use-semicolon-instead-of-period-in-option-de.patch
>
>
> From 2bac2f05a68bc3534b54b480469f58bfd2489c8f Mon Sep 17 00:00:00 2001
> From: Benno Schulenberg <bensberg <at> justemail.net>
> Date: Sun, 28 Jul 2013 13:54:20 +0200
> Subject: [PATCH] textual: use semicolon instead of period in option descriptions
>
> Also do not end option descriptions with a period, properly indent
> continuation lines, and make some tiny clarifications.
>
> * src/du.c (usage): Lowercase after semicolon.
> * src/ls.c (usage): Semicolons instead of periods, small rephrasing
> and two hyphens for clarity, proper indentation.
> * src/mktemp.c (usage): Semicolons and lowercase.
> * src/od.c (usage): Semicolons.
> * src/ptx.c (usage): Use the standard phrase, clarify default option.
> * src/setuidgid.c (usage): Properly indent continuation line.
> * src/split.c (usage): Semicolons, lowercase, no final period.
> * src/stat.c (usage): Semicolons, lowercase.
> * src/tail.c (usage): Proper indentation, one shorter rephrasing,
> semicolons, no final periods.
> * src/timeout.c (usage): Properly indent, semicolons, no final periods.
> ---
> src/du.c | 4 ++--
> src/ls.c | 28 ++++++++++++++--------------
> src/mktemp.c | 12 ++++++------
> src/od.c | 6 +++---
> src/ptx.c | 2 +-
> src/setuidgid.c | 2 +-
> src/split.c | 8 ++++----
> src/stat.c | 4 ++--
> src/tail.c | 21 ++++++++++-----------
> src/timeout.c | 16 ++++++++--------
> 10 files changed, 51 insertions(+), 52 deletions(-)
>
> diff --git a/src/du.c b/src/du.c
> index 9f1f98c..849ddab 100644
> --- a/src/du.c
> +++ b/src/du.c
> @@ -312,8 +312,8 @@ Summarize disk usage of each FILE, recursively for directories.\n\
> "), stdout);
> fputs (_("\
> --files0-from=F summarize disk usage of the NUL-terminated file\n\
> - names specified in file F;\n\
> - If F is - then read names from standard input\n\
> + names specified in file F; if F is -, then read\n\
> + names from standard input\n\
-1 I think it would be better to leave the "if F ..." on a separate line,
the ";" is OK here.
> -H equivalent to --dereference-args (-D)\n\
> -h, --human-readable print sizes in human readable format (e.g., 1K 234M 2G)\
> \n\
> diff --git a/src/ls.c b/src/ls.c
> index e341c67..2936498 100644
> --- a/src/ls.c
> +++ b/src/ls.c
> @@ -4758,19 +4758,19 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
> -b, --escape print C-style escapes for nongraphic characters\n\
> "), stdout);
> fputs (_("\
> - --block-size=SIZE scale sizes by SIZE before printing them. E.g.,\n\
> + --block-size=SIZE scale sizes by SIZE before printing them; e.g.,\n\
> '--block-size=M' prints sizes in units of\n\
> - 1,048,576 bytes. See SIZE format below.\n\
> + 1,048,576 bytes; see SIZE format below\n\
+1 Marginal but fair enough
> -B, --ignore-backups do not list implied entries ending with ~\n\
> -c with -lt: sort by, and show, ctime (time of last\n\
> - modification of file status information)\n\
> - with -l: show ctime and sort by name\n\
> + modification of file status information);\n\
> + with -l: show ctime and sort by name;\n\
+1
> otherwise: sort by ctime, newest first\n\
> "), stdout);
> fputs (_("\
> -C list entries by columns\n\
> --color[=WHEN] colorize the output. WHEN defaults to 'always'\n\
> - or can be 'never' or 'auto'. More info below\n\
> + or can be 'never' or 'auto'; more info below\n\
+1
> -d, --directory list directory entries instead of contents,\n\
> and do not dereference symbolic links\n\
> -D, --dired generate output designed for Emacs' dired mode\n\
> @@ -4788,8 +4788,8 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
> "), stdout);
> fputs (_("\
> --group-directories-first\n\
> - group directories before files.\n\
> - augment with a --sort option, but any\n\
> + group directories before files;\n\
> + can be augmented with a --sort option, but any\n\
+1
> use of --sort=none (-U) disables grouping\n\
> "), stdout);
> fputs (_("\
> @@ -4803,7 +4803,7 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
> follow symbolic links listed on the command line\n\
> --dereference-command-line-symlink-to-dir\n\
> follow each command line symbolic link\n\
> - that points to a directory\n\
> + that points to a directory\n\
+1
> --hide=PATTERN do not list implied entries matching shell PATTERN\
> \n\
> (overridden by -a or -A)\n\
> @@ -4823,7 +4823,7 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
> -L, --dereference when showing file information for a symbolic\n\
> link, show information for the file the link\n\
> references rather than for the link itself\n\
> - -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
> \n\
> "), stdout);
> fputs (_("\
> @@ -4835,7 +4835,7 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
> append / indicator to directories\n\
> "), stdout);
> fputs (_("\
> - -q, --hide-control-chars print ? instead of non graphic characters\n\
> + -q, --hide-control-chars print ? instead of non-graphic characters\n\
+1
> --show-control-chars show non graphic characters as-is (default\n\
> unless program is 'ls' and output is a terminal)\n\
> -Q, --quote-name enclose entry names in double quotes\n\
> @@ -4860,9 +4860,9 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
> "), stdout);
> fputs (_("\
> --time-style=STYLE with -l, show times using style STYLE:\n\
> - full-iso, long-iso, iso, locale, +FORMAT.\n\
> + full-iso, long-iso, iso, locale, +FORMAT;\n\
> FORMAT is interpreted like 'date'; if FORMAT is\n\
> - FORMAT1<newline>FORMAT2, FORMAT1 applies to\n\
> + FORMAT1<newline>FORMAT2, then FORMAT1 applies to\n\
+1
> non-recent files and FORMAT2 to recent files;\n\
> if STYLE is prefixed with 'posix-', STYLE\n\
> takes effect only outside the POSIX locale\n\
> @@ -4872,8 +4872,8 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
> -T, --tabsize=COLS assume tab stops at each COLS instead of 8\n\
> "), stdout);
> fputs (_("\
> - -u with -lt: sort by, and show, access time\n\
> - with -l: show access time and sort by name\n\
> + -u with -lt: sort by, and show, access time;\n\
> + with -l: show access time and sort by name;\n\
+1
> otherwise: sort by access time\n\
> -U do not sort; list entries in directory order\n\
> -v natural sort of (version) numbers within text\n\
> diff --git a/src/mktemp.c b/src/mktemp.c
> index aef140a..04342c3 100644
> --- a/src/mktemp.c
> +++ b/src/mktemp.c
> @@ -81,14 +81,14 @@ Files are created u+rw, and directories u+rwx, minus umask restrictions.\n\
> -q, --quiet suppress diagnostics about file/dir-creation failure\n\
> "), stdout);
> fputs (_("\
> - --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.
> "), stdout);
> fputs (_("\
> - --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?
> "), stdout);
> fputs ("\n", stdout);
> diff --git a/src/od.c b/src/od.c
> index 1c23401..5635d29 100644
> --- a/src/od.c
> +++ b/src/od.c
> @@ -316,18 +316,18 @@ suffixes may be . for octal and b for multiply by 512.\n\
> emit_mandatory_arg_note ();
>
> fputs (_("\
> - -A, --address-radix=RADIX output format for file offsets. RADIX is one\n\
> + -A, --address-radix=RADIX output format for file offsets; RADIX is one\n\
> of [doxn], for Decimal, Octal, Hex or None\n\
+1
> -j, --skip-bytes=BYTES skip BYTES input bytes first\n\
> "), stdout);
> fputs (_("\
> -N, --read-bytes=BYTES limit dump to BYTES input bytes\n\
> - -S BYTES, --strings[=BYTES] output strings of at least BYTES graphic chars.\
> + -S BYTES, --strings[=BYTES] output strings of at least BYTES graphic chars;\
> \n\
> 3 is implied when BYTES is not specified\n\
+1
> -t, --format=TYPE select output format or formats\n\
> -v, --output-duplicates do not use * to mark line suppression\n\
> - -w[BYTES], --width[=BYTES] output BYTES bytes per output line.\n\
> + -w[BYTES], --width[=BYTES] output BYTES bytes per output line;\n\
> 32 is implied when BYTES is not specified\n\
+1
> --traditional accept arguments in third form above\n\
> "), stdout);
> diff --git a/src/ptx.c b/src/ptx.c
> index f993673..49ea7a3 100644
> --- a/src/ptx.c
> +++ b/src/ptx.c
> @@ -1853,7 +1853,7 @@ Output a permuted index, including context, of the words in the input files.\n\
> fputs (VERSION_OPTION_DESCRIPTION, stdout);
> fputs (_("\
> \n\
> -With no FILE or if FILE is -, read Standard Input. '-F /' by default.\n\
> +With no FILE, or when FILE is -, read standard input. Default is '-F /'.\n\
+1
> "), stdout);
> emit_ancillary_info ();
> }
> diff --git a/src/setuidgid.c b/src/setuidgid.c
> index ed6b65d..4a72a15 100644
> --- a/src/setuidgid.c
> +++ b/src/setuidgid.c
> @@ -63,7 +63,7 @@ This program is useful only when run by root (user ID zero).\n\
> "), stdout);
> fputs (_("\
> -g GID[,GID1...] also set the primary group-ID to the numeric GID, and\n\
> - (if specified) supplemental group IDs to GID1, ...\n\
> + (if specified) supplemental group IDs to GID1, ...\n\
+1
> "), stdout);
> fputs (HELP_OPTION_DESCRIPTION, stdout);
> fputs (VERSION_OPTION_DESCRIPTION, stdout);
> diff --git a/src/split.c b/src/split.c
> index feabe39..f740652 100644
> --- a/src/split.c
> +++ b/src/split.c
> @@ -215,15 +215,15 @@ is -, read standard input.\n\
>
> fprintf (stdout, _("\
> -a, --suffix-length=N generate suffixes of length N (default %d)\n\
> - --additional-suffix=SUFFIX append an additional SUFFIX to file names.\n\
> + --additional-suffix=SUFFIX append an additional SUFFIX to file names\n\
+1
> -b, --bytes=SIZE put SIZE bytes per output file\n\
> -C, --line-bytes=SIZE put at most SIZE bytes of lines per output file\n\
> - -d, --numeric-suffixes[=FROM] use numeric suffixes instead of alphabetic.\n\
> - FROM changes the start value (default 0).\n\
> + -d, --numeric-suffixes[=FROM] use numeric suffixes instead of alphabetic;\n\
> + FROM changes the start value (default 0)\n\
+1
> -e, --elide-empty-files do not generate empty output files with '-n'\n\
> --filter=COMMAND write to shell COMMAND; file name is $FILE\n\
> -l, --lines=NUMBER put NUMBER lines per output file\n\
> - -n, --number=CHUNKS generate CHUNKS output files. See below\n\
> + -n, --number=CHUNKS generate CHUNKS output files; see explanation below\n\
+1
> -u, --unbuffered immediately copy input to output with '-n r/...'\n\
> "), DEFAULT_SUFFIX_LENGTH);
> fputs (_("\
> diff --git a/src/stat.c b/src/stat.c
> index 0a6497b..ce0aec8 100644
> --- a/src/stat.c
> +++ b/src/stat.c
> @@ -1368,8 +1368,8 @@ Display file or file system status.\n\
> -c --format=FORMAT use the specified FORMAT instead of the default;\n\
> output a newline after each use of FORMAT\n\
> --printf=FORMAT like --format, but interpret backslash escapes,\n\
> - and do not output a mandatory trailing newline.\n\
> - If you want a newline, include \\n in FORMAT\n\
> + and do not output a mandatory trailing newline;\n\
> + if you want a newline, include \\n in FORMAT\n\
+1
> -t, --terse print the information in terse form\n\
> "), stdout);
> fputs (HELP_OPTION_DESCRIPTION, stdout);
> diff --git a/src/tail.c b/src/tail.c
> index 0f1a37c..e3d8b40 100644
> --- a/src/tail.c
> +++ b/src/tail.c
> @@ -269,24 +269,23 @@ With no FILE, or when FILE is -, read standard input.\n\
>
> fputs (_("\
> -c, --bytes=K output the last K bytes; alternatively, use -c +K\n\
> - to output bytes starting with the Kth of each file\n\
> + to output bytes starting with the Kth of each file\n\
+1
> "), stdout);
> fputs (_("\
> -f, --follow[={name|descriptor}]\n\
> output appended data as the file grows;\n\
> - -f, --follow, and --follow=descriptor are\n\
> - equivalent\n\
> + --follow equals --follow=descriptor\n\
+1
> -F same as --follow=name --retry\n\
> "), stdout);
> printf (_("\
> -n, --lines=K output the last K lines, instead of the last %d;\n\
> - or use -n +K to output lines starting with the Kth\n\
> + or use -n +K to output lines starting with the Kth\n\
+1
> --max-unchanged-stats=N\n\
> with --follow=name, reopen a FILE which has not\n\
> - changed size after N (default %d) iterations\n\
> - to see if it has been unlinked or renamed\n\
> - (this is the usual case of rotated log files).\n\
> - With inotify, this option is rarely useful.\n\
> + changed size after N (default %d) iterations\n\
> + to see if it has been unlinked or renamed\n\
> + (this is the usual case of rotated log files);\n\
> + with inotify, this option is rarely useful\n\
+1
> "),
> DEFAULT_N_LINES,
> DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS
> @@ -298,9 +297,9 @@ With no FILE, or when FILE is -, read standard input.\n\
> "), stdout);
> fputs (_("\
> -s, --sleep-interval=N with -f, sleep for approximately N seconds\n\
> - (default 1.0) between iterations.\n\
> - With inotify and --pid=P, check process P at\n\
> - least once every N seconds.\n\
> + (default 1.0) between iterations;\n\
> + with inotify and --pid=P, check process P at\n\
> + least once every N seconds\n\
+1
> -v, --verbose always output headers giving file names\n\
> "), stdout);
> fputs (HELP_OPTION_DESCRIPTION, stdout);
> diff --git a/src/timeout.c b/src/timeout.c
> index 2ffd2b1..a121540 100644
> --- a/src/timeout.c
> +++ b/src/timeout.c
> @@ -235,18 +235,18 @@ Start COMMAND, and kill it if still running after DURATION.\n\
> fputs (_("\
> --preserve-status\n\
> exit with the same status as COMMAND, even when the\n\
> - command times out\n\
> + command times out\n\
+1 Given the length of the --long-options-which-delimit each entry,
the identation doesn't improve readability here, but it's good to be consistent.
> --foreground\n\
> - When not running timeout directly from a shell prompt,\n\
> - allow COMMAND to read from the TTY and receive TTY signals.\n\
> - In this mode, children of COMMAND will not be timed out.\n\
> + when not running timeout directly from a shell prompt,\n\
> + allow COMMAND to read from the TTY and receive TTY signals;\n\
> + in this mode, children of COMMAND will not be timed out\n\
+1
> -k, --kill-after=DURATION\n\
> also send a KILL signal if COMMAND is still running\n\
> - this long after the initial signal was sent.\n\
> + this long after the initial signal was sent\n\
+1
> -s, --signal=SIGNAL\n\
> - specify the signal to be sent on timeout.\n\
> - SIGNAL may be a name like 'HUP' or a number.\n\
> - See 'kill -l' for a list of signals\n"), stdout);
> + specify the signal to be sent on timeout;\n\
> + SIGNAL may be a name like 'HUP' or a number;\n\
> + see 'kill -l' for a list of signals\n"), stdout);
+1
thanks!
Pádraig.
bug-coreutils <at> gnu.org:bug#14976; Package coreutils.
(Thu, 01 Aug 2013 13:44:02 GMT) Full text and rfc822 format available.Message #11 received at 14976 <at> debbugs.gnu.org (full text, mbox):
From: Pádraig Brady <P <at> draigBrady.com> To: Benno Schulenberg <bensberg <at> justemail.net> Cc: 14976 <at> debbugs.gnu.org Subject: Re: bug#14976: [patch] use semicolons in option descriptions, not periods Date: Thu, 01 Aug 2013 14:43:47 +0100
On 07/29/2013 06:02 PM, Pádraig Brady wrote: > On 07/28/2013 08:27 PM, Benno Schulenberg wrote: >> Hi, >> >> 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. >> >> Regards, >> >> Benno Pushed with those adjustments and some more to keep lines < 80 chars. thanks! Pádraig
bug-coreutils <at> gnu.org:bug#14976; Package coreutils.
(Thu, 01 Aug 2013 19:57:01 GMT) Full text and rfc822 format available.Message #14 received at 14976 <at> debbugs.gnu.org (full text, mbox):
From: Benno Schulenberg <bensberg <at> justemail.net> To: Pádraig Brady <P <at> draigBrady.com> Cc: 14976 <at> debbugs.gnu.org Subject: Re: 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-coreutils <at> gnu.org:bug#14976; Package coreutils.
(Fri, 02 Aug 2013 08:13:02 GMT) Full text and rfc822 format available.Message #17 received at 14976 <at> debbugs.gnu.org (full text, mbox):
From: Pádraig Brady <P <at> draigBrady.com> To: Benno Schulenberg <bensberg <at> justemail.net> Cc: 14976 <at> debbugs.gnu.org Subject: Re: bug#14976: [patch] use semicolons in option descriptions, not periods Date: Fri, 02 Aug 2013 09:11:58 +0100
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.
bug-coreutils <at> gnu.org:bug#14976; Package coreutils.
(Sat, 03 Aug 2013 10:34:02 GMT) Full text and rfc822 format available.Message #20 received at 14976 <at> debbugs.gnu.org (full text, mbox):
From: Benno Schulenberg <bensberg <at> justemail.net> To: Pádraig Brady <P <at> draigBrady.com> Cc: 14976 <at> debbugs.gnu.org Subject: Re: bug#14976: [patch] use semicolons in option descriptions, not periods Date: Sat, 03 Aug 2013 12:33:01 +0200
[Message part 1 (text/plain, inline)]
Hello Pádraig, On Fri, Aug 2, 2013, at 10:11, Pádraig Brady wrote: > On 08/01/2013 08:56 PM, Benno Schulenberg wrote: > > 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" True. But as the phrases all describe aspects of the same option, there is in my opinion always some relationship between them, which could be expressed with "where" or "however" or something. Attached patch does some more semicolon substitutions, of periods I overlooked the first time. It also does more indentation adjustments, and adds some parentheses around equivalent short options for clarity. It also removes the phrase "and do not dereference symbolic links" from the 'ls -d' option, because 1) to be correct it would have to add "unless -H or -L etcera", but such precision is something for the manual; 2) the phrase is not given for -F nor -l either, for which it is also valid. Regards, Benno -- http://www.fastmail.fm - The way an email service should be
[0001-doc-more-semicolons-instead-of-periods-in-option-des.patch (text/x-patch, attachment)]
bug-coreutils <at> gnu.org:bug#14976; Package coreutils.
(Sat, 03 Aug 2013 16:09:02 GMT) Full text and rfc822 format available.Message #23 received at 14976 <at> debbugs.gnu.org (full text, mbox):
From: Pádraig Brady <P <at> draigBrady.com> To: Benno Schulenberg <bensberg <at> justemail.net> Cc: 14976 <at> debbugs.gnu.org Subject: Re: bug#14976: [patch] use semicolons in option descriptions, not periods Date: Sat, 03 Aug 2013 17:08:41 +0100
On 08/03/2013 11:33 AM, Benno Schulenberg wrote:
>
> Hello Pádraig,
>
> On Fri, Aug 2, 2013, at 10:11, Pádraig Brady wrote:
>> On 08/01/2013 08:56 PM, Benno Schulenberg wrote:
>>> 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"
>
> True. But as the phrases all describe aspects of the same option,
> there is in my opinion always some relationship between them,
> which could be expressed with "where" or "however" or something.
>
> Attached patch does some more semicolon substitutions, of periods
> I overlooked the first time. It also does more indentation adjustments,
> and adds some parentheses around equivalent short options for clarity.
All that looks good.
> It also removes the phrase "and do not dereference symbolic links" from
> the 'ls -d' option, because 1) to be correct it would have to add "unless
> -H or -L etcera", but such precision is something for the manual; 2) the
> phrase is not given for -F nor -l either, for which it is also valid.
So the change is:
- -d, --directory list directory entries instead of contents,
- and do not dereference symbolic links
+ -d, --directory list just names of directories, not their contents
So I was wondering why that clarification was added.
I guess that it's obvious from the output for -l and -F
that the symlink is being operated on:
$ ls -iF lsrc
4202161 lsrc@
$ ls -il lsrc
4202161 lrwxrwxrwx. 1 ... lsrc -> src
whereas with -d it's not:
$ ls -id lsrc
4202161 lsrc
Also I don't like the "just names" in the new description as
it might imply that it overrides -l or something.
So I was thinking instead to change to:
-d, --directory list directory entries instead of contents,
- and do not dereference symbolic links
+ and by default do not dereference symlinks
thanks!
Pádraig.
bug-coreutils <at> gnu.org:bug#14976; Package coreutils.
(Sun, 04 Aug 2013 09:13:02 GMT) Full text and rfc822 format available.Message #26 received at 14976 <at> debbugs.gnu.org (full text, mbox):
From: Benno Schulenberg <bensberg <at> justemail.net> To: Pádraig Brady <P <at> draigBrady.com> Cc: 14976 <at> debbugs.gnu.org Subject: Re: bug#14976: [patch] use semicolons in option descriptions, not periods Date: Sun, 04 Aug 2013 11:12:32 +0200
Hello Pádraig,
On Sat, Aug 3, 2013, at 18:08, Pádraig Brady wrote:
> - -d, --directory list directory entries instead of contents,
> - and do not dereference symbolic links
> + -d, --directory list just names of directories, not their contents
>
> So I was wondering why that clarification was added.
> I guess that it's obvious from the output for -l and -F
> that the symlink is being operated on: [...]
> whereas with -d it's not: [...]
Okay, I see. Although I still think it's an unneeded detail in a
help text, the addition of "by default" makes it better.
> Also I don't like the "just names" in the new description as
> it might imply that it overrides -l or something.
Well, the phrase was taken from the info documentation, where it says:
"List just the names of directories, [...] rather than listing their
contents." :) But I see your point.
The thing is, I have to read the phrase three times before I realize
that "directory entries" does not mean "entries OF directories" but
"entries that ARE directories". The problematic word is "entries",
which makes me think of "items in a container", whereas in fact it
refers to "items on the command line", which requires some stretch
of the imagination.
So I propose the following change:
- -d, --directory list directory entries instead of contents,
+ -d, --directory list directories themselves, not their contents,
(Oh, by the way, when you modify a patch, please make a note of this
in the log message -- I don't like to see changes that I would never
have made booked without further ado under my name.)
For the tail --follow thingy I have the following suggestion:
- -f and --follow[=descriptor] are equivalent\n\
+ an absent option argument means 'descriptor'\n\
Regards,
Benno
--
http://www.fastmail.fm - Or how I learned to stop worrying and
love email again
bug-coreutils <at> gnu.org:bug#14976; Package coreutils.
(Sun, 04 Aug 2013 10:55:01 GMT) Full text and rfc822 format available.Message #29 received at 14976 <at> debbugs.gnu.org (full text, mbox):
From: Pádraig Brady <P <at> draigBrady.com> To: Benno Schulenberg <bensberg <at> justemail.net> Cc: 14976 <at> debbugs.gnu.org Subject: Re: bug#14976: [patch] use semicolons in option descriptions, not periods Date: Sun, 04 Aug 2013 11:54:42 +0100
On 08/04/2013 10:12 AM, Benno Schulenberg wrote: > > Hello Pádraig, > > On Sat, Aug 3, 2013, at 18:08, Pádraig Brady wrote: >> - -d, --directory list directory entries instead of contents, >> - and do not dereference symbolic links >> + -d, --directory list just names of directories, not their contents >> >> So I was wondering why that clarification was added. >> I guess that it's obvious from the output for -l and -F >> that the symlink is being operated on: [...] >> whereas with -d it's not: [...] > > Okay, I see. Although I still think it's an unneeded detail in a > help text, the addition of "by default" makes it better. > >> Also I don't like the "just names" in the new description as >> it might imply that it overrides -l or something. > > Well, the phrase was taken from the info documentation, where it says: > "List just the names of directories, [...] rather than listing their > contents." :) But I see your point. > > The thing is, I have to read the phrase three times before I realize > that "directory entries" does not mean "entries OF directories" but > "entries that ARE directories". The problematic word is "entries", > which makes me think of "items in a container", whereas in fact it > refers to "items on the command line", which requires some stretch > of the imagination. > > So I propose the following change: > > - -d, --directory list directory entries instead of contents, > + -d, --directory list directories themselves, not their contents, better thanks. > (Oh, by the way, when you modify a patch, please make a note of this > in the log message -- I don't like to see changes that I would never > have made booked without further ado under my name.) > > For the tail --follow thingy I have the following suggestion: > > - -f and --follow[=descriptor] are equivalent\n\ > + an absent option argument means 'descriptor'\n\ Fair enough. My thinking was for patches like these I'd like to minimize the number of commits, whilst in this case I assumed the change wouldn't be controversial. I'll merge this adjustment into to current patch if that's OK with you? thanks, Pádraig.
Pádraig Brady <P <at> draigBrady.com>:Benno Schulenberg <bensberg <at> justemail.net>:Message #34 received at 14976-done <at> debbugs.gnu.org (full text, mbox):
From: Pádraig Brady <P <at> draigBrady.com> To: Benno Schulenberg <bensberg <at> justemail.net> Cc: 14976-done <at> debbugs.gnu.org Subject: Re: bug#14976: [patch] use semicolons in option descriptions, not periods Date: Sun, 04 Aug 2013 12:28:20 +0100
[Message part 1 (text/plain, inline)]
On 08/04/2013 10:12 AM, Benno Schulenberg wrote: > > Hello Pádraig, > > On Sat, Aug 3, 2013, at 18:08, Pádraig Brady wrote: >> - -d, --directory list directory entries instead of contents, >> - and do not dereference symbolic links >> + -d, --directory list just names of directories, not their contents >> >> So I was wondering why that clarification was added. >> I guess that it's obvious from the output for -l and -F >> that the symlink is being operated on: [...] >> whereas with -d it's not: [...] > > Okay, I see. Although I still think it's an unneeded detail in a > help text, the addition of "by default" makes it better. In retrospect, given it is a bit of an esoteric case, and the ls man page is already too long, and the extra line introduces slightly awkward indentation, it is probably best to remove. >> Also I don't like the "just names" in the new description as >> it might imply that it overrides -l or something. > > Well, the phrase was taken from the info documentation, where it says: > "List just the names of directories, [...] rather than listing their > contents." :) But I see your point. > > The thing is, I have to read the phrase three times before I realize > that "directory entries" does not mean "entries OF directories" but > "entries that ARE directories". The problematic word is "entries", > which makes me think of "items in a container", whereas in fact it > refers to "items on the command line", which requires some stretch > of the imagination. > > So I propose the following change: > > - -d, --directory list directory entries instead of contents, > + -d, --directory list directories themselves, not their contents, > > > (Oh, by the way, when you modify a patch, please make a note of this > in the log message -- I don't like to see changes that I would never > have made booked without further ado under my name.) > > For the tail --follow thingy I have the following suggestion: > > - -f and --follow[=descriptor] are equivalent\n\ > + an absent option argument means 'descriptor'\n\ The latest patch is attached, with all the above discussed changes. I'll wait for confirmation before pushing. thanks, Pádraig.
[0001-doc-more-semicolons-instead-of-periods-in-option-des.patch (text/x-patch, attachment)]
bug-coreutils <at> gnu.org:bug#14976; Package coreutils.
(Sun, 04 Aug 2013 15:41:01 GMT) Full text and rfc822 format available.Message #37 received at 14976 <at> debbugs.gnu.org (full text, mbox):
From: Bernhard Voelker <mail <at> bernhard-voelker.de> To: 14976 <at> debbugs.gnu.org, P <at> draigBrady.com, bensberg <at> justemail.net Subject: Re: bug#14976: [patch] use semicolons in option descriptions, not periods Date: Sun, 04 Aug 2013 17:40:07 +0200
On 08/04/2013 01:28 PM, Pádraig Brady wrote:
> The latest patch is attached,
diff --git a/src/du.c b/src/du.c
index b8aba0b..a265b10 100644
--- a/src/du.c
+++ b/src/du.c
@@ -338,9 +338,9 @@ Summarize disk usage of each FILE, recursively for directories.\n\
directory, or any of its subdirectories\n\
--time=WORD show time as WORD instead of modification time:\n\
atime, access, use, ctime or status\n\
- --time-style=STYLE show times using style STYLE:\n\
- full-iso, long-iso, iso, +FORMAT\n\
- FORMAT is interpreted like 'date'\n\
+ --time-style=STYLE show times using STYLE, which can be:\n\
+ full-iso, long-iso, iso, or +FORMAT;\n\
+ FORMAT is interpreted like in 'date'\n\
I'd say:
s/can be/is one of/
or
s/can be/must be/
because "can be" sounds somehow optional (to me at least).
Otherwise: +1
Have a nice day,
Berny
bug-coreutils <at> gnu.org:bug#14976; Package coreutils.
(Sun, 04 Aug 2013 19:52:02 GMT) Full text and rfc822 format available.Message #40 received at 14976-done <at> debbugs.gnu.org (full text, mbox):
From: Benno Schulenberg <bensberg <at> justemail.net> To: Pádraig Brady <P <at> draigBrady.com> Cc: 14976-done <at> debbugs.gnu.org Subject: Re: bug#14976: [patch] use semicolons in option descriptions, not periods Date: Sun, 04 Aug 2013 21:51:18 +0200
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.
Regards,
Benno
--
http://www.fastmail.fm - Accessible with your email software
or over the web
bug-coreutils <at> gnu.org:bug#14976; Package coreutils.
(Sun, 04 Aug 2013 20:29:02 GMT) Full text and rfc822 format available.Message #43 received at 14976 <at> debbugs.gnu.org (full text, mbox):
From: Pádraig Brady <P <at> draigBrady.com> To: Benno Schulenberg <bensberg <at> justemail.net> Cc: 14976 <at> debbugs.gnu.org Subject: Re: bug#14976: [patch] use semicolons in option descriptions, not periods Date: Sun, 04 Aug 2013 21:28:03 +0100
[Message part 1 (text/plain, inline)]
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 (text/x-patch, attachment)]
bug-coreutils <at> gnu.org:bug#14976; Package coreutils.
(Sun, 04 Aug 2013 21:02:03 GMT) Full text and rfc822 format available.Message #46 received at 14976 <at> debbugs.gnu.org (full text, mbox):
From: Benno Schulenberg <bensberg <at> justemail.net> To: Pádraig Brady <P <at> draigBrady.com> Cc: 14976 <at> debbugs.gnu.org Subject: Re: bug#14976: [patch] use semicolons in option descriptions, not periods Date: Sun, 04 Aug 2013 23:01:20 +0200
On Sun, Aug 4, 2013, at 22:28, Pádraig Brady wrote: > 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\ Hmmm... I don't like that. The "themselves" in my mind already expresses that this phrase is relevant only for directories. Also, saying "list themselves" is very strange usage, in my opinion. > Also with your changes, we've gone over 80 chars per line in various places. I don't think so -- I took care never to exceed 80 printing chars per line. Only when also counting the non-printing "\n\" are some lines too long. So... I would prefer not to do this realignment. Regards, Benno -- http://www.fastmail.fm - Send your email first class
bug-coreutils <at> gnu.org:bug#14976; Package coreutils.
(Mon, 05 Aug 2013 00:10:02 GMT) Full text and rfc822 format available.Message #49 received at 14976 <at> debbugs.gnu.org (full text, mbox):
From: Pádraig Brady <P <at> draigBrady.com> To: Benno Schulenberg <bensberg <at> justemail.net> Cc: 14976 <at> debbugs.gnu.org Subject: Re: bug#14976: [patch] use semicolons in option descriptions, not periods Date: Mon, 05 Aug 2013 01:09:28 +0100
On 08/04/2013 10:01 PM, Benno Schulenberg wrote: > > On Sun, Aug 4, 2013, at 22:28, Pádraig Brady wrote: >> 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\ > > Hmmm... I don't like that. The "themselves" in my mind already expresses > that this phrase is relevant only for directories. My point was that it might be interpreted to also mean, excluding non directories. > Also, saying "list themselves" > is very strange usage, in my opinion. OK we'll leave as is >> Also with your changes, we've gone over 80 chars per line in various places. > > I don't think so -- I took care never to exceed 80 printing chars per line. > Only when also counting the non-printing "\n\" are some lines too long. > So... I would prefer not to do this realignment. OK I've adjusted the code to be < 80 chars. Output is unaffected. pushed, thanks, Pádraig.
Debbugs Internal Request <help-debbugs <at> gnu.org>
to internal_control <at> debbugs.gnu.org.
(Mon, 02 Sep 2013 11:24:06 GMT) Full text and rfc822 format available.
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.