document m4_foreach*/AC_FOREACH

[Ralf Wildenhues]

To fulfill my months-old promise to document m4_foreach..

OK to apply?  I think consensus back then was that although AC_FOREACH
was never documented, it was useful to mention it (as deprecated).

Cheers,
Ralf

        * doc/autoconf.texi (Looping constructs): New node, to
        document m4_for, m4_foreach, m4_foreach_w, and mention
        obsolete AC_FOREACH.
        (Obsolete Macros): Document AC_FOREACH.

Index: doc/autoconf.texi
===================================================================
RCS file: /cvsroot/autoconf/autoconf/doc/autoconf.texi,v
retrieving revision 1.946
diff -u -r1.946 autoconf.texi
--- doc/autoconf.texi   13 Feb 2006 18:46:04 -0000      1.946
+++ doc/autoconf.texi   14 Feb 2006 22:47:27 -0000
@@ -437,6 +437,7 @@
 Programming in M4sugar
 
 * Redefined M4 Macros::         M4 builtins changed in M4sugar
+* Looping constructs::          Iteration in M4
 * Evaluation Macros::           More quotation and evaluation control
 * Forbidden Patterns::          Catching unexpanded macros
 
@@ -8772,6 +8773,7 @@
 
 @menu
 * Redefined M4 Macros::         M4 builtins changed in M4sugar
+* Looping constructs::          Iteration in M4
 * Evaluation Macros::           More quotation and evaluation control
 * Forbidden Patterns::          Catching unexpanded macros
 @end menu
@@ -8888,6 +8890,46 @@
 to recover the behavior of the builtin.
 @end defmac
 
+
+
address@hidden Looping constructs
address@hidden Looping constructs
+
+The following macros allow to implement loops in m4.
+
address@hidden m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, 
@var{expression})
address@hidden
+For each numeric value between @var{first} and @var{last}, including
+both bounds, expand @var{expression} with the counter assigned to
address@hidden  @var{step} may be @samp{+1}, or @samp{-1}.  If it is given,
+it has to match the order of the limits.
address@hidden defmac
+
address@hidden m4_foreach (@var{var}, @var{list}, @var{expression})
address@hidden
+Loop over the comma-separated m4 list @var{list}, assigning each value
+to @var{var}, and expand @var{expression}.  The following example will
+output two lines:
+
address@hidden
+m4_foreach([myvar], [[foo], [bar, baz]],
+           [echo myvar
+])
+
address@hidden example
address@hidden defmac
+
address@hidden m4_foreach_w (@var{var}, @var{list}, @var{expression})
address@hidden
+Loop over the whitespace-separated list @var{list}, assigning each value
+to @var{var}, and expand @var{expression}.
+
+The deprecated macro @code{AC_FOREACH} is an alias of
address@hidden
address@hidden defmac
+
+
+
 @node Evaluation Macros
 @subsection Evaluation Macros
 
@@ -14710,6 +14752,11 @@
 @code{AC_PATH_XTRA}
 @end defmac
 
address@hidden AC_FOREACH
address@hidden
address@hidden
address@hidden defmac
+
 @defmac AC_FUNC_CHECK
 @acindex{FUNC_CHECK}
 @code{AC_CHECK_FUNC}