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

[Paul Eggert]

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.