GNU bug report logs - #9939
Problems with the SIZE description in man pages for <ls> and <du>

Previous Next

Full log

Message #56 received at 9939 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 9939 <at> debbugs.gnu.org, abdallah clark <clark-adc <at> clear.net>,
	Bob Proulx <bob <at> proulx.com>
Subject: Re: bug#9939: Problems with the SIZE description in man pages for
	<ls>	and <du>
Date: Thu, 10 Nov 2011 14:36:48 -0700

On 11/10/2011 02:26 PM, Paul Eggert wrote:
> 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.

Hmm, and we already have "-k like --block-size=1K", rather than "like 
--block-size=K", so we are already gearing users towards always 
providing the integer.  Like you said, your wording is incomplete, but 
still covers the most common use cases.  I can live with it.

-- 
Eric Blake   eblake <at> redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.