Re: [PATCH] doc: du - clarify default blocksize in usage/manpage

[Pádraig Brady]

While this patch is more verbose than my previous patch
in this thread, it is more accurate. So let's drop the
previous one. However...

The info was inaccurate for ls, so I've split the SIZE
specific info into a new emit_size_note(). That also
allows refactoring to be done in split and truncate.

I've also changed the text in emit_blocksize_note() a bit.

Also I sync'd the SIZE text used in the info docs,
which is now more accurate.

cheers,
Pádraig

>From 43ee481910b5949941a6f7724c754c646875488f Mon Sep 17 00:00:00 2001
From: =?utf-8?q?Ond=C5=99ej=20Va=C5=A1=C3=ADk?= <address@hidden>
Date: Thu, 10 Sep 2009 12:33:41 +0100
Subject: [PATCH] doc: improve various BLOCKSIZE and SIZE help

* doc/coreutils.texi (multiplierSuffixes): Mention that
the suffix can be specified without a leading number
* src/split.c (usage): Refactor SIZE help to within a function
* src/truncate.c (usage): Likewise
* src/ls.c (usage): Likewise
* src/df.c (usage): Likewise. Also add a function with BLOCKSIZE help
* src/du.c (usage): Likewise.
* src/system.h: Define 2 functions to emit common help text
This was prompted by https://bugzilla.redhat.com/show_bug.cgi?id=511188
---
 doc/coreutils.texi |   15 ++++-----------
 src/df.c           |    6 ++----
 src/du.c           |    6 ++----
 src/ls.c           |    7 ++-----
 src/split.c        |    7 +------
 src/system.h       |   19 +++++++++++++++++++
 src/truncate.c     |    5 +----
 7 files changed, 31 insertions(+), 34 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 86394a1..1340fd4 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -618,15 +618,8 @@ from the shell.
 @end macro
 
 @macro multiplierSuffixes{varName}
address@hidden
-Appending @samp{b} multiplies @var{\varName\} by 512,
address@hidden by 1000, @samp{K} by 1024,
address@hidden by 1000*1000, @samp{M} by 1024*1024,
address@hidden by 1000*1000*1000, @samp{G} by 1024*1024*1024,
-and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}.
address@hidden ignore
address@hidden is a number which may have one of the following
-multiplicative suffixes:
address@hidden may be, or may be an integer optionally followed by,
+one of the following multiplicative suffixes:
 @example
 @samp{b}  =>            512 ("blocks")
 @samp{KB} =>           1000 (KiloBytes)
@@ -641,8 +634,8 @@ and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and 
@samp{Y}.
 
 @c FIXME: same as above, but no ``blocks'' line.
 @macro multiplierSuffixesNoBlocks{varName}
address@hidden is a number which may have one of the following
-multiplicative suffixes:
address@hidden may be, or may be an integer optionally followed by,
+one of the following multiplicative suffixes:
 @example
 @samp{KB} =>           1000 (KiloBytes)
 @samp{K}  =>           1024 (KibiBytes)
diff --git a/src/df.c b/src/df.c
index 86fd0e3..6cda35e 100644
--- a/src/df.c
+++ b/src/df.c
@@ -833,10 +833,8 @@ Mandatory arguments to long options are mandatory for 
short options too.\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
-      fputs (_("\n\
-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\
-"), stdout);
+      emit_blocksize_note ("DF");
+      emit_size_note ();
       emit_bug_reporting_address ();
     }
   exit (status);
diff --git a/src/du.c b/src/du.c
index 9da901a..321d30f 100644
--- a/src/du.c
+++ b/src/du.c
@@ -330,10 +330,8 @@ Mandatory arguments to long options are mandatory for 
short options too.\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
-      fputs (_("\n\
-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\
-"), stdout);
+      emit_blocksize_note ("DU");
+      emit_size_note ();
       emit_bug_reporting_address ();
     }
   exit (status);
diff --git a/src/ls.c b/src/ls.c
index 553090d..b62ea12 100644
--- a/src/ls.c
+++ b/src/ls.c
@@ -4543,7 +4543,7 @@ Mandatory arguments to long options are mandatory for 
short options too.\n\
   -b, --escape               print octal escapes for nongraphic characters\n\
 "), stdout);
       fputs (_("\
-      --block-size=SIZE      use SIZE-byte blocks\n\
+      --block-size=SIZE      use SIZE-byte blocks.  See SIZE format below\n\
   -B, --ignore-backups       do not list implied entries ending with ~\n\
   -c                         with -lt: sort by, and show, ctime (time of 
last\n\
                                modification of file status information)\n\
@@ -4664,10 +4664,7 @@ Mandatory arguments to long options are mandatory for 
short options too.\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
-      fputs (_("\n\
-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\
-"), stdout);
+      emit_size_note ();
       fputs (_("\
 \n\
 By default, color is not used to distinguish types of files.  That is\n\
diff --git a/src/split.c b/src/split.c
index 45c24aa..e02f743 100644
--- a/src/split.c
+++ b/src/split.c
@@ -126,12 +126,7 @@ Mandatory arguments to long options are mandatory for 
short options too.\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
-      fputs (_("\
-\n\
-SIZE may have a multiplier suffix:\n\
-b 512, kB 1000, K 1024, MB 1000*1000, M 1024*1024,\n\
-GB 1000*1000*1000, G 1024*1024*1024, and so on for T, P, E, Z, Y.\n\
-"), stdout);
+      emit_size_note ();
       emit_bug_reporting_address ();
     }
   exit (status);
diff --git a/src/system.h b/src/system.h
index 3a05501..878a001 100644
--- a/src/system.h
+++ b/src/system.h
@@ -616,6 +616,25 @@ ptr_align (void const *ptr, size_t alignment)
     ? false : (((Accum) = (Accum) * 10 + (Digit_val)), true))          \
   )
 
+static inline void
+emit_size_note (void)
+{
+      fputs (_("\n\
+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\
+"), stdout);
+}
+
+static inline void
+emit_blocksize_note (char const *program)
+{
+      printf (_("\n\
+If none of the environment variables BLOCKSIZE, BLOCK_SIZE or %s_BLOCK_SIZE\n\
+or --block-size option specify SIZE, display in units of 1024 bytes.\n\
+(or 512 bytes if the POSIXLY_CORRECT environment variable is set)\n\
+"), program);
+}
+
 #include "hard-locale.h"
 static inline void
 emit_bug_reporting_address (void)
diff --git a/src/truncate.c b/src/truncate.c
index 0cb7b35..7778379 100644
--- a/src/truncate.c
+++ b/src/truncate.c
@@ -124,10 +124,7 @@ Mandatory arguments to long options are mandatory for 
short options too.\n\
   -s, --size=SIZE        use this SIZE\n"), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
-      fputs (_("\n\
-SIZE is a number which may be followed by one of the following suffixes:\n\
-KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.\n\
-"), stdout);
+      emit_size_note ();
       fputs (_("\n\
 SIZE may also be prefixed by one of the following modifying characters:\n\
 `+' extend by, `-' reduce by, `<' at most, `>' at least,\n\
-- 
1.6.2.5