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.
+
[EMAIL PROTECTED]
+define(`foo', a'a)
[EMAIL PROTECTED]
+define(`a', `A')
[EMAIL PROTECTED]
+define(`echo', `$@')
[EMAIL PROTECTED]
+foo
[EMAIL PROTECTED]'A
+defn(`foo')
[EMAIL PROTECTED]'
+echo(foo)
[EMAIL PROTECTED]'
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED]
+pushdef(`define', `hidden')
[EMAIL PROTECTED]
+undefine(`undefine')
[EMAIL PROTECTED]
+define(`foo', `bar')
[EMAIL PROTECTED]
+foo
[EMAIL PROTECTED]
+builtin(`define', `foo', `BAR')
[EMAIL PROTECTED]
+foo
[EMAIL PROTECTED]
+undefine(`foo')
[EMAIL PROTECTED](foo)
+foo
[EMAIL PROTECTED]
+builtin(`undefine', `foo')
[EMAIL PROTECTED]
+foo
[EMAIL PROTECTED]
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED]
+builtin
[EMAIL PROTECTED]
+builtin()
[EMAIL PROTECTED]:2: m4: undefined builtin `'
[EMAIL PROTECTED]
+builtin(`builtin')
[EMAIL PROTECTED]:3: m4: Warning: too few arguments to builtin `builtin'
[EMAIL PROTECTED]
+builtin(`builtin',)
[EMAIL PROTECTED]:4: m4: undefined builtin `'
[EMAIL PROTECTED]
[EMAIL PROTECTED] 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}.
+
[EMAIL PROTECTED]
+define(`foo', `FOO')
[EMAIL PROTECTED]
+traceon(`foo')
[EMAIL PROTECTED]
+debugmode()
[EMAIL PROTECTED]
+foo
[EMAIL PROTECTED]: -1- foo -> `FOO'
[EMAIL PROTECTED]
+debugmode
[EMAIL PROTECTED]
+foo
[EMAIL PROTECTED]: -1- foo
[EMAIL PROTECTED]
+debugmode(`+l')
[EMAIL PROTECTED]
+foo
[EMAIL PROTECTED]:8: -1- foo
[EMAIL PROTECTED]
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED]
+traceon(`divnum')
[EMAIL PROTECTED]
+divnum(`extra')
[EMAIL PROTECTED]:2: m4: Warning: excess arguments to builtin `divnum' ignored
[EMAIL PROTECTED]: -1- divnum(`extra') -> `0'
[EMAIL PROTECTED]
+debugfile()
[EMAIL PROTECTED]
+divnum(`extra')
[EMAIL PROTECTED]:4: m4: Warning: excess arguments to builtin `divnum' ignored
[EMAIL PROTECTED]
+debugfile
[EMAIL PROTECTED]
+divnum
[EMAIL PROTECTED]: -1- divnum -> `0'
[EMAIL PROTECTED]
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] not this
+See how `foo' was defined, foo?
[EMAIL PROTECTED] 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(`#')
[EMAIL PROTECTED]
+# comment again
[EMAIL PROTECTED] comment again
@end example
@node Changeword
