Changes to m4/doc/m4.texinfo,v [branch-1_4]

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Branch:         branch-1_4
Changes by:     Eric Blake <ericb>      07/02/28 13:48:19

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.115
retrieving revision 1.1.1.1.2.116
diff -u -b -r1.1.1.1.2.115 -r1.1.1.1.2.116
--- doc/m4.texinfo      24 Feb 2007 14:02:23 -0000      1.1.1.1.2.115
+++ doc/m4.texinfo      28 Feb 2007 13:48:18 -0000      1.1.1.1.2.116
@@ -618,13 +618,12 @@
 @table @code
 @item -D @address@hidden@address@hidden
 @itemx address@hidden@address@hidden@r{]}
-This enters @var{NAME} into the symbol table, before any input files are
-read.  If @address@hidden is missing, the value is taken to be the
-empty string.  The @var{VALUE} can be any string, and the macro can be
-defined to take arguments, just as if it was defined from within the
-input.  This option may be given more than once; order with respect to
-file names is significant, and redefining the same @var{NAME} loses the
-previous value.
+This enters @var{NAME} into the symbol table.  If @address@hidden is
+missing, the value is taken to be the empty string.  The @var{VALUE} can
+be any string, and the macro can be defined to take arguments, just as
+if it was defined from within the input.  This option may be given more
+than once; order with respect to file names is significant, and
+redefining the same @var{NAME} loses the previous value.
 
 @item -I @var{DIRECTORY}
 @itemx address@hidden
@@ -1615,9 +1614,9 @@
 arguments.  The extension of accepting multiple digits is incompatible
 with @acronym{POSIX}, and is different than traditional implementations
 of @code{m4}, which only recognize one digit.  Therefore, future
-versions of @acronym{GNU} M4 will phase out this feature.
address@hidden, for an example of how to portably access the eleventh
-argument.
+versions of @acronym{GNU} M4 will phase out this feature.  To portably
+access beyond the ninth argument, you can use the @code{argn} macro
+documented later (@pxref{Shift}).
 
 @acronym{POSIX} also states that @samp{$} followed immediately by
 @address@hidden in a macro definition is implementation-defined.  This version
@@ -1645,10 +1644,10 @@
 @option{--warn-macro-sequence} command-line option (@pxref{Operation
 modes, , Invoking m4}) with the default regular expression.  This will
 add a warning any time a macro definition includes @samp{$} followed by
-multiple digits, or by @address@hidden and a digit.  The warning is not
-enabled by default, because it triggers a number of warnings in Autoconf
-2.61 (and Autoconf uses @option{-E} to treat warnings as errors), and
-because it will still be possible to restore older behavior in M4 2.0.
+multiple digits, or by @address@hidden  The warning is not enabled by
+default, because it triggers a number of warnings in Autoconf 2.61 (and
+Autoconf uses @option{-E} to treat warnings as errors), and because it
+will still be possible to restore older behavior in M4 2.0.
 
 @comment ignore
 @example
@@ -2439,6 +2438,34 @@
 @result{}divert`'dnl
 @end example
 
address@hidden nine arguments, more than
address@hidden more than nine arguments
address@hidden arguments, more than nine
+One more useful macro based on @code{shift} allows portably selecting
+an arbitrary argument (usually greater than the ninth argument), without
+relying on the @acronym{GNU} extension of multi-digit arguments
+(@pxref{Arguments}).
+
address@hidden Composite argn (@var{n}, @dots{})
+Expands to argument @var{n} out of the remaining arguments.  @var{n}
+must be a positive number.  Usually invoked as
address@hidden(address@hidden',$@@)}.
address@hidden deffn
+
+It is implemented as:
+
address@hidden
+define(`argn', `ifelse(`$1', 1, ``$2'',
+  `argn(decr(`$1'), shift(shift($@@)))')')
address@hidden
+argn(`1', `a')
address@hidden
+define(`foo', `argn(`11', $@@)')
address@hidden
+foo(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k', `l')
address@hidden
address@hidden example
+
 @node Forloop
 @section Iteration by counting
 
@@ -5716,6 +5743,9 @@
 @result{}k
 @end example
 
address@hidden
+Also see the @code{argn} macro (@pxref{Shift}).
+
 @item
 The @code{divert} (@pxref{Divert}) macro can manage more than 9
 diversions.  @acronym{GNU} @code{m4} treats all positive numbers as valid