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.
>From 516e4123a3ce5bc34d0e495b17cccaa838f18324 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. * src/rm.c (usage): Semicolons. * src/tail.c (usage): Adjust -f description to prefer explanatory language intead of option syntax. --- src/df.c | 6 +++--- src/du.c | 12 ++++++------ src/ls.c | 38 ++++++++++++++++++-------------------- src/rm.c | 4 ++-- src/tail.c | 2 +- 5 files changed, 30 insertions(+), 32 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..a991390 100644 --- a/src/ls.c +++ b/src/ls.c @@ -4769,10 +4769,9 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\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\ + --color[=WHEN] colorize the output; WHEN can be 'never', 'auto',\n\ + or 'always' (the default); more info below\n\ + -d, --directory list directories themselves, not their contents\n\ -D, --dired generate output designed for Emacs' dired mode\n\ "), stdout); fputs (_("\ @@ -4835,9 +4834,9 @@ 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\ - --show-control-chars show non graphic characters as-is (default\n\ - unless program is 'ls' and output is a terminal)\n\ + -q, --hide-control-chars print ? instead of nongraphic characters\n\ + --show-control-chars 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 use quoting style WORD for entry names:\n\ literal, locale, shell, shell-always, c, escape\ @@ -4850,22 +4849,21 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\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\ + --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\ + 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\ 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
