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

Previous Next

Full log

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

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Eric Blake <eblake <at> redhat.com>
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 13:26:59 -0800

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.

Previous Next

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