GNU bug report logs - #9939
Problems with the SIZE description in man pages for <ls> and <du>

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 9939 in the body.
You can then email your comments to 9939 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: abdallah clark <clark-adc <at> clear.net>
To: bug-coreutils <at> gnu.org
Subject: Problems with the SIZE description in man pages for <ls> and <du>
Date: Wed, 2 Nov 2011 05:40:21 -0500

Dear Sirs and Ladies:

I am taking a course in Red Hat Enterprise Linux and have met with
some difficulty interpreting the following statement in the man pages
for several commands:

    SIZE may be (or may be an integer optionally followed by) one of
    following: KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on
    for G, T, P, E, Z, Y.

This is troublesome for several reasons. One, it is just too awkwardly
written to be understood on the first reading. Second, the units are
not
consistent with the ISO/SI units-- K and M are in units of 1000, not
1024, because they are part of the metric system, not the binary
system. There are other concerns as well, but if you could clarify the
statement itself, they should be eliminated.

Also, the statement "Mandatory arguments to long options are mandatory
for short options too." puzzles me, as I'm not sure what long or short
options are, nor whether they apply to <ls> and <du>.

I'm not sure if your definition of "bug" includes errors in the man
pages, but I do hope so.

I thank you in advance for your consideration.

            All the best to you and yours,

                      Abdallah Clark

Message #8 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: 9939 <at> debbugs.gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls> and <du>
Date: Wed, 02 Nov 2011 15:59:52 +0000

On 11/02/2011 10:40 AM, abdallah clark wrote:
> Dear Sirs and Ladies:
> 
> I am taking a course in Red Hat Enterprise Linux and have met with
> some difficulty interpreting the following statement in the man pages
> for several commands:
> 
>     SIZE may be (or may be an integer optionally followed by) one of
>     following: KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on
>     for G, T, P, E, Z, Y.
> 
> This is troublesome for several reasons. One, it is just too awkwardly
> written to be understood on the first reading.

That's fairly clear to me. It's trying to convey that SIZE may
be in the following forms:

1000
1KB
KB

How about:

SIZE may be an integer, a unit, or both, with the units being:
KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for
G, T, P, E, Z, Y.

Not much better really.

> Second, the units are not
> consistent with the ISO/SI units-- K and M are in units of 1000, not
> 1024, because they are part of the metric system, not the binary
> system.

Well we can't make that change for backwards compat reasons.

> There are other concerns as well, but if you could clarify the
> statement itself, they should be eliminated.
> 
> Also, the statement "Mandatory arguments to long options are mandatory
> for short options too." puzzles me, as I'm not sure what long or short
> options are, nor whether they apply to <ls> and <du>.

--long
-s -h -o -r -t

> I'm not sure if your definition of "bug" includes errors in the man
> pages, but I do hope so.

Yes it does.
Though generally documentation complaints
should come with suggested improvements.

cheers,
Pádraig.

Message #11 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: abdallah clark <clark-adc <at> clear.net>
Cc: 9939 <at> debbugs.gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls> and <du>
Date: Wed, 02 Nov 2011 09:01:32 -0700

On 11/02/11 03:40, abdallah clark wrote:

> the units are not
> consistent with the ISO/SI units-- K and M are in units of 1000, not
> 1024, because they are part of the metric system, not the binary
> system.

coreutils is supporting three notations here: SI-ish,
IEC 60027-2 / ISO/IEC 80000-13:2008, and traditional Unix.
So:

  MB means 1000*1000 bytes.  This is like SI, except SI doesn't have "B".
  MiB means 1024*1024 bytes.  This is IEC 60027-2 and ISO/IEC 80000-13:2008.
  M means MiB.  This is traditional Unix.

See <http://en.wikipedia.org/wiki/Binary_prefix> for more info.
(coreutils cannot use plain SI, since SI doesn't specify
an abbreviation for "byte".)

> it is just too awkwardly
> written to be understood on the first reading.

Suggestions for improved wording are welcome.  We'd like it to be
short, of course.
	
> Also, the statement "Mandatory arguments to long options are mandatory
> for short options too." puzzles me

Yes, I don't like that sentence either.  Suggestions for
improvement are welcome here, too.  Maybe we should just get
rid of it?  I expect it causes more confusion than it cures.

Message #14 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: abdallah clark <clark-adc <at> clear.net>
Cc: 9939 <at> debbugs.gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls> and <du>
Date: Wed, 02 Nov 2011 23:24:26 -0700

On 11/02/11 19:33, abdallah clark wrote:

> am I to be able to use <1000*1000> or <1024*1024> in
> either one of those commands?

Not those exact strings, no.  At least, not as far as I know.
But "MB" is short for 1000*1000, and "M" for 1024*1024.

> I saw that I could use other numerics,
> even odd amounts, but nothing with an implied evaluation as the
> description of SIZE starts off by saying.

Sorry, don't follow.  Perhaps an example would clarify?

> I can see no rhyme or reason why I get lowercase K, or KB or
> kB, etc. for the <ls> command, either.

Again, I'm lost.  Got a specific example?

> The same goes for the statement on mandatory options. Just what is a
> long option as compared to a short option?

A long option is something like --ignore='*.x'.
A short option is something like -I '*.x'.
Typically, for every short option there's an equivalent long
option, but the reverse is not necessarily true.

> How do I know what is
> mandatory from what isn't?

Optional arguments are written in square brackets in the
documentation, e.g., --color[=WHEN].  This isn't written
down in the man page, unfortunately.  It is described (not
all that well) in the full manual, here:

http://www.gnu.org/s/coreutils/manual/html_node/General-output-formatting.html#index-g_t_002d_002dcolor-791

Message #17 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: abdallah clark <clark-adc <at> clear.net>
To: 9939 <at> debbugs.gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls> and <du>
Date: Thu, 3 Nov 2011 12:51:56 -0500

Dear Paul,

Thanks and more thanks must begin my message. I never expected this
much support and encouragement. So much of what I have heard about
Linux and UNIX shops is that they're closed-up environment where techs
are not helpful and "you've got to pay your dues" is the daily mantra
for new hires. Refreshing to see that the general community is
generous. Thanks.

In particular, your explanation of long options and short options was
an epiphany, since I had learned the hard way that I couldn't combine
options that have single hyphens and those with double hyphens.
Further, I'd seen that options with only one character used only one
hyphen and those with two characters, a full word or a hyphenated word
used two hyphens. Your explanation gave me more material to confirm
and expand upon that empirical denotation. Thanks again.

I started off in computing by taking an Honors class (there was no AP
back then) that taught us programming in Fortran III, so I understand
the long-standing traditions of keeping things short. Variable names
could only be one or two characters, so <dd>, <du> and <ls> are "old
friends"! However, modern memory and hard drive storage capacities are
such that descriptions in the man pages could be more helpful.

Succinctness is good for folks who slip into "discourses" (unlike
Voltaire  ;-)  ), but it would be great for newbies and those looking
at a command for the first time to give just a little more in some
cases. Also, as my instructor exemplifies, there are people who just
believe in playing with the system and others who "use the book." Man
pages and Internet searches are frustrating for a guy like me, then,
as the quality of info is irregular. Almost no one tells you whether a
command is root-level of authority only, or for general users. ??!

One aspect of what I'm trying to say is that the man pages include
examples in some cases, but in many cases they do not. Even when
examples are given, many are complex and not illustrative of how to
"just get it done." A simple example and a complex one would be best,
but it's rare to see.

For instance, the <man tee> pages only show one complex example. I
have never been successful using <tee> on my own for the simple cases,
so I gave up on it. Why should it be that way?? Internet results were
mostly verbatim copies of the man pages, so I was stuck.

I can only spend a certain amount of time researching, as there is so
much I need to learn and the Linux filesystems, admin tasks, other
commands, vi/vim, RPM, GRUB, shell programming, etc., for the RHELSA
certification exam. I figure that <ls> ought to one command that I
understand fully, otherwise I would have never expended the effort of
contacting bug-coreutils <at> gnu.org.

So, yes, I really wish the <ls --block-size> command was one of those
cases with examples, any examples at all. Let me show you some of my
attempts at "hacking" and "playing around" with <ls>, although it's
going to demonstrate my confusion, not my understanding.

First, consider the actual <man ls> extracted statement, as cited here:

   SIZE may be (or may be an integer optionally followed by) one of
   following: KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on
   for G, T, P, E, Z, Y.

So, I tried to use an integer followed by a character. That's what I
meant when I said
               >>  an implied evaluation as the description of SIZE
starts off by saying

Failure every time I tried to use the pattern:
--block-size=number+space+suffix


Trying the command with numerical values and suffixes:

<ls -alsi --block-size=1024KB>          Success, but no suffixes on the sizes
<ls -alsi --block-size=1KB>                 Success, but no suffixes
on the sizes
<ls -alsi --block-size=1MB>                Success, but no suffixes on the sizes
<ls -alsi --block-size=10K>                 Success, but no suffixes
on the sizes
<ls -alsi --block-size=10kB>               Success, but no suffixes on the sizes
<ls -alsi --block-size=10kb>                Fails; Invalid suffix in
--blocksize argument '10kb'

Also, when I run <ls -alsi --si>, the results have <K> or <M> or <G>
as a suffix on the filesize amounts, but the similar command <ls
-alsih> gives <k> or <m> or <g>. This is just one group of the cases
behind my statement: "I can see no rhyme or reason why I get lowercase
K, or KB or kB, etc. for the <ls> command, either." Another is given
later, with the "hackings" that had suffixes without numerical values.

Trying the command without any suffixes:

<ls -alsi --block-size=10>                    Success, but no suffixes
on the sizes
<ls -alsi --block-size=100>                  Success, but no suffixes
on the sizes
<ls -alsi --block-size=1024>                Success, but no suffixes
on the sizes
<ls -alsi --block-size=1000000>         Success, but no suffixes on the sizes


Trying the command with suffixes and no numerical values:

