From: Pádraig Brady <P@draigBrady.com>
Date: Mon, 28 Jul 2025 10:05:25 +0000 (+0100)
Subject: doc: use consistent references to standard files
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=69f21c5d4603b550b1cef89cdc269086260b189b;p=thirdparty%2Fcoreutils.git

doc: use consistent references to standard files

* cfg.mk (sc_standard_outputs): A new syntax check to
enforce standard references.
* doc/coreutils.texi: s/stderr/standard error/ etc.
* src/date.c: Likewise.
* src/dd.c: Likewise.
* src/env.c: Likewise.
* src/sort.c: Likewise.
* src/split.c: Likewise.
* src/stty.c: Likewise.
* src/timeout.c: Likewise.
* src/who.c: Likewise.
---

diff --git a/cfg.mk b/cfg.mk
index 56c70f244d..eecec2d727 100644
--- a/cfg.mk
+++ b/cfg.mk
@@ -336,6 +336,12 @@ sc_long_lines:
 	  sed -e "s|^|$$file:|" -e '$(FILTER_LONG_LINES)';		\
 	done | grep . && { msg="$$halt" $(_sc_say_and_exit) } || :
 
+sc_standard_outputs: $(ALL_MANS)
+	@grep -E 'std(in|out|err)' man/*.1 doc/*.texi			 \
+	  && { echo 1>&2 '$@: use "standard ....." in user docs'; exit 1; } || :
+	@grep -E '[Ss]tandard (in|out|err)([^op]|$$)' man/*.1 doc/*.texi \
+	  && { echo 1>&2 '$@: use "standard ..put" in user docs'; exit 1; } || :
+
 # Option descriptions should not start with a capital letter.
 # One could grep source directly as follows:
 # grep -E " {2,6}-.*[^.]  [A-Z][a-z]" $$($(VC_LIST_EXCEPT) | grep '\.c$$')
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 7ca5b222c6..40ecf3126f 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -3415,13 +3415,17 @@ with names @file{big-aa.xz}, @file{big-ab.xz}, @file{big-ac.xz}, etc.
 
 Split @var{input} to @var{chunks} output files where @var{chunks} may be:
 
+@macro Stdout
+standard output
+@end macro
+
 @example
 @var{n}      generate @var{n} files based on current size of @var{input}
 @var{k}/@var{n}    output only @var{k}th of @var{n} to standard output
 l/@var{n}    generate @var{n} files without splitting lines or records
-l/@var{k}/@var{n}  likewise but output only @var{k}th of @var{n} to stdout
+l/@var{k}/@var{n}  likewise but output only @var{k}th of @var{n} to @Stdout
 r/@var{n}    like @samp{l} but use round robin distribution
-r/@var{k}/@var{n}  likewise but output only @var{k}th of @var{n} to stdout
+r/@var{k}/@var{n}  likewise but output only @var{k}th of @var{n} to @Stdout
 @end example
 
 If the input size is not a multiple of @var{n}, early output files are
@@ -4147,7 +4151,8 @@ input digest string as what is output.  I.e., removing or adding any
 
 @item --debug
 @opindex --debug
-Output extra information to stderr, like the checksum implementation being used.
+Output extra information to standard error,
+like the checksum implementation being used.
 
 @macro cksumLengthOption
 @item -l
@@ -9056,7 +9061,7 @@ Equivalent to @option{--no-dereference --preserve=links}.
 @item --debug
 @opindex --debug
 @cindex debugging, copying
-Print extra information to stdout, explaining how files are copied.
+Print extra information to standard output, explaining how files are copied.
 This option implies the @option{--verbose} option.
 @end macro
 @optDebugCopy
diff --git a/src/date.c b/src/date.c
index 9539628201..6979399c3c 100644
--- a/src/date.c
+++ b/src/date.c
@@ -143,8 +143,8 @@ With -s, or with [MMDDhhmm[[CC]YY][.ss]], set the date and time.\n\
   -d, --date=STRING          display time described by STRING, not 'now'\n\
 "), stdout);
       fputs (_("\
-      --debug                annotate the parsed date,\n\
-                              and warn about questionable usage to stderr\n\
+      --debug                annotate the parsed date, and\n\
+                              warn about questionable usage to standard error\n\
 "), stdout);
       fputs (_("\
   -f, --file=DATEFILE        like --date; once for each line of DATEFILE\n\
diff --git a/src/dd.c b/src/dd.c
index c479f4cca2..33959b4952 100644
--- a/src/dd.c
+++ b/src/dd.c
@@ -550,14 +550,14 @@ Copy a file, converting and formatting according to the operands.\n\
   ibs=BYTES       read up to BYTES bytes at a time (default: 512)\n\
 "), stdout);
       fputs (_("\
-  if=FILE         read from FILE instead of stdin\n\
+  if=FILE         read from FILE instead of standard input\n\
   iflag=FLAGS     read as per the comma separated symbol list\n\
   obs=BYTES       write BYTES bytes at a time (default: 512)\n\
-  of=FILE         write to FILE instead of stdout\n\
+  of=FILE         write to FILE instead of standard output\n\
   oflag=FLAGS     write as per the comma separated symbol list\n\
   seek=N          (or oseek=N) skip N obs-sized output blocks\n\
   skip=N          (or iseek=N) skip N ibs-sized input blocks\n\
-  status=LEVEL    The LEVEL of information to print to stderr;\n\
+  status=LEVEL    The LEVEL of information to print to standard error;\n\
                   'none' suppresses everything but error messages,\n\
                   'noxfer' suppresses the final transfer statistics,\n\
                   'progress' shows periodic transfer statistics\n\
diff --git a/src/env.c b/src/env.c
index 17254c303e..baa1e1372d 100644
--- a/src/env.c
+++ b/src/env.c
@@ -144,7 +144,8 @@ Set each NAME to VALUE in the environment and run COMMAND.\n\
       --ignore-signal[=SIG]   set handling of SIG signal(s) to do nothing\n\
 "), stdout);
       fputs (_("\
-      --list-signal-handling  list non default signal handling to stderr\n\
+      --list-signal-handling  list non default signal handling to \
+standard error\n\
 "), stdout);
       fputs (_("\
   -v, --debug          print verbose information for each processing step\n\
diff --git a/src/sort.c b/src/sort.c
index 4a1fdfd375..7f1b51dd55 100644
--- a/src/sort.c
+++ b/src/sort.c
@@ -477,8 +477,8 @@ Other options:\n\
                               decompress them with PROG -d\n\
 "), stdout);
       fputs (_("\
-      --debug               annotate the part of the line used to sort,\n\
-                              and warn about questionable usage to stderr\n\
+      --debug               annotate the part of the line used to sort, and\n\
+                              warn about questionable usage to standard error\n\
       --files0-from=F       read input from the files specified by\n\
                             NUL-terminated names in file F;\n\
                             If F is - then read names from standard input\n\
diff --git a/src/split.c b/src/split.c
index 9cbbcccd1e..22a83ad5c8 100644
--- a/src/split.c
+++ b/src/split.c
@@ -262,11 +262,11 @@ default size is 1000 lines, and default PREFIX is 'x'.\n\
       fputs (_("\n\
 CHUNKS may be:\n\
   N       split into N files based on size of input\n\
-  K/N     output Kth of N to stdout\n\
+  K/N     output Kth of N to standard output\n\
   l/N     split into N files without splitting lines/records\n\
-  l/K/N   output Kth of N to stdout without splitting lines/records\n\
+  l/K/N   output Kth of N to standard output without splitting lines/records\n\
   r/N     like 'l' but use round robin distribution\n\
-  r/K/N   likewise but only output Kth of N to stdout\n\
+  r/K/N   likewise but only output Kth of N to standard output\n\
 "), stdout);
       emit_ancillary_info (PROGRAM_NAME);
     }
diff --git a/src/stty.c b/src/stty.c
index 0163ea48aa..3b2469a9b2 100644
--- a/src/stty.c
+++ b/src/stty.c
@@ -19,7 +19,7 @@
    Options:
    -a, --all    Write all current settings to stdout in human-readable form.
    -g, --save   Write all current settings to stdout in stty-readable form.
-   -F, --file   Open and use the specified device instead of stdin
+   -F, --file   Open and use the specified device instead of standard input.
 
    If no args are given, write to stdout the baud rate and settings that
    have been changed from their defaults.  Mode reading and changes
@@ -557,7 +557,7 @@ Print or change terminal characteristics.\n\
       fputs (_("\
   -a, --all          print all current settings in human-readable form\n\
   -g, --save         print all current settings in a stty-readable form\n\
-  -F, --file=DEVICE  open and use the specified DEVICE instead of stdin\n\
+  -F, --file=DEVICE  open and use DEVICE instead of standard input\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
diff --git a/src/timeout.c b/src/timeout.c
index b8df73b1f9..cc3b1b0849 100644
--- a/src/timeout.c
+++ b/src/timeout.c
@@ -285,7 +285,7 @@ Start COMMAND, and kill it if still running after DURATION.\n\
                    see 'kill -l' for a list of signals\n\
 "), stdout);
       fputs (_("\
-  -v, --verbose  diagnose to stderr any signal sent upon timeout\n\
+  -v, --verbose  diagnose to standard error any signal sent upon timeout\n\
 "), stdout);
 
       fputs (HELP_OPTION_DESCRIPTION, stdout);
diff --git a/src/who.c b/src/who.c
index 17c1e34acf..b481dd2f82 100644
--- a/src/who.c
+++ b/src/who.c
@@ -648,7 +648,7 @@ Print information about users who are currently logged in.\n\
 "), stdout);
       fputs (_("\
       --lookup      attempt to canonicalize hostnames via DNS\n\
-  -m                only hostname and user associated with stdin\n\
+  -m                only hostname and user associated with standard input\n\
   -p, --process     print active processes spawned by init\n\
 "), stdout);
       fputs (_("\