-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
According to Eric Blake on 10/16/2006 5:55 AM:
>
> 2006-10-16 Eric Blake <[EMAIL PROTECTED]>
>
> * doc/m4.texinfo (Invoking m4): Promote to a chapter, instead of
> a section of Preliminaries.
Some followup patches.
To the branch:
2006-10-16 Eric Blake <[EMAIL PROTECTED]>
* doc/m4.texinfo: Backport some minor cleanups from head.
(Cleardivert): Rename from cleardiv.
To head:
2006-10-16 Eric Blake <[EMAIL PROTECTED]>
* doc/m4.texinfo: Port some changes from the branch.
(Invoking m4): Promote to a chapter, instead of a section of
Preliminaries.
(Operation modes, Dynamic loading features, Preprocessor features)
(Limits control Frozen state, Debugging options)
(Command line files): Subdivide into new sections.
(Cleardivert): Rename from cleardiv.
- --
Life is short - so eat dessert first!
Eric Blake [EMAIL PROTECTED]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.1 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
iD8DBQFFM4WX84KuGfSFAYARAli2AKDE+qfDMrdx9K/6glpNja/XzB5a0wCgrS1I
1t6nAGeJlK++tFltYQMMtQ8=
=+Z7r
-----END PGP SIGNATURE-----
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.86
diff -u -p -r1.1.1.1.2.86 m4.texinfo
--- doc/m4.texinfo 16 Oct 2006 11:56:05 -0000 1.1.1.1.2.86
+++ doc/m4.texinfo 16 Oct 2006 13:12:35 -0000
@@ -151,14 +151,12 @@ Introduction and preliminaries
Invoking @code{m4}
[EMAIL PROTECTED]
* Operation modes:: Command line options for operation modes
* Preprocessor features:: Command line options for preprocessor features
* Limits control:: Command line options for limits control
* Frozen state:: Command line options for frozen state
* Debugging options:: Command line options for debugging
* Command line files:: Specifying input files on the command line
[EMAIL PROTECTED] menu
Lexical and syntactic conventions
@@ -219,7 +217,7 @@ Diverting and undiverting output
* Divert:: Diverting output
* Undivert:: Undiverting output
* Divnum:: Diversion numbers
-* Cleardiv:: Discarding diverted text
+* Cleardivert:: Discarding diverted text
Macros for text handling
@@ -654,7 +652,9 @@ increase this value, unless you define a
@itemx [EMAIL PROTECTED]
Artificially limit the nesting of macro calls to @var{NUM} levels,
stopping program execution if this limit is ever exceeded. When not
-specified, nesting is limited to 1024 levels.
+specified, nesting is limited to 1024 levels. A value of zero means
+unlimited; but then heavily nested code could potentially cause a stack
+overflow.
The precise effect of this option might be more correctly associated
with textual nesting than dynamic recursion. It has been useful
@@ -1006,9 +1006,8 @@ specific provision.
There is also a command line option (@option{--prefix-builtins}, or
@option{-P}, @pxref{Operation modes, , 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,
+builtin macros 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}. It also has
no effect on whether a macro requires parameters.
@@ -1767,10 +1766,10 @@ and @code{defn}.
@cindex @acronym{GNU} extensions
Any macro can be called indirectly with @code{indir}:
[EMAIL PROTECTED] Builtin indir (@var{name}, @dots{})
[EMAIL PROTECTED] Builtin indir (@var{name}, @[EMAIL PROTECTED])
Results in a call to the macro @var{name}, which is passed the
-rest of the arguments. If @var{name} is not defined, an error message
-is printed, and the expansion is void.
+rest of the arguments @var{args}. If @var{name} is not defined, an
+error message is printed, and the expansion is void.
The macro @code{indir} is recognized only with parameters.
@end deffn
@@ -1840,10 +1839,10 @@ indir(`divert', defn(`foo'))
@cindex @acronym{GNU} extensions
Builtin macros can be called indirectly with @code{builtin}:
[EMAIL PROTECTED] Builtin builtin (@var{name}, @dots{})
[EMAIL PROTECTED] Builtin builtin (@var{name}, @[EMAIL PROTECTED])
Results in a call to the builtin @var{name}, which is passed the
-rest of the arguments. If @var{name} does not name a builtin, an error
-message is printed, and the expansion is void.
+rest of the arguments @var{args}. If @var{name} does not name a
+builtin, an error message is printed, and the expansion is void.
The macro @code{builtin} is recognized only with parameters.
@end deffn
@@ -2196,10 +2195,10 @@ Fortunately, there is support for macro
If you want to see what a name expands into, you can use the builtin
@code{dumpdef}:
[EMAIL PROTECTED] Builtin dumpdef (@dots{})
[EMAIL PROTECTED] Builtin dumpdef (@[EMAIL PROTECTED])
Accepts any number of arguments. If called without any arguments,
it displays the definitions of all known names, otherwise it displays
-the definitions of the names given. The output is printed to the
+the definitions of the @var{names} given. The output is printed to the
current debug file (usually standard error), and is sorted by name. If
an unknown name is encountered, a warning is printed.
@@ -2245,12 +2244,13 @@ display.
It is possible to trace macro calls and expansions through the builtins
@code{traceon} and @code{traceoff}:
[EMAIL PROTECTED] Builtin traceon (@dots{})
[EMAIL PROTECTED] Builtin traceoff (@dots{})
[EMAIL PROTECTED] Builtin traceon (@[EMAIL PROTECTED])
[EMAIL PROTECTED] Builtin traceoff (@[EMAIL PROTECTED])
When called without any arguments, @code{traceon} and @code{traceoff}
will turn tracing on and off, respectively, for all defined macros.
-When called with arguments, only the named macros are affected, whether
-or not they are currently defined.
+
+When called with arguments, only the macros listed in @var{names} are
+affected, whether or not they are currently defined.
The expansion of @code{traceon} and @code{traceoff} is void.
@end deffn
@@ -2258,7 +2258,8 @@ The expansion of @code{traceon} and @cod
Whenever a traced macro is called and the arguments have been collected,
the call is displayed. If the expansion of the macro call is not void,
the expansion can be displayed after the call. The output is printed
-to the current debug file (usually standard error).
+to the current debug file (defaulting to standard error, @pxref{Debug
+output}).
@example
define(`foo', `Hello World.')
@@ -2447,13 +2448,13 @@ Debug and tracing output can be redirect
Invoking m4}), or with the builtin macro @code{debugfile}:
@deffn Builtin debugfile (@ovar{file})
-Sends all further debug and trace output to @var{file}. If
[EMAIL PROTECTED] is empty, debug and trace output are discarded. If
[EMAIL PROTECTED] is called without any arguments, debug and trace output
-are sent to standard error. This does not affect warnings, error
-messages, or @code{errprint} output, which are
+Sends all further debug and trace output to @var{file}, opened in append
+mode. If @var{file} is the empty string, debug and trace output are
+discarded. If @code{debugfile} is called without any arguments, debug
+and trace output are sent to standard error. This does not affect
+warnings, error messages, or @code{errprint} output, which are
always sent to standard error. If @var{file} cannot be opened, the
-current debug file is unchanged.
+current debug file is unchanged, and an error is issued.
The expansion of @code{debugfile} is void.
@end deffn
@@ -2499,7 +2500,8 @@ The builtin @code{dnl} stands for ``Disc
@deffn Builtin dnl
All characters, up to and including the next newline, are discarded
-without performing any macro expansion.
+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.
@end deffn
@@ -3331,7 +3333,7 @@ divert(`-1')undivert
* Divert:: Diverting output
* Undivert:: Undiverting output
* Divnum:: Diversion numbers
-* Cleardiv:: Discarding diverted text
+* Cleardivert:: Discarding diverted text
@end menu
@node Divert
@@ -3422,11 +3424,14 @@ We decided to divert the stream for irri
Diverted text can be undiverted explicitly using the builtin
@code{undivert}:
[EMAIL PROTECTED] Builtin undivert (@[EMAIL PROTECTED])
-Undiverts the diversions given by the arguments, in the order
-given. If no arguments are supplied, all diversions are undiverted, in
-numerical order. As a @acronym{GNU} extension, if @var{number} is not numeric,
-treat it as a file name instead.
[EMAIL PROTECTED] Builtin undivert (@[EMAIL PROTECTED])
+Undiverts the numeric @var{diversions} given by the arguments, in the
+order given. If no arguments are supplied, all diversions are
+undiverted, in numerical order.
+
+As a @acronym{GNU} extension, @var{diversions} may contain non-numeric
+strings, which are treated as the names of files to copy into the output
+without expansion. A warning is issued if a file could not be opened.
The expansion of @code{undivert} is void.
@end deffn
@@ -3548,7 +3553,7 @@ Diversion two: divnum
@result{}Diversion two: 2
@end example
[EMAIL PROTECTED] Cleardiv
[EMAIL PROTECTED] Cleardivert
@section Discarding diverted text
@cindex discarding diverted text
@@ -3575,8 +3580,8 @@ No output is produced at all.
Clearing selected diversions can be done with the following macro:
[EMAIL PROTECTED] Composite cleardivert (@[EMAIL PROTECTED])
-Discard the contents of each listed diversion.
[EMAIL PROTECTED] Composite cleardivert (@[EMAIL PROTECTED])
+Discard the contents of each of the listed numeric @var{diversions}.
@end deffn
@example
@@ -5222,7 +5227,7 @@ macro
@node Improved cleardivert
@section Solution for @code{cleardivert}
-The @code{cleardivert} macro (@pxref{Cleardiv}) cannot, as it stands, be
+The @code{cleardivert} macro (@pxref{Cleardivert}) cannot, as it stands, be
called without arguments to clear all pending diversions. That is
because using undivert with an empty string for an argument is different
than using it with no arguments at all. Compare the earlier definition
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.65
diff -u -p -r1.65 m4.texinfo
--- doc/m4.texinfo 14 Oct 2006 14:16:23 -0000 1.65
+++ doc/m4.texinfo 16 Oct 2006 13:12:49 -0000
@@ -94,24 +94,28 @@ running them.
@acronym{GNU} @code{m4} was originally written by Ren@'e Seindal, with
subsequent changes by Fran@,{c}ois Pinard and other volunteers
on the Internet. All names and email addresses can be found in the
-files @file{AUTHORS} and @file{THANKS} from the @acronym{GNU} M4 distribution.
+files @[EMAIL PROTECTED]/@/AUTHORS} and
[EMAIL PROTECTED]@value{VERSION}/@/THANKS} from the @acronym{GNU} M4
+distribution.
@ifclear beta
-This is release @value{VERSION}. It is now to be considered stable,
-future releases on this branch are only meant to fix bugs, increase
-speed, or improve documentation.
+This is release @value{VERSION}. It is now considered stable: future
+releases on this branch are only meant to fix bugs, increase speed, or
+improve documentation.
@end ifclear
@ifset beta
This is BETA release @value{VERSION}. This is a development release,
and as such, is prone to bugs, crashes, unforeseen features, incomplete
[EMAIL PROTECTED], therefore, use at your own peril. In case of
-problems, please do not hesitate to report them (see the @file{README}
-file in the distribution). @xref{Experiments}.
+problems, please do not hesitate to report them (see the
[EMAIL PROTECTED]@value{VERSION}/@/README} file in the distribution).
[EMAIL PROTECTED]
@end ifset
@menu
* Preliminaries:: Introduction and preliminaries
+* Invoking m4:: Invoking @code{m4}
* Syntax:: Lexical and syntactic conventions
* Macros:: How to invoke macros
@@ -144,10 +148,19 @@ Introduction and preliminaries
* Intro:: Introduction to @code{m4}
* History:: Historical references
-* Invoking m4:: Invoking @code{m4}
* Bugs:: Problems and bugs
* Manual:: Using this manual
+Invoking @code{m4}
+
+* Operation modes:: Command line options for operation modes
+* Dynamic loading features:: Command line options for dynamic loading
+* Preprocessor features:: Command line options for preprocessor features
+* Limits control:: Command line options for limits control
+* Frozen state:: Command line options for frozen state
+* Debugging options:: Command line options for debugging
+* Command line files:: Specifying input files on the command line
+
Lexical and syntactic conventions
* Names:: Macro names
@@ -214,7 +227,7 @@ Diverting and undiverting output
* Divert:: Diverting output
* Undivert:: Undiverting output
* Divnum:: Diversion numbers
-* Cleardiv:: Discarding diverted text
+* Cleardivert:: Discarding diverted text
Extending M4 with dynamic runtime modules
@@ -299,7 +312,6 @@ language, as shipped in the @acronym{GNU
@menu
* Intro:: Introduction to @code{m4}
* History:: Historical references
-* Invoking m4:: Invoking @code{m4}
* Bugs:: Problems and bugs
* Manual:: Using this manual
@end menu
@@ -393,8 +405,115 @@ rewriting the entire code base. This de
improvements to other @acronym{GNU} software, such as @acronym{GNU}
Libtool. @acronym{GNU} M4 2.0 is the result of this effort.
[EMAIL PROTECTED] Bugs
[EMAIL PROTECTED] Problems and bugs
+
+If you have problems with @acronym{GNU} M4 or think you've found a bug,
+please report it. Before reporting a bug, make sure you've actually
+found a real bug. Carefully reread the documentation and see if it
+really says you can do what you're trying to do. If it's not clear
+whether you should be able to do something or not, report that too; it's
+a bug in the documentation!
+
+Before reporting a bug or trying to fix it yourself, try to isolate it
+to the smallest possible input file that reproduces the problem. Then
+send us the input file and the exact results @code{m4} gave you. Also
+say what you expected to occur; this will help us decide whether the
+problem was really in the documentation.
+
+Once you've got a precise problem, send e-mail to (Internet)
[EMAIL PROTECTED]@@gnu.org}. Please include the version number of @code{m4}
+you are using. You can get this information with the command
[EMAIL PROTECTED] --version}. You can also run @kbd{make check} to generate
the file
[EMAIL PROTECTED]/@/testsuite.log}, useful for including in your report.
+
+Non-bug suggestions are always welcome as well. If you have questions
+about things that are unclear in the documentation or are just obscure
+features, please report them too.
+
[EMAIL PROTECTED] Manual
[EMAIL PROTECTED] Using this manual
+
+This manual contains a number of examples of @code{m4} input and output,
+and a simple notation is used to distinguish input, output and error
+messages from @code{m4}. Examples are set out from the normal text, and
+shown in a fixed width font, like this
+
[EMAIL PROTECTED] ignore
[EMAIL PROTECTED]
+This is an example of an example!
[EMAIL PROTECTED] example
+
+To distinguish input from output, all output from @code{m4} is prefixed
+by the string @[EMAIL PROTECTED], and all error messages by the string
[EMAIL PROTECTED]@error{}}. When showing how command line options affect
matters,
+the command line is shown with a prompt @samp{$ @kbd{like this}},
+otherwise, you can assume that a simple @kbd{m4} invocation will work.
+Thus:
+
[EMAIL PROTECTED] ignore
[EMAIL PROTECTED]
+$ @kbd{command line to invoke m4}
+Example of input line
[EMAIL PROTECTED] line from m4
[EMAIL PROTECTED] an error message
[EMAIL PROTECTED] example
+
+The sequence @samp{^D} in an example indicates the end of the input file.
+The majority of these examples are self-contained, and you can run them
+with similar results. In fact, the testsuite that is bundled in the
[EMAIL PROTECTED] M4 package consists in part of the examples
+in this document!
+
+As each of the predefined macros in @code{m4} is described, a prototype
+call of the macro will be shown, giving descriptive names to the
+arguments, e.g.,
+
[EMAIL PROTECTED] {Composite (none)} example (@var{string}, @dvar{count, 1}, @
+ @[EMAIL PROTECTED])
+This is a sample prototype. There is not really a macro named
[EMAIL PROTECTED], but this documents that if there were, it would be a
+Composite macro, rather than a Builtin, and would be provided by the
+module @code{none}.
+
+It requires at least one argument, @var{string}. Remember that in
[EMAIL PROTECTED], there must not be a space between the macro name and the
+opening parenthesis, unless it was intended to call the macro without
+any arguments. The brackets around @var{count} and @var{argument} show
+that these arguments are optional. If @var{count} is omitted, the macro
+behaves as if count were @samp{1}, whereas if @var{argument} is omitted,
+the macro behaves as if it were the empty string. A blank argument is
+not the same as an omitted argument. For example, @samp{example(`a')},
[EMAIL PROTECTED](`a',`1')}, and @samp{example(`a',`1',)} would behave
+identically with @var{count} set to @samp{1}; while @samp{example(`a',)}
+and @samp{example(`a',`')} would explicitly pass the empty string for
[EMAIL PROTECTED] The ellipses (@[EMAIL PROTECTED]) show that the macro
+processes additional arguments after @var{argument}, rather than
+ignoring them.
[EMAIL PROTECTED] deffn
+
+Each builtin definition will list, in parentheses, the module that must
+be loaded to use that macro. The standard modules include
[EMAIL PROTECTED] (which is always available), @samp{gnu} (for @acronym{GNU}
specific
+m4 extensions), and @samp{traditional} (for compatibility with System V
+m4). @xref{Modules}.
+
+All macro arguments in @code{m4} are strings, but some are given
+special interpretation, e.g., as numbers, file names, regular
+expressions, etc. The documentation for each macro will state how the
+parameters are interpreted, and what happens if the argument cannot be
+parsed according to the desired interpretation. Unless specified
+otherwise, a parameter specified to be a number is parsed as a decimal,
+even if the argument has leading zeros; and parsing the empty string as
+a number results in 0 rather than an error, although a warning will be
+issued.
+
+This document consistently writes and uses @dfn{builtin}, without a
+hyphen, as if it were an English word. This is how the @code{builtin}
+primitive is spelled within @code{m4}.
+
@node Invoking m4
[EMAIL PROTECTED] Invoking @code{m4}
[EMAIL PROTECTED] Invoking @code{m4}
The format of the @code{m4} command is:
@@ -418,19 +537,33 @@ with mandatory arguments may be provided
argument or as two arguments, and options with optional arguments must
be provided as a single argument. In other words, without
@env{POSIXLY_CORRECT}, @kbd{m4 -QPDfoo -d a -d+f} is equivalent to
[EMAIL PROTECTED] -Q -P -D foo -d -d+f -- a}, although the latter form is
[EMAIL PROTECTED] -Q -P -D foo -d -d+f -- ./a}, although the latter form is
considered canonical. (With @env{POSIXLY_CORRECT}, it is equivalent to
[EMAIL PROTECTED] -Q -P -D foo -d -- a ./-d+f}).
[EMAIL PROTECTED] -Q -P -D foo -d -- ./a ./-d+f}).
With long options, options with mandatory arguments may be provided with
an equal sign (@samp{=}) in a single argument, or as two arguments, and
options with optional arguments must be provided as a single argument.
In other words, @kbd{m4 --def foo --debug a} is equivalent to
[EMAIL PROTECTED] --define=foo --debug= -- a}, although the latter form is
[EMAIL PROTECTED] --define=foo --debug= -- ./a}, although the latter form is
considered canonical (not to mention more robust, in case a future
version of @code{m4} introduces an option named @option{--default}).
@code{m4} understands the following options, grouped by functionality.
+
[EMAIL PROTECTED]
+* Operation modes:: Command line options for operation modes
+* Dynamic loading features:: Command line options for dynamic loading
+* Preprocessor features:: Command line options for preprocessor features
+* Limits control:: Command line options for limits control
+* Frozen state:: Command line options for frozen state
+* Debugging options:: Command line options for debugging
+* Command line files:: Specifying input files on the command line
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] Operation modes
[EMAIL PROTECTED] Command line options for operation modes
+
Several options control the overall operation of @code{m4}:
@table @code
@@ -511,6 +644,9 @@ This option is intended to make it safer
unknown origin.
@end table
[EMAIL PROTECTED] Dynamic loading features
[EMAIL PROTECTED] Command line options for dynamic loading
+
On platforms that support dynamic libraries, there are some options
that affect dynamic loading.
@@ -528,9 +664,13 @@ for in each directory of the module sear
is found or the list is exhausted. @xref{Modules}, for more details.
By default, the modules @samp{m4}, @samp{traditional}, and @samp{gnu}
are preloaded, although this can be controlled during configuration
-with the @option{--with-modules} option to @file{configure}.
+with the @option{--with-modules} option to
[EMAIL PROTECTED]@value{VERSION}/@/configure}.
@end table
[EMAIL PROTECTED] Preprocessor features
[EMAIL PROTECTED] Command line options for preprocessor features
+
@cindex macro definitions, on the command line
@cindex command line, macro definitions on the
Several options allow @code{m4} to behave more like a preprocessor.
@@ -598,10 +738,14 @@ given more than once; undefining a @var{
definition is silently ignored.
@end table
[EMAIL PROTECTED] Limits control
[EMAIL PROTECTED] Command line options for limits control
+
There are some limits within @code{m4} that can be tuned. For
compatibility, @code{m4} also accepts some options that control limits
in other implementations, but which are automatically unbounded (limited
-only by your hardware constraints) in @acronym{GNU} @code{m4}.
+only by your hardware and operating system constraints) in @acronym{GNU}
[EMAIL PROTECTED]
@table @code
@comment FIXME - clean this up. POSIXLY_CORRECT should imply -G (as
@@ -660,6 +804,9 @@ do nothing in this implementation. They
releases, and issue a warning to that effect.
@end table
[EMAIL PROTECTED] Frozen state
[EMAIL PROTECTED] Command line options for frozen state
+
@acronym{GNU} @code{m4} comes with a feature of freezing internal state
(@pxref{Frozen files}). This can be used to speed up @code{m4}
execution when reusing a common initialization script.
@@ -679,6 +826,9 @@ frozen @var{FILE}. The options @option{
after state is reloaded, but before the input files are read.
@end table
[EMAIL PROTECTED] Debugging options
[EMAIL PROTECTED] Command line options for debugging
+
Finally, there are several options for aiding in debugging @code{m4}
scripts.
@@ -733,6 +883,9 @@ defined. @var{NAME} need not be defined
This option may be given more than once. @xref{Trace}, for more details.
@end table
[EMAIL PROTECTED] Command line files
[EMAIL PROTECTED] Specifying input files on the command line
+
@cindex command line, file names on the
@cindex file names, on the command line
The remaining arguments on the command line are taken to be input file
@@ -760,113 +913,6 @@ If you need to read a file whose name st
specify it as @samp{./-file}, or use @option{--} to mark the end of
options.
[EMAIL PROTECTED] Bugs
[EMAIL PROTECTED] Problems and bugs
-
-If you have problems with @acronym{GNU} M4 or think you've found a bug,
-please report it. Before reporting a bug, make sure you've actually
-found a real bug. Carefully reread the documentation and see if it
-really says you can do what you're trying to do. If it's not clear
-whether you should be able to do something or not, report that too; it's
-a bug in the documentation!
-
-Before reporting a bug or trying to fix it yourself, try to isolate it
-to the smallest possible input file that reproduces the problem. Then
-send us the input file and the exact results @code{m4} gave you. Also
-say what you expected to occur; this will help us decide whether the
-problem was really in the documentation.
-
-Once you've got a precise problem, send e-mail to (Internet)
[EMAIL PROTECTED]@@gnu.org}. Please include the version number of @code{m4}
-you are using. You can get this information with the command @samp{m4
---version}. You can also run @kbd{make check} to generate the file
[EMAIL PROTECTED]/@/testsuite.log}, useful for including in your report.
-
-Non-bug suggestions are always welcome as well. If you have questions
-about things that are unclear in the documentation or are just obscure
-features, please report them too.
-
[EMAIL PROTECTED] Manual
[EMAIL PROTECTED] Using this manual
-
-This manual contains a number of examples of @code{m4} input and output,
-and a simple notation is used to distinguish input, output and error
-messages from @code{m4}. Examples are set out from the normal text, and
-shown in a fixed width font, like this
-
[EMAIL PROTECTED] ignore
[EMAIL PROTECTED]
-This is an example of an example!
[EMAIL PROTECTED] example
-
-To distinguish input from output, all output from @code{m4} is prefixed
-by the string @[EMAIL PROTECTED], and all error messages by the string
[EMAIL PROTECTED]@error{}}. When showing how command line options affect
matters,
-the command line is shown with a prompt @samp{$ @kbd{like this}},
-otherwise, you can assume that a simple @kbd{m4} invocation will work.
-Thus:
-
[EMAIL PROTECTED] ignore
[EMAIL PROTECTED]
-$ @kbd{command line to invoke m4}
-Example of input line
[EMAIL PROTECTED] line from m4
[EMAIL PROTECTED] an error message
[EMAIL PROTECTED] example
-
-The sequence @samp{^D} in an example indicates the end of the input file.
-The majority of these examples are self-contained, and you can run them
-with similar results. In fact, the testsuite that is bundled in the
[EMAIL PROTECTED] M4 package consists in part of the examples
-in this document!
-
-As each of the predefined macros in @code{m4} is described, a prototype
-call of the macro will be shown, giving descriptive names to the
-arguments, e.g.,
-
[EMAIL PROTECTED] {Composite (none)} example (@var{string}, @dvar{count, 1}, @
- @[EMAIL PROTECTED])
-This is a sample prototype. There is not really a macro named
[EMAIL PROTECTED], but this documents that if there were, it would be a
-Composite macro, rather than a Builtin, and would be provided by the
-module @code{none}.
-
-It requires at least one argument, @var{string}. Remember that in
[EMAIL PROTECTED], there must not be a space between the macro name and the
-opening parenthesis, unless it was intended to call the macro without
-any arguments. The brackets around @var{count} and @var{argument} show
-that these arguments are optional. If @var{count} is omitted, the macro
-behaves as if count were @samp{1}, whereas if @var{argument} is omitted,
-the macro behaves as if it were the empty string. A blank argument is
-not the same as an omitted argument. For example, @samp{example(`a')},
[EMAIL PROTECTED](`a',`1')}, and @samp{example(`a',`1',)} would behave
-identically with @var{count} set to @samp{1}; while @samp{example(`a',)}
-and @samp{example(`a',`')} would explicitly pass the empty string for
[EMAIL PROTECTED] The ellipses (@[EMAIL PROTECTED]) show that the macro
-processes additional arguments after @var{argument}, rather than
-ignoring them.
[EMAIL PROTECTED] deffn
-
-Each builtin definition will list, in parentheses, the module that must
-be loaded to use that macro. The standard modules include
[EMAIL PROTECTED] (which is always available), @samp{gnu} (for @acronym{GNU}
specific
-m4 extensions), and @samp{traditional} (for compatibility with System V
-m4). @xref{Modules}.
-
-All macro arguments in @code{m4} are strings, but some are given
-special interpretation, e.g., as numbers, file names, regular
-expressions, etc. The documentation for each macro will state how the
-parameters are interpreted, and what happens if the argument cannot be
-parsed according to the desired interpretation. Unless specified
-otherwise, a parameter specified to be a number is parsed as a decimal,
-even if the argument has leading zeros; and parsing the empty string as
-a number results in 0 rather than an error, although a warning will be
-issued.
-
-This document consistently writes and uses @dfn{builtin}, without a
-hyphen, as if it were an English word. This is how the @code{builtin}
-primitive is spelled within @code{m4}.
-
@node Syntax
@chapter Lexical and syntactic conventions
@@ -897,7 +943,7 @@ exception of the @sc{nul} character (the
@section Macro names
@cindex names
-A name is any sequence of letters, digits, and the character @kbd{_}
+A name is any sequence of letters, digits, and the character @samp{_}
(underscore), where the first character is not a digit. @code{m4} will
use the longest such sequence found in the input. If a name has a
macro definition, it will be subject to macro expansion
@@ -915,7 +961,7 @@ changed at any time, using the builtin m
@cindex quoted string
A quoted string is a sequence of characters surrounded by quote
strings, defaulting to
[EMAIL PROTECTED] and @kbd{'}, where the nested begin and end quotes within the
[EMAIL PROTECTED] and @samp{'}, where the nested begin and end quotes within the
string are balanced. The value of a string token is the text, with one
level of quotes stripped off. Thus
@@ -946,9 +992,9 @@ Comments in @code{m4} are normally delim
and newline. All characters between the comment delimiters are ignored,
but the entire comment (including the delimiters) is passed through to
the output, unless you supply the @option{--discard-comments} or
[EMAIL PROTECTED] option at the command line (@pxref{Invoking m4}). When
-discarding comments, the comment delimiters are discarded, even if the
-close-comment string is a newline.
[EMAIL PROTECTED] option at the command line (@pxref{Operation modes, ,
+Invoking m4}). When discarding comments, the comment delimiters are
+discarded, even if the close-comment string is a newline.
Comments cannot be nested, so the first newline after a @samp{#} ends
the comment. The commenting effect of the begin-comment string
@@ -1037,7 +1083,7 @@ round of scanning for the tokens @samp{R
@end example
The order in which @code{m4} expands the macros can be explored using
-the @ref{Trace} facilities of @acronym{GNU} @code{m4}.
+the trace facilities of @acronym{GNU} @code{m4} (@pxref{Trace}).
This process continues until there are no more macro calls to expand and
all the input has been consumed.
@@ -1148,9 +1194,9 @@ eval(`1')
@end example
There is also a command line option (@option{--prefix-builtins}, or
[EMAIL PROTECTED]) that renames all builtin macro names to be prefixed
-by @samp{m4_} at startup. The option has no effect
-whatsoever on user defined macros. For example, with this option,
[EMAIL PROTECTED], @pxref{Operation modes, , Invoking m4})) that renames all
+builtin macros 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}. It also has
no effect on whether a macro requires parameters.
@@ -1269,7 +1315,7 @@ Unquoted leading whitespace is stripped
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{--quiet} command line option (or @option{--silent}, or
[EMAIL PROTECTED], @pxref{Invoking m4}). For user
[EMAIL PROTECTED], @pxref{Operation modes, , Invoking m4}). For user
defined macros, there is no check of the number of arguments given.
@example
@@ -1353,7 +1399,7 @@ foo(() (`(') `(')
@noindent
is a macro call, with one argument, whose value is @samp{() (() (}.
Commas separate arguments, except when they occur inside quotes,
-comments, or unquoted parentheses, @xref{Pseudo Arguments}, for
+comments, or unquoted parentheses. @xref{Pseudo Arguments}, for
examples.
It is common practice to quote all arguments to macros, unless you are
@@ -1483,8 +1529,8 @@ As a @acronym{GNU} extension, the first
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 recognized. It can only be referenced by the builtins @ref{Indir}
-and @ref{Defn}.
+not recognized. It can only be referenced by the builtins @code{Indir}
+(@pxref{Indir}) and @code{Defn} (@pxref{Defn}).
@cindex arrays
Arrays and associative arrays can be simulated by using this trick.
@@ -1539,7 +1585,7 @@ macro
@xref{Quoting Arguments}, for an explanation of the double quotes.
(You should try and improve this example so that clients of @code{exch}
-do not have to double quote. @pxref{Answers})
+do not have to double quote; or @pxref{Improved exch, , Answers}).
@cindex @acronym{GNU} extensions
@acronym{GNU} @code{m4} allows the number following the @samp{$} to
@@ -2191,8 +2237,8 @@ foo
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.
[EMAIL PROTECTED] modes, , Invoking m4}) is in effect. This is different
+from @code{indir}, which only tracks current macro names.
@comment options: -P
@example
@@ -2626,8 +2672,8 @@ gone into an infinite loop thanks to mac
rescanning. Choosing @samp{()} as the list delimiters made this
example rather awkward in terms of proper quoting. (A different
implementation can be acheived by changing @var{list} from a
-parenthesized list to a quoted list; try reimplementing @code{foreach}
-with these semantics yourself, then check @pxref{Answers}).
+parenthesized list to a quoted list. Try reimplementing @code{foreach}
+with these semantics yourself; or @pxref{Improved foreach, , Answers}).
@node Debugging
@chapter How to debug macros and input
@@ -2658,7 +2704,7 @@ Accepts any number of arguments. If cal
it displays the definitions of all known names, otherwise it displays
the definitions of the @var{names} given. The output is printed
directly to standard error, independently of the @option{--debugfile}
-option (@pxref{Invoking m4}), or @code{debugfile} macro.
+option (@pxref{Debugging options, , Invoking m4}), or @code{debugfile} macro.
The output is sorted by name. If an unknown name is encountered, a
warning is printed.
@@ -2697,9 +2743,9 @@ f(popdef(`f')dumpdef(`f'))
@xref{Debugmode}, for information on how the @samp{m}, @samp{q}, and
@samp{s} flags affect the details of the display. Remember, the
@samp{q} flag is implied when the @option{--debug} option (@option{-d},
[EMAIL PROTECTED] m4}) is used in the command line without arguments.
-Also, @code{--debuglen} (@pxref{Debuglen}) can affect output, by
-truncating longer strings.
[EMAIL PROTECTED] options, , Invoking m4}) is used in the command line
+without arguments. Also, @code{--debuglen} (@pxref{Debuglen}) can affect
+output, by truncating longer strings.
@comment options: -ds -l3
@example
@@ -2736,11 +2782,12 @@ It is possible to trace macro calls and
When called without any arguments, @code{traceon} and @code{traceoff}
will turn tracing on and off, respectively, for all macros, identical to
using the @samp{t} flag of @code{debugmode} (@pxref{Debugmode}).
-When called with arguments, only the named macros are affected, whether
-or not they are currently defined. A macro's expansion will be traced
-if global tracing is on, or if the individual macro tracing flag is
-set; to avoid tracing a macro, both the global flag and the macro must
-have tracing off.
+
+When called with arguments, only the macros listed in @var{names} are
+affected, whether or not they are currently defined. A macro's
+expansion will be traced if global tracing is on, or if the individual
+macro tracing flag is set; to avoid tracing a macro, both the global
+flag and the macro must have tracing off.
The expansion of @code{traceon} and @code{traceoff} is void.
@end deffn
@@ -2771,9 +2818,10 @@ The number between dashes is the depth o
of the time, signifying an expansion at the outermost level, but it
increases when macro arguments contain unquoted macro calls. The
maximum number that will appear between dashes is controlled by the
-option @option{--nesting-limit} (or @option{-L}, @pxref{Invoking m4}).
-Additionally, the option @option{--trace} (or @option{-t}) can be used
-to invoke @code{traceon(@var{name})} before parsing input.
+option @option{--nesting-limit} (or @option{-L}, @pxref{Limits control,
+, Invoking m4}). Additionally, the option @option{--trace} (or
[EMAIL PROTECTED]) can be used to invoke @code{traceon(@var{name})} before
+parsing input.
@comment options: -d-V -L3 -tifelse
@comment status: 1
@@ -2935,8 +2983,8 @@ display.
@cindex controlling debugging output
@cindex debugging output, controlling
The @option{--debug} option to @code{m4} (also spelled
[EMAIL PROTECTED] or @option{-d},
[EMAIL PROTECTED] m4}) controls the amount of details presented in three
[EMAIL PROTECTED] or @option{-d}, @pxref{Debugging options, ,
+Invoking m4}) controls the amount of details presented in three
categories of output. Trace output is requested by @code{traceon}
(@pxref{Trace}), and each line is prefixed by @samp{m4trace:} in
relation to a macro invocation. Debug output tracks useful events not
@@ -3079,8 +3127,8 @@ When debugging, sometimes it is desirabl
arbitrary-length strings, because the prefix carries enough information
to understand the issues. The builtin macro @code{debuglen}, along with
the command line option counterpart @option{--debuglen} (or @option{-l},
[EMAIL PROTECTED] m4}), allow on-the-fly control of debugging string
-lengths:
[EMAIL PROTECTED] options, , Invoking m4}), allow on-the-fly control of
+debugging string lengths:
@deffn {Builtin (gnu)} debuglen (@var{len})
The argument @var{len} is an integer that controls how much of
@@ -3131,8 +3179,8 @@ echo(`long string')
@cindex output, saving debugging
@cindex @acronym{GNU} extensions
Debug and tracing output can be redirected to files using either the
[EMAIL PROTECTED] option to @code{m4} (@pxref{Invoking m4}), or with
-the builtin macro @code{debugfile}:
[EMAIL PROTECTED] option to @code{m4} (@pxref{Debugging options, ,
+Invoking m4}), or with the builtin macro @code{debugfile}:
@deffn {Builtin (gnu)} debugfile (@ovar{file})
Send all further debug and trace output to @var{file}, opened in append
@@ -3143,9 +3191,9 @@ affect warnings, error messages, or @cod
output, which are always sent to standard error. If @var{file} cannot
be opened, the current debug file is unchanged, and an error is issued.
-When the @option{--safer} option (@pxref{Invoking m4}) is in effect,
[EMAIL PROTECTED] must be empty or omitted, since otherwise an input file
-could cause the modification of arbitrary files.
+When the @option{--safer} option (@pxref{Operation modes, , Invoking
+m4}) is in effect, @var{file} must be empty or omitted, since otherwise
+an input file could cause the modification of arbitrary files.
The expansion of @code{debugfile} is void.
@end deffn
@@ -3240,7 +3288,7 @@ foo
The input up to and including the next newline is discarded, as opposed
to the way comments are treated (@pxref{Comments}), when the command
line option @option{--discard-comments} is not in effect
-(@pxref{Invoking m4}).
+(@pxref{Operation modes, , Invoking m4}).
Usually, @code{dnl} is immediately followed by an end of line or some
other whitespace. @acronym{GNU} @code{m4} will produce a warning diagnostic if
@@ -3395,9 +3443,9 @@ expression syntax (@pxref{Regular expres
The @code{changeresyntax} macro expands to nothing, but changes the
default regular expression syntax used by M4 according to the value of
@var{resyntax}, equivalent to passing @var{resyntax} as the argument to
[EMAIL PROTECTED] when invoking @code{m4}. @xref{Invoking m4},
-for more details. If @var{resyntax} is empty or omitted the default
-settings are reverted to emacs style.
[EMAIL PROTECTED] when invoking @code{m4}. @xref{Operation
+modes, , Invoking m4}, for more details. If @var{resyntax} is empty or
+omitted the default settings are reverted to emacs style.
@end deffn
Any one of the values below, case is not important, and optionally
@@ -3940,7 +3988,8 @@ GNU @code{m4} allows included files to b
than the current working directory.
If the @option{--prepend-include} or @option{-B} option was provided
-(@pxref{Invoking m4}), those directories are searched first, in reverse
+(@pxref{Preprocessor features, , Invoking m4}), those directories are
+searched first, in reverse
order that those options were listed on the command line. Then
@code{m4} looks in the current working directory. Next comes the
directories specified with the @option{--include} or @option{-I} option
@@ -3979,7 +4028,7 @@ limited by the number of available file
* Divert:: Diverting output
* Undivert:: Undiverting output
* Divnum:: Diversion numbers
-* Cleardiv:: Discarding diverted text
+* Cleardivert:: Discarding diverted text
@end menu
@node Divert
@@ -4033,8 +4082,7 @@ This is a common programming idiom in @c
@node Undivert
@section Undiverting output
[EMAIL PROTECTED] {Builtin (m4)} undivert
[EMAIL PROTECTED] {Builtin (m4)} undivert (@[EMAIL PROTECTED])
[EMAIL PROTECTED] {Builtin (m4)} undivert (@[EMAIL PROTECTED])
Diverted text can be undiverted explicitly using the builtin
@code{undivert}, which reinserts the diverted output given by the
arguments into the current output stream, in the order given. If no
@@ -4143,7 +4191,7 @@ divert
The last call of @code{divert} without arguments is necessary because the
undiverted text would otherwise be diverted itself.
[EMAIL PROTECTED] Cleardiv
[EMAIL PROTECTED] Cleardivert
@section Discarding diverted text
@cindex discarding diverted text
@@ -4178,7 +4226,8 @@ define(`cleardivert',
It is called just like @code{undivert}, but the effect is to clear the
diversions, given by the arguments. (This macro has a nasty bug! You
-should try to see if you can find it and correct it. @xref{Answers}.)
+should try to see if you can find it and correct it; or @pxref{Improved
+cleardivert, , Answers}).
@node Modules
@chapter Extending M4 with dynamic runtime modules
@@ -4957,9 +5006,9 @@ Prior to executing the command, @code{m4
The default standard input, output and error of @var{shell-command} are
the same as those of @code{m4}.
-When the @option{--safer} option (@pxref{Invoking m4}) is in effect,
[EMAIL PROTECTED] results in an error, since otherwise an input file could
-execute arbitrary code.
+When the @option{--safer} option (@pxref{Operation modes, , Invoking
+m4}) is in effect, @code{syscmd} results in an error, since otherwise an
+input file could execute arbitrary code.
The builtin macro @code{syscmd} is recognized only when given arguments.
@end deffn
@@ -5010,9 +5059,9 @@ esyscmd(`echo foo')
Note how the expansion of @code{esyscmd} keeps the trailing newline of
the command, as well as using the newline that appeared after the macro.
-When the @option{--safer} option (@pxref{Invoking m4}) is in effect,
[EMAIL PROTECTED] results in an error, since otherwise an input file could
-execute arbitrary code.
+When the @option{--safer} option (@pxref{Operation modes, , Invoking
+m4}) is in effect, @code{esyscmd} results in an error, since otherwise
+an input file could execute arbitrary code.
The builtin macro @code{esyscmd} is recognized only when given
arguments.
@@ -5051,8 +5100,9 @@ sysval
@result{}0
@end example
-When the @option{--safer} option (@pxref{Invoking m4}) is in effect,
[EMAIL PROTECTED] will always remain at its default value of zero.
+When the @option{--safer} option (@pxref{Operation modes, , Invoking
+m4}) is in effect, @code{sysval} will always remain at its default value
+of zero.
@comment options: --safer
@comment status: 1
@@ -5089,10 +5139,10 @@ maketemp(`/tmp/fooXXXXXX')
@result{}/tmp/fooa07346
@end example
-When the @option{--safer} option (@pxref{Invoking m4}) is in effect,
[EMAIL PROTECTED] results in an error, since otherwise an input file could
-perform a mild denial-of-service attack by filling up a disk with
-multiple empty files.
+When the @option{--safer} option (@pxref{Operation modes, Invoking m4})
+is in effect, @code{maketemp} results in an error, since otherwise an
+input file could perform a mild denial-of-service attack by filling up a
+disk with multiple empty files.
The builtin macro @code{maketemp} is recognized only when given
arguments.
@@ -5129,7 +5179,8 @@ any of the previous chapters.
@deffn {Builtin (m4)} errprint (@var{message}, @dots{})
You can print error messages using @code{errprint}, which simply prints
@var{message} and the rest of the arguments on standard error,
-independently of the @option{--debugfile} option (@pxref{Invoking m4}).
+independently of the @option{--debugfile} option (@pxref{Debugging
+options, , Invoking m4}).
The expansion of @code{errprint} is void.
@end deffn
@@ -5170,7 +5221,7 @@ Line numbers start at 1 for each file.
@option{-I} option or @env{M4PATH} environment variable, that is
reflected in the file name. Synclines, via @code{syncoutput}
(@pxref{Syncoutput}) or the command line option @option{--synclines}
-(or @option{-s}, @pxref{Invoking m4}), and the
+(or @option{-s}, @pxref{Preprocessor features, , Invoking m4}), and the
@samp{f} and @samp{l} flags of @code{debugmode} (@pxref{Debugmode}),
also use this notion of current file and line. Redefining the three
location macros has no effect on syncline, debug, warning, or error
@@ -5670,7 +5721,8 @@ define the macro @code{__windows__}, whi
Certain features of GNU @code{m4} are experimental.
Some are only available if activated by an option given to
[EMAIL PROTECTED] at GNU @code{m4} installation time. The functionality
[EMAIL PROTECTED]@value{VERSION}/@/configure} at GNU @code{m4} installation
+time. The functionality
might change or even go away in the future. @emph{Do not rely on it}.
Please direct your comments about it the same way you would do for bugs.
@@ -5814,7 +5866,7 @@ foreach(`a', ``1',`2',`3'', `a
@node Improved cleardivert
@section Solution for @code{cleardivert}
-The @code{cleardivert} macro (@pxref{Cleardiv}) cannot, as it stands, be
+The @code{cleardivert} macro (@pxref{Cleardivert}) cannot, as it stands, be
called without arguments to clear all pending diversions. That is
because using undivert with an empty string for an argument is different
than using it with no arguments at all. Compare the earlier definition
_______________________________________________
M4-patches mailing list
[email protected]
http://lists.gnu.org/mailman/listinfo/m4-patches
