[PATCH] Clarify comparison of echo, printf, and AS_ECHO*.

[Paolo Bonzini]

Discussed starting at
<http://lists.gnu.org/archive/html/bug-autoconf/2009-07/msg00025.html>.

* doc/autoconf.texi (Limitations of Builtins): In echo's entry,
give a reason why printf is better than echo.  In printf's
entry, cross-reference echo's entry.
---
        Here is what I committed.

 ChangeLog         |    8 ++++++++
 doc/autoconf.texi |   28 ++++++++++++++++++----------
 2 files changed, 26 insertions(+), 10 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 9011143..1e22e63 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2009-07-30  Paolo Bonzini  <address@hidden>
+           Joel E. Denny  <address@hidden>
+
+       Clarify comparison of echo, printf, and AS_ECHO*.
+       * doc/autoconf.texi (Limitations of Builtins): In echo's entry,
+       give a reason why printf is better than echo.  In printf's
+       entry, cross-reference echo's entry.
+
 2009-07-26  Eric Blake  <address@hidden>
 
        Release Version 2.64.
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 4f046c0..419d7cd 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -15826,9 +15826,14 @@ Limitations of Builtins
 
 Because of these problems, do not pass a string containing arbitrary
 characters to @command{echo}.  For example, @samp{echo "$foo"} is safe
-if you know that @var{foo}'s value cannot contain backslashes and cannot
-start with @samp{-}, but otherwise you should use a here-document like
-this:
+only if you know that @var{foo}'s value cannot contain backslashes and
+cannot start with @samp{-}.
+
address@hidden is in general safer and easier to use than @command{echo}
+and @command{echo -n}.  Thus, scripts where portability is not a major
+concern should use @command{printf '%s\n'} instead of @command{echo},
+and @command{printf %s} instead of @command{echo -n}. For portable
+shell scripts it is suggested to use a here-document like this:
 
 @example
 cat <<EOF
@@ -15836,12 +15841,12 @@ Limitations of Builtins
 EOF
 @end example
 
-New applications which are not aiming at portability should use
address@hidden instead of @command{echo}.  M4sh provides the
address@hidden and @code{AS_ECHO_N} macros, which choose between
address@hidden -n} on implementations where that works, @command{printf} if
-it is available, or other creative tricks in order to work around the
-above problems.
address@hidden
+in cases that could trigger bugs in @command{echo}.  Alternatively,
+M4sh provides @code{AS_ECHO} and @code{AS_ECHO_N} macros which choose
+between various portable implementations: @samp{echo} or @samp{print}
+where that works, @command{printf} if it is available, or other creative
+tricks in order to work around the above problems.
 
 
 @item @command{eval}
@@ -16143,11 +16148,14 @@ Limitations of Builtins
 core.
 
 Since @command{printf} is not always a shell builtin, there is a
-potential speed penalty for using @code{printf %s\\n} as a replacement
+potential speed penalty for using @code{printf '%s\n'} as a replacement
 for an @command{echo} that does not interpret @samp{\} or leading
 @samp{-}. With Solaris @command{ksh}, it is possible to use @code{print
 -r --} for this role instead.
 
+For a discussion of portable alternatives to both @command{printf}
+and @command{echo}, @xref{echo, , Limitations of Shell Builtins}.
+
 
 @item @command{pwd}
 @c ----------------
-- 
1.6.2.5