doc: standardize messages about the '-' stdin FILE

* src/system.h (emit_stdin_note): A new function, refactoring
the usage note about the '-' FILE implying stdin.
* src/base64.c (usage): Use the new function to emit the
note in a standard location and with standard separation.
* src/cat.c (usage): Likewise.
* src/csplit.c (usage): Likewise.
* src/cut.c (usage): Likewise.
* src/expand.c (usage): Likewise.
* src/fmt.c (usage): Likewise.
* src/head.c (usage): Likewise.
* src/md5sum.c (usage): Likewise.
* src/nl.c (usage): Likewise.
* src/od.c (usage): Likewise.
* src/paste.c (usage): Likewise.
* src/pr.c (usage): Likewise.
* src/ptx.c (usage): Likewise.
* src/shred.c (usage): Likewise.
* src/shuf.c (usage): Likewise.
* src/sort.c (usage): Likewise.
* src/sum.c (usage): Likewise.
* src/tac.c (usage): Likewise.
* src/tail.c (usage): Likewise.
* src/tsort.c (usage): Likewise.
* src/unexpand.c (usage): Likewise.
* src/wc.c (usage): Likewise.
* src/join.c (usage): Adjust the separation used for
the message referring to FILE1 or FILE2 as stdin.
* src/comm.c (usage): Add a message using the same
wording (translation) as used in join.
* src/split.c (usage): Reword to using FILE rather than
INPUT, allowing use of emit_stdin_note().  Also remove
the mention of "fixed-size" pieces as this isn't now
always the case.
Fixes http://pad.lv/1450179

27 files changed, 94 insertions, 66 deletions

diff --git a/src/base64.c b/src/base64.c
index 00e0a7610..ec3fe0720 100644
--- a/src/base64.c
+++ b/src/base64.c
@@ -62,6 +62,7 @@ Usage: %s [OPTION]... [FILE]\n\
 Base64 encode or decode FILE, or standard input, to standard output.\n\
 "), program_name);
 
