bug#16922: df --si -h should emit a warning

[Pádraig Brady]

On 03/03/2014 08:00 AM, Bernhard Voelker wrote:
> On 03/03/2014 04:02 AM, Pádraig Brady wrote:
>> Very few read info pages, and anyway in this case we should be clear at the 
>> man page level.
>>
>> Mateusz stated the issue was that on a quick glance, the --si option wasn't 
>> described
>> well enough in isolation. Likewise, the description of -h requires reading 
>> that of -H
>> to know the power used. So hopefully the attached patch fixes this and more.
> 
> Hi Padraig,
> 
> great idea to use an example, thanks.
> It's clearer than before:
> 
>   -h, --human-readable  print abbreviated sizes in powers of 1024 (e.g. 1023M)
>   -H, --si              print abbreviated sizes in powers of 1000 (e.g. 1.1G)
> 
> However, I still see 2 problems:
> 
> a) The reader doesn't know the code, and therefore doesn't know
> that both numbers originate from a calculation based on the same
> number:

True. I considered mentioning that, but the user doesn't really _need_
to know that. The more mathematically inclined will see it immediately,
but that's a small advantage and shouldn't be needed as we wanted these
descriptions to be meaningful in isolation anyway.

> 
>> +      const int example_size = 1023*1024*1024;
> 
> I would be good to let the user know that.
> 
> b) Both numbers are suffixed with the one-character notation (M,G),
> i.e. comparing that to the explanation of these below in the usage
> text, the reader may be confused again:
> 
>   SIZE is an integer and optional unit (example: 10M is 10*1024*1024).  Units
>   are K, M, G, T, P, E, Z, Y (powers of 1024) or KB, MB, ... (powers of 1000).

So SIZE here refers to the _input_ argument mentioned previously in the --help.
We might make this a bit more clear with BSIZE, but this same note is refactored
for use by df, du, ls, split, truncate. truncate(1) for example uses it to refer
to both a threshold and block size. Perhaps we should clarify like:

    The SIZE argument is an integer and optional unit (example: 10K is 10*1024).
    Units are K,M,G,T,P,E,Z,Y (powers of 1024) or KB,MB, ... (powers of 1000).

> Well, in the texinfo manual, it's mentioned that `M' can stand both for
> a mebibyte (in the -h case) as well as for a megabyte (in the -H case).
> But somehow this is confusing: when used in SIZE, i.e. together with -B
> as input option, then the user must use 'M' vs. 'MB' to make clear whether
> to use powers of 1024 vs. 1000, while df(1) doesn't make that difference
> in the output with -h vs. -H.
> 
>   $ src/df -h / | sed 1d
>   /dev/sdb2        20G  8.7G   10G  47% /
> 
>   $ src/df -H / | sed 1d
>   /dev/sdb2        22G  9.3G   11G  47% /
> 
> Shouldn't it say 22GB etc. in the latter -H case? And "1.1GB" in
> the above usage text?  Now I'm confused, too ... ;-/
> Monday morning syndrome?

It is confusing unfortunately.
I previously summarized some of these inconsistencies here:
http://lists.gnu.org/archive/html/coreutils/2012-09/msg00179.html

Who would have thought that df would have so many inconsistencies and edge 
cases :/

thanks,
Pádraig.