On 03/12/17 08:12, Jean Delvare wrote:
> Hi Pádraig,
>
> On Sat, 2 Dec 2017 16:37:02 -0800, Pádraig Brady wrote:
>> On 01/12/17 02:26, Jean Delvare wrote:
>>> Users may expect a different effect from option -k than is actually
>>> implemented, especially when the effect of that option has changed
>>> over time. The info page explains it well, but "ls --help" (and thus
>>> the ls.1 man page) do not.
>>>
>>> * src/ls.c: Improve the description of option -k.
>>> ---
>>> src/ls.c | 10 +++++++++-
>>> 1 file changed, 9 insertions(+), 1 deletion(-)
>>>
>>> --- coreutils.orig/src/ls.c 2017-12-01 10:14:46.297551197 +0100
>>> +++ coreutils/src/ls.c 2017-12-01 10:45:17.298050350 +0100
>>> @@ -5203,7 +5203,15 @@ Sort entries alphabetically if none of -
>>> -i, --inode print the index number of each file\n\
>>> -I, --ignore=PATTERN do not list implied entries matching shell
>>> PATTERN\
>>> \n\
>>> - -k, --kibibytes default to 1024-byte blocks for disk usage\n\
>>> +"), stdout);
>>> + fputs (_("\
>>> + -k, --kibibytes default to 1024-byte blocks for disk usage;\n\
>>> + affects the per-directory block count
>>> written by\
>>> +\n\
>>> + -l and -s, and the size written by -s, but
>>> not\
>>> +\n\
>>> + the file size written by -l (use\n\
>>> + '--block-size=1024' for that)\n\
>>> "), stdout);
>>> fputs (_("\
>>> -l use a long listing format\n\
>>>
>>>
>>
>>
>> Way too verbose.
>
> And you didn't see my first attempt, which was even longer ;-) I
> expected some conciseness was desirable.
>
> That being said... "too verbose" according to what?
Well brevity is much appreciated
as indicated by efforts such as https://tldr.sh/
> The description of
> --time-style is longer that than, and those of -c, --time and
> --quoting-style come close.
Indeed. The attached reorganizes --time-style too.
cheers,
Pádraig
From b697bac049dd10db486dea9148ce4b2251147cd4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email protected]>
Date: Sat, 2 Dec 2017 16:56:50 -0800
Subject: [PATCH] doc: reorganize ls -k and --time-style help
* src/ls.c (usage): Clarify -k only applies to -s usage
and directory 'total' lines. Move the description
of TIME_STYLE out of the option section as it was awkward
to read and write there within 80 columns.
---
src/ls.c | 36 ++++++++++++++++++++----------------
1 file changed, 20 insertions(+), 16 deletions(-)
diff --git a/src/ls.c b/src/ls.c
index 073e135..4becd06 100644
--- a/src/ls.c
+++ b/src/ls.c
@@ -5140,9 +5140,10 @@ 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=M' prints sizes in units of\n\
- 1,048,576 bytes; see SIZE format below\n\
+ --block-size=SIZE with -l, scale sizes by SIZE when printing them;\n\
+ e.g., '--block-size=M'; see SIZE format below\n\
+"), stdout);
+ fputs (_("\
-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\
@@ -5177,8 +5178,9 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
"), stdout);
fputs (_("\
-G, --no-group in a long listing, don't print group names\n\
- -h, --human-readable with -l and/or -s, print human readable sizes\n\
- (e.g., 1K 234M 2G)\n\
+"), stdout);
+ fputs (_("\
+ -h, --human-readable with -l and -s, print sizes like 1K 234M 2G etc.\n\
--si likewise, but use powers of 1000 not 1024\n\
"), stdout);
fputs (_("\
@@ -5203,7 +5205,10 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\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 default to 1024-byte blocks for disk usage\n\
+"), stdout);
+ fputs (_("\
+ -k, --kibibytes default to 1024-byte blocks for disk usage;\n\
+ used only with -s and per directory totals\n\
"), stdout);
fputs (_("\
-l use a long listing format\n\
@@ -5248,16 +5253,7 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
as sort key if --sort=time (newest first)\n\
"), stdout);
fputs (_("\
- --time-style=STYLE 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\
+ --time-style=TIME_STYLE time/date format with -l; see TIME_STYLE below\n\
"), stdout);
fputs (_("\
-t sort by modification time, newest first\n\
@@ -5283,6 +5279,14 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
emit_size_note ();
fputs (_("\
\n\
+The TIME_STYLE argument can be full-iso, long-iso, iso, locale, or +FORMAT.\n\
+FORMAT is interpreted like in date(1). If FORMAT is FORMAT1<newline>FORMAT2,\n\
+then FORMAT1 applies to non-recent files and FORMAT2 to recent files.\n\
+TIME_STYLE prefixed with 'posix-' takes effect only outside the POSIX locale.\n\
+Also the TIME_STYLE environment variable sets the default style to use.\n\
+"), stdout);
+ fputs (_("\
+\n\
Using color to distinguish file types is disabled both by default and\n\
with --color=never. With --color=auto, ls emits color codes only when\n\
standard output is connected to a terminal. The LS_COLORS environment\n\
--
2.9.3
