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 5e0c019f9a98a891ab232a45d41e051ab359eba3..6068d8b08d8d3487e467d5a8092838a379408013 100644 (file)
--- 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 9c4fa8131d9d9c020626a718352c099b437ed964..61a36706bf7c069f084c3b1fc2239eed69c4cafa 100644 (file)
--- 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 18513398a81935fe94871e617a5cda6f73b795d1..966e31409d94081172af44d2f2f6996ddad11962 100644 (file)
--- 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);
 }