Changes to m4/doc/m4.texinfo,v

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Eric Blake <ericb>      06/09/29 13:33:14

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.55
retrieving revision 1.56
diff -u -b -r1.55 -r1.56
--- doc/m4.texinfo      29 Sep 2006 12:26:06 -0000      1.55
+++ doc/m4.texinfo      29 Sep 2006 13:33:13 -0000      1.56
@@ -1119,9 +1119,8 @@
 @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(`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 @@
 @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 @@
 @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 @@
 @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 @@
 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