Document m4_expand limitation.

* lib/m4sugar/m4sugar.m4 (m4_expand): Mention problem with
unbalanced parse.
* doc/autoconf.texi (Pretty Help Strings, Evaluation Macros)
(Writing Testsuites): Mention limitations inherited from
m4_expand.

Signed-off-by: Eric Blake <ebb9@byu.net>

diff --git a/ChangeLog b/ChangeLog
index bd1e5864c74c1b52727ff65db10c65860b28faf8..9cd6b9ff4a63efa647e338ffcd529d6f3d9eb82b 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2007-10-19  Eric Blake  <ebb9@byu.net>
 
+       Document m4_expand limitation.
+       * lib/m4sugar/m4sugar.m4 (m4_expand): Mention problem with
+       unbalanced parse.
+       * doc/autoconf.texi (Pretty Help Strings, Evaluation Macros)
+       (Writing Testsuites): Mention limitations inherited from
+       m4_expand.
+
        Improve AT_BANNER handling.
        * lib/autotest/general.m4 (BANNERS): New named diversion.
        (TESTS_END): Diversion no longer used.

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index ff79cb0ead36ad510e63c7f5ef487609bd6f4c9b..cd04092366927a3efe1a2e1da38f45f05610e5c6 100644 (file)
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -10768,6 +10768,12 @@ collection rules discard the whitespace.  However, with @code{m4_expand},
 whitespace is discarded only if it results from unquoted commas in the
 expansion of macros contained in @var{arg}.
 
+Note that @code{m4_expand} cannot parse everything.  The expansion of
+@var{arg} must not contain unbalanced quotes (although quadrigraphs can
+get around this), nor unbalanced parenthesis (portable shell @code{case}
+statements are a major culprit here, but creative shell comments can get
+around this).
+
 @example
 m4_define([active], [ACT, IVE])dnl
 m4_define([active2], [[ACT, IVE]])dnl
@@ -17369,7 +17375,8 @@ Since it is not expanded, it should not be double quoted.
 
 The @code{AS_HELP_STRING} macro is particularly helpful when the
 @var{left-hand-side} and/or @var{right-hand-side} are composed of macro
-arguments, as shown in the following example.
+arguments, as shown in the following example.  Be aware that
+@var{left-hand-side} may not contain unbalanced quotes or parenthesis.
 
 @example
 AC_DEFUN([MY_ARG_WITH],
@@ -19938,7 +19945,8 @@ isolation.
 This macro starts a group of related tests, all to be executed in the
 same subshell.  It accepts a single argument, which holds a few words
 (no more than about 30 or 40 characters) quickly describing the purpose
-of the test group being started.
+of the test group being started.  @var{test-group-name} must not contain
+unbalanced quotes or parenthesis.
 @end defmac
 
 @defmac AT_KEYWORDS (@var{keywords})

diff --git a/lib/m4sugar/m4sugar.m4 b/lib/m4sugar/m4sugar.m4
index b7ca5eaefacb7f14172c057ae5ff0df381db5e25..70b9a84a889dffe395b3aec309e404c5539cdb50 100644 (file)
--- a/lib/m4sugar/m4sugar.m4
+++ b/lib/m4sugar/m4sugar.m4
@@ -675,6 +675,10 @@ m4_define([m4_echo], [$@])
 #   m4_expand([active, active2])
 #   => ACT,IVE, ACT, IVE
 #
+# Unfortunately, due to limitations in m4, ARG must contain balanced quotes
+# (use quadrigraphs) and balanced parenthesis (use creative shell comments
+# when writing shell case statements).
+#
 # Splitting a quoted ARG on `,' preserves space, but produces a quoted list.
 # Unquote the list, then expand each argument while preserving the leading
 # spaces; finally, collect each argument back into the final string.