m4-commit
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Changes to m4/doc/m4.texinfo,v


From: Eric Blake
Subject: Changes to m4/doc/m4.texinfo,v
Date: Mon, 16 Oct 2006 13:17:51 +0000

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Eric Blake <ericb>      06/10/16 13:17:50

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.65
retrieving revision 1.66
diff -u -b -r1.65 -r1.66
--- doc/m4.texinfo      14 Oct 2006 14:16:23 -0000      1.65
+++ doc/m4.texinfo      16 Oct 2006 13:17:50 -0000      1.66
@@ -94,24 +94,28 @@
 @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 @@
 
 * 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 @@
 * 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 @@
 @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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 @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 @@
 @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 @@
 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 @@
 @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 @@
 @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 @@
 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 @@
 @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 @@
 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 @@
 
 @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 @@
 
 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 @@
 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 @@
 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 @@
 @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 @@
 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 @@
 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 @@
 @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 @@
 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 @@
 @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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 * 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 @@
 @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 @@
 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 @@
 
 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 @@
 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 @@
 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 @@
 @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 @@
 @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 @@
 @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 @@
 @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 @@
 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 @@
 @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




reply via email to

[Prev in Thread] Current Thread [Next in Thread]