Re: autconf, configure & purify...

[Ben Pfaff]

Eric Blake <address@hidden> writes:

> According to Ben Pfaff on 10/23/2008 10:06 PM:
>>> AC_ARG_ENABLE([purify],
>>>   [AS_HELP_STRING([--enable-purify], [build with Purify [default=no]]),
>> 
>> The Autoconf manual explicitly recommends underquoting
>> AS_HELP_STRING (though not its arguments):
>
> Where did you see that, and in which version of the manual?  In the
> current autoconf.texi, every mention of AS_HELP_STRING is within quotes.

Ouch.  I owe you an apology: I am looking at an antique manual,
for Autoconf 2.59.  This happens to be the one locally installed
because Debian has never upgraded the autoconf-doc package from
that version, even though autoconf itself is newer.

I maintain the autoconf package for Debian, but not autoconf-doc,
and hadn't realized that the latter had fallen so badly behind.
(See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=447861.)

For the record, here is the commit that deleted the advice in
question from the manual:

commit 39dc4d1039a49ac30a00869612ff17e63d693d2e
Author: Paul Eggert <address@hidden>
Date:   Mon Nov 22 23:31:56 2004 +0000

    (Autoconf Language): Explain that
    ``descriptions'' may not be double quotes.
    (Quotation Rule Of Thumb): Likewise.
    (Pretty Help Strings): Likewise; remove the wrong comment;
    simplify the examples and improve their quoting.

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 0eeb0e6..6aeee50 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -1068,6 +1068,12 @@ AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you 
lose])])
 @noindent
 address@hidden, you actually produce @samp{char b[10];} this time!
 
+On the other hand, descriptions (e.g., the last parameter of
address@hidden or @code{AS_HELP_STRING}) are not literals---they
+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,
@@ -8114,9 +8120,11 @@ your macros.  If one or more words have disappeared in 
the M4
 output, you need more quotes.  When in doubt, quote.
 
 However, it's also possible to put on too many layers of quotes.  If
-this happens, the resulting @command{configure} script will contain
+this happens, the resulting @command{configure} script may contain
 unexpanded macros.  The @command{autoconf} program checks for this problem
-by doing @samp{grep AC_ configure}.
+by looking for the string @samp{AC_} in @file{configure}.  However, this
+heuristic does not work in general: for example, it does not catch
+overquoting in @code{AC_DEFINE} descriptions.
 
 
 @c ---------------------------------------- Using autom4te
@@ -13042,22 +13050,22 @@ Expands into an help string that looks pretty when 
the user executes
 Options}).  The following example will make this clearer.
 
 @example
-AC_DEFUN([TEST_MACRO],
-[AC_ARG_WITH([foo],
-             AS_HELP_STRING([--with-foo],
-                            [use foo (default is NO)]),
-             [ac_cv_use_foo=$withval], [ac_cv_use_foo=no])
-AC_CACHE_CHECK([whether to use foo],
-               [ac_cv_use_foo], [ac_cv_use_foo=no])])
+AC_ARG_WITH(foo,
+  [AS_HELP_STRING(--with-foo,
+     [use foo (default is no)])],
+  [ac_cv_use_foo=$withval],
+  [ac_cv_use_foo=no])
 @end example
 
-Please note that the call to @code{AS_HELP_STRING} is @strong{unquoted}.
+The second argument of @code{AS_HELP_STRING} is
+not a literal, and should not be double quoted. @xref{Autoconf
+Language}, for a more detailed explanation.
 Then the last few lines of @samp{configure --help} will appear like
 this:
 
 @example
 --enable and --with options recognized:
-  --with-foo              use foo (default is NO)
+  --with-foo              use foo (default is no)
 @end example
 
 The @code{AS_HELP_STRING} macro is particularly helpful when the
@@ -13065,11 +13073,11 @@ The @code{AS_HELP_STRING} macro is particularly 
helpful when the
 arguments, as shown in the following example.
 
 @example
-AC_DEFUN(MY_ARG_WITH,
-[AC_ARG_WITH([$1],
-             AS_HELP_STRING([--with-$1], [use $1 (default is $2)]),
-             ac_cv_use_$1=$withval, ac_cv_use_$1=no),
-AC_CACHE_CHECK(whether to use $1, ac_cv_use_$1, ac_cv_use_$1=$2)])
+AC_DEFUN([MY_ARG_WITH],
+  [AC_ARG_WITH([$1],
+     [AS_HELP_STRING([--with-$1], [use $1 (default is $2)])],
+     [ac_cv_use_$1=$withval],
+     [ac_cv_use_$1=no])])
 @end example
 @end defmac
 

-- 
Ben Pfaff 
http://benpfaff.org