From: Pádraig Brady <P@draigBrady.com>
Date: Thu, 21 Oct 2021 12:05:47 +0000 (+0100)
Subject: doc: say that printf(1) is preferred over echo(1)
X-Git-Tag: v9.1~200
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f60a3981c31519d03fd2be19e006349ea00b4464;p=thirdparty%2Fcoreutils.git

doc: say that printf(1) is preferred over echo(1)

* src/echo.c (usage): Say printf(1) is preferred
due to being more standard and robust.
* man/echo.x [SEE ALSO]: Reference printf(1).
* doc/coreutils.texi (echo invocation): Mention in the
summary that echo is not robust when outputting
any string, and that printf is preferred.
Also expand on the examples showing how to
output a single '-n' string.
Addresses https://bugs.gnu.org/51311
---

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 5e0c019f9a..6068d8b08d 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -12896,6 +12896,13 @@ echo [@var{option}]@dots{} [@var{string}]@dots{}
 
 @mayConflictWithShellBuiltIn{echo}
 
+Due to historical and backwards compatibility reasons, certain bare option-like
+strings cannot be passed to @command{echo} as non-option arguments.
+It is therefore not advisable to use @command{echo} for printing unknown or
+variable arguments.  The @command{printf} command is recommended as a more
+portable and flexible replacement for tasks historically performed by
+@command{echo}.  @xref{printf invocation}.
+
 The program accepts the following options.  Also see @ref{Common options}.
 Options must precede operands, and the normally-special argument
 @samp{--} has no special meaning and is treated like any other
@@ -12961,13 +12968,15 @@ If the @env{POSIXLY_CORRECT} environment variable is set, then when
 option-like arguments instead of treating them as options.  For
 example, @code{echo -ne hello} outputs @samp{-ne hello} instead of
 plain @samp{hello}.  Also backslash escapes are always enabled.
+Note to echo the string @samp{-n}, one of the characters
+can be escaped in either octal or hexadecimal representation.
+For example, @code{echo -e '\x2dn'}.
 
 POSIX does not require support for any options, and says
 that the behavior of @command{echo} is implementation-defined if any
-@var{string} contains a backslash or if the first argument is
-@option{-n}.  Portable programs can use the @command{printf} command
-if they need to omit trailing newlines or output control characters or
-backslashes.  @xref{printf invocation}.
+@var{string} contains a backslash or if the first argument is @option{-n}.
+Portable programs should use the @command{printf} command instead.
+@xref{printf invocation}.
 
 @exitstatus
 
diff --git a/man/echo.x b/man/echo.x
index 9c4fa8131d..61a36706bf 100644
--- a/man/echo.x
+++ b/man/echo.x
@@ -2,3 +2,5 @@
 echo \- display a line of text
 [DESCRIPTION]
 .\" Add any additional description here
+[SEE ALSO]
+printf(1)
diff --git a/src/echo.c b/src/echo.c
index 18513398a8..966e31409d 100644
--- a/src/echo.c
+++ b/src/echo.c
@@ -80,6 +80,10 @@ If -e is in effect, the following sequences are recognized:\n\
   \\xHH    byte with hexadecimal value HH (1 to 2 digits)\n\
 "), stdout);
   printf (USAGE_BUILTIN_WARNING, PROGRAM_NAME);
+  fputs (_("\n\
+NOTE: printf(1) is a preferred alternative,\n\
+which does not have issues outputting option-like strings.\n\
+"), stdout);
   emit_ancillary_info (PROGRAM_NAME);
   exit (status);
 }