<ls -alsi --block-size=M>          Success, <M> suffix on the sizes
<ls -alsi --block-size=m>          Success, <M> suffix on the sizes
(case is opposite of suffix)
<ls -alsi --block-size=kb>         Fails;  Invalid suffix in
--blocksize argument 'kb'
<ls -alsi --block-size=kB>        Success, <kB> suffix on the sizes
<ls -alsi --block-size=KB>        Success, <kB> suffix on the sizes  (
<KB> suffix expected, tho)
<ls -alsi --block-size=MB>       Success, <MB> suffix on the sizes
<ls -alsi --block-size=K>          Success, <K> suffix on the sizes
<ls -alsi --block-size=k>          Success, <K> suffix on the sizes
(case is opposite of suffix)
<ls -alsi --block-size=mb>        Fails;  Invalid suffix in
--blocksize argument 'mb'
<ls -alsi --block-size=g>          Success, <G> suffix on the sizes
(case is opposite of suffix)
<ls -alsi --block-size=t>            Success, <T> suffix on the sizes
(case is opposite of suffix)
<ls -alsi --block-size=EB>       Success, <K> suffix on the sizes
<ls -alsi --block-size=eb>        Failed; Invalid suffix in
--blocksize argument 'eb'
<ls -alsi --block-size=eB>        Failed; Invalid suffix in
--blocksize argument 'eB'  (differs from kB)

G, GB, T, TB, E, EB, P and PB worked. However, Z, ZB, Y and YB all
failed, despite what I see above. Error message said, "--block-size
argument . . . too large" where the ellipses are the suffixes.

Another set of issues revolve around the accuracy/precision of the
filesizes. <ls -alh> and <ls -al --block-size=k> were different only
in the number of decimal places shown to the right of the decimal
point, <ls -alh> showing one place and the other command showing none.
I tried a lot of combinations here, but I'll let this suffice for now.

Oh, you should know that I'm running CentOS 6 at home (Kernel is
2.6.32-71.el6.i686 on my laptop and the 64-bit on my desktop) and Red
Hat 6 at school. Bash is the default at both.

Also, I found that the <man dd> had a very different wording for the
SIZE argument. Also, there was an equals sign given between each
suffix and each numeric value.
Now things got really weird, when I tried to use a suffix and a
number, to attempt to understand the segment "may be one of the
following:  KB 1000, K 1024, MB 1000*1000, . . . "

