Improve documentation on quoting.

* doc/autoconf.texi (Autoconf Language): Clarify quoting example.
* THANKS: Update.
Reported by santilín.

Signed-off-by: Eric Blake <ebb9@byu.net>

diff --git a/ChangeLog b/ChangeLog
index af08473eeae9899a8bf164b48b80123f9bb44252..64fb8ab1c21ea94ea2981faf8abaacbf7310b593 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2009-09-12  Eric Blake  <ebb9@byu.net>
+
+       Improve documentation on quoting.
+       * doc/autoconf.texi (Autoconf Language): Clarify quoting example.
+       * THANKS: Update.
+       Reported by santilín.
+
 2009-09-11  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>
 
        New config.status option --config.

diff --git a/THANKS b/THANKS
index 0901d6ac74371ac84e008bb9c9ae6e63426404c5..4a96e347043366c69797ec7b20f922dc0257d83d 100644 (file)
--- a/THANKS
+++ b/THANKS
@@ -327,6 +327,7 @@ Sam Sexton                  Sam.Sexton@reuters.com
 Sam Sirlin                  sam@kalessin.jpl.nasa.gov
 Sam Varshavchik             mrsam@courier-mta.com
 Sander Niemeijer            niemeijer@science-and-technology.nl
+santilín                    listas@gestiong.org
 Scott Bambrough             scottb@corelcomputer.com
 Scott Stanton               stanton@scriptics.com
 Sebastian Freundt           hroptatyr@gna.org

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 098d512ebdebd628cd0543fb4ceace7a10acf7ca..47645597420484cf61475a9a17c2774eb27bc6c6 100644 (file)
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -1177,29 +1177,46 @@ AC_CHECK_HEADER(stdio.h,
 
 In other cases, you may have to use text that also resembles a macro
 call.  You must quote that text even when it is not passed as a macro
-argument:
+argument.  For example, these two approaches in @file{configure.ac}
+(quoting just the potential problems, or quoting the entire line) will
+protect your script in case autoconf ever adds a macro @code{AC_DC}:
 
 @example
 echo "Hard rock was here!  --[AC_DC]"
+[echo "Hard rock was here!  --AC_DC"]
 @end example
 
 @noindent
-which results in:
+which results in this text in @file{configure}:
 
 @example
 echo "Hard rock was here!  --AC_DC"
+echo "Hard rock was here!  --AC_DC"
 @end example
 
 @noindent
 When you use the same text in a macro argument, you must therefore have
 an extra quotation level (since one is stripped away by the macro
 substitution).  In general, then, it is a good idea to @emph{use double
-quoting for all literal string arguments}:
+quoting for all literal string arguments}, either around just the
+problematic portions, or over the entire argument:
 
 @example
+AC_MSG_WARN([[AC_DC] stinks  --Iron Maiden])
 AC_MSG_WARN([[AC_DC stinks  --Iron Maiden]])
 @end example
 
+However, the above example triggers a warning about a possibly
+unexpanded macro when running @command{autoconf}, because it collides
+with the namespace of macros reserved for the Autoconf language.  To be
+really safe, you can use additional escaping (either a quadrigraph, or
+creative shell constructs) to silence that particular warning:
+
+@example
+echo "Hard rock was here!  --AC""_DC"
+AC_MSG_WARN([[AC@@&t@@_DC stinks  --Iron Maiden]])
+@end example
+
 You are now able to understand one of the constructs of Autoconf that
 has been continually misunderstood@enddots{}  The rule of thumb is that
 @emph{whenever you expect macro expansion, expect quote expansion};