Re: head: more doc syncs

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Eric Blake on 8/23/2006 6:24 PM:
> 
> Another round.  This time, I made a testsuite improvement - now the manual
> can demonstrate the effect of the command line on examples.

Next node.  And now I am turning up failures in the testsuite that need
patches ported from the branch.

2006-08-25  Eric Blake  <address@hidden>

        * doc/m4.texinfo (Macro Arguments): Another section merged;
        testsuite failures now exposed.

- --
Life is short - so eat dessert first!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.1 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFE7xgl84KuGfSFAYARAqKTAKCwbFLn1V3+aXrt6ZbiRNLADZ1b0ACfdGKE
LIkgf5EDc3IYWbELeRWTatY=
=5EFJ
-----END PGP SIGNATURE-----

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.33
diff -u -p -r1.33 m4.texinfo
--- doc/m4.texinfo      24 Aug 2006 00:25:04 -0000      1.33
+++ doc/m4.texinfo      25 Aug 2006 15:31:05 -0000
@@ -838,6 +838,7 @@ level of quotes stripped off.  Thus
 @result{}
 @end example
 
address@hidden
 is the empty string, and double-quoting turns into single-quoting.
 
 @comment ignore
@@ -1137,7 +1138,7 @@ x`'y
 
 Unquoted strings on either side of a quoted string are subject to
 being recognized as macro names.  In the following example, quoting the
-empty string allows for the @code{macro} to be recognized as such:
+empty string allows for the second @code{macro} to be recognized as such:
 
 @example
 define(`macro', `m')
@@ -1174,14 +1175,40 @@ as a macro.
 
 If the name is followed by an opening parenthesis, the arguments will be
 collected before the macro is called.  If too few arguments are
-supplied, the missing arguments are taken to be the empty string.  If
-there are too many arguments, the excess arguments are ignored.  Leading
-whitespace are stripped of all arguments.
+supplied, the missing arguments are taken to be the empty string.
+However, some builtins are documented to behave differently for a
+missing optional argument than for an explicit empty string.  If
+there are too many arguments, the excess arguments are ignored.
+Unquoted leading whitespace is stripped off all arguments.
 
 Normally @code{m4} will issue warnings if a builtin macro is called
 with an inappropriate number of arguments, but it can be suppressed with
-the @samp{-Q} command line option.  For user defined macros, there is no
-check of the number of arguments given.
+the @option{--quiet} command line option (or @option{--silent}, or
address@hidden, @pxref{Invoking m4}).  For user
+defined macros, there is no check of the number of arguments given.
+
address@hidden
+$ @kbd{m4}
+index(`abc')
address@hidden:input.m4:1: Warning: index: too few arguments: 1 < 2
address@hidden
+index(`abc',)
address@hidden
+index(`abc', `b', `ignored')
address@hidden:input.m4:3: Warning: index: extra arguments ignored: 3 > 2
address@hidden
address@hidden example
+
address@hidden options: -Q
address@hidden
+$ @kbd{m4 -Q}
+index(`abc')
address@hidden
+index(`abc',)
address@hidden
+index(`abc', `b', `ignored')
address@hidden
address@hidden example
 
 Macros are expanded normally during argument collection, and whatever
 commas, quotes and parentheses that might show up in the resulting
@@ -1193,11 +1220,33 @@ expanded text will serve to define the a
 bar(a foo, d)
 @end example
 
address@hidden
 is a macro call with four arguments, which are @samp{a }, @samp{b},
 @samp{c} and @samp{d}.  To understand why the first argument contains
 whitespace, remember that leading unquoted whitespace is never part
 of an argument, but trailing whitespace always is.
 
+It is possible for a macro's definition to change during argument
+collection, in which case the expansion uses the definition that was in
+effect at the time the opening @samp{(} was seen.
+
address@hidden
+define(`f', `1')
address@hidden
+f(define(`f', `2'))
address@hidden
+f
address@hidden
address@hidden example
+
+It is an error if the end of file occurs while collecting arguments.
+
address@hidden
+define(
+^D
address@hidden:input.m4:1: ERROR: end of file in argument list
address@hidden example
+
 @node Quoting Arguments
 @section Quoting macro arguments