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.
>From 1805ed8091cc594a89a06149091f702343456901 Mon Sep 17 00:00:00 2001 From: Benno Schulenberg <[email protected]> Date: Sat, 3 Aug 2013 10:38:12 +0200 Subject: [PATCH] doc: more semicolons instead of periods in option descriptions Also slightly rephrase some descriptions for extra clarity, and add more consistent indentation. * src/df.c (usage): Semicolon, no final period. * src/du.c (usage): Likewise, plus indentation and clarifying words. * src/ls.c (usage): Semicolon, rephrasings, added parentheses for clarity, indentation, realignment. * src/rm.c (usage): Semicolons. * src/tail.c (usage): Adjust -f description to prefer explanatory language instead of option syntax. --- src/df.c | 6 +- src/du.c | 12 ++-- src/ls.c | 186 ++++++++++++++++++++++++++++++------------------------------ src/rm.c | 4 +- src/tail.c | 2 +- 5 files changed, 104 insertions(+), 106 deletions(-) diff --git a/src/df.c b/src/df.c index e018064..c2c390e 100644 --- a/src/df.c +++ b/src/df.c @@ -1233,9 +1233,9 @@ or all file systems by default.\n\ fputs (_("\ -a, --all include dummy file systems\n\ - -B, --block-size=SIZE scale sizes by SIZE before printing them. E.g.,\n\ - '-BM' prints sizes in units of 1,048,576 bytes.\n\ - See SIZE format below.\n\ + -B, --block-size=SIZE scale sizes by SIZE before printing them; e.g.,\n\ + '-BM' prints sizes in units of 1,048,576 bytes;\n\ + see SIZE format below\n\ --total produce a grand total\n\ -h, --human-readable print sizes in human readable format (e.g., 1K 234M 2G)\ \n\ diff --git a/src/du.c b/src/du.c index b8aba0b..a265b10 100644 --- a/src/du.c +++ b/src/du.c @@ -298,9 +298,9 @@ Summarize disk usage of each FILE, recursively for directories.\n\ fragmentation, indirect blocks, and the like\n\ "), stdout); fputs (_("\ - -B, --block-size=SIZE scale sizes by SIZE before printing them. E.g.,\n\ - '-BM' prints sizes in units of 1,048,576 bytes.\n\ - See SIZE format below.\n\ + -B, --block-size=SIZE scale sizes by SIZE before printing them; e.g.,\n\ + '-BM' prints sizes in units of 1,048,576 bytes;\n\ + see SIZE format below\n\ -b, --bytes equivalent to '--apparent-size --block-size=1'\n\ -c, --total produce a grand total\n\ -D, --dereference-args dereference only symlinks that are listed on the\n\ @@ -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\ "), stdout); fputs (_("\ -X, --exclude-from=FILE exclude files that match any pattern in FILE\n\ diff --git a/src/ls.c b/src/ls.c index f3c3a1b..51b5a15 100644 --- a/src/ls.c +++ b/src/ls.c @@ -4752,138 +4752,136 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\ emit_mandatory_arg_note (); fputs (_("\ - -a, --all do not ignore entries starting with .\n\ - -A, --almost-all do not list implied . and ..\n\ - --author with -l, print the author of each file\n\ - -b, --escape print C-style escapes for nongraphic characters\n\ + -a, --all do not ignore entries starting with .\n\ + -A, --almost-all do not list implied . and ..\n\ + --author with -l, print the author of each file\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=M' prints sizes in units of\n\ - 1,048,576 bytes; see SIZE format below\n\ - -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\ - otherwise: sort by ctime, newest first\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\ + -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\ + 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\ - -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\ + -C list entries by columns\n\ + --color[=WHEN] colorize the output; WHEN can be 'never', 'auto',\n\ + or 'always' (the default); more info below\n\ + -d, --directory for directories, list themselves, not their contents\n\ + -D, --dired generate output designed for Emacs' dired mode\n\ "), stdout); fputs (_("\ - -f do not sort, enable -aU, disable -ls --color\n\ - -F, --classify append indicator (one of */=>@|) to entries\n\ - --file-type likewise, except do not append '*'\n\ - --format=WORD across -x, commas -m, horizontal -x, long -l,\n\ - single-column -1, verbose -l, vertical -C\n\ - --full-time like -l --time-style=full-iso\n\ + -f do not sort, enable -aU, disable -ls --color\n\ + -F, --classify append indicator (one of */=>@|) to entries\n\ + --file-type likewise, except do not append '*'\n\ + --format=WORD across -x, commas -m, horizontal -x, long -l,\n\ + single-column -1, verbose -l, vertical -C\n\ + --full-time like -l --time-style=full-iso\n\ "), stdout); fputs (_("\ - -g like -l, but do not list owner\n\ + -g like -l, but do not list owner\n\ "), stdout); fputs (_("\ --group-directories-first\n\ - group directories before files;\n\ - can be augmented with a --sort option, but any\n\ - use of --sort=none (-U) disables grouping\n\ + group directories before files;\n\ + can be augmented with a --sort option, but any\n\ + use of --sort=none (-U) disables grouping\n\ "), stdout); fputs (_("\ - -G, --no-group in a long listing, don't print group names\n\ - -h, --human-readable with -l, print sizes in human readable format\n\ - (e.g., 1K 234M 2G)\n\ - --si likewise, but use powers of 1000 not 1024\n\ + -G, --no-group in a long listing, don't print group names\n\ + -h, --human-readable with -l, print sizes in human readable format\n\ + (e.g., 1K 234M 2G)\n\ + --si likewise, but use powers of 1000 not 1024\n\ "), stdout); fputs (_("\ -H, --dereference-command-line\n\ - follow symbolic links listed on the command line\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\ - --hide=PATTERN do not list implied entries matching shell PATTERN\ -\n\ - (overridden by -a or -A)\n\ + follow each command line symbolic link\n\ + that points to a directory\n\ + --hide=PATTERN do not list implied entries matching shell PATTERN\n\ + (overridden by -a or -A)\n\ "), stdout); fputs (_("\ - --indicator-style=WORD append indicator with style WORD to entry names:\ -\n\ - none (default), slash (-p),\n\ - file-type (--file-type), classify (-F)\n\ - -i, --inode print the index number of each file\n\ - -I, --ignore=PATTERN do not list implied entries matching shell PATTERN\ -\n\ - -k, --kibibytes use 1024-byte blocks\n\ + --indicator-style=WORD\n\ + append indicator with style WORD to entry names:\n\ + none (default), slash (-p),\n\ + file-type (--file-type), classify (-F)\n\ + -i, --inode print the index number of each file\n\ + -I, --ignore=PATTERN do not list implied entries matching shell PATTERN\n\ + -k, --kibibytes use 1024-byte blocks\n\ "), stdout); fputs (_("\ - -l use a long listing format\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\ -\n\ + -l use a long listing format\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\n\ "), stdout); fputs (_("\ - -n, --numeric-uid-gid like -l, but list numeric user and group IDs\n\ - -N, --literal print raw entry names (don't treat e.g. control\n\ - characters specially)\n\ - -o like -l, but do not list group information\n\ + -n, --numeric-uid-gid like -l, but list numeric user and group IDs\n\ + -N, --literal print raw entry names (don't treat e.g. control\n\ + characters specially)\n\ + -o like -l, but do not list group information\n\ -p, --indicator-style=slash\n\ - append / indicator to directories\n\ + append / indicator to directories\n\ "), stdout); fputs (_("\ - -q, --hide-control-chars print ? instead of non-graphic characters\n\ - --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\ - --quoting-style=WORD use quoting style WORD for entry names:\n\ - literal, locale, shell, shell-always, c, escape\ -\n\ + -q, --hide-control-chars\n\ + print ? instead of nongraphic characters\n\ + --show-control-chars\n\ + show nongraphic characters as-is (the default,\n\ + unless program is 'ls' and output is a terminal)\n\ + -Q, --quote-name enclose entry names in double quotes\n\ + --quoting-style=WORD\n\ + use quoting style WORD for entry names:\n\ + literal, locale, shell, shell-always, c, escape\n\ "), stdout); fputs (_("\ - -r, --reverse reverse order while sorting\n\ - -R, --recursive list subdirectories recursively\n\ - -s, --size print the allocated size of each file, in blocks\n\ + -r, --reverse reverse order while sorting\n\ + -R, --recursive list subdirectories recursively\n\ + -s, --size print the allocated size of each file, in blocks\n\ "), stdout); fputs (_("\ - -S sort by file size\n\ - --sort=WORD sort by WORD instead of name: none -U,\n\ - extension -X, size -S, time -t, version -v\n\ - --time=WORD with -l, show time as WORD instead of modification\ -\n\ - time: atime -u, access -u, use -u, ctime -c,\n\ - or status -c; use specified time as sort key\n\ - if --sort=time\n\ + -S sort by file size\n\ + --sort=WORD sort by WORD instead of name: none (-U), size (-S),\n\ + time (-t), version (-v), extension (-X)\n\ + --time=WORD with -l, show time as WORD instead of default\n\ + modification time: atime or access or use (-u)\n\ + ctime or status (-c); also use specified time\n\ + as sort key if --sort=time\n\ "), stdout); fputs (_("\ - --time-style=STYLE with -l, show times using style STYLE:\n\ - full-iso, long-iso, iso, locale, +FORMAT;\n\ - FORMAT is interpreted like 'date'; if FORMAT is\n\ - FORMAT1<newline>FORMAT2, then FORMAT1 applies to\n\ - 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\ + --time-style=STYLE\n\ + with -l, show times using style STYLE:\n\ + full-iso, long-iso, iso, locale, or +FORMAT;\n\ + FORMAT is interpreted like in 'date'; if FORMAT\n\ + is FORMAT1<newline>FORMAT2, then FORMAT1 applies\n\ + to 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\ "), stdout); fputs (_("\ - -t sort by modification time, newest first\n\ - -T, --tabsize=COLS assume tab stops at each COLS instead of 8\n\ + -t sort by modification time, newest first\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\ - 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\ + -u with -lt: sort by, and show, access time;\n\ + with -l: show access time and sort by name;\n\ + 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\ "), stdout); fputs (_("\ - -w, --width=COLS assume screen width instead of current value\n\ - -x list entries by lines instead of by columns\n\ - -X sort alphabetically by entry extension\n\ - -Z, --context print any SELinux security context of each file\n\ - -1 list one file per line\n\ + -w, --width=COLS assume screen width instead of current value\n\ + -x list entries by lines instead of by columns\n\ + -X sort alphabetically by entry extension\n\ + -Z, --context print any SELinux security context of each file\n\ + -1 list one file per line\n\ "), stdout); fputs (HELP_OPTION_DESCRIPTION, stdout); fputs (VERSION_OPTION_DESCRIPTION, stdout); diff --git a/src/rm.c b/src/rm.c index b9b84e1..4b87c12 100644 --- a/src/rm.c +++ b/src/rm.c @@ -141,10 +141,10 @@ Remove (unlink) the FILE(s).\n\ "), stdout); fputs (_("\ -I prompt once before removing more than three files, or\n\ - when removing recursively. Less intrusive than -i,\n\ + when removing recursively; less intrusive than -i,\n\ while still giving protection against most mistakes\n\ --interactive[=WHEN] prompt according to WHEN: never, once (-I), or\n\ - always (-i). Without WHEN, prompt always\n\ + always (-i); without WHEN, prompt always\n\ "), stdout); fputs (_("\ --one-file-system when removing a hierarchy recursively, skip any\n\ diff --git a/src/tail.c b/src/tail.c index 8389467..e7fefda 100644 --- a/src/tail.c +++ b/src/tail.c @@ -274,7 +274,7 @@ With no FILE, or when FILE is -, read standard input.\n\ fputs (_("\ -f, --follow[={name|descriptor}]\n\ output appended data as the file grows;\n\ - -f and --follow[=descriptor] are equivalent\n\ + an absent option argument means 'descriptor'\n\ -F same as --follow=name --retry\n\ "), stdout); printf (_("\ -- 1.7.7.6
