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

[Pádraig Brady]

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.