Re: AC_DEFINE_UNQUOTED doc update

[Paul Eggert]

Ralf Wildenhues <address@hidden> writes:

> the documentation should also mention the need for double-m4-quoted
> second argument in order to achieve this.

Sorry, I don't understand this point.  For example:

> -AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups,
> +AC_DEFINE_UNQUOTED(GETGROUPS_T, [$ac_cv_type_getgroups],

The added quotes here don't change the meaning, since
ac_cv_type_getgroups is not a macro.  And if ac_cv_type_getgroups were
a macro and you didn't want it invoked (ouch!), you'd need
double-quotes.

> The text does not specify exactly what `simple text' in m4 context
> is, and I just don't understand the reason against telling users to
> quote every argument at least once.

Thanks for mentioning that.  I installed the following to try to
help clarify things.

2005-04-29  Paul Eggert  <address@hidden>

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

--- autoconf.texi       29 Apr 2005 13:16:55 -0000      1.889
+++ autoconf.texi       29 Apr 2005 19:22:57 -0000      1.890
@@ -988,8 +988,8 @@ space between the macro name and the ope
 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:
@@ -1005,15 +1005,37 @@ AC_CHECK_HEADER([stdio.h],
 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])])
address@hidden example
+
address@hidden
+because @samp{1} cannot contain a macro call.  Here, the argument of
address@hidden 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
address@hidden 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:
+
address@hidden
 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
address@hidden  Though it is also safe here to omit the quotes around
address@hidden 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 exampl
 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