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

[Eric Blake]

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