Changes to m4/doc/m4.texinfo,v

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Eric Blake <ericb>      06/09/18 13:16:45

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.44
retrieving revision 1.45
diff -u -b -r1.44 -r1.45
--- doc/m4.texinfo      15 Sep 2006 03:37:53 -0000      1.44
+++ doc/m4.texinfo      18 Sep 2006 13:16:43 -0000      1.45
@@ -613,7 +613,7 @@
 @itemx -T @var{NUM}
 These options are present for compatibility with System V @code{m4}, but
 do nothing in this implementation.  They may disappear in future
-releases.
+releases, and issue a warning to that effect.
 @end table
 
 @acronym{GNU} @code{m4} comes with a feature of freezing internal state
@@ -631,8 +631,8 @@
 @itemx address@hidden
 Before execution starts, recover the internal state from the specified
 frozen @var{FILE}.  The options @option{-D}, @option{-U}, @option{-t},
address@hidden, and @option{-r} take effect after state is reloaded, but
-before the input files are read.
address@hidden, @option{-r}, and @option{--import-environment} take effect
+after state is reloaded, but before the input files are read.
 @end table
 
 Finally, there are several options for aiding in debugging @code{m4}
@@ -661,6 +661,11 @@
 error messages, and the output of @code{errprint} and @code{dumpdef},
 are still printed to standard error.  @xref{Debug Output}, for more
 details.
address@hidden FIXME the name --error-output is misleading, since errprint
address@hidden and errors still prints to stderr in spite of this option.  We
address@hidden should rename the option; perhaps --trace-output or
address@hidden --debug-output, or perhaps --debugfile to match the macro
address@hidden name.
 
 @item -t @var{NAME}
 @itemx address@hidden
@@ -672,8 +677,8 @@
 @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
-names.  If no names are present, the standard input is read.  A file
-name of @file{-} is taken to mean the standard input.  It is
+names.  If no names are present, standard input is read.  A file
+name of @file{-} is taken to mean standard input.  It is
 conventional, but not required, for input files to end in @samp{.m4}.
 
 The input files are read in the sequence given.  Standard input can be
@@ -1484,10 +1489,11 @@
 is not so in UNIX implementations of @code{m4}, which only recognize
 one digit.
 @comment FIXME - See Austin group XCU ERN 111.  This is controversial,
