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

7 files changed, 31 insertions, 34 deletions

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 93f939019..22d307a99 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -618,15 +618,8 @@ from the shell.
 @end macro
 
 @macro multiplierSuffixes{varName}
-@ignore
-Appending @samp{b} multiplies @var{\varName\} by 512,
-@samp{kB} by 1000, @samp{K} by 1024,
-@samp{MB} by 1000*1000, @samp{M} by 1024*1024,
-@samp{GB} 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}.
-@end ignore
-@var{\varName\} is a number which may have one of the following
-multiplicative suffixes:
+@var{\varName\} 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}
-@var{\varName\} is a number which may have one of the following
-multiplicative suffixes:
+@var{\varName\} 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 86fd0e32e..6cda35e75 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 9da901a62..321d30feb 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 553090dc5..b62ea128c 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 45c24aaa4..e02f7433a 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 3a0550122..a15c298b8 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\
+Display values are in units of the first available SIZE from --block-size,\n\
+and the %s_BLOCK_SIZE, BLOCK_SIZE and BLOCKSIZE environment variables.\n\
+Otherwise, units default to 1024 bytes (or 512 if POSIXLY_CORRECT 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 0cb7b35ee..77783794e 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\