add macro varargs node to cpp documentation

[Matthias Klose <doko at cs dot tu-berlin dot de>]

The documentation about making macros with a variable number of
arguments (Node Macro Varargs) is in the compiler's documentation, not 
in the preprocessor documentation. The cpp docs don't have an
extensions node, so this is added to the macros node.

Sat Aug  7 14:56:50 1999  Matthias Klose  <doko@cs.tu-berlin.de>

	* cpp.texi: cpp.texi: add a node documenting macro varargs (copied
 	from extend.texi).

--- gcc/cpp.texi~	Wed May 19 13:22:57 1999
+++ gcc/cpp.texi	Sat Aug  7 14:53:42 1999
@@ -542,6 +542,7 @@
 * Simple Macros::    Macros that always expand the same way.
 * Argument Macros::  Macros that accept arguments that are substituted
                        into the macro expansion.
+* Macro Varargs::    Macros with variable number of arguments.
 * Predefined::       Predefined macros that are always available.
 * Stringification::  Macro arguments converted into string constants.
 * Concatenation::    Building tokens from parts taken from macro arguments.
@@ -645,7 +646,7 @@
 that the result of its expansion is checked for more macro names.
 @xref{Cascaded Macros}.
 
-@node Argument Macros, Predefined, Simple Macros, Macros
+@node Argument Macros, Macro Varargs, Simple Macros, Macros
 @subsection Macros with Arguments
 @cindex macros with argument
 @cindex arguments in macro definitions
@@ -799,7 +800,68 @@
 the left parenthesis; it's the @emph{definition} where it matters whether
 there is a space.
 
-@node Predefined, Stringification, Argument Macros, Macros
+@node Macro Varargs, Predefined, Argument Macros, Macros
+@subsection Macros with Variable Numbers of Arguments
+@cindex variable number of arguments
+@cindex macro with variable arguments
+@cindex rest argument (in macro)
+
+In GNU C, a macro can accept a variable number of arguments, much as a
+function can.  The syntax for defining the macro looks much like that
+used for a function.  Here is an example:
+
+@example
+#define eprintf(format, args...)  \
+ fprintf (stderr, format , ## args)
+@end example
+
+Here @code{args} is a @dfn{rest argument}: it takes in zero or more
+arguments, as many as the call contains.  All of them plus the commas
+between them form the value of @code{args}, which is substituted into
+the macro body where @code{args} is used.  Thus, we have this expansion:
+
+@example
+eprintf ("%s:%d: ", input_file_name, line_number)
+@expansion{}
+fprintf (stderr, "%s:%d: " , input_file_name, line_number)
+@end example
+
+@noindent
+Note that the comma after the string constant comes from the definition
+of @code{eprintf}, whereas the last comma comes from the value of
+@code{args}.
+
+The reason for using @samp{##} is to handle the case when @code{args}
+matches no arguments at all.  In this case, @code{args} has an empty
+value.  In this case, the second comma in the definition becomes an
+embarrassment: if it got through to the expansion of the macro, we would
+get something like this:
+
+@example
+fprintf (stderr, "success!\n" , )
+@end example
+
+@noindent
+which is invalid C syntax.  @samp{##} gets rid of the comma, so we get
+the following instead:
+
+@example
+fprintf (stderr, "success!\n")
+@end example
+
+This is a special feature of the GNU C preprocessor: @samp{##} before a
+rest argument that is empty discards the preceding sequence of
+non-whitespace characters from the macro definition.  (If another macro
+argument precedes, none of it is discarded.)
+
+It might be better to discard the last preprocessor token instead of the
+last preceding sequence of non-whitespace characters; in fact, we may
+someday change this feature to do so.  We advise you to write the macro
+definition so that the preceding sequence of non-whitespace characters
+is just a single token, so that the meaning will not change if we change
+the definition of this feature.
+
+@node Predefined, Stringification, Macro Varargs, Macros
 @subsection Predefined Macros
 
 @cindex predefined macros