Failure every time I used the pattern:      --block-size=suffix+space+number.
Failure every time I used the pattern:      --block-size=suffix+number
Failure every time I used the pattern:
--block-size=suffix+number+asterisk+number
Failure every time I used the pattern:      --block-size=number+asterisk+number
Failure every time I used the pattern:
--block-size=suffix+space+number+asterisk+number
            (Error message: "ls: cannot access 1024*1024: No such file
or directory")
Failure every time I used the pattern
--block-size=suffix=number+asterisk+number
                   (This last attempt was based on the <man dd> material.)

Since the number+suffix "sequence" worked in so many earlier cases, I
tried that here, too, but every attempt to do so failed:

Failure every time I used the pattern:
--block-size=number+asterisk+number+suffix
Failure every time I used the pattern:
--block-size=number+asterisk+number+suffix

The following attempt to evaluate the asterisk expression had
absolutely disastrous results:

<ls -alsi --block-size=`1000*1000`>  where the back-tick/grave accent
encloses the value.

Now, I saw a greater-than symbol on the next line as a prompt that
accepted characters until <exit> was supplied. Then the following
error message was presented:

>  -bash: unexpected EOF while looking for matching ``'
-bash: syntax error: unexpected end of file

Newbie me was very frustrated, to say the least. No smoke coming out
of my ears after all of this, but enough midnight oil was consumed
that I just went to bed, trying to forget about it all. Three lines of
text really caused me a lot of grief and I still don't understand it
any better than when I started, except for a few "no no, not that"s.

I await your response to these situations and thank you in advance for
your patience and consideration.

               All the best to you and yours,

                       Mr. Abdallah Clark





ls -alsi








On Thu, Nov 3, 2011 at 1:24 AM, Paul Eggert <eggert <at> cs.ucla.edu> wrote:
> On 11/02/11 19:33, abdallah clark wrote:
>
>> am I to be able to use <1000*1000> or <1024*1024> in
>> either one of those commands?
>
> Not those exact strings, no.  At least, not as far as I know.
> But "MB" is short for 1000*1000, and "M" for 1024*1024.
>
>> I saw that I could use other numerics,
>> even odd amounts, but nothing with an implied evaluation as the
>> description of SIZE starts off by saying.
>
> Sorry, don't follow.  Perhaps an example would clarify?
>
>> I can see no rhyme or reason why I get lowercase K, or KB or
>> kB, etc. for the <ls> command, either.
>
> Again, I'm lost.  Got a specific example?
>
>> The same goes for the statement on mandatory options. Just what is a
>> long option as compared to a short option?
>
> A long option is something like --ignore='*.x'.
> A short option is something like -I '*.x'.
> Typically, for every short option there's an equivalent long
> option, but the reverse is not necessarily true.
>
>> How do I know what is
>> mandatory from what isn't?
>
> Optional arguments are written in square brackets in the
> documentation, e.g., --color[=WHEN].  This isn't written
> down in the man page, unfortunately.  It is described (not
> all that well) in the full manual, here:
>
> http://www.gnu.org/s/coreutils/manual/html_node/General-output-formatting.html#index-g_t_002d_002dcolor-791
>
>

Message #20 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: abdallah clark <clark-adc <at> clear.net>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 9939 <at> debbugs.gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls> and <du>
Date: Wed, 9 Nov 2011 05:37:59 -0600

Dear Paul,

I hope that you and your family are well. I'm doing fine and feeling
like I'm making better progress on a few levels lately. Also, I found
a set of simple examples for the tee command in a very old book that
were quite useful. I was reading it for shell programming and it's
index didn't even list "tee" at all, but they had four  pages using
it. Thank God for "serendipity!"

I was wondering if you received my very detailed account of the issues
I found with the <ls -l --block-size=SIZE> command. It's been about a
week since I sent it, so I wasn't sure what was happening.

I saved it as a text file also, so it would be easy to re-send it to
you if necessary.

I am very curious to see whether my understanding of the option is the
case, or if there really are errors/bugs in it.

I await your acknowledgement of that e-mail. Thanks again for your
consideration.

          All the best to you and yours,

                 Abdallah Clark




On Wed, Nov 2, 2011 at 11:01 AM, Paul Eggert <eggert <at> cs.ucla.edu> wrote:
> On 11/02/11 03:40, abdallah clark wrote:
>
>> the units are not
>> consistent with the ISO/SI units-- K and M are in units of 1000, not
>> 1024, because they are part of the metric system, not the binary
>> system.
>
> coreutils is supporting three notations here: SI-ish,
> IEC 60027-2 / ISO/IEC 80000-13:2008, and traditional Unix.
> So:
>
>  MB means 1000*1000 bytes.  This is like SI, except SI doesn't have "B".
>  MiB means 1024*1024 bytes.  This is IEC 60027-2 and ISO/IEC 80000-13:2008.
>  M means MiB.  This is traditional Unix.
>
> See <http://en.wikipedia.org/wiki/Binary_prefix> for more info.
> (coreutils cannot use plain SI, since SI doesn't specify
> an abbreviation for "byte".)
>
>> it is just too awkwardly
>> written to be understood on the first reading.
>
> Suggestions for improved wording are welcome.  We'd like it to be
> short, of course.
>
>> Also, the statement "Mandatory arguments to long options are mandatory
>> for short options too." puzzles me
>
> Yes, I don't like that sentence either.  Suggestions for
> improvement are welcome here, too.  Maybe we should just get
> rid of it?  I expect it causes more confusion than it cures.
>

Message #23 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: abdallah clark <clark-adc <at> clear.net>
Cc: 9939 <at> debbugs.gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls> and <du>
Date: Wed, 09 Nov 2011 10:59:34 -0800

On 11/09/11 03:37, abdallah clark wrote:
> I was wondering if you received my very detailed account

Yes, I got it, and I'm afraid that it was long enough and
required enough thinking that it got put into my TO-DO
list, which is a very bad place to be (I have hundreds of
items in it....).

What I was hoping for, is a specific proposed patch to the
coreutils, in the format generated by "git diff".  This patch
would fix the documentation to make it clearer.  Is that
something you could do?

Message #26 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: "Alan Curry" <pacman-cu <at> kosh.dhis.org>
To: clark-adc <at> clear.net (abdallah clark)
Cc: 9939 <at> debbugs.gnu.org, Paul Eggert <eggert <at> cs.ucla.edu>
Subject: Re: bug#9939: Problems with the SIZE description in man pages for <ls>
Date: Wed, 9 Nov 2011 17:48:39 -0500 (GMT+5)

abdallah clark writes:
> 
> I was wondering if you received my very detailed account of the issues
> I found with the <ls -l --block-size=3DSIZE> command. It's been about a
> week since I sent it, so I wasn't sure what was happening.

I looked over that message and prepared a reply explaining the things that
you had misunderstood. Then I tried running your examples and realized that I
didn't understand some of them either. According to my understanding, several
of the behaviors you observed are bugs. So I deleted my reply and decided to
wait along with you for someone else to explain it all.

Since that hasn't happened yet, I'll go ahead and cover the main point:

You're interested in altering the block size used in the ls output, but you
haven't investigated what portions of the output are affected by block size.
There are 3 instances of the word "block" in ls(1).

2 of them are in the description of the options that change the block size:
--block-size and -k.

The 3rd instance is under the only option that actually makes use of the
block size: -s.

A quick demonstration of -k working. First I have to set POSIXLY_CORRECT
because the default block size when not in POSIXLY_CORRECT mode is already
1K, so -k is normally a no-op.

$ POSIXLY_CORRECT=1 ; export POSIXLY_CORRECT
$ ls -s /bin/ls
224 /bin/ls
$ ls -sk /bin/ls
112 /bin/ls

Since the -l output is not defined in terms of block size, ls -l and ls -lk
will produce exactly the same output.

$ ls -l /bin/ls
-rwxr-xr-x 1 root root 107124 Feb  8  2011 /bin/ls
$ ls -lk /bin/ls
-rwxr-xr-x 1 root root 105 Feb  8  2011 /bin/ls

Oops.

Well, I know they used to produce the same output. And I think they still
should and this is a bug. Anyone?

> 
> On Wed, Nov 2, 2011 at 11:01 AM, Paul Eggert <eggert <at> cs.ucla.edu> wrote:
[snip]
Quote what you're replying to, and put your reply in logical order with it.

-- 
Alan Curry

Message #29 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: abdallah clark <clark-adc <at> clear.net>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 9939 <at> debbugs.gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls> and <du>
Date: Wed, 9 Nov 2011 20:08:18 -0600

Dear Paul,

Thank you for the prompt response.

In terms of being able to follow up with GIT DIFF, you need to
remember that I am a newbie. I have no idea even what that it, let
alone being able to reformat anything with it. I did a search on Yahoo
and got over 8 and a half million hits on that combination. Hopeless,
no doubt.

The easy way to see the text is to just put it into a text editor and
let no word-wrap be in effect. It was formatted beautifully when I was
writing it. I spent a lot of time making the columns align and putting
the experiments in logical groupings.

I figured on hitting someone's frustration level a lot earlier. Thanks
for listening so far, anyway.


            All the best to you and yours,

                   Abdallah Clark



On Wed, Nov 9, 2011 at 12:59 PM, Paul Eggert <eggert <at> cs.ucla.edu> wrote:
> On 11/09/11 03:37, abdallah clark wrote:
>> I was wondering if you received my very detailed account
>
> Yes, I got it, and I'm afraid that it was long enough and
> required enough thinking that it got put into my TO-DO
> list, which is a very bad place to be (I have hundreds of
> items in it....).
>
> What I was hoping for, is a specific proposed patch to the
> coreutils, in the format generated by "git diff".  This patch
> would fix the documentation to make it clearer.  Is that
> something you could do?
>

Message #32 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: abdallah clark <clark-adc <at> clear.net>
Cc: 9939 <at> debbugs.gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls> and <du>
Date: Wed, 09 Nov 2011 18:43:48 -0800

On 11/09/11 18:08, abdallah clark wrote:
> In terms of being able to follow up with GIT DIFF, you need to
> remember that I am a newbie.

Ah, sorry, in that case, how about if you simply take the
output of the command "ls --help", edit it to improve
it, and send us your fixes.

Thus, you can use the following shell command:

ls --help > lshelp.txt

to create the file lshelp.txt.  Then edit that file to be the way
that you like.  Then send us the output of the following shell command:

ls --help | diff -u - lshelp.txt

so that we can see what edits you made.

If you want to improve the documentation for other commands,
you can repeat the recipe by using them in place of "ls".

Please bear in mind that small changes are easier for us to
review, so you probably want to avoid the temptation to
reformat the text.  The goal is to send us the wording changes
that you'd like to see.

It's probably best to start with one command, and maybe a simpler
one, so that we can iron out the procedure without having to spend
a lot of time on blind alleys.

Message #35 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: abdallah clark <clark-adc <at> clear.net>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 9939 <at> debbugs.gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls> and <du>
Date: Thu, 10 Nov 2011 12:27:53 -0600

Dear Paul and others:

Thank you for your suggestions, but not only are you not realizing
what it means to be a newbie, you have also missed the point of my
communication. Not only patience but also the consideration of others
new to Linux ought to be in play.

The SIZE notation is confusing and I have no idea how to "fix" it,
since I do not understand what was intended and none of you have
explained that. Instead, you have launched into a flurry of
complications that do not help resolve that issue. I am not playing
games with anyone. It is not my job to do more than report bugs or
other problems, as the man pages indicate.

Your earlier comment about the MB or M or MiB was a circular argument
as well. If M equals MiB, then UNIX/Linux is not applying the
conventions.

If you cannot clarify something that is already written and cannot
refer me to any material, anywhere that will clarify what the SIZE
paragraph is saying, then please do not attempt to assign to me the
task of rewriting the SIZE paragraph or any other part of the <man ls>
material. That is a task for an intermediate or advanced user, not a
newbie.

All the best to you and yours,

         Abdallah Clark




On Wed, Nov 9, 2011 at 8:43 PM, Paul Eggert <eggert <at> cs.ucla.edu> wrote:
> On 11/09/11 18:08, abdallah clark wrote:
>> In terms of being able to follow up with GIT DIFF, you need to
>> remember that I am a newbie.
>
> Ah, sorry, in that case, how about if you simply take the
> output of the command "ls --help", edit it to improve
> it, and send us your fixes.
>
> Thus, you can use the following shell command:
>
> ls --help > lshelp.txt
>
> to create the file lshelp.txt.  Then edit that file to be the way
> that you like.  Then send us the output of the following shell command:
>
> ls --help | diff -u - lshelp.txt
>
> so that we can see what edits you made.
>
> If you want to improve the documentation for other commands,
> you can repeat the recipe by using them in place of "ls".
>
> Please bear in mind that small changes are easier for us to
> review, so you probably want to avoid the temptation to
> reformat the text.  The goal is to send us the wording changes
> that you'd like to see.
>
> It's probably best to start with one command, and maybe a simpler
> one, so that we can iron out the procedure without having to spend
> a lot of time on blind alleys.
>

Message #38 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Jim Meyering <jim <at> meyering.net>
To: abdallah clark <clark-adc <at> clear.net>
Cc: 9939 <at> debbugs.gnu.org, Paul Eggert <eggert <at> cs.ucla.edu>
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls> and <du>
Date: Thu, 10 Nov 2011 20:04:50 +0100

abdallah clark wrote:

> Dear Paul and others:
>
> Thank you for your suggestions, but not only are you not realizing
> what it means to be a newbie, you have also missed the point of my
> communication. Not only patience but also the consideration of others
> new to Linux ought to be in play.
>
> The SIZE notation is confusing and I have no idea how to "fix" it,
> since I do not understand what was intended and none of you have
> explained that. Instead, you have launched into a flurry of
> complications that do not help resolve that issue. I am not playing
> games with anyone. It is not my job to do more than report bugs or
> other problems, as the man pages indicate.
>
> Your earlier comment about the MB or M or MiB was a circular argument
> as well. If M equals MiB, then UNIX/Linux is not applying the
> conventions.
>
> If you cannot clarify something that is already written and cannot
> refer me to any material, anywhere that will clarify what the SIZE
> paragraph is saying, then please do not attempt to assign to me the
> task of rewriting the SIZE paragraph or any other part of the <man ls>
> material. That is a task for an intermediate or advanced user, not a
> newbie.

If you are trying to understand how the tool works, a good first step
would be to read the complete manual mentioned at the bottom of the man page:

  SEE ALSO
     The full documentation for ls is maintained as a  Texinfo  manual.  If
     the info and ls programs are properly installed at your site, the command

        info coreutils 'ls invocation'

     should give you access to the complete manual.

ls --help output (from which the man page is derived) is intended solely
as a minimal quick reference.

Message #41 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Bob Proulx <bob <at> proulx.com>
To: abdallah clark <clark-adc <at> clear.net>
Cc: 9939 <at> debbugs.gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls> and <du>
Date: Thu, 10 Nov 2011 12:18:25 -0700

abdallah clark wrote:
> Thank you for your suggestions, but not only are you not realizing
> what it means to be a newbie, you have also missed the point of my
> communication. Not only patience but also the consideration of others
> new to Linux ought to be in play.
> ...
> It is not my job to do more than report bugs or other problems, as
> the man pages indicate.

I am compelled by this to write that you are also failing to realize
what is is like to share work on a community project.  This is not a
job or any of us.  We gather together in a shared hope of improving
the world by the shared effort of producing free software.  The result
is donated to the community.

Think of it this way.  There are several people working in the kitchen
preparing meals.  These meals are set out on the table for people to
eat.  Someone eats the meal.  They think, there isn't enough spice in
this dish.  They complain to the volunteers cooking, "Hey, there isn't
enough spice."  The cooks say, there are thousands of people eating
the food and some of them need a low spice content.  If you like more
spice please feel free to add some.  Or feel free to come into the
kitchen and help us prepare a good tasting meal that will be good for
everyone.  But please remember that some people can't tolerate a lot
of spice.  But then you say, it is not my job to cook.  It is only my
job to submit feedback.  As cooks you should consider that people want
more spice.

Think about that and think about how you will react if you are one of
the cooks in the kitchen?  What would you do in that case.  You are
volunteering your time to cook.  You are providing this service free
and donating the result.  Would you think, "No one is helping.  Why am
I doing this?  Why am I donating time and effort and resources?  I
should stop cooking."

> If you cannot clarify something that is already written and cannot
> refer me to any material, anywhere that will clarify what the SIZE
> paragraph is saying, then please do not attempt to assign to me the
> task of rewriting the SIZE paragraph or any other part of the <man ls>
> material. That is a task for an intermediate or advanced user, not a
> newbie.

Do you ride a bicycle?  If so did you learn from a book?  Or did
someone teach you?  There are some tasks that can be learned from
written documentation.  But there are some things that are much better
learned from a teacher.  Riding a bicycle is one of those tasks that
is better learned from a teacher than from a book.  Operating a
bicycle would be really scary to try to do if you could only learn
from a book.  It just isn't possible to sufficiently cover everything
that you need to know all in one place.  No matter how much someone
were to complain about it.

Operating a computer operating system is not completely different.
Some things can be learned from a book.  Perhaps most of it.  But
different people learn things in different ways.  Sometimes people
will learn better from a human teacher than from a written document.

Perhaps you could find a computer users group from which you could get
face to face help and instruction?  I think you would really get the
most benefit from someone who could immediately spot what you needed
and then could react with the right words to help make the points
clear.

Bob

Message #44 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: abdallah clark <clark-adc <at> clear.net>
To: Bob Proulx <bob <at> proulx.com>
Cc: 9939 <at> debbugs.gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls> and <du>
Date: Thu, 10 Nov 2011 14:07:59 -0600

Gentlemen:

That was already done, to no avail. Has anyone actually looked at that
paragraph on SIZE and thought about what it means?




On Thu, Nov 10, 2011 at 1:18 PM, Bob Proulx <bob <at> proulx.com> wrote:
> abdallah clark wrote:
>> Thank you for your suggestions, but not only are you not realizing
>> what it means to be a newbie, you have also missed the point of my
>> communication. Not only patience but also the consideration of others
>> new to Linux ought to be in play.
>> ...
>> It is not my job to do more than report bugs or other problems, as
>> the man pages indicate.
>
> I am compelled by this to write that you are also failing to realize
> what is is like to share work on a community project.  This is not a
> job or any of us.  We gather together in a shared hope of improving
> the world by the shared effort of producing free software.  The result
> is donated to the community.
>
> Think of it this way.  There are several people working in the kitchen
> preparing meals.  These meals are set out on the table for people to
> eat.  Someone eats the meal.  They think, there isn't enough spice in
> this dish.  They complain to the volunteers cooking, "Hey, there isn't
> enough spice."  The cooks say, there are thousands of people eating
> the food and some of them need a low spice content.  If you like more
> spice please feel free to add some.  Or feel free to come into the
> kitchen and help us prepare a good tasting meal that will be good for
> everyone.  But please remember that some people can't tolerate a lot
> of spice.  But then you say, it is not my job to cook.  It is only my
> job to submit feedback.  As cooks you should consider that people want
> more spice.
>
> Think about that and think about how you will react if you are one of
> the cooks in the kitchen?  What would you do in that case.  You are
> volunteering your time to cook.  You are providing this service free
> and donating the result.  Would you think, "No one is helping.  Why am
> I doing this?  Why am I donating time and effort and resources?  I
> should stop cooking."
>
>> If you cannot clarify something that is already written and cannot
>> refer me to any material, anywhere that will clarify what the SIZE
>> paragraph is saying, then please do not attempt to assign to me the
>> task of rewriting the SIZE paragraph or any other part of the <man ls>
>> material. That is a task for an intermediate or advanced user, not a
>> newbie.
>
> Do you ride a bicycle?  If so did you learn from a book?  Or did
> someone teach you?  There are some tasks that can be learned from
> written documentation.  But there are some things that are much better
> learned from a teacher.  Riding a bicycle is one of those tasks that
> is better learned from a teacher than from a book.  Operating a
> bicycle would be really scary to try to do if you could only learn
> from a book.  It just isn't possible to sufficiently cover everything
> that you need to know all in one place.  No matter how much someone
> were to complain about it.
>
> Operating a computer operating system is not completely different.
> Some things can be learned from a book.  Perhaps most of it.  But
> different people learn things in different ways.  Sometimes people
> will learn better from a human teacher than from a written document.
>
> Perhaps you could find a computer users group from which you could get
> face to face help and instruction?  I think you would really get the
> most benefit from someone who could immediately spot what you needed
> and then could react with the right words to help make the points
> clear.
>
> Bob
>

Message #47 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
To: abdallah clark <clark-adc <at> clear.net>
Cc: 9939 <at> debbugs.gnu.org, Bob Proulx <bob <at> proulx.com>
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls>	and <du>
Date: Thu, 10 Nov 2011 13:22:07 -0700

On 11/10/2011 01:07 PM, abdallah clark wrote:
> Gentlemen:
>
> That was already done, to no avail. Has anyone actually looked at that
> paragraph on SIZE and thought about what it means?

[Please don't top-post on technical lists.]

The paragraph in question:

SIZE may be (or may be an integer optionally followed by) one of following:
KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.

That first sentence means there are three valid forms:

SIZE may be one of the following (suffix-only case)
SIZE may be an integer (size-only case)
SIZE may be an integer followed by one of the following 
(size-and-suffix-case)

Next are the possible suffixes:

KB is a suffix for 1000 (kilobytes)
K is a suffix for 1024 (kibibytes)
not listed: KiB is a synonym for K (the info pages list this, but as the 
--help output tries to be terse, we skip the longer spelling here)

MB is a suffix for 1000*1000 (megabytes)
M is a suffix for 1024*1024 (mebibytes)
again, not listed is MiB as a synonym for M

And so on means that:

GB is a suffix for 1000*1000*1000 (gigabytes)
G and GiB are a suffix for 1024*1024*1024 (GiB)

Or in a rough BNF form,

SIZE : integer [SUFFIX]
     | SUFFIX
SUFFIX : LETTER /* in powers of 1024 */
       | LETTER 'B' /* in powers of 1000 */
       | LETTER 'i' 'B' /* in powers of 1024 */
LETTER : 'K' /* base ^ 1, for 1024 or 1000 */
       | 'M' /* base ^ 2, for 1024*1024 or 1000*1000 */
       | 'G' /* base ^ 3 */
       | 'T' /* base ^ 4 */
       | 'P' /* base ^ 5 */
       | 'E' /* base ^ 6 */
       | 'Z' /* base ^ 7 */
       | 'Y' /* base ^ 8 */

(and if you have a disk larger than 1Y, I'm jealous)


I followed that fairly easily, but I've also read the code that 
implements it, so I'm unfortunately biased.  I'm not sure where you are 
having difficulties following it, which is why we're asking that you 
provide an alternative wording, at which point we can evaluate the two 
wordings and pick the strongest of both approaches.

-- 
Eric Blake   eblake <at> redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

Message #50 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
Cc: 9939 <at> debbugs.gnu.org, abdallah clark <clark-adc <at> clear.net>,
	Bob Proulx <bob <at> proulx.com>
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls>	and <du>
Date: Thu, 10 Nov 2011 13:33:59 -0700

On 11/10/2011 01:22 PM, Eric Blake wrote:
> SIZE may be (or may be an integer optionally followed by) one of following:
> KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.
>
> That first sentence means there are three valid forms:
>
> SIZE may be one of the following (suffix-only case)
> SIZE may be an integer (size-only case)
> SIZE may be an integer followed by one of the following
> (size-and-suffix-case)

Just looking at this in isolation, how about:

SIZE may be a integer, a suffix, or both.

> SUFFIX : LETTER /* in powers of 1024 */
> | LETTER 'B' /* in powers of 1000 */
> | LETTER 'i' 'B' /* in powers of 1024 */
> LETTER : 'K' /* base ^ 1, for 1024 or 1000 */
> | 'M' /* base ^ 2, for 1024*1024 or 1000*1000 */
> | 'G' /* base ^ 3 */
> | 'T' /* base ^ 4 */
> | 'P' /* base ^ 5 */
> | 'E' /* base ^ 6 */
> | 'Z' /* base ^ 7 */
> | 'Y' /* base ^ 8 */

And here, how about:

A valid suffix selects a power [KMGTPEZY] and optional base ('' or 'iB' 
for 1024, 'B' for 1000).

Put together, those two sentences are slightly shorter than the 
original, yet still convey about the same amount of information.  Here's 
the same thing in patch format:

diff --git i/src/system.h w/src/system.h
index 926def9..b7a5c5f 100644
--- i/src/system.h
+++ w/src/system.h
@@ -516,8 +516,8 @@ static inline void
 emit_size_note (void)
 {
   fputs (_("\n\
-SIZE may be (or may be an integer optionally followed by) one of 
following:\n\
-KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, 
Z, Y.\n\
+SIZE may be a integer, a suffix, or both.  A valid suffix selects a 
power\n\
+from [KMGTPEZY], and an optional base ('' or 'iB' for 1024, 'B' for 
1000).\n\
 "), stdout);
 }



-- 
Eric Blake   eblake <at> redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

Message #53 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Eric Blake <eblake <at> redhat.com>
Cc: 9939 <at> debbugs.gnu.org, abdallah clark <clark-adc <at> clear.net>,
	Bob Proulx <bob <at> proulx.com>
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls>	and <du>
Date: Thu, 10 Nov 2011 13:26:59 -0800

On 11/10/11 12:33, Eric Blake wrote:
> -SIZE may be (or may be an integer optionally followed by) one of following:\n\
> -KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.\n\
> +SIZE may be a integer, a suffix, or both.  A valid suffix selects a power\n\
> +from [KMGTPEZY], and an optional base ('' or 'iB' for 1024, 'B' for 1000).\n\

How about if we not bother to document the integerless suffix here?
Similarly, we can omit the documentation for 'iB'.
That kind of trivia can be left to the full manual, as it isn't
needed to use the program conveniently and effectively.
I realize that this'll mean that the 'ls --help' output isn't complete,
but it's already incomplete by design (it's a summary, not the full
manual), and this particular bit of incompleteness should be OK.

On the other hand, what I think is most missing here is an *example*.
An example can help communicate intent clearly and quickly
to non-experts.  I think an example would have helped Abdallah
get the point without having to ask us what the sentence means.

Given the above, how about the following rewording?

  SIZE is an integer with an optional suffix (example: 10GB).  Suffixes are:
  KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.

Message #56 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 9939 <at> debbugs.gnu.org, abdallah clark <clark-adc <at> clear.net>,
	Bob Proulx <bob <at> proulx.com>
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls>	and <du>
Date: Thu, 10 Nov 2011 14:36:48 -0700

On 11/10/2011 02:26 PM, Paul Eggert wrote:
> On 11/10/11 12:33, Eric Blake wrote:
>> -SIZE may be (or may be an integer optionally followed by) one of following:\n\
>> -KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.\n\
>> +SIZE may be a integer, a suffix, or both.  A valid suffix selects a power\n\
>> +from [KMGTPEZY], and an optional base ('' or 'iB' for 1024, 'B' for 1000).\n\
>
> How about if we not bother to document the integerless suffix here?
> Similarly, we can omit the documentation for 'iB'.
> That kind of trivia can be left to the full manual, as it isn't
> needed to use the program conveniently and effectively.
> I realize that this'll mean that the 'ls --help' output isn't complete,
> but it's already incomplete by design (it's a summary, not the full
> manual), and this particular bit of incompleteness should be OK.
>
> On the other hand, what I think is most missing here is an *example*.
> An example can help communicate intent clearly and quickly
> to non-experts.  I think an example would have helped Abdallah
> get the point without having to ask us what the sentence means.
>
> Given the above, how about the following rewording?
>
>    SIZE is an integer with an optional suffix (example: 10GB).  Suffixes are:
>    KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.

Hmm, and we already have "-k like --block-size=1K", rather than "like 
--block-size=K", so we are already gearing users towards always 
providing the integer.  Like you said, your wording is incomplete, but 
still covers the most common use cases.  I can live with it.

-- 
Eric Blake   eblake <at> redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

Message #59 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Jim Meyering <jim <at> meyering.net>
Cc: 9939 <at> debbugs.gnu.org, 10016-done <at> debbugs.gnu.org,
	Eric Blake <eblake <at> redhat.com>, Alan Curry <pacman-cu <at> kosh.dhis.org>
Subject: Re: bug#10016: ls -lk is wrong
Date: Fri, 11 Nov 2011 23:40:36 -0800

On 11/11/11 13:10, Jim Meyering wrote:
> Do you feel like writing the patch?

Sure.  I wrote and pushed the following.
The test case isn't elegant, but at least it catches the bug.

ls: -k no longer affects -l's file sizes
This fixes an incompatibility with POSIX 2008 and with BSD.
Problem reported by Abdallah Clark (Bug#9939)
via Alan Curry (Bug#10016).
* NEWS: Document this.
* doc/coreutils.texi (General output formatting): Document the
new -k behavior, and --kibibytes.
* src/ls.c (file_human_output_opts): New static var.
(long_options, usage): Add --kibibytes.
(decode_switches, gobble_file, print_long_format):
Implement the new -k behavior.
* tests/ls/block-size: New file.
* tests/Makefile.am (TESTS): Add it.
diff --git a/NEWS b/NEWS
index 081989d..1b0f2f5 100644
--- a/NEWS
+++ b/NEWS
@@ -4,6 +4,13 @@ GNU coreutils NEWS                                    -*- outline -*-

 ** Bug fixes

+  ls's -k option no longer affects how ls -l outputs file sizes.
+  It now affects only the per-directory block counts written by -l,
+  and the sizes written by -s.  This is for compatibility with BSD
+  and with POSIX 2008.  Because -k is no longer equivalent to
+  --block-size=1KiB, a new long option --kibibyte stands for -k.
+  [bug introduced in coreutils-4.5.4]
+
   rm -rf DIR would fail with "Device or resource busy" on Cygwin with NWFS
   and NcFsd file systems.  This did not affect Unix/Linux-based kernels.
   [bug introduced in coreutils-8.0, when rm began using fts]
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 2c33fe8..4531440 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -7127,10 +7127,19 @@ Append @samp{*} for executable regular files, otherwise behave as for
 @end table

 @item -k
+@itemx --kibibytes
 @opindex -k
-Print file sizes in 1024-byte blocks, overriding the default block
-size (@pxref{Block size}).
-This option is equivalent to @option{--block-size=1K}.
+@opindex --kibibytes
+Set the default block size to its normal value of 1024 bytes,
+overriding any contrary specification in environment variables
+(@pxref{Block size}).  This option is in turn overridden by the
+@option{--block-size}, @option{-h} or @option{--human-readable}, and
+@option{--si} options.
+
+The @option{-k} or @option{--kibibytes} option affects the
+per-directory block count written by the @option{-l} and similar
+options, and the size written by the @option{-s} or @option{--size}
+option.  It does not affect the file size written by @option{-l}.

 @item -m
 @itemx --format=commas
diff --git a/src/ls.c b/src/ls.c
index 1b0c250..b8a09b3 100644
--- a/src/ls.c
+++ b/src/ls.c
@@ -479,13 +479,14 @@ static bool numeric_ids;

 static bool print_block_size;

-/* Human-readable options for output.  */
+/* Human-readable options for output, when printing block counts.  */
 static int human_output_opts;

-/* The units to use when printing sizes other than file sizes.  */
+/* The units to use when printing block counts.  */
 static uintmax_t output_block_size;

 /* Likewise, but for file sizes.  */
+static int file_human_output_opts;
 static uintmax_t file_output_block_size = 1;

 /* Follow the output with a special string.  Using this format,
@@ -809,6 +810,7 @@ static struct option const long_options[] =
    GROUP_DIRECTORIES_FIRST_OPTION},
   {"human-readable", no_argument, NULL, 'h'},
   {"inode", no_argument, NULL, 'i'},
+  {"kibibytes", no_argument, NULL, 'k'},
   {"numeric-uid-gid", no_argument, NULL, 'n'},
   {"no-group", no_argument, NULL, 'G'},
   {"hide-control-chars", no_argument, NULL, 'q'},
@@ -1512,8 +1514,8 @@ decode_switches (int argc, char **argv)
 {
   char *time_style_option = NULL;

-  /* Record whether there is an option specifying sort type.  */
   bool sort_type_specified = false;
+  bool kibibytes_specified = false;

   qmark_funny_chars = false;

@@ -1582,14 +1584,6 @@ decode_switches (int argc, char **argv)
       }
   }

-  {
-    char const *ls_block_size = getenv ("LS_BLOCK_SIZE");
-    human_options (ls_block_size,
-                   &human_output_opts, &output_block_size);
-    if (ls_block_size || getenv ("BLOCK_SIZE"))
-      file_output_block_size = output_block_size;
-  }
-
   line_length = 80;
   {
     char const *p = getenv ("COLUMNS");
@@ -1689,7 +1683,8 @@ decode_switches (int argc, char **argv)
           break;

         case 'h':
-          human_output_opts = human_autoscale | human_SI | human_base_1024;
+          file_human_output_opts = human_output_opts =
+            human_autoscale | human_SI | human_base_1024;
           file_output_block_size = output_block_size = 1;
           break;

@@ -1698,8 +1693,7 @@ decode_switches (int argc, char **argv)
           break;

         case 'k':
-          human_output_opts = 0;
-          file_output_block_size = output_block_size = 1024;
+          kibibytes_specified = true;
           break;

         case 'l':
@@ -1937,12 +1931,14 @@ decode_switches (int argc, char **argv)
                                                  &output_block_size);
             if (e != LONGINT_OK)
               xstrtol_fatal (e, oi, 0, long_options, optarg);
+            file_human_output_opts = human_output_opts;
             file_output_block_size = output_block_size;
           }
           break;

         case SI_OPTION:
-          human_output_opts = human_autoscale | human_SI;
+          file_human_output_opts = human_output_opts =
+            human_autoscale | human_SI;
           file_output_block_size = output_block_size = 1;
           break;

@@ -1959,6 +1955,23 @@ decode_switches (int argc, char **argv)
         }
     }