+      emit_stdin_note ();
       emit_mandatory_arg_note ();
 
       fputs (_("\
@@ -75,9 +76,6 @@ Base64 encode or decode FILE, or standard input, to standard output.\n\
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
       fputs (_("\
 \n\
-With no FILE, or when FILE is -, read standard input.\n"), stdout);
-      fputs (_("\
-\n\
 The data are encoded as described for the base64 alphabet in RFC 3548.\n\
 When decoding, the input may contain newlines in addition to the bytes of\n\
 the formal base64 alphabet.  Use --ignore-garbage to attempt to recover\n\
diff --git a/src/cat.c b/src/cat.c
index 42fadb9a8..948f1341b 100644
--- a/src/cat.c
+++ b/src/cat.c
@@ -90,7 +90,12 @@ Usage: %s [OPTION]... [FILE]...\n\
 "),
               program_name);
       fputs (_("\
-Concatenate FILE(s), or standard input, to standard output.\n\
+Concatenate FILE(s) to standard output.\n\
+"), stdout);
+
+      emit_stdin_note ();
+
+      fputs (_("\
 \n\
   -A, --show-all           equivalent to -vET\n\
   -b, --number-nonblank    number nonempty output lines, overrides -n\n\
@@ -107,10 +112,6 @@ Concatenate FILE(s), or standard input, to standard output.\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
-      fputs (_("\
-\n\
-With no FILE, or when FILE is -, read standard input.\n\
-"), stdout);
       printf (_("\
 \n\
 Examples:\n\
diff --git a/src/comm.c b/src/comm.c
index cd3e5d91d..ea7a28415 100644
--- a/src/comm.c
+++ b/src/comm.c
@@ -109,6 +109,10 @@ Compare sorted files FILE1 and FILE2 line by line.\n\
 "), stdout);
       fputs (_("\
 \n\
+When FILE1 or FILE2 (not both) is -, read standard input.\n\
+"), stdout);
+      fputs (_("\
+\n\
 With no options, produce three-column output.  Column one contains\n\
 lines unique to FILE1, column two contains lines unique to FILE2,\n\
 and column three contains lines common to both files.\n\
diff --git a/src/csplit.c b/src/csplit.c
index edc051ba9..d966df57a 100644
--- a/src/csplit.c
+++ b/src/csplit.c
@@ -1482,6 +1482,10 @@ Usage: %s [OPTION]... FILE PATTERN...\n\
 Output pieces of FILE separated by PATTERN(s) to files 'xx00', 'xx01', ...,\n\
 and output byte counts of each piece to standard output.\n\
 "), stdout);
+       fputs (_("\
+\n\
+Read standard input if FILE is -\n\
+"), stdout);
 
       emit_mandatory_arg_note ();
 
@@ -1502,10 +1506,7 @@ and output byte counts of each piece to standard output.\n\
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
       fputs (_("\
 \n\
-Read standard input if FILE is -.  Each PATTERN may be:\n\
-"), stdout);
-      fputs (_("\
-\n\
+Each PATTERN may be:\n\
   INTEGER            copy up to but not including specified line number\n\
   /REGEXP/[OFFSET]   copy up to but not including a matching line\n\
   %REGEXP%[OFFSET]   skip to, but not including a matching line\n\
diff --git a/src/cut.c b/src/cut.c
index d2cab196b..4f80ebd45 100644
--- a/src/cut.c
+++ b/src/cut.c
@@ -177,6 +177,7 @@ Usage: %s OPTION... [FILE]...\n\
 Print selected parts of lines from each FILE to standard output.\n\
 "), stdout);
 
+      emit_stdin_note ();
       emit_mandatory_arg_note ();
 
       fputs (_("\
@@ -214,8 +215,6 @@ Each range is one of:\n\
   N-    from N'th byte, character or field, to end of line\n\
   N-M   from N'th to M'th (included) byte, character or field\n\
   -M    from first to M'th (included) byte, character or field\n\
-\n\
-With no FILE, or when FILE is -, read standard input.\n\
 "), stdout);
       emit_ancillary_info (PROGRAM_NAME);
     }
diff --git a/src/expand.c b/src/expand.c
index aea64103c..0a40a1a8e 100644
--- a/src/expand.c
+++ b/src/expand.c
@@ -106,9 +106,9 @@ Usage: %s [OPTION]... [FILE]...\n\
               program_name);
       fputs (_("\
 Convert tabs in each FILE to spaces, writing to standard output.\n\
-With no FILE, or when FILE is -, read standard input.\n\
 "), stdout);
 
+      emit_stdin_note ();
       emit_mandatory_arg_note ();
 
       fputs (_("\
diff --git a/src/fmt.c b/src/fmt.c
index 707dcadfa..b12c9b9ed 100644
--- a/src/fmt.c
+++ b/src/fmt.c
@@ -273,6 +273,7 @@ Reformat each paragraph in the FILE(s), writing to standard output.\n\
 The option -WIDTH is an abbreviated form of --width=DIGITS.\n\
 "), stdout);
 
+      emit_stdin_note ();
       emit_mandatory_arg_note ();
 
       fputs (_("\
@@ -292,10 +293,6 @@ The option -WIDTH is an abbreviated form of --width=DIGITS.\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
-      fputs (_("\
-\n\
-With no FILE, or when FILE is -, read standard input.\n"),
-             stdout);
       emit_ancillary_info (PROGRAM_NAME);
     }
   exit (status);
diff --git a/src/fold.c b/src/fold.c
index 1d8a1502b..0955c09d9 100644
--- a/src/fold.c
+++ b/src/fold.c
@@ -67,10 +67,10 @@ Usage: %s [OPTION]... [FILE]...\n\
 "),
               program_name);
       fputs (_("\
-Wrap input lines in each FILE (standard input by default), writing to\n\
-standard output.\n\
+Wrap input lines in each FILE, writing to standard output.\n\
 "), stdout);
 
+      emit_stdin_note ();
       emit_mandatory_arg_note ();
 
       fputs (_("\
diff --git a/src/head.c b/src/head.c
index 576e55c0b..3ea81b651 100644
--- a/src/head.c
+++ b/src/head.c
@@ -110,9 +110,9 @@ Usage: %s [OPTION]... [FILE]...\n\
       fputs (_("\
 Print the first 10 lines of each FILE to standard output.\n\
 With more than one FILE, precede each with a header giving the file name.\n\
-With no FILE, or when FILE is -, read standard input.\n\
 "), stdout);
 
+      emit_stdin_note ();
       emit_mandatory_arg_note ();
 
       fputs (_("\
diff --git a/src/join.c b/src/join.c
index 0329e023b..52e4b18b3 100644
--- a/src/join.c
+++ b/src/join.c
@@ -194,8 +194,14 @@ Usage: %s [OPTION]... FILE1 FILE2\n\
               program_name);
       fputs (_("\
 For each pair of input lines with identical join fields, write a line to\n\
-standard output.  The default join field is the first, delimited\n\
-by whitespace.  When FILE1 or FILE2 (not both) is -, read standard input.\n\
+standard output.  The default join field is the first, delimited by whitespace.\
+\n\
+"), stdout);
+      fputs (_("\
+\n\
+When FILE1 or FILE2 (not both) is -, read standard input.\n\
+"), stdout);
+      fputs (_("\
 \n\
   -a FILENUM        also print unpairable lines from file FILENUM, where\n\
                       FILENUM is 1 or 2, corresponding to FILE1 or FILE2\n\
diff --git a/src/md5sum.c b/src/md5sum.c
index 8c5f8761b..bc2b70927 100644
--- a/src/md5sum.c
+++ b/src/md5sum.c
@@ -164,18 +164,21 @@ usage (int status)
       printf (_("\
 Usage: %s [OPTION]... [FILE]...\n\
 Print or check %s (%d-bit) checksums.\n\
-With no FILE, or when FILE is -, read standard input.\n\
-\n\
 "),
               program_name,
               DIGEST_TYPE_STRING,
               DIGEST_BITS);
+
+      emit_stdin_note ();
+
       if (O_BINARY)
         fputs (_("\
+\n\
   -b, --binary         read in binary mode (default unless reading tty stdin)\n\
 "), stdout);
       else
         fputs (_("\
+\n\
   -b, --binary         read in binary mode\n\
 "), stdout);
       printf (_("\
diff --git a/src/nl.c b/src/nl.c
index 015e31288..1132af398 100644
--- a/src/nl.c
+++ b/src/nl.c
@@ -178,9 +178,9 @@ Usage: %s [OPTION]... [FILE]...\n\
               program_name);
       fputs (_("\
 Write each FILE to standard output, with line numbers added.\n\
-With no FILE, or when FILE is -, read standard input.\n\
 "), stdout);
 
+      emit_stdin_note ();
       emit_mandatory_arg_note ();
 
       fputs (_("\
diff --git a/src/od.c b/src/od.c
index 2ea101b38..c1241f541 100644
--- a/src/od.c
+++ b/src/od.c
@@ -328,10 +328,12 @@ Usage: %s [OPTION]... [FILE]...\n\
 Write an unambiguous representation, octal bytes by default,\n\
 of FILE to standard output.  With more than one FILE argument,\n\
 concatenate them in the listed order to form the input.\n\
-With no FILE, or when FILE is -, read standard input.\n\
-\n\
 "), stdout);
+
+      emit_stdin_note ();
+
       fputs (_("\
+\n\
 If first and second call formats both apply, the second format is assumed\n\
 if the last operand begins with + or (if there are 2 operands) a digit.\n\
 An OFFSET operand means -j OFFSET.  LABEL is the pseudo-address\n\
diff --git a/src/paste.c b/src/paste.c
index 775bfbf76..7a5b5d7ab 100644
--- a/src/paste.c
+++ b/src/paste.c
@@ -439,9 +439,9 @@ Usage: %s [OPTION]... [FILE]...\n\
       fputs (_("\
 Write lines consisting of the sequentially corresponding lines from\n\
 each FILE, separated by TABs, to standard output.\n\
-With no FILE, or when FILE is -, read standard input.\n\
 "), stdout);
 
+      emit_stdin_note ();
       emit_mandatory_arg_note ();
 
       fputs (_("\
diff --git a/src/pr.c b/src/pr.c
index 6ff51ec5a..d79d84f18 100644
--- a/src/pr.c
+++ b/src/pr.c
@@ -2728,6 +2728,7 @@ Usage: %s [OPTION]... [FILE]...\n\
 Paginate or columnate FILE(s) for printing.\n\
 "), stdout);
 
+      emit_stdin_note ();
       emit_mandatory_arg_note ();
 
       fputs (_("\
@@ -2768,7 +2769,10 @@ Paginate or columnate FILE(s) for printing.\n\
       fputs (_("\
   -l, --length=PAGE_LENGTH\n\
                     set the page length to PAGE_LENGTH (66) lines\n\
-                    (default number of lines of text 56, and with -F 63)\n\
+                    (default number of lines of text 56, and with -F 63).\n\
+                    implies -t if PAGE_LENGTH <= 10\n\
+"), stdout);
+      fputs (_("\
   -m, --merge       print all files in parallel, one in each column,\n\
                     truncate lines, but join lines of full length with -J\n\
 "), stdout);
@@ -2800,7 +2804,10 @@ Paginate or columnate FILE(s) for printing.\n\
                     separate columns by STRING,\n\
                     without -S: Default separator <TAB> with -J and <space>\n\
                     otherwise (same as -S\" \"), no effect on column options\n\
-  -t, --omit-header  omit page headers and trailers\n\
+"), stdout);
+      fputs (_("\
+  -t, --omit-header  omit page headers and trailers;\n\
+                     implied if PAGE_LENGTH <= 10\n\
 "), stdout);
       fputs (_("\
   -T, --omit-pagination\n\
@@ -2820,11 +2827,6 @@ Paginate or columnate FILE(s) for printing.\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
-      fputs (_("\
-\n\
--t is implied if PAGE_LENGTH <= 10.  With no FILE, or when FILE is -, read\n\
-standard input.\n\
-"), stdout);
       emit_ancillary_info (PROGRAM_NAME);
     }
   exit (status);
diff --git a/src/ptx.c b/src/ptx.c
index 679803ddc..ff4e63a5f 100644
--- a/src/ptx.c
+++ b/src/ptx.c
@@ -1825,12 +1825,16 @@ Usage: %s [OPTION]... [INPUT]...   (without -G)\n\
 Output a permuted index, including context, of the words in the input files.\n\
 "), stdout);
 
+      emit_stdin_note ();
       emit_mandatory_arg_note ();
 
       fputs (_("\
   -A, --auto-reference           output automatically generated references\n\
   -G, --traditional              behave more like System V 'ptx'\n\
-  -F, --flag-truncation=STRING   use STRING for flagging line truncations\n\
+"), stdout);
+      fputs (_("\
+  -F, --flag-truncation=STRING   use STRING for flagging line truncations.\n\
+                                 The default is '/'\n\
 "), stdout);
       fputs (_("\
   -M, --macro-name=STRING        macro name to use instead of 'xx'\n\
@@ -1854,10 +1858,6 @@ Output a permuted index, including context, of the words in the input files.\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
-      fputs (_("\
-\n\
-With no FILE, or when FILE is -, read standard input.  Default is '-F /'.\n\
-"), stdout);
       emit_ancillary_info (PROGRAM_NAME);
     }
   exit (status);
diff --git a/src/shred.c b/src/shred.c
index 543dcb0ca..63bcd6fc5 100644
--- a/src/shred.c
+++ b/src/shred.c
@@ -171,6 +171,10 @@ usage (int status)
 Overwrite the specified FILE(s) repeatedly, in order to make it harder\n\
 for even very expensive hardware probing to recover the data.\n\
 "), stdout);
+      fputs (_("\
+\n\
+If FILE is -, shred standard output.\n\
+"), stdout);
 
       emit_mandatory_arg_note ();
 
@@ -191,8 +195,6 @@ for even very expensive hardware probing to recover the data.\n\
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
       fputs (_("\
 \n\
-If FILE is -, shred standard output.\n\
-\n\
 Delete FILE(s) if --remove (-u) is specified.  The default is not to remove\n\
 the files because it is common to operate on device files like /dev/hda,\n\
 and those files usually should not be removed.\n\
diff --git a/src/shuf.c b/src/shuf.c
index 5a25e581c..ff2337d34 100644
--- a/src/shuf.c
+++ b/src/shuf.c
@@ -69,6 +69,7 @@ Usage: %s [OPTION]... [FILE]\n\
 Write a random permutation of the input lines to standard output.\n\
 "), stdout);
 
+      emit_stdin_note ();
       emit_mandatory_arg_note ();
 
       fputs (_("\
@@ -84,10 +85,6 @@ Write a random permutation of the input lines to standard output.\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
-      fputs (_("\
-\n\
-With no FILE, or when FILE is -, read standard input.\n\
-"), stdout);
       emit_ancillary_info (PROGRAM_NAME);
     }
 
diff --git a/src/sort.c b/src/sort.c
index 23d45654d..85fc38f73 100644
--- a/src/sort.c
+++ b/src/sort.c
@@ -428,6 +428,7 @@ Usage: %s [OPTION]... [FILE]...\n\
 Write sorted concatenation of all FILE(s) to standard output.\n\
 "), stdout);
 
+      emit_stdin_note ();
       emit_mandatory_arg_note ();
 
       fputs (_("\
@@ -524,8 +525,6 @@ SIZE may be followed by the following multiplicative suffixes:\n\
       fputs (_("\
 % 1% of memory, b 1, K 1024 (default), and so on for M, G, T, P, E, Z, Y.\n\
 \n\
-With no FILE, or when FILE is -, read standard input.\n\
-\n\
 *** WARNING ***\n\
 The locale specified by the environment affects sort order.\n\
 Set LC_ALL=C to get the traditional sort order that uses\n\
diff --git a/src/split.c b/src/split.c
index e0f83692b..5d6043f70 100644
--- a/src/split.c
+++ b/src/split.c
@@ -204,15 +204,15 @@ usage (int status)
   else
     {
       printf (_("\
-Usage: %s [OPTION]... [INPUT [PREFIX]]\n\
+Usage: %s [OPTION]... [FILE [PREFIX]]\n\
 "),
               program_name);
       fputs (_("\
-Output fixed-size pieces of INPUT to PREFIXaa, PREFIXab, ...; default\n\
-size is 1000 lines, and default PREFIX is 'x'.  With no INPUT, or when INPUT\n\
-is -, read standard input.\n\
+Output pieces of FILE to PREFIXaa, PREFIXab, ...;\n\
+default size is 1000 lines, and default PREFIX is 'x'.\n\
 "), stdout);
 
+      emit_stdin_note ();
       emit_mandatory_arg_note ();
 
       fprintf (stdout, _("\
diff --git a/src/sum.c b/src/sum.c
index 163821289..51956c61f 100644
--- a/src/sum.c
+++ b/src/sum.c
@@ -61,16 +61,17 @@ Usage: %s [OPTION]... [FILE]...\n\
               program_name);
       fputs (_("\
 Print checksum and block counts for each FILE.\n\
+"), stdout);
+
+      emit_stdin_note ();
+
+      fputs (_("\
 \n\
   -r              use BSD sum algorithm, use 1K blocks\n\
   -s, --sysv      use System V sum algorithm, use 512 bytes blocks\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
-      fputs (_("\
-\n\
-With no FILE, or when FILE is -, read standard input.\n\
-"), stdout);
       emit_ancillary_info (PROGRAM_NAME);
     }
   exit (status);
diff --git a/src/system.h b/src/system.h
index 46edd07d5..c55f6d8bd 100644
--- a/src/system.h
+++ b/src/system.h
@@ -542,6 +542,13 @@ is_nul (void const *buf, size_t bufsize)
   )
 
 static inline void
+emit_stdin_note (void)
+{
+  fputs (_("\n\
+With no FILE, or when FILE is -, read standard input.\n\
+"), stdout);
+}
+static inline void
 emit_mandatory_arg_note (void)
 {
   fputs (_("\n\
diff --git a/src/tac.c b/src/tac.c
index b69953f35..2d73c6e78 100644
--- a/src/tac.c
+++ b/src/tac.c
@@ -136,9 +136,9 @@ Usage: %s [OPTION]... [FILE]...\n\
               program_name);
       fputs (_("\
 Write each FILE to standard output, last line first.\n\
-With no FILE, or when FILE is -, read standard input.\n\
 "), stdout);
 
+      emit_stdin_note ();
       emit_mandatory_arg_note ();
 
       fputs (_("\
diff --git a/src/tail.c b/src/tail.c
index b29dab1c9..19e658b32 100644
--- a/src/tail.c
+++ b/src/tail.c
@@ -257,9 +257,9 @@ Usage: %s [OPTION]... [FILE]...\n\
       printf (_("\
 Print the last %d lines of each FILE to standard output.\n\
 With more than one FILE, precede each with a header giving the file name.\n\
-With no FILE, or when FILE is -, read standard input.\n\
 "), DEFAULT_N_LINES);
 
+      emit_stdin_note ();
       emit_mandatory_arg_note ();
 
      fputs (_("\
diff --git a/src/tsort.c b/src/tsort.c
index 07841e48a..d4be03d42 100644
--- a/src/tsort.c
+++ b/src/tsort.c
@@ -82,9 +82,13 @@ usage (int status)
       printf (_("\
 Usage: %s [OPTION] [FILE]\n\
 Write totally ordered list consistent with the partial ordering in FILE.\n\
-With no FILE, or when FILE is -, read standard input.\n\
-\n\
 "), program_name);
+
+      emit_stdin_note ();
+
+      fputs (_("\
+\n\
+"), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
       emit_ancillary_info (PROGRAM_NAME);
diff --git a/src/unexpand.c b/src/unexpand.c
index 2281aaa4e..e0f7c22aa 100644
--- a/src/unexpand.c
+++ b/src/unexpand.c
@@ -116,9 +116,9 @@ Usage: %s [OPTION]... [FILE]...\n\
               program_name);
       fputs (_("\
 Convert blanks in each FILE to tabs, writing to standard output.\n\
-With no FILE, or when FILE is -, read standard input.\n\
 "), stdout);
 
+      emit_stdin_note ();
       emit_mandatory_arg_note ();
 
       fputs (_("\
diff --git a/src/wc.c b/src/wc.c
index fe73d2ce1..ae7ae952d 100644
--- a/src/wc.c
+++ b/src/wc.c
@@ -116,9 +116,14 @@ Usage: %s [OPTION]... [FILE]...\n\
               program_name, program_name);
       fputs (_("\
 Print newline, word, and byte counts for each FILE, and a total line if\n\
-more than one FILE is specified.  With no FILE, or when FILE is -,\n\
-read standard input.  A word is a non-zero-length sequence of characters\n\
-delimited by white space.\n\
+more than one FILE is specified.  A word is a non-zero-length sequence of\n\
+characters delimited by white space.\n\
+"), stdout);
+
+      emit_stdin_note ();
+
+      fputs (_("\
+\n\
 The options below may be used to select which counts are printed, always in\n\
 the following order: newline, word, character, byte, maximum line length.\n\
   -c, --bytes            print the byte counts\n\