2004-10-27  Stepan Kasal  <address@hidden>

	* doc/autoconf.texi (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.

--- doc/autoconf.texi.a1	2004-10-27 09:45:46.000000000 +0200
+++ doc/autoconf.texi	2004-10-27 11:12:47.000000000 +0200
@@ -1068,6 +1068,12 @@
 @noindent
 address@hidden, you actually produce @samp{char b[10];} this time!
 
+On the other hand, the ``descriptions'' (eg.@ the last parameter of
address@hidden or @code{AS_HELP_STRING}) are not ``literals''---they
+are subject to line breaking, for example---and cannot be double quoted.
+Even if these descriptions are short and are not actually broken, you'd
+get weird results if you double quoted them.
+
 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,
@@ -8138,9 +8144,10 @@
 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
-unexpanded macros.  The @command{autoconf} program checks for this problem
-by doing @samp{grep AC_ configure}.
+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}.  Or you may see weirdly looking
+text in ``descriptions'', if you double quote them.
 
 
 @c ---------------------------------------- Using autom4te
@@ -13055,16 +13062,15 @@
 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}.
+Please note that the second argument of @code{AS_HELP_STRING} is
address@hidden a literal and may 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:
 
@@ -13080,9 +13086,8 @@
 @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)])
+             [AS_HELP_STRING([--with-$1], [use $1 (default is $2)])],
+             ac_cv_use_$1=$withval, ac_cv_use_$1=no)])
 @end example
 @end defmac