doc merges

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.55
diff -u -p -r1.55 m4.texinfo
--- doc/m4.texinfo	29 Sep 2006 12:26:06 -0000	1.55
+++ doc/m4.texinfo	29 Sep 2006 13:25:23 -0000
@@ -1119,9 +1119,8 @@ eval(`1')
 @result{}1
 @end example
 
-@ignore
 @comment options: -G
-@comment ignore
+@comment xfail
 @example
 $ @kbd{m4 -G}
 eval
@@ -1129,7 +1128,6 @@ eval
 eval(`1')
 @result{}1
 @end example
-@end ignore
 
 There is also a command line option (@option{--prefix-builtins}, or
 @option{-P}) that renames all builtin macro names to be prefixed
@@ -2969,6 +2967,10 @@ are enabled without impacting other flag
 @samp{-}, the named flags are disabled without impacting other flags.
 Without either of these starting characters, @var{flags} simply replaces
 the previous setting.
+@comment FIXME - should we accept usage like debugmode(+fl-q)?  Also,
+@comment should we add debugmode(?) which expands to the current
+@comment enabled flags, and debugmode(e?) which expands to e if e is
+@comment currently enabled?
 
 If no flags are specified with the @option{--debug} option, the default is
 @samp{aeq}. Many examples in this manual show their output using
@@ -3125,11 +3127,18 @@ to @code{m4}.
 @section Deleting whitespace in input
 
 @cindex deleting whitespace in input
+The builtin @code{dnl} stands for ``Discard to Next Line'':
+
 @deffn {Builtin (m4)} dnl
-The builtin @code{dnl} reads and discards all characters, up to and
-including the first newline and is often used in connection with
-@code{define}, to remove the newline that follow the call to
-@code{define}.  Thus
+All characters, up to and including the next newline, are discarded
+without performing any macro expansion.  A warning is issued if the end
+of the file is encountered without a newline.
+
+The expansion of @code{dnl} is void.
+@end deffn
+
+It is often used in connection with @code{define}, to remove the
+newline that follows the call to @code{define}.  Thus
 
 @example
 define(`foo', `Macro `foo'.')dnl A very simple macro, indeed.
@@ -3138,11 +3147,12 @@ foo
 @end example
 
 The input up to and including the next newline is discarded, as opposed
-to the way comments are treated (@pxref{Comments}).
-@end deffn
+to the way comments are treated (@pxref{Comments}), when the command
+line option @option{--discard-comments} is not in effect
+(@pxref{Invoking m4}).
 
 Usually, @code{dnl} is immediately followed by an end of line or some
-other whitespace.  GNU @code{m4} will produce a warning diagnostic if
+other whitespace.  @acronym{GNU} @code{m4} will produce a warning diagnostic if
 @code{dnl} is followed by an open parenthesis.  In this case, @code{dnl}
 will collect and process all arguments, looking for a matching close
 parenthesis.  All predictable side effects resulting from this
@@ -3150,6 +3160,28 @@ collection will take place.  @code{dnl} 
 input following the matching close parenthesis up to and including the
 next newline, on whatever line containing it, will still be discarded.
 
+@example
+dnl(`args are ignored, but side effects occur',
+define(`foo', `like this')) while this text is ignored: undefine(`foo')
+@error{}m4:stdin:2: Warning: dnl: extra arguments ignored: 2 > 0
+See how `foo' was defined, foo?
+@result{}See how foo was defined, like this?
+@end example
+
+If the end of file is encountered without a newline character, a
+warning is issued and dnl stops consuming input.
+
+@example
+define(`hi', `HI')
+@result{}
+m4wrap(`m4wrap(`2 hi
+')0 hi dnl 1 hi')
+@result{}
+^D
+@error{}m4: Warning: dnl: end of file treated as newline
+@result{}0 HI 2 HI
+@end example
+
 @node Changequote
 @section Changing the quote characters
 
Index: m4/input.c
===================================================================
RCS file: /sources/m4/m4/m4/input.c,v
retrieving revision 1.47
diff -u -p -r1.47 input.c
--- m4/input.c	7 Sep 2006 23:53:04 -0000	1.47
+++ m4/input.c	29 Sep 2006 13:25:23 -0000
@@ -653,10 +653,11 @@ unget_input (int ch)
     m4_push_single (ch);
 }
 
-/* skip_line () simply discards all immediately following characters, up to
-   the first newline.  It is only used from m4_dnl ().  */
+/* skip_line () simply discards all immediately following characters,
+   up to the first newline.  It is only used from m4_dnl ().  NAME is
+   the spelling of argv[0], for use in any warning message.  */
 void
-m4_skip_line (m4 *context)
+m4_skip_line (m4 *context, const char *name)
 {
   int ch;
   const char *file = m4_get_current_file (context);
@@ -667,7 +668,7 @@ m4_skip_line (m4 *context)
   if (ch == CHAR_EOF)
     /* current_file changed; use the previous value we cached.  */
     m4_warn_at_line (context, 0, file, line,
-		     _("end of file treated as newline"));
+		     _("%s: end of file treated as newline"), name);
 }
 
 
Index: m4/m4module.h
===================================================================
RCS file: /sources/m4/m4/m4/m4module.h,v
retrieving revision 1.89
diff -u -p -r1.89 m4module.h
--- m4/m4module.h	28 Sep 2006 04:22:33 -0000	1.89
+++ m4/m4module.h	29 Sep 2006 13:25:23 -0000
@@ -386,7 +386,7 @@ extern int	m4_set_syntax	(m4_syntax_tabl
 
 extern	void	m4_input_init	(m4 *context);
 extern	void	m4_input_exit	(void);
-extern	void	m4_skip_line	(m4 *context);
+extern	void	m4_skip_line	(m4 *context, const char *);
 
 /* push back input */
 
Index: modules/m4.c
===================================================================
RCS file: /sources/m4/m4/modules/m4.c,v
retrieving revision 1.76
diff -u -p -r1.76 m4.c
--- modules/m4.c	28 Sep 2006 04:22:33 -0000	1.76
+++ modules/m4.c	29 Sep 2006 13:25:23 -0000
@@ -593,7 +593,7 @@ M4BUILTIN_HANDLER (undivert)
    lives in input.c.  */
 M4BUILTIN_HANDLER (dnl)
 {
-  m4_skip_line (context);
+  m4_skip_line (context, M4ARG (0));
 }
 
 /* Shift all argument one to the left, discarding the first argument.  Each
Index: src/main.c
===================================================================
RCS file: /sources/m4/m4/src/main.c,v
retrieving revision 1.89
diff -u -p -r1.89 main.c
--- src/main.c	29 Sep 2006 12:26:07 -0000	1.89
+++ src/main.c	29 Sep 2006 13:25:23 -0000
@@ -146,7 +146,7 @@ FLAGS is any of:\n\
   l   include current input line number in trace and debug\n\
 "), stdout);
       fputs (_("\
-  m   show actions related to modules in debug\n\
+  m   show module information in debug and dumpdef\n\
   p   show results of path searches in debug\n\
   q   quote values as necessary in dumpdef and trace, useful with a or e\n\
   s   show full stack of pushdef values in dumpdef\n\