From: Pádraig Brady Date: Thu, 30 Apr 2015 13:02:46 +0000 (+0100) Subject: doc: standardize messages about the '-' stdin FILE X-Git-Tag: v8.24~70 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e981643ae3e57affdf3f4f6aa8bf53cf06433f17;p=thirdparty%2Fcoreutils.git 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 --- diff --git a/src/base64.c b/src/base64.c index 00e0a7610f..ec3fe0720e 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 42fadb9a84..948f1341bf 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 cd3e5d91d2..ea7a28415f 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 edc051ba9d..d966df57a3 100644 --- a/src/csplit.c +++ b/src/csplit.c @@ -1481,6 +1481,10 @@ Usage: %s [OPTION]... FILE PATTERN...\n\ fputs (_("\ 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 d2cab196b1..4f80ebd459 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 aea64103ce..0a40a1a8ea 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 707dcadfa2..b12c9b9edf 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 1d8a1502bc..0955c09d94 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 576e55c0b9..3ea81b6515 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 0329e023b5..52e4b18b39 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 8c5f8761bd..bc2b70927b 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 015e312885..1132af3981 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 2ea101b381..c1241f5410 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 775bfbf76a..7a5b5d7ab8 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 6ff51ec5ac..d79d84f186 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 with -J and \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 679803ddc5..ff4e63a5fb 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 543dcb0caf..63bcd6fc51 100644 --- a/src/shred.c +++ b/src/shred.c @@ -170,6 +170,10 @@ usage (int status) fputs (_("\ 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 5a25e581c7..ff2337d340 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 23d45654d7..85fc38f73d 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 e0f83692bd..5d6043f70b 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 163821289f..51956c61fc 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 46edd07d54..c55f6d8bd1 100644 --- a/src/system.h +++ b/src/system.h @@ -541,6 +541,13 @@ is_nul (void const *buf, size_t bufsize) ? false : (((Accum) = (Accum) * 10 + (Digit_val)), true)) \ ) +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) { diff --git a/src/tac.c b/src/tac.c index b69953f356..2d73c6e78b 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 b29dab1c9f..19e658b32d 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 07841e48a4..d4be03d427 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 2281aaa4ee..e0f7c22aaa 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 fe73d2ce16..ae7ae952dc 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\