Re: AC_DEFINE_UNQUOTED doc update

[Paul Eggert]

Akim Demaille <address@hidden> writes:

> I strongly recommend quoting every argument once.  The recent changes
> that specify that it's not always useful are just making things easier
> to write incorrectly.

Are you referring to the changes mentioned below?  If so, I don't
follow this remark, as these changes make the manual more cautious
about quoting (not less cautious).  It's true that the manual is still
not as cautious as your strong recommendation, but at least it's
closer to the strong recommendation than it was before.

Fixing the manual (and code) to follow the strong recommendation
throughout would be a lot more work than this (work I don't have the
time to do right now either :-).


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