[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: branch-1_4 doc sweep
|
From: |
Eric Blake |
|
Subject: |
Re: branch-1_4 doc sweep |
|
Date: |
Mon, 16 Oct 2006 07:14:00 -0600 |
|
User-agent: |
Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.0.7) Gecko/20060909 Thunderbird/1.5.0.7 Mnenhy/0.7.4.666 |
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
According to Eric Blake on 10/16/2006 5:55 AM:
>
> 2006-10-16 Eric Blake <address@hidden>
>
> * 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 <address@hidden>
* doc/m4.texinfo: Backport some minor cleanups from head.
(Cleardivert): Rename from cleardiv.
To head:
2006-10-16 Eric Blake <address@hidden>
* 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 address@hidden
-----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}
address@hidden
* 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
address@hidden 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 address@hidden
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}:
address@hidden Builtin indir (@var{name}, @dots{})
address@hidden Builtin indir (@var{name}, @address@hidden)
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}:
address@hidden Builtin builtin (@var{name}, @dots{})
address@hidden Builtin builtin (@var{name}, @address@hidden)
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}:
address@hidden Builtin dumpdef (@dots{})
address@hidden Builtin dumpdef (@address@hidden)
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}:
address@hidden Builtin traceon (@dots{})
address@hidden Builtin traceoff (@dots{})
address@hidden Builtin traceon (@address@hidden)
address@hidden Builtin traceoff (@address@hidden)
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
address@hidden is empty, debug and trace output are discarded. If
address@hidden 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}:
address@hidden Builtin undivert (@address@hidden)
-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.
address@hidden Builtin undivert (@address@hidden)
+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
address@hidden Cleardiv
address@hidden 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:
address@hidden Composite cleardivert (@address@hidden)
-Discard the contents of each listed diversion.
address@hidden Composite cleardivert (@address@hidden)
+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 @address@hidden/@/AUTHORS} and
address@hidden@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
address@hidden, 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
address@hidden@value{VERSION}/@/README} file in the distribution).
address@hidden
@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.
address@hidden Bugs
address@hidden 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)
address@hidden@@gnu.org}. Please include the version number of @code{m4}
+you are using. You can get this information with the command
address@hidden --version}. You can also run @kbd{make check} to generate the
file
address@hidden/@/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.
+
address@hidden Manual
address@hidden 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
+
address@hidden ignore
address@hidden
+This is an example of an example!
address@hidden example
+
+To distinguish input from output, all output from @code{m4} is prefixed
+by the string @address@hidden, and all error messages by the string
address@hidden@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:
+
address@hidden ignore
address@hidden
+$ @kbd{command line to invoke m4}
+Example of input line
address@hidden line from m4
address@hidden an error message
address@hidden 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
address@hidden 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.,
+
address@hidden {Composite (none)} example (@var{string}, @dvar{count, 1}, @
+ @address@hidden)
+This is a sample prototype. There is not really a macro named
address@hidden, 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
address@hidden, 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')},
address@hidden(`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
address@hidden The ellipses (@address@hidden) show that the macro
+processes additional arguments after @var{argument}, rather than
+ignoring them.
address@hidden deffn
+
+Each builtin definition will list, in parentheses, the module that must
+be loaded to use that macro. The standard modules include
address@hidden (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
address@hidden Invoking @code{m4}
address@hidden 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
address@hidden -Q -P -D foo -d -d+f -- a}, although the latter form is
address@hidden -Q -P -D foo -d -d+f -- ./a}, although the latter form is
considered canonical. (With @env{POSIXLY_CORRECT}, it is equivalent to
address@hidden -Q -P -D foo -d -- a ./-d+f}).
address@hidden -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
address@hidden --define=foo --debug= -- a}, although the latter form is
address@hidden --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.
+
address@hidden
+* 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
address@hidden menu
+
address@hidden Operation modes
address@hidden 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
address@hidden Dynamic loading features
address@hidden 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
address@hidden@value{VERSION}/@/configure}.
@end table
address@hidden Preprocessor features
address@hidden 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
address@hidden Limits control
address@hidden 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}
address@hidden
@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
address@hidden Frozen state
address@hidden 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
address@hidden Debugging options
address@hidden 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
address@hidden Command line files
address@hidden 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.
address@hidden Bugs
address@hidden 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)
address@hidden@@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
address@hidden/@/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.
-
address@hidden Manual
address@hidden 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
-
address@hidden ignore
address@hidden
-This is an example of an example!
address@hidden example
-
-To distinguish input from output, all output from @code{m4} is prefixed
-by the string @address@hidden, and all error messages by the string
address@hidden@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:
-
address@hidden ignore
address@hidden
-$ @kbd{command line to invoke m4}
-Example of input line
address@hidden line from m4
address@hidden an error message
address@hidden 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
address@hidden 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.,
-
address@hidden {Composite (none)} example (@var{string}, @dvar{count, 1}, @
- @address@hidden)
-This is a sample prototype. There is not really a macro named
address@hidden, 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
address@hidden, 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')},
address@hidden(`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
address@hidden The ellipses (@address@hidden) show that the macro
-processes additional arguments after @var{argument}, rather than
-ignoring them.
address@hidden deffn
-
-Each builtin definition will list, in parentheses, the module that must
-be loaded to use that macro. The standard modules include
address@hidden (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
address@hidden and @kbd{'}, where the nested begin and end quotes within the
address@hidden 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
address@hidden 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.
address@hidden 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
address@hidden) 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,
address@hidden, @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
address@hidden, @pxref{Invoking m4}). For user
address@hidden, @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},
address@hidden m4}) is in effect. This is different from @code{indir},
-which only tracks current macro names.
address@hidden 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},
address@hidden m4}) is used in the command line without arguments.
-Also, @code{--debuglen} (@pxref{Debuglen}) can affect output, by
-truncating longer strings.
address@hidden 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
address@hidden) 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
address@hidden or @option{-d},
address@hidden m4}) controls the amount of details presented in three
address@hidden 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},
address@hidden m4}), allow on-the-fly control of debugging string
-lengths:
address@hidden 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
address@hidden option to @code{m4} (@pxref{Invoking m4}), or with
-the builtin macro @code{debugfile}:
address@hidden 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,
address@hidden 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
address@hidden 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.
address@hidden 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
address@hidden {Builtin (m4)} undivert
address@hidden {Builtin (m4)} undivert (@address@hidden)
address@hidden {Builtin (m4)} undivert (@address@hidden)
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.
address@hidden Cleardiv
address@hidden 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,
address@hidden 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,
address@hidden 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,
address@hidden 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,
address@hidden 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
address@hidden at GNU @code{m4} installation time. The functionality
address@hidden@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