03-quote-doc.patch

[Akim Demaille]

Index: ChangeLog
from  Akim Demaille  <address@hidden>
        
        * doc/autoconf.texi (Evaluation Macros): New.
        * lib/m4sugar/m4sugar.m4 (m4_lquote): Remove, it is totally
        useless.
        (_m4_foreach): Define the variant with immediate evaluation so
        that it contains exactly the items, not an expression which
        evaluation is the current item.
        (m4_re_string, m4_re_word): Don't over quote them.
        
Index: doc/autoconf.texi
--- doc/autoconf.texi Tue, 26 Feb 2002 22:32:15 +0100 akim
+++ doc/autoconf.texi Fri, 01 Mar 2002 13:40:33 +0100 akim
@@ -327,6 +327,7 @@ @node Top
 Programming in M4sugar
 
 * Redefined M4 Macros::         M4 builtins changed in M4sugar
+* Evaluation Macros::           More quotation and evaluation control
 * Forbidden Patterns::          Catching unexpanded macros
 
 Writing Autoconf Macros
@@ -6853,6 +6854,7 @@ @node Programming in M4sugar
 
 @menu
 * Redefined M4 Macros::         M4 builtins changed in M4sugar
+* Evaluation Macros::           More quotation and evaluation control
 * Forbidden Patterns::          Catching unexpanded macros
 @end menu
 
@@ -6939,6 +6941,44 @@ m4_define([foobar], [FOOBAR])
 @result{}FOOBAR
 @end example
 @end defmac
+
address@hidden Evaluation Macros
address@hidden Evaluation Macros
+
+The following macros give some control over the order of the evaluation
+by adding or removing levels of quotes.  They are meant for hard core M4
+programmers.
+
address@hidden m4_dquote (@var{arg1}, ...)
address@hidden dquote
+Return the arguments as a quoted list of quoted arguments.
address@hidden defmac
+
address@hidden m4_quote (@var{arg1}, ...)
address@hidden quote
+Return the arguments as a single entity, i.e., wrap them into a pair of
+quotes.
address@hidden defmac
+
+The following example aims at emphasing the difference between (i), not
+using these macros, (ii), using @code{m4_quote}, and (iii), using
address@hidden
+
address@hidden
+$ @kbd{cat example.m4}
+# Over quote, so that quotes are visible.
+m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
+m4_divert(0)dnl
+show(a, b)
+show(m4_quote(a, b))
+show(m4_dquote(a, b))
+$ @kbd{autom4te -l m4sugar example.m4}
+$1 = a, $@@ = [a],[b]
+$1 = a,b, $@@ = [a,b]
+$1 = [a],[b], $@@ = [[a],[b]]
address@hidden example
+
+
 
 @node Forbidden Patterns
 @subsection Forbidden Patterns
Index: lib/m4sugar/m4sugar.m4
--- lib/m4sugar/m4sugar.m4 Thu, 28 Feb 2002 19:30:33 +0100 akim
+++ lib/m4sugar/m4sugar.m4 Fri, 01 Mar 2002 13:33:06 +0100 akim
@@ -523,17 +523,14 @@ m4_define([m4_popdef],
 
 # m4_quote(ARGS)
 # --------------
-# Return ARGS quoted.  Note that a list of quoted arguments is returned,
-# not a quoted list.
+# Return ARGS as a single arguments.
 #
 # It is important to realize the difference between `m4_quote(exp)' and
 # `[exp]': in the first case you obtain the quoted *result* of the
 # expansion of EXP, while in the latter you just obtain the string
 # `exp'.
 m4_define([m4_quote],  [[$*]])
-m4_define([m4_lquote], address@hidden)
-m4_define([m4_dquote], address@hidden)
-
+m4_define([m4_dquote],  address@hidden)
 
 # m4_noquote(STRING)
 # ------------------
@@ -701,9 +698,9 @@ m4_define([m4_car], [[$1]])
 m4_define([m4_cdr], [m4_dquote(m4_shift($@))])
 m4_define([_m4_foreach],
 [m4_if([$2], [[]], [],
-       [m4_define([$1], [m4_car($2)])$3[]_m4_foreach([$1],
-                                                     m4_cdr($2),
-                                                     [$3])])])
+       [m4_define([$1], m4_car($2))$3[]_m4_foreach([$1],
+                                                   m4_cdr($2),
+                                                   [$3])])])
 
 
 
@@ -1377,7 +1374,7 @@ m4_define([m4_re_escape],
 # ------------
 # Regexp for `[a-zA-Z_0-9]*'
 m4_define([m4_re_string],
-m4_quote(m4_defn([m4_cr_symbols2]))dnl
+m4_defn([m4_cr_symbols2])dnl
 [*]dnl
 )
 
@@ -1386,7 +1383,7 @@ m4_define([m4_re_string],
 # ----------
 # Regexp for `[a-zA-Z_][a-zA-Z_0-9]*'
 m4_define([m4_re_word],
-m4_quote(m4_defn([m4_cr_symbols1]))dnl
+m4_defn([m4_cr_symbols1])dnl
 m4_defn([m4_re_string])dnl
 )