Changes to m4/doc/m4.texinfo,v [branch-1_4]

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Branch:         branch-1_4
Changes by:     Eric Blake <ericb>      06/07/14 15:15:59

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.41
retrieving revision 1.1.1.1.2.42
diff -u -b -r1.1.1.1.2.41 -r1.1.1.1.2.42
--- doc/m4.texinfo      13 Jul 2006 22:09:54 -0000      1.1.1.1.2.41
+++ doc/m4.texinfo      14 Jul 2006 15:15:58 -0000      1.1.1.1.2.42
@@ -1427,6 +1427,8 @@
 definition.  This token is only meaningful as the second argument to
 @code{define} (and @code{pushdef}), and is ignored in any other context.
 
+The macro @code{defn} is recognized only with parameters.
+
 Its normal use is best understood through an example, which shows how to
 rename @code{undefine} to @code{zap}:
 
@@ -1470,7 +1472,27 @@
 @result{}
 @end example
 
-The macro @code{defn} is recognized only with parameters.
+However, it is important to remember that @code{m4} rescanning is purely
+textual.  If an unbalanced right quote string occurs in a macro
+definition, the rescan will see that embedded quote as the termination
+of the quoted string, and the remainder of the macro's definition will
+be rescanned unquoted.  Thus it is a good idea to avoid unbalanced right
+quotes in macro definitions or arguments to macros.
+
address@hidden
+define(`foo', a'a)
address@hidden
+define(`a', `A')
address@hidden
+define(`echo', `$@')
address@hidden
+foo
address@hidden'A
+defn(`foo')
address@hidden'
+echo(foo)
address@hidden'
address@hidden example
 
 @node Pushdef
 @section Temporarily redefining macros
@@ -1617,6 +1639,51 @@
 
 The macro @code{builtin} is recognized only with parameters.
 
+This can be used even if @var{name} has been given another definition
+that has covered the original, or been undefined so that no @var{name}
+maps to the builtin.
+
address@hidden
+pushdef(`define', `hidden')
address@hidden
+undefine(`undefine')
address@hidden
+define(`foo', `bar')
address@hidden
+foo
address@hidden
+builtin(`define', `foo', `BAR')
address@hidden
+foo
address@hidden
+undefine(`foo')
address@hidden(foo)
+foo
address@hidden
+builtin(`undefine', `foo')
address@hidden
+foo
address@hidden
address@hidden example
+
+Note that this can be used to invoke builtins that normally require
+parameters without actually providing them; but it will provoke a
+warning, and usually result in a void expansion.
+
address@hidden
+builtin
address@hidden
+builtin()
address@hidden:2: m4: undefined builtin `'
address@hidden
+builtin(`builtin')
address@hidden:3: m4: Warning: too few arguments to builtin `builtin'
address@hidden
+builtin(`builtin',)
address@hidden:4: m4: undefined builtin `'
address@hidden
address@hidden example
+
 @node Conditionals
 @chapter Conditionals, loops, and recursion
 
@@ -2114,9 +2181,31 @@
 The argument @var{flags} should be a subset of the letters listed above.
 As special cases, if the argument starts with a @samp{+}, the flags are
 added to the current debug flags, and if it starts with a @samp{-}, they
-are removed.  If no argument is present, the debugging flags are set to
-zero (as if no @option{-d} was given), and with an empty argument the flags
-are reset to the default.
+are removed.  If no argument is present, the debugging flags are cleared
+(as if no @option{-d} was given), and with an empty argument the flags
+are reset to the default of @samp{aeq}.
+
address@hidden
+define(`foo', `FOO')
address@hidden
+traceon(`foo')
address@hidden
+debugmode()
address@hidden
+foo
address@hidden: -1- foo -> `FOO'
address@hidden
+debugmode
address@hidden
+foo
address@hidden: -1- foo
address@hidden
+debugmode(`+l')
address@hidden
+foo
address@hidden:8: -1- foo
address@hidden
address@hidden example
 
 @node Debug Output
 @section Saving debugging output
@@ -2140,6 +2229,25 @@
 @code{debugfile} is called without any arguments, debug and trace output
 are sent to the standard error output.
 
address@hidden
+traceon(`divnum')
address@hidden
+divnum(`extra')
address@hidden:2: m4: Warning: excess arguments to builtin `divnum' ignored
address@hidden: -1- divnum(`extra') -> `0'
address@hidden
+debugfile()
address@hidden
+divnum(`extra')
address@hidden:4: m4: Warning: excess arguments to builtin `divnum' ignored
address@hidden
+debugfile
address@hidden
+divnum
address@hidden: -1- divnum -> `0'
address@hidden
address@hidden example
+
 @node Input Control
 @chapter Input control
 
@@ -2190,11 +2298,11 @@
 next newline, on whatever line containing it, will still be discarded.
 
 @example
-dnl(`this is ignored',
-`so is this') and this too
+dnl(`args are ignored, but side effects occur',
+define(`foo', `like this')) while this text is ignored: undefine(`foo')
 @error{}stdin:2: m4: Warning: excess arguments to builtin `dnl' ignored
-but not this
address@hidden not this
+See how `foo' was defined, foo?
address@hidden how foo was defined, like this?
 @end example
 
 @node Changequote
@@ -2310,6 +2418,8 @@
 
 Calling @code{changecom} without any arguments, or with an empty string
 for the first argument, disables the commenting mechanism completely.
+To restore the original comment start of @samp{#}, you must explicitly
+ask for it.
 
 @example
 define(`comment', `COMMENT')
@@ -2318,6 +2428,10 @@
 @result{}
 # Not a comment anymore
 @result{}# Not a COMMENT anymore
+changecom(`#')
address@hidden
+# comment again
address@hidden comment again
 @end example
 
 @node Changeword