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

Previous Next

Full log

View this message in rfc822 format

From: Eric Blake <eblake <at> redhat.com>
To: abdallah clark <clark-adc <at> clear.net>
Cc: 9939 <at> debbugs.gnu.org, Bob Proulx <bob <at> proulx.com>
Subject: bug#9939: Problems with the SIZE description in man pages for <ls> and <du>
Date: Tue, 15 Nov 2011 08:46:56 -0700

[Message part 1 (text/plain, inline)]

[please don't top-post on technical lists]

On 11/15/2011 08:29 AM, abdallah clark wrote:
> So, here goes.
> 
>        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's a run-on sentence, jammed up with at least three different
> ideas that need to be separated. It also implies that one could use
> 1000*1000 and 1024*1024, which is certainly not the case. Talk about
> what <size> does first, in just one sentence, if you have to, but let
> it be separate.

Paul did just that:
https://lists.gnu.org/archive/html/bug-coreutils/2011-11/msg00088.html

The wording in the next release of coreutils will have SIZE described in
a separate sentence from the description of suffixes, and will include
an example.

 SIZE is an integer with an optional suffix (example: 10MB).  Suffixes are:
 KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.

> Explain what the suffixes mean in a separate sentence. My preference
> would actually be to omit that explanation. But you must recognize
> that a Newbie is not going to intuitively accept that M = MiB.

If you want to know as much as possible about coreutils, then the man
page already tells you to read 'info coreutils "ls invocation"', and on
the info page, we DO give lots of examples and describe M vs. MB vs. MiB.

But for a short --help example (which in turn is copied into the man
page), it is sufficient to merely document the shortest (and most
popular) two forms: a suffix letter in isolation is based on units of
1024, and a suffix letter + B is based on units of 1000.

If you can provide a one-liner phrasing of that concept which reads
better than what is already there, then please do so.

> You really should change the man pages to be consistent, for our sake.

They already are consistent.  'man ls' and 'ls --help' give the same
information.  That information may not be complete (for completeness,
use 'info coreutils'), but what is there is accurate.

-- 
Eric Blake   eblake <at> redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

[signature.asc (application/pgp-signature, attachment)]

Previous Next

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