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