* doc/autoconf.texi (Autoconf Language): Add more description

about quoting heuristics.

diff --git a/ChangeLog b/ChangeLog
index ef81485e8a6deca4413252641b2fefa17767899f..0e2fe2ef7d708c921864f26a417fa4f4602f06c1 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2005-04-29  Paul Eggert  <eggert@cs.ucla.edu>
+
+       * doc/autoconf.texi (Autoconf Language): Add more description
+       about quoting heuristics.
+
 2005-04-29  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>
 
        * doc/autoconf.texi (External Software): Replace AC_DEFINE_UNQUOTED

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 0bb996936da98bd1718e1d33520f7ad7f574ef3d..89f8f6581f560663081a8a525036b93dfab14bda 100644 (file)
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -988,8 +988,8 @@ space between the macro name and the open parenthesis.  Arguments should
 be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
 separated by commas.  Any leading spaces in arguments are ignored,
 unless they are quoted.  You may safely leave out the quotes when the
-argument is simple text, but @emph{always} quote complex arguments such
-as other macro calls.  This rule applies recursively for every macro
+argument cannot contain any macro calls, but @emph{always} quote arguments
+that might contain macro calls.  This rule applies recursively for every macro
 call, including macros called from other macros.
 
 For instance:
@@ -1004,16 +1004,38 @@ AC_CHECK_HEADER([stdio.h],
 @noindent
 is quoted properly.  You may safely simplify its quotation to:
 
+@example
+AC_CHECK_HEADER([stdio.h],
+                [AC_DEFINE([HAVE_STDIO_H], 1,
+                   [Define to 1 if you have <stdio.h>.])],
+                [AC_MSG_ERROR([Sorry, can't do anything for you])])
+@end example
+
+@noindent
+because @samp{1} cannot contain a macro call.  Here, the argument of
+@code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be
+interpreted as an argument separator.  Also, @samp{AC_CHECK_HEADER}'s
+second and third arguments must be quoted, since those arguments contain
+macro calls.  The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h},
+and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but
+if you unwisely defined a macro with a name like @samp{Define} or
+@samp{stdio} then they would need quoting.  Cautious Autoconf users
+would keep the quotes, but many Autoconf users find such precautions
+annoying, and would rewrite the example as follows:
+
 @example
 AC_CHECK_HEADER(stdio.h,
                 [AC_DEFINE(HAVE_STDIO_H, 1,
-                   Define to 1 if you have <stdio.h>.)],
+                   [Define to 1 if you have <stdio.h>.])],
                 [AC_MSG_ERROR([Sorry, can't do anything for you])])
 @end example
 
 @noindent
-Notice that the argument of @code{AC_MSG_ERROR} is still quoted;
-otherwise, its comma would have been interpreted as an argument separator.
+This is safe, so long as you adopt good naming conventions and do not
+define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or
+@samp{h}.  Though it is also safe here to omit the quotes around
+@samp{Define to 1 if you have <stdio.h>.} this is not recommended, as
+message strings are more likely to inadvertently contain commas.
 
 The following example is wrong and dangerous, as it is underquoted:
 
@@ -1079,11 +1101,6 @@ are subject to line breaking, for example---and should not be double quoted.
 Even if these descriptions are short and are not actually broken, double
 quoting them yields weird results.
 
-The careful reader will notice that, according to these guidelines, the
-``properly'' quoted @code{AC_CHECK_HEADER} example above is actually
-lacking three pairs of quotes!  Nevertheless, for the sake of readability,
-double quotation of literals is used only where needed in this manual.
-
 Some macros take optional arguments, which this documentation represents
 as @ovar{arg} (not to be confused with the quote characters).  You may
 just leave them empty, or use @samp{[]} to make the emptiness of the