branch-1_4 docs on arguments

[Eric Blake]

Today was the first time I realized m4 was already compliant with
the POSIX requirement that unquoted parenthesis around commas
stop the commas from delimiting macro arguments.  So it was worth
documenting and making sure we don't regress on this point, since
I had never seen this use of m4 before.

Plus it points out a weird corner case of the interaction between
comments with mismatched quoting and address@hidden  But sure enough,
Solaris m4 agreed on the behavior.  The thing that Solaris didn't
agree with was POSIX statement that changequote(^) used
newline as the close terminator; instead, it behaved as though
I explicitly used changequote(^,^).  I'll be filing an aardvark to
get a POSIX interpretation on that (I have been filing a few
lately to clarify GNU behaviors that are not compliant with the
current POSIX wording).

2006-06-26  Eric Blake  <address@hidden>

        * doc/m4.texinfo (Quoting Arguments): Document that unquoted
        parenthesis group arguments.
        (Pseudo Arguments): Expand tests to show this.
        (Incompatibilities): Contrast traditional behavior of
        changequote.

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.24
diff -u -p -r1.1.1.1.2.24 m4.texinfo
--- doc/m4.texinfo      23 Jun 2006 13:22:30 -0000      1.1.1.1.2.24
+++ doc/m4.texinfo      27 Jun 2006 04:07:30 -0000
@@ -886,6 +886,7 @@ 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
@@ -919,7 +920,11 @@ argument, all unquoted parentheses must 
 foo(() (`(') `(')
 @end example
 
-is a macro call, with one argument, whose value is @samp{()@w{ }(()@w{ }(}.
address@hidden
+is a macro call, with one argument, whose value is @samp{() (() (}.
+Commas separate arguments, except when they occur inside quotes,
+comments, or unquoted parentheses, @pxref(Pseudo Arguments} for
+examples.
 
 It is common practice to quote all arguments to macros, unless you are
 sure you want the arguments expanded.  Thus, in the above
@@ -933,7 +938,7 @@ foo(`() (() (')
 It is, however, in certain cases necessary or convenient to leave out
 quotes for some arguments, and there is nothing wrong in doing it.  It
 just makes life a bit harder, if you are not careful.  For consistency,
-this manual follows the rule of thumb that each layer of parenthesis
+this manual follows the rule of thumb that each layer of parentheses
 introduces another layer of single quoting, except when showing the
 consequences of quoting rules.  This is done even when the quoted string
 cannot be a macro, such as with integers.
@@ -1115,6 +1120,13 @@ nargs()
 @result{}1
 nargs(`arg1', `arg2', `arg3')
 @result{}3
+nargs(`commas can be quoted, like this')
address@hidden
+nargs(arg1#inside comments, commas do not separate arguments
+still arg1)
address@hidden
+nargs((unquoted parentheses, like this, group arguments))
address@hidden
 @end example
 
 The notation @code{$*} can be used in the expansion text to denote all
@@ -1159,7 +1171,26 @@ echo2(`foo')
 @end example
 
 @noindent
address@hidden, if you do not understand this.
address@hidden, if you do not understand this.  As another example of the
+difference, remember that comments encountered in arguments are passed
+untouched to the macro, and that quoting disables comments.
+
address@hidden
+define(`echo1', `$*')
address@hidden
+define(`echo2', `$@')
address@hidden
+define(`foo', `bar')
address@hidden
+echo1(#foo'foo
+foo)
address@hidden'foo
address@hidden
+echo2(#foo'foo
+foo)
address@hidden
address@hidden'
address@hidden example
 
 A @samp{$} sign in the expansion text, that is not followed by anything
 @code{m4} understands, is simply copied to the macro expansion, as any
@@ -3723,7 +3754,10 @@ of the macro is different even if the in
 @item
 @acronym{POSIX} requires @code{changequote(@var{arg})}
 (@pxref{Changequote}) to use newline as the close quote, but GNU
address@hidden uses @samp{'} as the close quote.
address@hidden uses @samp{'} as the close quote.  Meanwhile,  some
+traditional implementations use @var{arg} as the close quote, making it
+impossible to nest quotes.  For predictable results, never call
+changequote with just one argument.
 
 @item
 Traditional @code{m4} treats @code{traceon} (@pxref{Trace}) without