address@hidden and perhaps we should consider an alternate syntax ${10}
address@hidden and phase out $10, for better POSIX compliance.  There are
address@hidden existing m4 scripts that depend on $10 being the first
address@hidden parameter concatenated with 0, not the tenth argument.
address@hidden and POSIX is moving to reserve ${ for implementation use.  We
address@hidden should phase out $10 and replace it with ${10}, and consider
address@hidden other extensions like ${1-default}.  There are existing m4
address@hidden scripts that depend on $10 being the first parameter
address@hidden concatenated with 0, not the tenth argument.
 
 As a special case, the zeroth argument, @code{$0}, is always the name
 of the macro being expanded.
@@ -1993,10 +1999,10 @@
 @cindex @acronym{GNU} extensions
 Any macro can be called indirectly with @code{indir}:
 
address@hidden {Builtin (gnu)} indir (@var{name}, @dots{})
address@hidden {Builtin (gnu)} 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
@@ -2045,10 +2051,10 @@
 @cindex @acronym{GNU} extensions
 Builtin macros can be called indirectly with @code{builtin}:
 
address@hidden {Builtin (gnu)} builtin (@var{name}, @dots{})
address@hidden {Builtin (gnu)} 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, a warning
-message is printed, and the expansion is void.
+rest of the arguments @var{args}.  If @var{name} does not name a
+builtin, a warning message is printed, and the expansion is void.
 
 The macro @code{builtin} is recognized only with parameters.
 @end deffn
@@ -2130,14 +2136,14 @@
 The name of the currently defined macros can be accessed by
 @code{symbols}:
 
address@hidden {Builtin (gnu)} symbols (@dots{})
address@hidden {Builtin (gnu)} symbols (@address@hidden)
 Without arguments, @samp{symbols} expands to a sorted list of quoted
 strings, separated by commas.  This contrasts with @code{dumpdef}
 (@pxref{Dumpdef}), whose output cannot be accessed by @code{m4}
 programs.
 
 When given arguments, @code{symbols} returns the sorted subset of the
-symbols currently defined.
address@hidden currently defined, and silently ignores the rest.
 @end deffn
 
 @example
@@ -2524,9 +2530,9 @@
 @node Debugging
 @chapter How to debug macros and input
 
-When writing macros for @code{m4}, most of the time they would not
-work as intended (as is the case with most programming languages).
-There is a little support for macro debugging in @code{m4}.
+When writing macros for @code{m4}, they often do not work as intended on
+the first try (as is the case with most programming languages).
+Fortunately, there is support for macro debugging in @code{m4}.
 
 @menu
 * Dumpdef::                     Displaying macro definitions
@@ -2544,18 +2550,20 @@
 If you want to see what a name expands into, you can use the builtin
 @code{dumpdef}:
 
address@hidden {Builtin (m4)} dumpdef
address@hidden {Builtin (m4)} dumpdef (@dots{})
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
-directly on the standard error output, independently of
address@hidden
address@hidden {Builtin (m4)} 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 @var{names} given.  The output is printed
+directly to standard error, independently of the @option{--error-output}
+option (or @option{-o}, @pxref{Invoking m4}), or @code{debugfile} macro.
+The output is sorted by name.  If an unknown name is encountered, a
+warning is printed.
 
 The expansion of @code{dumpdef} is void.
 @end deffn
 
 @example
+$ @kbd{m4 -d}
 define(`foo', `Hello world.')
 @result{}
 dumpdef(`foo')
@@ -2567,9 +2575,25 @@
 @end example
 
 The last example shows how builtin macros definitions are displayed.
+The definition that is dumped corresponds to what would occur if the
+macro were to be called at that point, even if other definitions are
+still live due to redefining a macro during argument collection.
+
address@hidden
+$ @kbd{m4 -d}
+pushdef(`f', ``$0'1')pushdef(`f', ``$0'2')
address@hidden
+f(popdef(`f')dumpdef(`f'))
address@hidden:@tabchar{}``$0'1'
address@hidden
+f(popdef(`f')dumpdef(`f'))
address@hidden:stdin:3: Warning: dumpdef: undefined macro `f'
address@hidden
address@hidden example
 
 @xref{Debug Levels}, for information on controlling the details of the
-display.
+display; in particular, the @samp{q} flag, implied by @option{-d} in the
+example command line, has an impact.
 
 @node Trace
 @section Tracing macro calls
@@ -2580,13 +2604,16 @@
 It is possible to trace macro calls and expansions through the builtins
 @code{traceon} and @code{traceoff}:
 
address@hidden {Builtin (m4)} traceon
address@hidden {Builtin (m4)} traceon (@dots{})
address@hidden {Builtin (m4)} traceoff
address@hidden {Builtin (m4)} traceoff (@dots{})
address@hidden {Builtin (m4)} traceon (@address@hidden)
address@hidden {Builtin (m4)} 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.
+will turn tracing on and off, respectively, for all macros, identical to
+using the @samp{t} flag of @code{debugmode} (@pxref{Debug Levels}).
+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.
 
 The expansion of @code{traceon} and @code{traceoff} is void.
 @end deffn
@@ -2594,9 +2621,11 @@
 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
-directly on the standard error output.
+to the current debug file (defaulting to standard error, @pxref{Debug
+Output}).
 
 @example
+$ @kbd{m4 -d}
 define(`foo', `Hello World.')
 @result{}
 define(`echo', `$@@')
@@ -2613,7 +2642,162 @@
 
 The number between dashes is the depth of the expansion.  It is one most
 of the time, signifying an expansion at the outermost level, but it
-increases when macro arguments contain unquoted macro calls.
+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.
+
address@hidden options: -d-V -L3 -tifelse
address@hidden status: 1
address@hidden
+$ @kbd{m4 -L 3 -t ifelse}
+ifelse(`one level')
address@hidden: -1- ifelse
address@hidden
+ifelse(ifelse(ifelse(`three levels')))
address@hidden: -3- ifelse
address@hidden: -2- ifelse
address@hidden: -1- ifelse
address@hidden
+ifelse(ifelse(ifelse(ifelse(`four levels'))))
address@hidden:stdin:3: recursion limit of 3 exceeded, use -L<N> to change it
address@hidden example
+
+Tracing by name is an attribute that is preserved whether the macro is
+defined or not.  This allows the selection of macros to trace before
+those macros are defined.
+
address@hidden
+$ @kbd{m4 -d}
+traceoff(`foo')
address@hidden
+traceon(`foo')
address@hidden
+foo
address@hidden
+define(`foo', `bar')
address@hidden
+foo
address@hidden: -1- foo -> `bar'
address@hidden
+undefine(`foo')
address@hidden
+ifdef(`foo', `yes', `no')
address@hidden
+indir(`foo')
address@hidden:stdin:8: Warning: indir: undefined macro `foo'
address@hidden
+define(`foo', `blah')
address@hidden
+foo
address@hidden: -1- foo -> `blah'
address@hidden
address@hidden example
+
+Tracing even works on builtins.  However, @command{defn} (@pxref{Defn})
+does not transfer tracing status.
+
address@hidden
+$ @kbd{m4 -d}
+traceon(`eval', `m4_divnum')
address@hidden
+define(`m4_eval', defn(`eval'))
address@hidden
+define(`m4_divnum', defn(`divnum'))
address@hidden
+eval(divnum)
address@hidden: -1- eval(`0') -> `0'
address@hidden
+m4_eval(m4_divnum)
address@hidden: -2- m4_divnum -> `0'
address@hidden
address@hidden example
+
+As of @acronym{GNU} M4 2.0, named macro tracing is independent of global
+tracing status; calling @code{traceoff} without arguments turns off the
+global trace flag, but does not turn off tracing for macros where
+tracing was requested by name.  Likewise, calling @code{traceon} without
+arguments will affect tracing of macros that are not defined yet.  This
+behavior matches traditional implementations of @code{m4}.
+
address@hidden
+$ @kbd{m4 -d}
+traceon
address@hidden
+define(`foo', `bar')
address@hidden: -1- define(`foo', `bar')
address@hidden
+foo # traced, even though foo was not defined at traceon
address@hidden: -1- foo -> `bar'
address@hidden # traced, even though foo was not defined at traceon
+traceoff(`foo')
address@hidden: -1- traceoff(`foo')
address@hidden
+foo # traced, since global tracing is still on
address@hidden: -1- foo -> `bar'
address@hidden # traced, since global tracing is still on
+traceon(`foo')
address@hidden: -1- traceon(`foo')
address@hidden
+traceoff
address@hidden: -1- traceoff
address@hidden
+foo # traced, since foo is now traced by name
address@hidden: -1- foo -> `bar'
address@hidden # traced, since foo is now traced by name
+traceoff(`foo')
address@hidden
+foo # untraced
address@hidden # untraced
address@hidden example
+
+However, @acronym{GNU} M4 1.4.7 and earlier had slightly different
+semantics, where @code{traceon} without arguments only affected symbols
+that were defined at that moment, and @code{traceoff} without arguments
+stopped all tracing, even when tracing was requested by macro name.  The
+addition of the macro @code{symbols} (@pxref{Symbols}) in 2.0 makes it
+possible to write a file that approximates the older semantics
+regardless of which version of @acronym{GNU} M4 is in use.
+
address@hidden options: -d-V
address@hidden
+$ @kbd{m4}
+ifdef(`symbols',
+  `define(`traceon', `ifelse(`$#', `0', `builtin(`traceon', symbols)',
+    `builtin(`traceon', $@@)')')dnl
+define(`traceoff', `ifelse(`$#', `0',
+    `builtin(`traceoff')builtin(`traceoff', symbols)',
+    `builtin(`traceoff', $@@)')')')dnl
+define(`a', `1')
address@hidden
+traceon # called before b is defined, so b is not traced
address@hidden # called before b is defined, so b is not traced
+define(`b', `2')
address@hidden: -1- define
address@hidden
+a b
address@hidden: -1- a
address@hidden 2
+traceon(`b')
address@hidden: -1- traceon
address@hidden: -1- ifelse
address@hidden: -1- builtin
address@hidden
+a b
address@hidden: -1- a
address@hidden: -1- b
address@hidden 2
+traceoff # stops tracing b, even though it was traced by name
address@hidden: -1- traceoff
address@hidden: -1- ifelse
address@hidden: -1- builtin
address@hidden: -2- symbols
address@hidden: -1- builtin
address@hidden # stops tracing b, even though it was traced by name
+a b
address@hidden 2
address@hidden example
 
 @xref{Debug Levels}, for information on controlling the details of the
 display.
@@ -2623,43 +2807,37 @@
 
 @cindex controlling debugging output
 @cindex debugging output, controlling
-The @samp{-d} option to @code{m4} controls the amount of details
-presented, when using the macros described in the preceding sections.
+The @option{--debug} option to @code{m4} (or @option{-d},
address@hidden 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:
 
 @table @code
address@hidden t
-Trace all macro calls made in this invocation of @code{m4}.
-
 @item a
 Show the actual arguments in each macro call.  This applies to all macro
 calls if the @samp{t} flag is used, otherwise only the macros covered by
 calls of @code{traceon}.
 
address@hidden e
-Show the expansion of each macro call, if it is not void.  This applies
-to all macro calls if the @samp{t} flag is used, otherwise only the
-macros covered by calls of @code{traceon}.
-
address@hidden q
-Quote actual arguments and macro expansions in the display with the
-current quotes.
-
 @item c
 Show several trace lines for each macro call.  A line is shown when the
 macro is seen, but before the arguments are collected; a second line
 when the arguments have been collected and a third line after the call
 has completed.
 
address@hidden x
-Add a unique `macro call id' to each line of the trace output.  This is
-useful in connection with the @samp{c} flag above.
address@hidden e
+Show the expansion of each macro call, if it is not void.  This applies
+to all macro calls if the @samp{t} flag is used, otherwise only the
+macros covered by calls of @code{traceon}.
 
 @item f
 Show the name of the current input file in each trace output line.
 
address@hidden i
+Print a message each time the current input file is changed, giving file
+name and input line number.
+
 @item l
 Show the current input line number in each trace output line.
 
@@ -2670,54 +2848,119 @@
 Print a message when a named file is found through the path search
 mechanism (@pxref{Search Path}), giving the actual file name used.
 
address@hidden i
-Print a message each time the current input file is changed, giving file
-name and input line number.
address@hidden q
+Quote actual arguments and macro expansions in the display with the
+current quotes.  This affects traced macros, as well as @code{dumpdef}
+output.
+
address@hidden t
+Trace all macro calls made in this invocation of @code{m4}.  This is
+equivalent to using @code{traceon} without arguments.
+
address@hidden x
+Add a unique `macro call id' to each line of the trace output.  This is
+useful in connection with the @samp{c} flag above.
 
 @item V
 A shorthand for all of the above flags.
 @end table
 
-If no flags are specified with the @samp{-d} option, the default is
address@hidden The examples in the previous two sections assumed the
+As special cases, if @var{flags} starts with a @samp{+}, the remaining
+flags are added to the current debug flags, and if it starts with a
address@hidden, remaining flags are removed.  Without either of these
+starting characters, @var{flags} simply replaces the previous setting.
+
+If no flags are specified with the @option{-d} option, the default is
address@hidden Many examples in this manual show their output using
 default flags.
 
address@hidden GNU extensions
address@hidden @acronym{GNU} extensions
 There is a builtin macro @code{debugmode}, which allows on-the-fly control of
 the debugging output format:
 
address@hidden {Builtin (gnu)} debugmode
address@hidden {Builtin (gnu)} debugmode @w{(opt @var{flags})}
address@hidden {Builtin (gnu)} debugmode (@ovar{flags})
 The argument @var{flags} should be a subset of the letters listed above.
-As special cases, if the argument starts with a @samp{+}, the flags are
-added to the current debug flags, and if it starts with a @samp{-}, they
-are removed.  If no argument is present, the debugging flags are set to
-zero (as if no @samp{-d} was given), and with an empty argument the flags
-are reset to the default.
+If no argument is present, all debugging flags are cleared
+(as if no @option{-d} was given), and with an empty argument the flags
+are reset to the default of @samp{aeq}.  If an unknown flag is
+encountered, an error is issued.
+
+The expansion of @code{debugmode} is void.
 @end deffn
 
address@hidden
+define(`foo', `FOO')
address@hidden
+traceon(`foo')
address@hidden
+debugmode()
address@hidden
+foo
address@hidden: -1- foo -> `FOO'
address@hidden
+debugmode
address@hidden
+foo
address@hidden: -1- foo
address@hidden
+debugmode(`+l')
address@hidden
+foo
address@hidden:8: -1- foo
address@hidden
address@hidden example
+
 @node Debug Output
 @section Saving debugging output
 
 @cindex saving debugging output
 @cindex debugging output, saving
 @cindex output, saving debugging
address@hidden GNU extensions
address@hidden @acronym{GNU} extensions
 Debug and tracing output can be redirected to files using either the
address@hidden option to @code{m4}, or with the builtin macro @code{debugfile}:
address@hidden option to @code{m4} (@pxref{Invoking m4}), or with the
+builtin macro @code{debugfile}:
 
address@hidden {Builtin (gnu)} debugfile
address@hidden {Builtin (gnu)} debugfile @w{(opt @var{file})}
address@hidden {Builtin (gnu)} debugfile (@ovar{file})
 Send 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 and if @code{debugfile} is called without any arguments, debug
-and trace output are sent to the standard error output.
+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} and @code{dumpdef}
+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,
 @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
 
address@hidden
+$ @kbd{m4 -d}
+traceon(`divnum')
address@hidden
+divnum(`extra')
address@hidden:stdin:2: Warning: divnum: extra arguments ignored: 1 > 0
address@hidden: -1- divnum(`extra') -> `0'
address@hidden
+debugfile()
address@hidden
+divnum(`extra')
address@hidden:stdin:4: Warning: divnum: extra arguments ignored: 1 > 0
address@hidden
+debugfile
address@hidden
+divnum
address@hidden: -1- divnum -> `0'
address@hidden
address@hidden example
+
+Although the @option{--safer} option cripples @code{debugfile} to a
+limited subset of capabilities, you may still use the @option{-o}
+option from the command line with no restrictions.
+
 @comment options: --safer
 @comment status: 1
 @example
@@ -2780,7 +3023,7 @@
 
 @cindex changing the quote delimiters
 @cindex quote delimiters, changing the
address@hidden {Builtin (m4)} changequote (@w{opt @var{start}}, @w{opt 
@var{end})}
address@hidden {Builtin (m4)} changequote (@ovar{start}, @ovar{end})
 The default quote delimiters can be changed with the builtin
 @code{changequote}, where @var{start} is the new start-quote delimiter
 and @var{end} is the new end-quote delimiter.  If any of the arguments
@@ -2843,7 +3086,7 @@
 
 @cindex changing comment delimiters
 @cindex comment delimiters, changing
address@hidden {Builtin (m4)} changecom (@w{opt @var{start}}, @w{opt @var{end})}
address@hidden {Builtin (m4)} changecom (@ovar{start}, @ovar{end})
 The default comment delimiters can be changed with the builtin
 macro @code{changecom}, where @var{start} is the new start-comment
 delimiter and @var{end} is the new end-comment delimiter.  If any of the
@@ -2889,7 +3132,7 @@
 
 @cindex regular expression syntax, changing
 @cindex GNU extensions
address@hidden {Builtin (gnu)} changeresyntax (@w{opt @var{resyntax}})
address@hidden {Builtin (gnu)} changeresyntax (@var{resyntax})
 By default, the @sc{gnu} extensions @code{patsubst}, @code{regexp} and
 more recently @code{renamesyms} continue to use emacs style regular
 expression syntax (@pxref{Regular expression syntax}).
@@ -3411,11 +3654,11 @@
 @example
 define(`bar', include(`incl.m4'))
 @result{}
-This is `bar':  >>>bar<<<
address@hidden is bar:  >>>Include file start
+This is `bar':  >>bar<<
address@hidden is bar:  >>Include file start
 @result{}foo
 @result{}Include file end
address@hidden<<<
address@hidden<<
 @end example
 
 This use of @code{include} is not trivial, though, as files can contain
@@ -3482,7 +3725,7 @@
 @cindex output, diverting to files
 @cindex files, diverting output to
 @deffn {Builtin (m4)} divert
address@hidden {Builtin (m4)} divert (@w{opt @var{number}})
address@hidden {Builtin (m4)} divert (@ovar{number})
 Output is diverted using @code{divert} where @var{number} is the
 diversion to be used.  If @var{number} is left out, it is assumed to be
 zero.
@@ -3527,7 +3770,7 @@
 @section Undiverting output
 
 @deffn {Builtin (m4)} undivert
address@hidden {Builtin (m4)} undivert (@w{opt @var{number}}, @dots{})
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
@@ -3958,7 +4201,8 @@
 @cindex regular expressions
 @cindex GNU extensions
 @deffn {Builtin (gnu)} regexp (@var{string}, @var{regexp}, @var{resyntax})
address@hidden {Builtin (gnu)} regexp (@var{string}, @var{regexp}, @w{opt 
@var{replacement},} @w{opt @var{resyntax})}
address@hidden {Builtin (gnu)} regexp (@var{string}, @var{regexp}, @
+  @ovar{replacement}, @ovar{resyntax})
 Searching for regular expressions is done with the builtin
 @code{regexp}, which searches for @var{regexp} in @var{string}.  The
 syntax of regular expressions is similar to that of Perl, @sc{gnu} Awk
@@ -4019,7 +4263,7 @@
 
 @cindex extracting substrings
 @cindex substrings, extracting
address@hidden {Builtin (m4)} substr (@var{string}, @var{from}, @w{opt 
@var{length})}
address@hidden {Builtin (m4)} substr (@var{string}, @var{from}, @ovar{length})
 Substrings are extracted with @code{substr}, which expands to the
 substring of @var{string}, which starts at index @var{from}, and extends
 for @var{length} characters, or to the end of @var{string}, if
@@ -4084,7 +4328,8 @@
 @cindex pattern substitution
 @cindex substitution by regular expression
 @cindex GNU extensions
address@hidden {Builtin (gnu)} patsubst (@var{string}, @var{regexp}, @w{opt 
@var{replacement},} @w{opt @var{resyntax})}
address@hidden {Builtin (gnu)} patsubst (@var{string}, @var{regexp}, @
+  @ovar{replacement}, @ovar{resyntax})
 Global substitution in a string is done by @code{patsubst}, which
 searches @var{string} for matches of @var{regexp}, and substitutes
 @var{replacement} for each match.
@@ -4275,7 +4520,7 @@
 @cindex integer expression evaluation
 @cindex evaluation, of integer expressions
 @cindex expressions, evaluation of integer
address@hidden {Builtin (m4)} eval (@var{expression}, @w{opt @var{radix},} 
@w{opt @var{width})}
address@hidden {Builtin (m4)} eval (@var{expression}, @ovar{radix}, 
@ovar{width})
 Integer expressions are evaluated with @code{eval}, which expands to the
 value of @var{expression}.
 
@@ -4393,7 +4638,7 @@
 When @code{m4} is compiled with a multiple precision arithmetic library
 (@pxref{Experiments}), a builtin @code{mpeval} is defined.
 
address@hidden {Builtin (mpeval)} mpeval (@var{expression}, @w{opt 
@var{radix},} @w{opt @var{width})}
address@hidden {Builtin (mpeval)} mpeval (@var{expression}, @ovar{radix}, 
@ovar{width})
 It is almost identical to @code{eval}, except the calculations are done
 with infinite precision.  Numbers may be of any length.
 
@@ -4484,7 +4729,7 @@
 command @var{shell-command}.
 
 Prior to executing the command, @code{m4} flushes its output buffers.
-The default standard input and error output of @var{shell-command} are
+The default standard input and standard error of @var{shell-command} are
 the same as those of @code{m4}.  The error output of @var{shell-command}
 is not a part of the expansion: it will appear along with the error
 output of @code{m4}.
@@ -4618,8 +4863,8 @@
 @cindex messages, printing error
 @deffn {Builtin (m4)} errprint (@var{message}, @dots{})
 You can print error messages using @code{errprint}, which simply prints
address@hidden and the rest of the arguments on the standard error
-output, independently of @option{--error-output}.
address@hidden and the rest of the arguments on standard error,
+independently of @option{--error-output}.
 
 The expansion of @code{errprint} is void.
 @end deffn
@@ -4658,8 +4903,7 @@
 @section Exiting from @code{m4}
 
 @cindex exiting from @code{m4}
address@hidden {Builtin (m4)} m4exit
address@hidden {Builtin (m4)} m4exit (@w{opt @var{code}})
address@hidden {Builtin (m4)} m4exit (@ovar{code})
 If you need to exit from @code{m4} before the entire input has been
 read, you can use @code{m4exit}, which causes @code{m4} to exit, with
 exit code @var{code}.  If @var{code} is left out, the exit code is