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

[Eric Blake]

On 11/15/2011 07:35 PM, Rüdiger Meier wrote:
> On Tuesday 15 November 2011, Eric Blake wrote:
> 
>> From e36e6f2c6e95d6e23be805f7bab6c596b1818d22 Mon Sep 17 00:00:00
>> [...]
>> -SIZE is an integer with an optional suffix (example: 10MB). 
>> Suffixes are:\n\
>> -KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P,
>> E, Z, Y.\n\
>> +SIZE is an integer and optional unit (example: 10M is 10*1024*1024).
>> Units\n\
>> +are K, M, G, T, P, E, Z, Y (powers of 1024) or KB, MB, ... (powers
>> of 1000).\n\
> 
> Reviewing this I see that the case "unit only without int" is not 
> documented now. This has been changed already in 50e5d024.

Yes, and we made the change intentionally.

> Probably no problem because it's only --help and not info page. Just 
> want to note that.

Well, it's also the man page; but again, --help and man output are for
concise references, focusing on just enough to get the job done, whereas
the info page is the full documentation and does cover the alternative.

> 
> Saying "and/or" instead of "and" could make it narrowly but still not 
> 100% exactly and more confusing again.

I think we've already hit a good balance of conciseness vs.
understandability, and tweaking things to mention unit without int in
the --help output seems counterproductive at this point.

-- 
Eric Blake   address@hidden    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature