branch-1_4 doc sweep

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

The 'invoking m4' node was getting rather long, so I broke it into its own
chapter with sections.  I also fixed some @xref/@pxref that read awkwardly
in dvi or info output.

I'd still like to touch up the forloop section, and add a foreach section,
before releasing 1.4.8.  At this point, I don't know of any code bugs
(other than the fact that I still have a pending gnulib patch required for
correct mingw compilation), so I may be able to make the release in the
next week or two.

2006-10-16  Eric Blake  <address@hidden>

        * doc/m4.texinfo (Invoking m4): Promote to a chapter, instead of
        a section of Preliminaries.
        (Operation modes, Preprocessor features, Limits control)
        (Frozen state, Debugging options, Command line files): Subdivide
        into new sections.
        (Input processing, Quoting Arguments, Define, Arguments)
        (Cleardiv, Format, M4exit): Fix grammar of references.
        (Inhibiting Invocation, Macro Arguments, Builtin, Trace)
        (Debug Levels, Debug Output, Include, Search Path, Divert)
        (Platform macros, Syscmd, Location, Extensions): Point to new
        sections.
        (Top, Loops, Include, Undivert, Location, Incompatibilities):
        Improve file references.

- --
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

iD8DBQFFM3NE84KuGfSFAYARArbAAJ9OYjhI8XlAp0QzGMzaMSGNISCDHwCgpbuj
OND9mAwxJ2WFVOQ9mY9k6hM=
=1JoP
-----END PGP SIGNATURE-----

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.85
diff -u -p -r1.1.1.1.2.85 m4.texinfo
--- doc/m4.texinfo      13 Oct 2006 22:25:32 -0000      1.1.1.1.2.85
+++ doc/m4.texinfo      16 Oct 2006 11:54:40 -0000
@@ -91,7 +91,9 @@ 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.
 
 This is release @value{VERSION}.  It is now considered stable:  future
 releases in the 1.4.x series are only meant to fix bugs, increase speed,
@@ -113,6 +115,7 @@ changeword will go away and @emph{you sh
 
 @menu
 * Preliminaries::               Introduction and preliminaries
+* Invoking m4::                 Invoking @code{m4}
 * Syntax::                      Lexical and syntactic conventions
 
 * Macros::                      How to invoke macros
@@ -143,10 +146,20 @@ 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}
+
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
 
 * Names::                       Macro names
@@ -280,7 +293,6 @@ language.
 @menu
 * Intro::                       Introduction to @code{m4}
 * History::                     Historical references
-* Invoking m4::                 Invoking @code{m4}
 * Bugs::                        Problems and bugs
 * Manual::                      Using this manual
 @end menu
@@ -372,8 +384,102 @@ Meanwhile, development has continued on 
 as dynamic module loading and additional builtins.  When complete,
 @acronym{GNU} @code{m4} 2.0 will start a new series of releases.
 
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}.  Also provide details about the platform you are
+executing on.
+
+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{}}.  Thus
+
address@hidden ignore
address@hidden
+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 by invoking @kbd{m4 -d}.  In fact, the testsuite
+that is bundled in the @acronym{GNU} M4 package consists 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 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.  It requires at least one
+argument, @var{string}.  Remember that in @code{m4}, 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
address@hidden 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')}, @samp{example(`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 @var{count}.  The ellipses
+(@address@hidden) show that the macro processes additional arguments
+after @var{argument}, rather than ignoring them.
address@hidden deffn
+
+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:
 
@@ -397,19 +503,32 @@ 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
+* 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
@@ -454,10 +573,13 @@ calls, or treating the empty string as z
 @item -W @var{REGEXP}
 @itemx address@hidden
 Use @var{REGEXP} as an alternative syntax for macro names.  This
-experimental option will not be present on all @acronym{GNU} @code{m4}
+experimental option will not be present in all @acronym{GNU} @code{m4}
 implementations (@pxref{Changeword}).
 @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.
@@ -506,10 +628,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
 @item -G
@@ -563,6 +689,9 @@ because there is no fixed limit anymore.
 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.
@@ -582,6 +711,9 @@ frozen @var{FILE}.  The options @option{
 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.
 
@@ -619,6 +751,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
@@ -642,100 +777,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}.  Also provide details about the platform you are executing
-on.
-
-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{}}.  Thus
-
address@hidden ignore
address@hidden
-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 by invoking @kbd{m4 -d}.  In fact, the testsuite
-that is bundled in the @acronym{GNU} M4 package consists 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 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.  It requires at least one
-argument, @var{string}.  Remember that in @code{m4}, 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
address@hidden 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')}, @samp{example(`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 @var{count}.  The ellipses
-(@address@hidden) show that the macro processes additional arguments
-after @var{argument}, rather than ignoring them.
address@hidden deffn
-
-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
 
@@ -763,7 +804,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
@@ -777,7 +818,7 @@ Examples of legal names are: @samp{foo},
 @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
 
@@ -885,7 +926,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.
@@ -964,7 +1005,8 @@ call is not triggered.  This solves the 
 specific provision.
 
 There is also a command line option (@option{--prefix-builtins}, or
address@hidden, @pxref{Invoking m4}) that renames all builtin macro with a
address@hidden, @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,
 one has to write @code{m4_dnl} and even @code{m4_m4exit}.  It also has
@@ -1075,7 +1117,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.
 
 Macros are expanded normally during argument collection, and whatever
@@ -1135,7 +1177,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
@@ -1254,8 +1296,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.
@@ -1310,7 +1352,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
@@ -1839,8 +1881,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.
 
 Note that @code{indir} and @code{builtin} can be used to invoke builtins
 without arguments, even when they normally require parameters to be
@@ -2106,7 +2148,7 @@ the iteration variable (using the predef
 @pxref{Incr}), and recurses.
 
 Here is the actual implementation of @code{forloop}, distributed as
address@hidden/@/forloop.m4} in this package:
address@hidden@value{VERSION}/@/examples/@/forloop.m4} in this package:
 
 @example
 undivert(`forloop.m4')
@@ -2237,7 +2279,7 @@ 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} (@pxref{Invoking m4}).
+option @option{--nesting-limit} (@pxref{Limits control, , Invoking m4}).
 
 Tracing by name is an attribute that is preserved whether the macro is
 defined or not.  This allows the @option{-t} option to select macros to
@@ -2299,9 +2341,9 @@ display.
 
 @cindex controlling debugging output
 @cindex debugging output, controlling
-The @option{-d} option to @code{m4} (@pxref{Invoking m4}) controls the
-amount of details presented, when using the macros described in the
-preceding sections.
+The @option{-d} option to @code{m4} (@pxref{Debugging options, ,
+Invoking m4}) controls the amount of details presented, when using the
+macros described in the preceding sections.
 
 The @var{flags} following the option can be one or more of the
 following:
@@ -2401,8 +2443,8 @@ foo
 @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 debugfile (@ovar{file})
 Sends all further debug and trace output to @var{file}.  If
@@ -3156,9 +3198,11 @@ sinclude()
 @end example
 
 The rest of this section assumes that @code{m4} is invoked with the
address@hidden option (@pxref{Invoking m4}) pointing to the @file{examples}
address@hidden option (@pxref{Preprocessor features, , Invoking m4})
+pointing to the @address@hidden/@/examples}
 directory shipped as part of the @acronym{GNU} @code{m4} package.  The
-file @file{examples/@/incl.m4} in the distribution contains the lines:
+file @address@hidden/@/examples/@/incl.m4} in the distribution
+contains the lines:
 @comment ignore
 @example
 Include file start
@@ -3216,8 +3260,8 @@ than the current working directory.
 If a file is not found in the current working directory, and the file
 name is not absolute, the file will be looked for in a specified search
 path.  First, the directories specified with the @option{-I} option will
-be searched, in the order found on the command line (@pxref{Invoking
-m4}).  Second, if the
+be searched, in the order found on the command line (@pxref{Preprocessor
+features, , Invoking m4}).  Second, if the
 @env{M4PATH} environment variable is set, it is expected to contain a
 colon-separated list of directories, which will be searched in order.
 
@@ -3356,8 +3400,8 @@ Note that @code{divert} is an English wo
 without arguments.  When processing plain text, the word might appear in
 normal text and be unintentionally swallowed as a macro invocation.  One
 way to avoid this is to use the @option{-P} option to rename all
-builtins (@pxref{Invoking m4}).  Another is to write a wrapper that
-requires a parameter to be recognized.
+builtins (@pxref{Operation modes, , Invoking m4}).  Another is to write
+a wrapper that requires a parameter to be recognized.
 
 @example
 We decided to divert the stream for irrigation.
@@ -3464,7 +3508,7 @@ non-numeric
 argument, the contents of the file named will be copied, uninterpreted, to
 the current output.  This complements the builtin @code{include}
 (@pxref{Include}).  To illustrate the difference, the file
address@hidden/@/foo} contains the word @samp{bar}:
address@hidden@value{VERSION}/@/examples/@/foo} contains the word @samp{bar}:
 
 @example
 define(`bar', `BAR')
@@ -3543,7 +3587,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.  @pxref{Answers})
+should try to see if you can find it and correct it; or @pxref{Improved
+cleardivert, , Answers}).
 
 @node Text handling
 @chapter Macros for text handling
@@ -3902,7 +3947,7 @@ len(format(`%-*X', `300', `1'))
 @result{}300
 @end example
 
-Using the @code{forloop} macro defined in @xref{Loops}, this
+Using the @code{forloop} macro defined earlier (@pxref{Loops}), this
 example shows how @code{format} can be used to produce tabular output.
 
 @example
@@ -4188,7 +4233,8 @@ string.
 @end deffn
 
 When @acronym{GNU} extensions are in effect (that is, when you did not use the
address@hidden option, @pxref{Invoking m4}), @acronym{GNU} @code{m4} will
address@hidden option, @pxref{Limits control, , Invoking m4}),
address@hidden @code{m4} will
 define the macro @code{__gnu__} to expand to the empty string.
 
 @example
@@ -4262,7 +4308,8 @@ will tell @code{m4} to read all of its i
 wrapped text, then hand a valid (albeit emptied) pipe as standard input
 for the @code{cat} subcommand.  Therefore, you should be careful when
 using standard input (either by specifying no files, or by passing
address@hidden as a file name on the command line, @pxref{Invoking m4}), and
address@hidden as a file name on the command line, @pxref{Command line files,
+, Invoking m4}), and
 also invoking subcommands via @code{syscmd} or @code{esyscmd} that
 consume data from standard input.  When standard input is a seekable
 file, the subprocess will pick up with the next character not yet
@@ -4507,14 +4554,14 @@ errprint(__program__:__file__:__line__: 
 Line numbers start at 1 for each file.  If the file was found due to the
 @option{-I} option or @env{M4PATH} environment variable, that is
 reflected in the file name.  The syncline option (@option{-s},
address@hidden m4}), and the
address@hidden features, , Invoking m4}), and the
 @samp{f} and @samp{l} flags of @code{debugmode} (@pxref{Debug Levels}),
 also use this notion of current file and line.  Redefining the three
 location macros has no effect on syncline, debug, or warning message
 output.  Assume this example is run in the
address@hidden directory of the @acronym{GNU} M4 package, using
address@hidden/examples} in the command line to find the file
address@hidden mentioned earlier:
address@hidden@value{VERSION}/@/checks} directory of the @acronym{GNU} M4
+package, using @samp{--include=../examples} in the command line to find
+the file @file{incl.m4} mentioned earlier:
 
 @example
 define(`foo', ``$0' called at __file__:__line__')
@@ -4614,7 +4661,7 @@ is only intended for error exits, since 
 not followed, e.g., diverted text is not undiverted, and saved text
 (@pxref{M4wrap}) is not reread.  (This macro could be made more robust
 to earlier versions of @code{m4}.  You should try to see if you can find
-weaknesses and correct them.  @pxref{Answers})
+weaknesses and correct them; or @pxref{Improved fatal_error, , Answers}).
 
 Note that it is still possible for the exit status to be different than
 what was requested by @code{m4exit}.  If @code{m4} detects some other
@@ -4757,7 +4804,7 @@ of @code{.m4f}.
 These are simple (editable) text files, made up of directives,
 each starting with a capital letter and ending with a newline
 (@key{NL}).  Wherever a directive is expected, the character
address@hidden introduces a comment line; empty lines are also ignored if they
address@hidden introduces a comment line; empty lines are also ignored if they
 are not part of an embedded string.
 In the following descriptions, each @var{len} refers to the length of
 the corresponding strings @var{str} in the next line of input.  Numbers
@@ -4835,8 +4882,8 @@ is made to summarize these here.
 @cindex @acronym{GNU} extensions
 This version of @code{m4} contains a few facilities that do not exist
 in System V @code{m4}.  These extra facilities are all suppressed by
-using the @option{-G} command line option (@pxref{Invoking m4}), unless
-overridden by other command line options.
+using the @option{-G} command line option (@pxref{Limits control, ,
+Invoking m4}), unless overridden by other command line options.
 
 @itemize @bullet
 @item
@@ -4966,7 +5013,8 @@ argument to @code{m4wrap} is saved for l
 separated by spaces.
 
 However, it is possible to emulate @acronym{POSIX} behavior by
-including the file @file{examples/@/wrapfifo.m4} from the distribution:
+including the file @address@hidden/@/examples/@/wrapfifo.m4}
+from the distribution:
 
 @example
 undivert(`wrapfifo.m4')dnl