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

[Eric Blake]

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