CVSROOT: /sources/m4
Module name: m4
Branch: branch-1_4
Changes by: Eric Blake <ericb> 06/09/06 03:58:05
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.72
retrieving revision 1.1.1.1.2.73
diff -u -b -r1.1.1.1.2.72 -r1.1.1.1.2.73
--- doc/m4.texinfo 4 Sep 2006 14:19:37 -0000 1.1.1.1.2.72
+++ doc/m4.texinfo 6 Sep 2006 03:58:05 -0000 1.1.1.1.2.73
@@ -131,7 +131,7 @@
* Miscellaneous:: Miscellaneous builtin macros
* Frozen files:: Fast loading of frozen state
-* Compatibility:: Compatibility with other versions of m4
+* Compatibility:: Compatibility with other versions of @code{m4}
* Answers:: Correct version of some examples
* Copying This Manual:: How to make copies of this manual
* Indices:: Indices of concepts and macros
@@ -150,10 +150,10 @@
Lexical and syntactic conventions
* Names:: Macro names
-* Quoted strings:: Quoting input to m4
-* Comments:: Comments in m4 input
+* Quoted strings:: Quoting input to @code{m4}
+* Comments:: Comments in @code{m4} input
* Other tokens:: Other kinds of input tokens
-* Input processing:: How m4 copies input to output
+* Input processing:: How @code{m4} copies input to output
How to invoke macros
@@ -167,7 +167,7 @@
* Define:: Defining a new macro
* Arguments:: Arguments to macros
-* Pseudo Arguments:: Pseudo arguments to macros
+* Pseudo Arguments:: Special arguments to macros
* Undefine:: Deleting a macro
* Defn:: Renaming macros
* Pushdef:: Temporarily redefining macros
@@ -194,7 +194,7 @@
* Changequote:: Changing the quote characters
* Changecom:: Changing the comment delimiters
* Changeword:: Changing the lexical structure of words
-* M4wrap:: Saving input until end of input
+* M4wrap:: Saving text until end of input
File inclusion
@@ -223,19 +223,19 @@
* Incr:: Decrement and increment operators
* Eval:: Evaluating integer expressions
-Running shell commands
+Macros for running shell commands
* Platform macros:: Determining the platform
* Syscmd:: Executing simple commands
* Esyscmd:: Reading the output of commands
* Sysval:: Exit status
-* Maketemp:: Making names for temporary files
+* Maketemp:: Making temporary files
Miscellaneous builtin macros
* Errprint:: Printing error messages
* Location:: Printing current location
-* M4exit:: Exiting from m4
+* M4exit:: Exiting from @code{m4}
Fast loading of frozen state
@@ -248,14 +248,14 @@
* Incompatibilities:: Facilities in System V m4 not in GNU M4
* Other Incompatibilities:: Other incompatibilities
-Copying This Manual
+How to make copies of this manual
* GNU Free Documentation License:: License for copying this manual
-Indices
+Indices of concepts and macros
* Concept index:: Index for many concepts
-* Macro index:: Index for all m4 macros
+* Macro index:: Index for all @code{m4} macros
@end detailmenu
@end menu
@@ -519,14 +519,15 @@
@itemx -S @var{NUM}
@itemx -T @var{NUM}
These options are present for compatibility with System V @code{m4}, but
-do nothing in this implementation.
+do nothing in this implementation. They may disappear in future releases.
@item -N @var{NUM}
@itemx [EMAIL PROTECTED]
These options are present only for compatibility with previous
versions of @acronym{GNU} @code{m4}, and were controlling the number of
possible diversions which could be used at the same time. They do nothing,
-because there is no fixed limit anymore.
+because there is no fixed limit anymore. They may disappear in future
+releases.
@end table
@acronym{GNU} @code{m4} comes with a feature of freezing internal state
@@ -712,14 +713,14 @@
@menu
* Names:: Macro names
-* Quoted strings:: Quoting input to m4
-* Comments:: Comments in m4 input
+* Quoted strings:: Quoting input to @code{m4}
+* Comments:: Comments in @code{m4} input
* Other tokens:: Other kinds of input tokens
-* Input processing:: How m4 copies input to output
+* Input processing:: How @code{m4} copies input to output
@end menu
@node Names
[EMAIL PROTECTED] Names
[EMAIL PROTECTED] Macro names
@cindex names
A name is any sequence of letters, digits, and the character @kbd{_}
@@ -731,7 +732,7 @@
Examples of legal names are: @samp{foo}, @samp{_tmp}, and @samp{name01}.
@node Quoted strings
[EMAIL PROTECTED] Quoted strings
[EMAIL PROTECTED] Quoting input to @code{m4}
@cindex quoted string
A quoted string is a sequence of characters surrounded by quote
@@ -759,7 +760,7 @@
@code{changequote}. @xref{Changequote}, for more information.
@node Comments
[EMAIL PROTECTED] Comments
[EMAIL PROTECTED] Comments in @code{m4} input
@cindex comments
Comments in @code{m4} are normally delimited by the characters @samp{#}
@@ -783,7 +784,7 @@
information.
@node Other tokens
[EMAIL PROTECTED] Other tokens
[EMAIL PROTECTED] Other kinds of input tokens
Any character, that is neither a part of a name, nor of a quoted string,
nor a comment, is a token by itself. When not in the context of macro
@@ -794,7 +795,7 @@
roles, explained later.
@node Input processing
[EMAIL PROTECTED] Input Processing
[EMAIL PROTECTED] How @code{m4} copies input to output
As @code{m4} reads the input token by token, it will copy each token
directly to the output immediately.
@@ -923,11 +924,11 @@
specific provision.
There is also a command line option (@option{--prefix-builtins}, or
[EMAIL PROTECTED], @pxref{Invoking m4}) which requires all builtin macro names
-to be prefixed
-by @samp{m4_} for them to be recognized. The option has no effect
[EMAIL PROTECTED], @pxref{Invoking m4}) that renames all builtin macro with a
+prefix of @samp{m4_} at startup. The option has no effect
whatsoever on user defined macros. For example, with this option,
-one has to write @code{m4_dnl} and even @code{m4_m4exit}.
+one has to write @code{m4_dnl} and even @code{m4_m4exit}. It also has
+no effect on whether a macro requires parameters.
Another alternative is to redefine problematic macros to a name less
likely to cause conflicts, @xref{Definitions}.
@@ -948,7 +949,6 @@
to quote the empty string, but this works only @emph{inside} the name.
For example:
[EMAIL PROTECTED] ignore
@example
`divert'
@result{}divert
@@ -963,7 +963,6 @@
@noindent
all yield the string @samp{divert}. While in both:
[EMAIL PROTECTED] ignore
@example
`'divert
@result{}
@@ -1035,7 +1034,8 @@
Normally @code{m4} will issue warnings if a builtin macro is called
with an inappropriate number of arguments, but it can be suppressed with
-the @option{-Q} command line option (@pxref{Invoking m4}). For user
+the @option{--quiet} command line option (or @option{--silent}, or
[EMAIL PROTECTED], @pxref{Invoking m4}). For user
defined macros, there is no check of the number of arguments given.
Macros are expanded normally during argument collection, and whatever
@@ -1076,7 +1076,7 @@
@end example
@node Quoting Arguments
[EMAIL PROTECTED] Quoting macro arguments
[EMAIL PROTECTED] On Quoting Arguments to macros
@cindex quoted macro arguments
@cindex macros, quoted arguments to
@@ -1111,7 +1111,8 @@
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.
+cannot be a macro, such as with integers when you have not changed the
+syntax via @code{changeword} (@pxref{Changeword}).
@node Macro expansion
@section Macro expansion
@@ -1148,7 +1149,7 @@
@menu
* Define:: Defining a new macro
* Arguments:: Arguments to macros
-* Pseudo Arguments:: Pseudo arguments to macros
+* Pseudo Arguments:: Special arguments to macros
* Undefine:: Deleting a macro
* Defn:: Renaming macros
* Pushdef:: Temporarily redefining macros
@@ -1200,11 +1201,18 @@
@result{}two
@end example
[EMAIL PROTECTED] @acronym{GNU} extensions
[EMAIL PROTECTED] @code{m4} normally replaces only the @emph{topmost}
+definition of a macro if it has several definitions from @code{pushdef}
+(@pxref{Pushdef}). Some other implementations of @code{m4} replace all
+definitions of a macro with @code{define}. @xref{Incompatibilities},
+for more details.
+
As a @acronym{GNU} extension, the first argument to @code{define} does
not have to be a simple word.
It can be any text string, even the empty string. A macro with a
non-standard name cannot be invoked in the normal way, as the name is
-not recognised. It can only be referenced by the builtins @ref{Indir}
+not recognized. It can only be referenced by the builtins @ref{Indir}
and @ref{Defn}.
@cindex arrays
@@ -1259,8 +1267,8 @@
@end example
@xref{Quoting Arguments}, for an explanation of the double quotes.
-(You should try and improve this example so that clients of exch do not
-have to double quote. @pxref{Answers})
+(You should try and improve this example so that clients of @code{exch}
+do not have to double quote. @pxref{Answers})
@cindex @acronym{GNU} extensions
@acronym{GNU} @code{m4} allows the number following the @samp{$} to
@@ -1373,7 +1381,7 @@
@example
define(`echo1', `$*')
@result{}
-define(`echo2', `$@')
+define(`echo2', `$@@')
@result{}
define(`foo', `bar')
@result{}
@@ -1398,9 +1406,34 @@
@result{}$$$ hello $$$
@end example
-If you want a macro to expand to something like @samp{$12}, put a pair
-of quotes after the @code{$}. This will prevent @code{m4} from
-interpreting the @code{$} sign as a reference to an argument.
+If you want a macro to expand to something like @samp{$12}, the
+judicious use of nested quoting can put a safe character between the
[EMAIL PROTECTED] and the next character, relying on the rescanning to remove
the
+nested quote. This will prevent @code{m4} from interpreting the
[EMAIL PROTECTED] sign as a reference to an argument.
+
[EMAIL PROTECTED]
+define(`foo', `no nested quote: $1')
[EMAIL PROTECTED]
+foo(`arg')
[EMAIL PROTECTED] nested quote: arg
+define(`foo', `nested quote around $: `$'1')
[EMAIL PROTECTED]
+foo(`arg')
[EMAIL PROTECTED] quote around $: $1
+define(`foo', `nested empty quote after $: $`'1')
[EMAIL PROTECTED]
+foo(`arg')
[EMAIL PROTECTED] empty quote after $: $1
+define(`foo', `nested quote around next character: $`1'')
[EMAIL PROTECTED]
+foo(`arg')
[EMAIL PROTECTED] quote around next character: $1
+define(`foo', `nested quote around both: `$1'')
[EMAIL PROTECTED]
+foo(`arg')
[EMAIL PROTECTED] quote around both: arg
[EMAIL PROTECTED] example
@node Undefine
@section Deleting a macro
@@ -1466,7 +1499,8 @@
the quoted expansion text. If, instead, @var{name} is a builtin, the
expansion is a special token, which points to the builtin's internal
definition. This token is only meaningful as the second argument to
[EMAIL PROTECTED] (and @code{pushdef}), and is ignored in any other context.
[EMAIL PROTECTED] (and @code{pushdef}), and is silently converted to an
+empty string in most other contexts.
The macro @code{defn} is recognized only with parameters.
@end deffn
@@ -1526,7 +1560,7 @@
@result{}
define(`a', `A')
@result{}
-define(`echo', `$@')
+define(`echo', `$@@')
@result{}
foo
@result{}A'A
@@ -1536,6 +1570,20 @@
@result{}AA'
@end example
+Using @code{defn} to generate special tokens for builtin macros outside
+of expected contexts can sometimes trigger warnings. But most of the
+time, such tokens are silently converted to the empty string.
+
[EMAIL PROTECTED]
+defn(`defn')
[EMAIL PROTECTED]
+define(defn(`divnum'), `cannot redefine a builtin token')
[EMAIL PROTECTED]:stdin:2: Warning: define: invalid macro name ignored
[EMAIL PROTECTED]
+divnum
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
@node Pushdef
@section Temporarily redefining macros
@@ -1643,7 +1691,7 @@
The macro @code{indir} is recognized only with parameters.
@end deffn
-This can be used to call macros with ``invalid''
+This can be used to call macros with computed or ``invalid''
names (@code{define} allows such names to be defined):
@example
@@ -1659,6 +1707,25 @@
defined, that will not be called by accident. They can @emph{only} be
called through the builtin @code{indir}.
+One other point to observe is that argument collection occurs before
[EMAIL PROTECTED] invokes @var{name}, so if argument collection changes the
+value of @var{name}, that will be reflected in the final expansion.
+This is different than the behavior when invoking macros directly,
+where the definition that was in effect before argument collection is
+used.
+
[EMAIL PROTECTED]
+define(`f', `1')
[EMAIL PROTECTED]
+f(define(`f', `2'))
[EMAIL PROTECTED]
+indir(`f', define(`f', `3'))
[EMAIL PROTECTED]
+indir(`f', undefine(`f'))
[EMAIL PROTECTED]:stdin:4: undefined macro `f'
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
@node Builtin
@section Indirect call of builtins
@@ -1703,9 +1770,14 @@
@result{}foo
@end example
-Note that this can be used to invoke builtins without arguments, even
-when they normally require parameters to be recognized; but it will
-provoke a warning, and result in a void expansion.
+The @var{name} argument only matches the original name of the builtin,
+even when the @option{--prefix-builtins} option (or @option{-P},
[EMAIL PROTECTED] m4}) is in effect. This is different from @code{indir},
+which only tracks current macro names.
+
+Note that @code{indir} and @code{builtin} can be used to invoke builtins
+without arguments, even when they normally require parameters to be
+recognized; but it will provoke a warning, and result in a void expansion.
@example
builtin
@@ -1737,7 +1809,7 @@
@end menu
@node Ifdef
[EMAIL PROTECTED] Testing macro definitions
[EMAIL PROTECTED] Testing if a macro is defined
@cindex conditionals
There are two different builtin conditionals in @code{m4}. The first is
@@ -1765,7 +1837,7 @@
@end example
@node Ifelse
[EMAIL PROTECTED] Comparing strings
[EMAIL PROTECTED] If-else construct, or multibranch
@cindex comparing strings
The other conditional, @code{ifelse}, is much more powerful. It can be
@@ -1782,10 +1854,11 @@
If called with three or four arguments, @code{ifelse} expands into
@var{equal}, if @var{string-1} and @var{string-2} are equal (character
-for character), otherwise it expands to @var{not-equal}.
+for character), otherwise it expands to @var{not-equal}. A final fifth
+argument is ignored, after triggering a warning.
If called with six or more arguments, and @var{string-1} and
[EMAIL PROTECTED] are equal, @code{ifelse} expands into @var{equal},
[EMAIL PROTECTED] are equal, @code{ifelse} expands into @var{equal-1},
otherwise the first three arguments are discarded and the processing
starts again.
@@ -1845,8 +1918,16 @@
calls for an example:
@example
+ifelse(`foo', `bar', `third', `gnu', `gnats')
[EMAIL PROTECTED]:stdin:1: Warning: excess arguments to builtin `ifelse' ignored
[EMAIL PROTECTED]
+ifelse(`foo', `bar', `third', `gnu', `gnats', `sixth')
[EMAIL PROTECTED]
ifelse(`foo', `bar', `third', `gnu', `gnats', `sixth', `seventh')
@result{}seventh
+ifelse(`foo', `bar', `3', `gnu', `gnats', `6', `7', `8')
[EMAIL PROTECTED]:stdin:4: Warning: excess arguments to builtin `ifelse' ignored
[EMAIL PROTECTED]
@end example
Naturally, the normal case will be slightly more advanced than these
@@ -1869,9 +1950,9 @@
There is a builtin macro, @code{shift}, which can, among other things,
be used for iterating through the actual arguments to a macro:
[EMAIL PROTECTED] Builtin shift (@dots{})
-Takes any number of arguments, and expands to all but the first
-argument, separated by commas, with each argument quoted.
[EMAIL PROTECTED] Builtin shift (@var{arg1}, @dots{})
+Takes any number of arguments, and expands to all its arguments except
[EMAIL PROTECTED], separated by commas, with each argument quoted.
The macro @code{shift} is recognized only with parameters.
@end deffn
@@ -1906,7 +1987,8 @@
@end example
While not a very interesting macro, it does show how simple loops can be
-made with @code{shift}, @code{ifelse} and recursion.
+made with @code{shift}, @code{ifelse} and recursion. It also shows
+that @code{shift} is usually used with @samp{$@@}.
@cindex for loops
@cindex loops, counting
@@ -2079,7 +2161,7 @@
foo
@error{}m4trace: -1- foo -> `Hello World.'
@result{}Hello World.
-echo(gnus, and gnats)
+echo(`gnus', `and gnats')
@error{}m4trace: -1- echo(`gnus', `and gnats') -> ``gnus',`and gnats''
@result{}gnus,and gnats
@end example
@@ -2297,7 +2379,7 @@
* Changequote:: Changing the quote characters
* Changecom:: Changing the comment delimiters
* Changeword:: Changing the lexical structure of words
-* M4wrap:: Saving input until end of input
+* M4wrap:: Saving text until end of input
@end menu
@node Dnl
@@ -2463,7 +2545,7 @@
@samp{)} as the first character in @var{start}.
@example
-define(`echo', `$#:$@:')
+define(`echo', `$#:$@@:')
@result{}
define(`hi', `HI')
@result{}
@@ -2524,7 +2606,7 @@
@end example
@node Changecom
[EMAIL PROTECTED] Changing comment delimiters
[EMAIL PROTECTED] Changing the comment delimiters
@cindex changing comment delimiters
@cindex comment delimiters, changing
@@ -2618,7 +2700,7 @@
@samp{)} as the first character in @var{start}.
@example
-define(`echo', `$#:$@:')
+define(`echo', `$#:$@@:')
@result{}
define(`hi', `HI')
@result{}
@@ -2830,7 +2912,7 @@
the parsing speed.
@node M4wrap
[EMAIL PROTECTED] Saving input
[EMAIL PROTECTED] Saving text until end of input
@cindex saving input
@cindex input, saving
@@ -2842,7 +2924,7 @@
To save input text, use the builtin @code{m4wrap}:
[EMAIL PROTECTED] Builtin m4wrap (@ovar{string}, @dots{})
[EMAIL PROTECTED] Builtin m4wrap (@var{string}, @dots{})
Stores @var{string} in a safe place, to be reread when end of input is
reached. As a @acronym{GNU} extension, additional arguments are
concatenated with a space to the @var{string}.
@@ -3909,7 +3991,7 @@
@end example
@node Shell commands
[EMAIL PROTECTED] Running shell commands
[EMAIL PROTECTED] Macros for running shell commands
@cindex executing UNIX commands
@cindex running UNIX commands
@@ -3934,7 +4016,7 @@
* Syscmd:: Executing simple commands
* Esyscmd:: Reading the output of commands
* Sysval:: Exit status
-* Maketemp:: Making names for temporary files
+* Maketemp:: Making temporary files
@end menu
@node Platform macros
@@ -4137,7 +4219,7 @@
@end example
@node Maketemp
[EMAIL PROTECTED] Making names for temporary files
[EMAIL PROTECTED] Making temporary files
@cindex temporary file names
@cindex files, names of temporary
@@ -4161,12 +4243,15 @@
@result{}/tmp/fooa07346
@end example
[EMAIL PROTECTED]
[EMAIL PROTECTED] FIXME: POSIX requires maketemp to replace the trailing XXX
with the
[EMAIL PROTECTED] process id, without creating the file; meaning you only get
one
[EMAIL PROTECTED] string no matter how many times you use maketemp. Instead,
we treat
[EMAIL PROTECTED] it like mkstemp(), and create a unique file every invocation.
+Traditional implementations of @code{m4} replaced the trailing @samp{X}
+sequence with the process id, without creating the file; meaning you
+only get one result no matter how many times you use maketemp on the
+same string. As of this release, @acronym{POSIX} is considering the
+addition of a new macro @code{mkstemp} that behaves like @acronym{GNU}
[EMAIL PROTECTED], so a future version of @acronym{GNU} M4 may have
+changes in this area.
[EMAIL PROTECTED]
@c This test makes sure maketemp gets testsuite coverage, but is
@c somewhat complex for use in the manual.
@example
@@ -4194,7 +4279,7 @@
@menu
* Errprint:: Printing error messages
* Location:: Printing current location
-* M4exit:: Exiting from m4
+* M4exit:: Exiting from @code{m4}
@end menu
@node Errprint
@@ -4926,7 +5011,7 @@
@c ========================================================== Appendices
@node Copying This Manual
[EMAIL PROTECTED] Copying This Manual
[EMAIL PROTECTED] How to make copies of this manual
@cindex License
@menu
@@ -4936,20 +5021,20 @@
@include fdl.texi
@node Indices
[EMAIL PROTECTED] Indices
[EMAIL PROTECTED] Indices of concepts and macros
@menu
* Concept index:: Index for many concepts
-* Macro index:: Index for all m4 macros
+* Macro index:: Index for all @code{m4} macros
@end menu
@node Concept index
[EMAIL PROTECTED] Concept index
[EMAIL PROTECTED] Index for many concepts
@printindex cp
@node Macro index
[EMAIL PROTECTED] Macro index
[EMAIL PROTECTED] Index for all @code{m4} macros
References are exclusively to the places where a builtin is introduced
the first time.