+  if (! output_block_size)
+    {
+      char const *ls_block_size = getenv ("LS_BLOCK_SIZE");
+      human_options (ls_block_size,
+                     &human_output_opts, &output_block_size);
+      if (ls_block_size || getenv ("BLOCK_SIZE"))
+        {
+          file_human_output_opts = human_output_opts;
+          file_output_block_size = output_block_size;
+        }
+      if (kibibytes_specified)
+        {
+          human_output_opts = 0;
+          output_block_size = 1024;
+        }
+    }
+
   max_idx = MAX (1, line_length / MIN_COLUMN_WIDTH);

   filename_quoting_options = clone_quoting_options (NULL);
@@ -3025,7 +3038,8 @@ gobble_file (char const *name, enum filetype type, ino_t inode,
             {
               char buf[LONGEST_HUMAN_READABLE + 1];
               uintmax_t size = unsigned_file_size (f->stat.st_size);
-              int len = mbswidth (human_readable (size, buf, human_output_opts,
+              int len = mbswidth (human_readable (size, buf,
+                                                  file_human_output_opts,
                                                   1, file_output_block_size),
                                   0);
               if (file_size_width < len)
@@ -3767,7 +3781,8 @@ print_long_format (const struct fileinfo *f)
         (! f->stat_ok
          ? "?"
          : human_readable (unsigned_file_size (f->stat.st_size),
-                           hbuf, human_output_opts, 1, file_output_block_size));
+                           hbuf, file_human_output_opts, 1,
+                           file_output_block_size));
       int pad;
       for (pad = file_size_width - mbswidth (size, 0); 0 < pad; pad--)
         *p++ = ' ';
@@ -4672,7 +4687,7 @@ Mandatory arguments to long options are mandatory for short options too.\n\
   -i, --inode                print the index number of each file\n\
   -I, --ignore=PATTERN       do not list implied entries matching shell PATTERN\
 \n\
-  -k                         like --block-size=1K\n\
+  -k, --kibibytes            use 1024-byte blocks\n\
 "), stdout);
       fputs (_("\
   -l                         use a long listing format\n\
diff --git a/tests/Makefile.am b/tests/Makefile.am
index 5021c18..64366a4 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -415,6 +415,7 @@ TESTS =						\
   ln/slash-decorated-nonexistent-dest		\
   ln/target-1					\
   ls/abmon-align				\
+  ls/block-size					\
   ls/color-clear-to-eol				\
   ls/color-dtype-dir				\
   ls/color-norm					\
diff --git a/tests/ls/block-size b/tests/ls/block-size
new file mode 100644
index 0000000..16ede04
--- /dev/null
+++ b/tests/ls/block-size
@@ -0,0 +1,173 @@
+#!/bin/sh
+# Exercise ls --block-size and related options.
+
+# Copyright (C) 2011 Free Software Foundation, Inc.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+. "${srcdir=.}/init.sh"; path_prepend_ ../src
+print_ver_ ls
+
+TZ=UTC0
+export TZ
+
+mkdir sub
+cd sub
+
+for size in 1024 4096 262144; do
+  echo foo | dd conv=sync bs=$size >file$size || fail=1
+done
+touch -d '2001-01-01 00:00' file* || fail=1
+
+size_etc='s/[^ ]* *[^ ]* *[^ ]* *[^ ]* *//'
+
+ls -l * | sed "$size_etc" >../out || fail=1
+POSIXLY_CORRECT=1 ls -l * | sed "$size_etc" >>../out || fail=1
+POSIXLY_CORRECT=1 ls -k -l * | sed "$size_etc" >>../out || fail=1
+
+for var in BLOCKSIZE BLOCK_SIZE LS_BLOCK_SIZE; do
+  for blocksize in 1 512 1K 1KiB; do
+    (eval $var=$blocksize && export $var &&
+     ls -l * &&
+     ls -l -k * &&
+     ls -l -k --block-size=$blocksize *
+    ) | sed "$size_etc" >>../out || fail=1
+  done
+done
+
+cd ..
+
+cat >exp <<'EOF'
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+2 Jan  1  2001 file1024
+512 Jan  1  2001 file262144
+8 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+1 Jan  1  2001 file1024
+256 Jan  1  2001 file262144
+4 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+1 Jan  1  2001 file1024
+256 Jan  1  2001 file262144
+4 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+2 Jan  1  2001 file1024
+512 Jan  1  2001 file262144
+8 Jan  1  2001 file4096
+2 Jan  1  2001 file1024
+512 Jan  1  2001 file262144
+8 Jan  1  2001 file4096
+2 Jan  1  2001 file1024
+512 Jan  1  2001 file262144
+8 Jan  1  2001 file4096
+1 Jan  1  2001 file1024
+256 Jan  1  2001 file262144
+4 Jan  1  2001 file4096
+1 Jan  1  2001 file1024
+256 Jan  1  2001 file262144
+4 Jan  1  2001 file4096
+1 Jan  1  2001 file1024
+256 Jan  1  2001 file262144
+4 Jan  1  2001 file4096
+1 Jan  1  2001 file1024
+256 Jan  1  2001 file262144
+4 Jan  1  2001 file4096
+1 Jan  1  2001 file1024
+256 Jan  1  2001 file262144
+4 Jan  1  2001 file4096
+1 Jan  1  2001 file1024
+256 Jan  1  2001 file262144
+4 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+1024 Jan  1  2001 file1024
+262144 Jan  1  2001 file262144
+4096 Jan  1  2001 file4096
+2 Jan  1  2001 file1024
+512 Jan  1  2001 file262144
+8 Jan  1  2001 file4096
+2 Jan  1  2001 file1024
+512 Jan  1  2001 file262144
+8 Jan  1  2001 file4096
+2 Jan  1  2001 file1024
+512 Jan  1  2001 file262144
+8 Jan  1  2001 file4096
+1 Jan  1  2001 file1024
+256 Jan  1  2001 file262144
+4 Jan  1  2001 file4096
+1 Jan  1  2001 file1024
+256 Jan  1  2001 file262144
+4 Jan  1  2001 file4096
+1 Jan  1  2001 file1024
+256 Jan  1  2001 file262144
+4 Jan  1  2001 file4096
+1 Jan  1  2001 file1024
+256 Jan  1  2001 file262144
+4 Jan  1  2001 file4096
+1 Jan  1  2001 file1024
+256 Jan  1  2001 file262144
+4 Jan  1  2001 file4096
+1 Jan  1  2001 file1024
+256 Jan  1  2001 file262144
+4 Jan  1  2001 file4096
+EOF
+
+compare out exp || fail=1
+
+Exit $fail

Message #62 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Eric Blake <eblake <at> redhat.com>
Cc: 9939 <at> debbugs.gnu.org, abdallah clark <clark-adc <at> clear.net>
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls>	and <du>
Date: Fri, 11 Nov 2011 23:45:50 -0800

On 11/10/11 13:36, Eric Blake wrote:
> I can live with it.

OK, thanks, I changed "10GB" to "10MB" since it might refer to a RAM
quantity I suppose, and pushed it:

* src/system.h (emit_size_note): Reword for clarity.
See discussion in Bug#9939.
diff --git a/src/system.h b/src/system.h
index 926def9..1cbde92 100644
--- a/src/system.h
+++ b/src/system.h
@@ -516,7 +516,7 @@ static inline void
 emit_size_note (void)
 {
   fputs (_("\n\
-SIZE may be (or may be an integer optionally followed by) one of following:\n\
+SIZE is an integer with an optional suffix (example: 10MB).  Suffixes are:\n\
 KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.\n\
 "), stdout);
 }

Message #65 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Jim Meyering <jim <at> meyering.net>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 9939 <at> debbugs.gnu.org, 10016-done <at> debbugs.gnu.org,
	Eric Blake <eblake <at> redhat.com>, Alan Curry <pacman-cu <at> kosh.dhis.org>
Subject: Re: bug#10016: ls -lk is wrong
Date: Sat, 12 Nov 2011 10:46:45 +0100

Paul Eggert wrote:
> On 11/11/11 13:10, Jim Meyering wrote:
>> Do you feel like writing the patch?
>
> Sure.  I wrote and pushed the following.
> The test case isn't elegant, but at least it catches the bug.

That was quick.  Thanks!

Message #68 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: abdallah clark <clark-adc <at> clear.net>
To: Eric Blake <eblake <at> redhat.com>
Cc: 9939 <at> debbugs.gnu.org, Bob Proulx <bob <at> proulx.com>
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls> and <du>
Date: Tue, 15 Nov 2011 09:29:11 -0600

Gentlemen:

This situation is frustrating, but I'll exercise patience and comply.
May I suggest, first of all, that if someone tells you they don't
understand, trust them. If you were to show that SIZE paragraph to
someone in your families who were not familiar with *nix, then it may
be clearer for you what I am going through. I keep telling you that I
am a Newbie to *nix, but that isn't getting into your comments.

So, from a layman's point of view, you are suffering "expert-itis,"
being very comfortable with the subject and forgetting what it was
like in your beginnings. Also, being terse will often obfuscate
material rather than keeping it succinct. I gave up on *nix back in
the 90's after seeing a presentation from Red Hat because it was too
"messy" to implement on my own and came to te erroneous conclusion
that it wasn't going to go very far. Well, I was wrong and not ashamed
to admit it. I'm taking a course, rather than trying to learn it on my
own, to make sure I get past any parts that are still messy. I am also
not ashamed to admit that there are problems here and my contribution
to resolving them may be minuscule. Like a reporter slamming against
the Blue Wall of a corrupt police department, I'm getting a headache
from the "That's the way we've always done it in *nix and no one else
has complained about it" syndrome here [no corruption implied,
however].

So, here goes.

       SIZE may be (or may be an integer optionally followed by) one
of following:
       KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T,
P, E, Z, Y.

That's a run-on sentence, jammed up with at least three different
ideas that need to be separated. It also implies that one could use
1000*1000 and 1024*1024, which is certainly not the case. Talk about
what <size> does first, in just one sentence, if you have to, but let
it be separate. You can eat a plate with a "rainbow of food" for
health's sake by taking up each kind on your fork at the same time,
but most people are accustomed to taking up a forkful of one kind at a
time, yes?

Explain what the suffixes mean in a separate sentence. My preference
would actually be to omit that explanation. But you must recognize
that a Newbie is not going to intuitively accept that M = MiB. We're
used to kilograms being 1000 grams, which is the convention in the
real world, but not the "UNIX universe." (I ought to link this to
Orwellian/1984, but I'll refrain.) We may not be on the metric system
exclusively, but that sort of explanation is going to be confusing. M
= MiB looks too much like 2 + 2 = 5.

Also, the <ls --block-size> command should be tested to make sure it
works with KiB, MiB, GiB, etc. in a consistent manner. I didn't try it
exhaustively, since I had already been confused enough.

You really should change the man pages to be consistent, for our sake.
Run them through an editor and search/replace that bit, since "being
terse" about two characters-- <iB>-- is really not a big deal
nowadays. Ensuring clarity validates this point as much as
substituting a variable <a> with <monthly_Income> now that we are no
longer looking at 64 KB of RAM limitations in computer programming
languages. Other commands I have found since looking at <ls> do not
fail to implement this convention of KiB, MiB, etc., also. The man
pages should "read the same."

Examples would be good, at least one simple case and one complex case.
I had difficulty with the <tee> command because only a complex example
was given. Many commands give no examples at all in their man pages.
Maybe it's a manpower issue, but <ls> is so important, let it be a
valuable template for many other commands-- your best-case scenario
and THE model.

POSIX and BNF are intermediate or advanced topics. I have no ideas on
what to do about them for this case. I have a B.S., not a Ph.D., in
Computer Science. It was about breadth, not depth.

I'll end here, before I'm blamed for giving too much text again.

Thanks for your consideration.

         All the best to you and yours,
                 Abdallah Clark








On Thu, Nov 10, 2011 at 2:22 PM, Eric Blake <eblake <at> redhat.com> wrote:
> On 11/10/2011 01:07 PM, abdallah clark wrote:
>>
>> Gentlemen:
>>
>> That was already done, to no avail. Has anyone actually looked at that
>> paragraph on SIZE and thought about what it means?
>
> [Please don't top-post on technical lists.]
>
> The paragraph in question:
>
> SIZE may be (or may be an integer optionally followed by) one of following:
> KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.
>
> That first sentence means there are three valid forms:
>
> SIZE may be one of the following (suffix-only case)
> SIZE may be an integer (size-only case)
> SIZE may be an integer followed by one of the following
> (size-and-suffix-case)
>
> Next are the possible suffixes:
>
> KB is a suffix for 1000 (kilobytes)
> K is a suffix for 1024 (kibibytes)
> not listed: KiB is a synonym for K (the info pages list this, but as the
> --help output tries to be terse, we skip the longer spelling here)
>
> MB is a suffix for 1000*1000 (megabytes)
> M is a suffix for 1024*1024 (mebibytes)
> again, not listed is MiB as a synonym for M
>
> And so on means that:
>
> GB is a suffix for 1000*1000*1000 (gigabytes)
> G and GiB are a suffix for 1024*1024*1024 (GiB)
>
> Or in a rough BNF form,
>
> SIZE : integer [SUFFIX]
>     | SUFFIX
> SUFFIX : LETTER /* in powers of 1024 */
>       | LETTER 'B' /* in powers of 1000 */
>       | LETTER 'i' 'B' /* in powers of 1024 */
> LETTER : 'K' /* base ^ 1, for 1024 or 1000 */
>       | 'M' /* base ^ 2, for 1024*1024 or 1000*1000 */
>       | 'G' /* base ^ 3 */
>       | 'T' /* base ^ 4 */
>       | 'P' /* base ^ 5 */
>       | 'E' /* base ^ 6 */
>       | 'Z' /* base ^ 7 */
>       | 'Y' /* base ^ 8 */
>
> (and if you have a disk larger than 1Y, I'm jealous)
>
>
> I followed that fairly easily, but I've also read the code that implements
> it, so I'm unfortunately biased.  I'm not sure where you are having
> difficulties following it, which is why we're asking that you provide an
> alternative wording, at which point we can evaluate the two wordings and
> pick the strongest of both approaches.
>
> --
> Eric Blake   eblake <at> redhat.com    +1-801-349-2682
> Libvirt virtualization library http://libvirt.org
>

Message #71 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
To: abdallah clark <clark-adc <at> clear.net>
Cc: 9939 <at> debbugs.gnu.org, Bob Proulx <bob <at> proulx.com>
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls> and <du>
Date: Tue, 15 Nov 2011 08:46:56 -0700

[Message part 1 (text/plain, inline)]

[please don't top-post on technical lists]

On 11/15/2011 08:29 AM, abdallah clark wrote:
> So, here goes.
> 
>        SIZE may be (or may be an integer optionally followed by) one
> of following:
>        KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T,
> P, E, Z, Y.
> 
> That's a run-on sentence, jammed up with at least three different
> ideas that need to be separated. It also implies that one could use
> 1000*1000 and 1024*1024, which is certainly not the case. Talk about
> what <size> does first, in just one sentence, if you have to, but let
> it be separate.

Paul did just that:
https://lists.gnu.org/archive/html/bug-coreutils/2011-11/msg00088.html

The wording in the next release of coreutils will have SIZE described in
a separate sentence from the description of suffixes, and will include
an example.

 SIZE is an integer with an optional suffix (example: 10MB).  Suffixes are:
 KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.

> Explain what the suffixes mean in a separate sentence. My preference
> would actually be to omit that explanation. But you must recognize
> that a Newbie is not going to intuitively accept that M = MiB.

If you want to know as much as possible about coreutils, then the man
page already tells you to read 'info coreutils "ls invocation"', and on
the info page, we DO give lots of examples and describe M vs. MB vs. MiB.

But for a short --help example (which in turn is copied into the man
page), it is sufficient to merely document the shortest (and most
popular) two forms: a suffix letter in isolation is based on units of
1024, and a suffix letter + B is based on units of 1000.

If you can provide a one-liner phrasing of that concept which reads
better than what is already there, then please do so.

> You really should change the man pages to be consistent, for our sake.

They already are consistent.  'man ls' and 'ls --help' give the same
information.  That information may not be complete (for completeness,
use 'info coreutils'), but what is there is accurate.

-- 
Eric Blake   eblake <at> redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

[signature.asc (application/pgp-signature, attachment)]

Message #74 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: abdallah clark <clark-adc <at> clear.net>
Cc: 9939 <at> debbugs.gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls> and <du>
Date: Tue, 15 Nov 2011 08:32:55 -0800

On 11/15/11 07:29, abdallah clark wrote:
> Maybe it's a manpower issue

We are short of people and time, yes.  I've found your
comments to be helpful in pointing out places where the
--help output (man pages) could be clearer.  We've fixed the SIZE sentence
and I'd like to go onto the next issue.  In your long message
about this <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=9939#17>
you write:

  Also, when I run <ls -alsi --si>, the results have <K> or <M> or <G>
  as a suffix on the filesize amounts, but the similar command <ls
  -alsih> gives <k> or <m> or <g>.

That's not the behavior I get.  First, I get uppercase M and G with
either option set.  Second, I get lowercase k with --si, and uppercase
K with -h.  But this is because SI uses lowercase k, whereas binary
prefixes use uppercase K (yes, it's silly, but it's standard :-).

The above quotation seems to be more a complaint about the *behavior*
than about the *documentation*, and so I hope I've explained the
behavior.  This explanation is also in the full manual.  I don't
see a need for correcting the --help output (man pages) as they're
intended to be succinct summaries of the full manual, more reminders
to the expert than introduction to novices as it were.

Message #77 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: "Voelker, Bernhard" <bernhard.voelker <at> siemens-enterprise.com>
To: Eric Blake <eblake <at> redhat.com>, abdallah clark <clark-adc <at> clear.net>
Cc: "9939 <at> debbugs.gnu.org" <9939 <at> debbugs.gnu.org>, Bob Proulx <bob <at> proulx.com>
Subject: RE: bug#9939: Problems with the SIZE description in man pages for
	<ls>	and <du>
Date: Tue, 15 Nov 2011 17:45:53 +0100

Eric Blake wrote:

> SIZE is an integer with an optional suffix (example: 10MB).  Suffixes are:
> KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.

I didn't jump in the discussion yet, but personally also find the
multiplication confusing. I know, there's already been a patch, but
what about the following?

Bye,
Berny

From d8819575ede3c4803787030869edaf865bd40711 Mon Sep 17 00:00:00 2001
From: Bernhard Voelker <mail <at> bernhard-voelker.de>
Date: Tue, 15 Nov 2011 17:42:26 +0100
Subject: [PATCH] * src/system.h (emit_size_note): Reword for clarity again

---
 src/system.h |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/src/system.h b/src/system.h
index 1cbde92..afb1a40 100644
--- a/src/system.h
+++ b/src/system.h
@@ -517,7 +517,7 @@ emit_size_note (void)
 {
   fputs (_("\n\
 SIZE is an integer with an optional suffix (example: 10MB).  Suffixes are:\n\
-KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.\n\
+KB (1000), K (1024), MB (1000KB), M (1024K), and so on for G, T, P, E, Z, Y.\n\
 "), stdout);
 }
 
-- 
1.7.3.4

Message #80 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: bug-coreutils <at> gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls>	and <du>
Date: Tue, 15 Nov 2011 08:52:49 -0800

On 11/15/11 08:45, Voelker, Bernhard wrote:
> -KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.\n\
> +KB (1000), K (1024), MB (1000KB), M (1024K), and so on for G, T, P, E, Z, Y.\n\

That would be fine with me.  (I find them equally confusing. :-)

Message #83 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Jim Meyering <jim <at> meyering.net>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 9939 <at> debbugs.gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls>	and <du>
Date: Tue, 15 Nov 2011 18:08:07 +0100

Paul Eggert wrote:

> On 11/15/11 08:45, Voelker, Bernhard wrote:
>> -KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.\n\
>> +KB (1000), K (1024), MB (1000KB), M (1024K), and so on for G, T, P, E, Z, Y.\n\
>
> That would be fine with me.  (I find them equally confusing. :-)

I'm 60/40 for the use of "*" (i.e., 1000*1000), because with it,
each comma-separated item is self-contained.

In your replacement, each of MB and M relies on the
just-defined "KB" or "K" notation.  Without that context,
they may be misinterpreted.

Message #86 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Ruediger Meier <sweet_f_a <at> gmx.de>
To: bug-coreutils <at> gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls>	and <du>
Date: Tue, 15 Nov 2011 19:12:16 +0100

On Tuesday 15 November 2011, Jim Meyering wrote:
> Paul Eggert wrote:
> > On 11/15/11 08:45, Voelker, Bernhard wrote:
> >> -KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T,
> >> P, E, Z, Y.\n\ +KB (1000), K (1024), MB (1000KB), M (1024K), and
> >> so on for G, T, P, E, Z, Y.\n\
> >
> > That would be fine with me.  (I find them equally confusing. :-)
>
> I'm 60/40 for the use of "*" (i.e., 1000*1000), because with it,
> each comma-separated item is self-contained.
>
> In your replacement, each of MB and M relies on the
> just-defined "KB" or "K" notation.  Without that context,
> they may be misinterpreted.


I also think the multiplier version is a bit easier to read.
My preferred one would be something like this: 

-SIZE is an integer with an optional suffix (example: 10MB).  Suffixes are:\n\
-KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.\n\
+SIZE is an integer with an optional unit, e.g. 10M (1024*1024). Valid units\n\
+are K, M, G, T, P, E, Z, Y (powers of 1024) or KB, MB, ... (powers of 1000).\n\


I guess if we've had 20 chars more or even a whole line then it could be
slightly polished to be really readable and clearly. ;)


cu,
Rudi

Message #89 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
To: Ruediger Meier <sweet_f_a <at> gmx.de>
Cc: 9939 <at> debbugs.gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls>	and <du>
Date: Tue, 15 Nov 2011 11:20:50 -0700

[Message part 1 (text/plain, inline)]

On 11/15/2011 11:12 AM, Ruediger Meier wrote:
> I also think the multiplier version is a bit easier to read.
> My preferred one would be something like this: 
> 
> -SIZE is an integer with an optional suffix (example: 10MB).  Suffixes are:\n\
> -KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.\n\
> +SIZE is an integer with an optional unit, e.g. 10M (1024*1024). Valid units\n\
> +are K, M, G, T, P, E, Z, Y (powers of 1024) or KB, MB, ... (powers of 1000).\n\

Not quite accurate on 10M.  But I think it does read a bit better.  How
about this tweak to fix the example, while still fitting in the line
limitations:

+SIZE is an integer and optional unit (example: 10M is 10*1024*1024).
Units\n\
+are K, M, G, T, P, E, Z, Y (powers of 1024) or KB, MB, ... (powers of
1000).\n\

-- 
Eric Blake   eblake <at> redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

[signature.asc (application/pgp-signature, attachment)]

Message #92 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Jim Meyering <jim <at> meyering.net>
To: Eric Blake <eblake <at> redhat.com>
Cc: 9939 <at> debbugs.gnu.org, Ruediger Meier <sweet_f_a <at> gmx.de>
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls>	and <du>
Date: Tue, 15 Nov 2011 19:25:29 +0100

Eric Blake wrote:

> On 11/15/2011 11:12 AM, Ruediger Meier wrote:
>> I also think the multiplier version is a bit easier to read.
>> My preferred one would be something like this:
>>
>> -SIZE is an integer with an optional suffix (example: 10MB).  Suffixes are:\n\
>> -KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.\n\
>> +SIZE is an integer with an optional unit, e.g. 10M (1024*1024). Valid units\n\
>> +are K, M, G, T, P, E, Z, Y (powers of 1024) or KB, MB, ... (powers of 1000).\n\
>
> Not quite accurate on 10M.  But I think it does read a bit better.  How
> about this tweak to fix the example, while still fitting in the line
> limitations:
>
> +SIZE is an integer and optional unit (example: 10M is 10*1024*1024).  Units\n\
> +are K, M, G, T, P, E, Z, Y (powers of 1024) or KB, MB,... (powers of 1000).\n\

Go for it.  Thanks to both of you.

Message #95 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
To: Jim Meyering <jim <at> meyering.net>
Cc: 9939 <at> debbugs.gnu.org, Ruediger Meier <sweet_f_a <at> gmx.de>
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls>	and <du>
Date: Tue, 15 Nov 2011 11:57:35 -0700

[Message part 1 (text/plain, inline)]

On 11/15/2011 11:25 AM, Jim Meyering wrote:
> Eric Blake wrote:
> 
>> On 11/15/2011 11:12 AM, Ruediger Meier wrote:
>>> I also think the multiplier version is a bit easier to read.
>>> My preferred one would be something like this:
>>>
>>> -SIZE is an integer with an optional suffix (example: 10MB).  Suffixes are:\n\
>>> -KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.\n\
>>> +SIZE is an integer with an optional unit, e.g. 10M (1024*1024). Valid units\n\
>>> +are K, M, G, T, P, E, Z, Y (powers of 1024) or KB, MB, ... (powers of 1000).\n\
>>
>> Not quite accurate on 10M.  But I think it does read a bit better.  How
>> about this tweak to fix the example, while still fitting in the line
>> limitations:
>>
>> +SIZE is an integer and optional unit (example: 10M is 10*1024*1024).  Units\n\
>> +are K, M, G, T, P, E, Z, Y (powers of 1024) or KB, MB,... (powers of 1000).\n\
> 
> Go for it.  Thanks to both of you.

Ruediger, if you're okay with this commit being in your name, then I
will push this:


From e36e6f2c6e95d6e23be805f7bab6c596b1818d22 Mon Sep 17 00:00:00 2001
From: Ruediger Meier <sweet_f_a <at> gmx.de>
Date: Tue, 15 Nov 2011 11:55:23 -0700
Subject: [PATCH] ls: another reword of generic size note

* src/system.h (emit_size_note): Use "unit" rather than "suffix",
and move multiplication to example instead of in suffix list.
See additional discussion in Bug#9939.
---
 src/system.h |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/system.h b/src/system.h
index 1cbde92..ae8dcc2 100644
--- a/src/system.h
+++ b/src/system.h
@@ -516,8 +516,8 @@ static inline void
 emit_size_note (void)
 {
   fputs (_("\n\
-SIZE is an integer with an optional suffix (example: 10MB).  Suffixes
are:\n\
-KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E,
Z, Y.\n\
+SIZE is an integer and optional unit (example: 10M is 10*1024*1024).
Units\n\
+are K, M, G, T, P, E, Z, Y (powers of 1024) or KB, MB, ... (powers of
1000).\n\
 "), stdout);
 }

-- 
1.7.7.1

-- 
Eric Blake   eblake <at> redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

[signature.asc (application/pgp-signature, attachment)]

Message #98 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Ruediger Meier <sweet_f_a <at> gmx.de>
To: bug-coreutils <at> gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls>	and <du>
Date: Tue, 15 Nov 2011 20:09:23 +0100

On Tuesday 15 November 2011, Eric Blake wrote:
> On 11/15/2011 11:25 AM, Jim Meyering wrote:
> > Eric Blake wrote:
> >> On 11/15/2011 11:12 AM, Ruediger Meier wrote:
> >>> I also think the multiplier version is a bit easier to read.
> >>> My preferred one would be something like this:
> >>>
> >>> -SIZE is an integer with an optional suffix (example: 10MB). 
> >>> Suffixes are:\n\ -KB 1000, K 1024, MB 1000*1000, M 1024*1024, and
> >>> so on for G, T, P, E, Z, Y.\n\ +SIZE is an integer with an
> >>> optional unit, e.g. 10M (1024*1024). Valid units\n\ +are K, M, G,
> >>> T, P, E, Z, Y (powers of 1024) or KB, MB, ... (powers of
> >>> 1000).\n\
> >>
> >> Not quite accurate on 10M.  But I think it does read a bit better.

Hehe, I guess I'd given up to fit it into the line if I had noticed it 
after 20 minutes trying hard tweaking it. :)

> >>  How about this tweak to fix the example, while still fitting in
> >> the line limitations:
>>
> >> +SIZE is an integer and optional unit (example: 10M is
> >> 10*1024*1024).  Units\n\ +are K, M, G, T, P, E, Z, Y (powers of
> >> 1024) or KB, MB,... (powers of 1000).\n\
> >
> > Go for it.  Thanks to both of you.
>
> Ruediger, if you're okay with this commit being in your name, then I
> will push this:

Yes, thanks for the fame!


cu,
Rudi

Message #101 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Rüdiger Meier <sweet_f_a <at> gmx.de>
To: bug-coreutils <at> gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls>	and <du>
Date: Wed, 16 Nov 2011 03:35:21 +0100

On Tuesday 15 November 2011, Eric Blake wrote:

> From e36e6f2c6e95d6e23be805f7bab6c596b1818d22 Mon Sep 17 00:00:00
> [...]
> -SIZE is an integer with an optional suffix (example: 10MB). 
> Suffixes are:\n\
> -KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P,
> E, Z, Y.\n\
> +SIZE is an integer and optional unit (example: 10M is 10*1024*1024).
> Units\n\
> +are K, M, G, T, P, E, Z, Y (powers of 1024) or KB, MB, ... (powers
> of 1000).\n\

Reviewing this I see that the case "unit only without int" is not 
documented now. This has been changed already in 50e5d024.
Probably no problem because it's only --help and not info page. Just 
want to note that.

Saying "and/or" instead of "and" could make it narrowly but still not 
100% exactly and more confusing again.

cu,
Rudi

Message #104 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
To: Rüdiger Meier <sweet_f_a <at> gmx.de>
Cc: 9939 <at> debbugs.gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls>	and <du>
Date: Wed, 16 Nov 2011 07:48:38 -0700

[Message part 1 (text/plain, inline)]

On 11/15/2011 07:35 PM, Rüdiger Meier wrote:
> On Tuesday 15 November 2011, Eric Blake wrote:
> 
>> From e36e6f2c6e95d6e23be805f7bab6c596b1818d22 Mon Sep 17 00:00:00
>> [...]
>> -SIZE is an integer with an optional suffix (example: 10MB). 
>> Suffixes are:\n\
>> -KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P,
>> E, Z, Y.\n\
>> +SIZE is an integer and optional unit (example: 10M is 10*1024*1024).
>> Units\n\
>> +are K, M, G, T, P, E, Z, Y (powers of 1024) or KB, MB, ... (powers
>> of 1000).\n\
> 
> Reviewing this I see that the case "unit only without int" is not 
> documented now. This has been changed already in 50e5d024.

Yes, and we made the change intentionally.

> Probably no problem because it's only --help and not info page. Just 
> want to note that.

Well, it's also the man page; but again, --help and man output are for
concise references, focusing on just enough to get the job done, whereas
the info page is the full documentation and does cover the alternative.

> 
> Saying "and/or" instead of "and" could make it narrowly but still not 
> 100% exactly and more confusing again.

I think we've already hit a good balance of conciseness vs.
understandability, and tweaking things to mention unit without int in
the --help output seems counterproductive at this point.

-- 
Eric Blake   eblake <at> redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

[signature.asc (application/pgp-signature, attachment)]

Message #107 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Assaf Gordon <assafgordon <at> gmail.com>
To: 9939 <at> debbugs.gnu.org
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
 <ls> and <du>
Date: Mon, 15 Oct 2018 08:36:24 -0600

tags 9939 fixed
close 9939
stop

(triaging old bugs)

Hello,

On 02/11/11 04:40 AM, abdallah clark wrote:
> I am taking a course in Red Hat Enterprise Linux and have met with
> some difficulty interpreting the following statement in the man pages
> for several commands:
>
>      SIZE may be (or may be an integer optionally followed by) one of
>      following: KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on
>      for G, T, P, E, Z, Y.


[ ... dozens of messages and several commits later ... ]

On 16/11/11 07:48 AM, Eric Blake wrote:
> I think we've already hit a good balance of conciseness vs.
> understandability, and tweaking things to mention unit without int in
> the --help output seems counterproductive at this point.

As such, I'm closing this bug as 'fixed'.

regards,
 - assaf

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.