CVSROOT: /sources/m4
Module name: m4
Branch: branch-1_4
Changes by: Eric Blake <ericb> 06/06/27 12:49:52
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.24
retrieving revision 1.1.1.1.2.25
diff -u -b -r1.1.1.1.2.24 -r1.1.1.1.2.25
--- doc/m4.texinfo 23 Jun 2006 13:22:30 -0000 1.1.1.1.2.24
+++ doc/m4.texinfo 27 Jun 2006 12:49:52 -0000 1.1.1.1.2.25
@@ -886,6 +886,7 @@
bar(a foo, d)
@end example
[EMAIL PROTECTED]
is a macro call with four arguments, which are @samp{a }, @samp{b},
@samp{c} and @samp{d}. To understand why the first argument contains
whitespace, remember that leading unquoted whitespace is never part
@@ -919,7 +920,11 @@
foo(() (`(') `(')
@end example
-is a macro call, with one argument, whose value is @samp{()@w{ }(()@w{ }(}.
[EMAIL PROTECTED]
+is a macro call, with one argument, whose value is @samp{() (() (}.
+Commas separate arguments, except when they occur inside quotes,
+comments, or unquoted parentheses, @pxref{Pseudo Arguments} for
+examples.
It is common practice to quote all arguments to macros, unless you are
sure you want the arguments expanded. Thus, in the above
@@ -933,7 +938,7 @@
It is, however, in certain cases necessary or convenient to leave out
quotes for some arguments, and there is nothing wrong in doing it. It
just makes life a bit harder, if you are not careful. For consistency,
-this manual follows the rule of thumb that each layer of parenthesis
+this manual follows the rule of thumb that each layer of parentheses
introduces another layer of single quoting, except when showing the
consequences of quoting rules. This is done even when the quoted string
cannot be a macro, such as with integers.
@@ -994,7 +999,8 @@
define(@var{name} [, @var{expansion}])
@end example
[EMAIL PROTECTED] which defines @var{name} to expand to @var{expansion}. If
[EMAIL PROTECTED]
+which defines @var{name} to expand to @var{expansion}. If
@var{expansion} is not given, it is taken to be empty.
The expansion of @code{define} is void.
@@ -1115,6 +1121,13 @@
@result{}1
nargs(`arg1', `arg2', `arg3')
@result{}3
+nargs(`commas can be quoted, like this')
[EMAIL PROTECTED]
+nargs(arg1#inside comments, commas do not separate arguments
+still arg1)
[EMAIL PROTECTED]
+nargs((unquoted parentheses, like this, group arguments))
[EMAIL PROTECTED]
@end example
The notation @code{$*} can be used in the expansion text to denote all
@@ -1159,7 +1172,26 @@
@end example
@noindent
[EMAIL PROTECTED], if you do not understand this.
[EMAIL PROTECTED], if you do not understand this. As another example of the
+difference, remember that comments encountered in arguments are passed
+untouched to the macro, and that quoting disables comments.
+
[EMAIL PROTECTED]
+define(`echo1', `$*')
[EMAIL PROTECTED]
+define(`echo2', `$@')
[EMAIL PROTECTED]
+define(`foo', `bar')
[EMAIL PROTECTED]
+echo1(#foo'foo
+foo)
[EMAIL PROTECTED]'foo
[EMAIL PROTECTED]
+echo2(#foo'foo
+foo)
[EMAIL PROTECTED]
[EMAIL PROTECTED]'
[EMAIL PROTECTED] example
A @samp{$} sign in the expansion text, that is not followed by anything
@code{m4} understands, is simply copied to the macro expansion, as any
@@ -1375,6 +1407,7 @@
@example
indir(@var{name}, ...)
@end example
+
@noindent
which results in a call to the macro @var{name}, which is passed the
rest of the arguments. This can be used to call macros with ``invalid''
@@ -1409,6 +1442,7 @@
@example
builtin(@var{name}, ...)
@end example
+
@noindent
which results in a call to the builtin @var{name}, which is passed the
rest of the arguments. This can be used, if @var{name} has been given
@@ -1478,7 +1512,6 @@
ifelse(@var{string-1}, @var{string-2}, @var{equal}, ...)
@end example
[EMAIL PROTECTED]
Used with only one argument, the @code{ifelse} simply discards it and
produces no output. This is a common @code{m4} idiom for introducing a
block comment, as an alternative to repeatedly using @code{dnl}. This
@@ -1636,9 +1669,11 @@
@example
define(`forloop',
`pushdef(`$1', `$2')_forloop(`$1', `$2', `$3', `$4')popdef(`$1')')
[EMAIL PROTECTED]
define(`_forloop',
`$4`'ifelse($1, `$3', ,
`define(`$1', incr($1))_forloop(`$1', `$2', `$3', `$4')')')
[EMAIL PROTECTED]
@end example
Notice the careful use of quotes. Only three macro arguments are
@@ -1891,7 +1926,7 @@
@example
debugmode(opt @var{flags})
@end example
[EMAIL PROTECTED]
+
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
@@ -1914,6 +1949,7 @@
@example
debugfile(opt @var{filename})
@end example
+
@noindent
will send all further debug and trace output to @var{filename}. If
@var{filename} is empty, debug and trace output are discarded and if
@@ -1946,6 +1982,7 @@
@example
dnl
@end example
+
@noindent
and it is often used in connection with @code{define}, to remove the
newline that follow the call to @code{define}. Thus
@@ -1989,6 +2026,7 @@
@example
changequote(opt @var{start}, opt @var{end})
@end example
+
@noindent
where @var{start} is the new start-quote delimiter and @var{end} is the
new end-quote delimiter. If any of the arguments are missing, the default
@@ -2054,6 +2092,7 @@
@example
changecom(opt @var{start}, opt @var{end})
@end example
+
@noindent
where @var{start} is the new start-comment delimiter and @var{end} is
the new end-comment delimiter. If only one argument is provided,
@@ -2233,6 +2272,7 @@
@example
m4wrap(@var{string}, ...)
@end example
+
@noindent
which stores @var{string} and the rest of the arguments in a safe place,
to be reread when end of input is reached.
@@ -2849,6 +2889,7 @@
@example
patsubst(@var{string}, @var{regexp}, opt @var{replacement})
@end example
+
@noindent
which searches @var{string} for matches of @var{regexp}, and substitutes
@var{replacement} for each match. The syntax for regular expressions
@@ -3311,6 +3352,7 @@
@example
errprint(@var{message}, ...)
@end example
+
@noindent
which simply prints @var{message} and the rest of the arguments on the
standard error output.
@@ -3338,6 +3380,7 @@
__file__
__line__
@end example
+
@noindent
which expands to the quoted name of the current input file, and the
current input line number in that file.
@@ -3361,6 +3404,7 @@
@example
m4exit(opt @var{code})
@end example
+
@noindent
which causes @code{m4} to exit, with exit code @var{code}. If
@var{code} is left out, the exit code is zero.
@@ -3723,7 +3767,10 @@
@item
@acronym{POSIX} requires @code{changequote(@var{arg})}
(@pxref{Changequote}) to use newline as the close quote, but GNU
[EMAIL PROTECTED] uses @samp{'} as the close quote.
[EMAIL PROTECTED] uses @samp{'} as the close quote. Meanwhile, some
+traditional implementations use @var{arg} as the close quote, making it
+impossible to nest quotes. For predictable results, never call
+changequote with just one argument.
@item
Traditional @code{m4} treats @code{traceon} (@pxref{Trace}) without
