bug#9939: Problems with the SIZE description in man pages for <ls> and <du>

[abdallah clark]

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 <address@hidden> 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   address@hidden    +1-801-349-2682
> Libvirt virtualization library http://libvirt.org
>