doc merges

[Eric Blake]

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

This seems to be a perpetual project.

2006-09-29  Eric Blake  <address@hidden>

        * modules/m4.c (dnl): Include macro name in warning message.
        * m4/input.c (m4_skip_line): Add parameter.
        * m4/m4module.h (m4_skip_line): Likewise.
        * src/main.c (usage): Update wording.
        * doc/m4.texinfo (Inhibiting Invocation): Add xfailed test until
        issue of blind macros vs. POSIX is resolved.
        (Dnl): Merge another node from branch.

- --
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

iD8DBQFFHSCb84KuGfSFAYARAv21AKC+CB4ejIDX/zdAKPex3w9F96ZAwQCgnUw7
7+Xkr4oUpn+FJbZBxrYdaKo=
=XTUZ
-----END PGP SIGNATURE-----

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
 
address@hidden
 @comment options: -G
address@hidden ignore
address@hidden xfail
 @example
 $ @kbd{m4 -G}
 eval
@@ -1129,7 +1128,6 @@ eval
 eval(`1')
 @result{}1
 @end example
address@hidden 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.
address@hidden FIXME - should we accept usage like debugmode(+fl-q)?  Also,
address@hidden should we add debugmode(?) which expands to the current
address@hidden enabled flags, and debugmode(e?) which expands to e if e is
address@hidden 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
address@hidden, to remove the newline that follow the call to
address@hidden  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.
address@hidden 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}).
address@hidden 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.
 
address@hidden
+dnl(`args are ignored, but side effects occur',
+define(`foo', `like this')) while this text is ignored: undefine(`foo')
address@hidden:stdin:2: Warning: dnl: extra arguments ignored: 2 > 0
+See how `foo' was defined, foo?
address@hidden how foo was defined, like this?
address@hidden example
+
+If the end of file is encountered without a newline character, a
+warning is issued and dnl stops consuming input.
+
address@hidden
+define(`hi', `HI')
address@hidden
+m4wrap(`m4wrap(`2 hi
+')0 hi dnl 1 hi')
address@hidden
+^D
address@hidden: Warning: dnl: end of file treated as newline
address@hidden HI 2 HI
address@hidden 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\