Changes to m4/doc/m4.texinfo,v [branch-1_4]

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Branch:         branch-1_4
Changes by:     Eric Blake <ericb>      06/07/15 01:56:46

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.43
retrieving revision 1.1.1.1.2.44
diff -u -b -r1.1.1.1.2.43 -r1.1.1.1.2.44
--- doc/m4.texinfo      14 Jul 2006 20:43:23 -0000      1.1.1.1.2.43
+++ doc/m4.texinfo      15 Jul 2006 01:56:46 -0000      1.1.1.1.2.44
@@ -99,9 +99,9 @@
 on the Internet.  All names and email addresses can be found in the
 files @file{AUTHORS} and @file{THANKS} from the GNU M4 distribution.
 
-This is release @value{VERSION}.  It is now to be considered stable,
-future releases in the 1.4.x series are only meant to fix bugs, increase
-speed, or improve documentation.  address@hidden
+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,
+or improve documentation.  address@hidden
 
 An experimental feature, which would improve @code{m4} usefulness,
 allows for changing the syntax for what is a @dfn{word} in @code{m4}.
@@ -292,15 +292,16 @@
 builtin or user-defined, and can take any number of arguments.
 Besides just doing macro expansion, @code{m4} has builtin functions
 for including named files, running shell commands, doing integer
-arithmetic, manipulating text in various ways, recursion, address@hidden
address@hidden can be used either as a front-end to a compiler, or as a
-macro processor in its own right.
+arithmetic, manipulating text in various ways, performing recursion,
address@hidden @code{m4} can be used either as a front-end to a compiler, or
+as a macro processor in its own right.
 
-The @code{m4} macro processor is widely available on all UNIXes.
+The @code{m4} macro processor is widely available on all UNIXes, and has
+been standardized by @acronym{POSIX}.
 Usually, only a small percentage of users are aware of its existence.
 However, those who find it often become committed users.  The
 popularity of GNU Autoconf, which requires GNU @code{m4} for
address@hidden the @file{configure} scripts, is an incentive
address@hidden @file{configure} scripts, is an incentive
 for many to install it, while these people will not themselves
 program in @code{m4}.  GNU @code{m4} is mostly compatible with the
 System V, Release 3 version, except for some minor differences.
@@ -308,7 +309,7 @@
 
 Some people find @code{m4} to be fairly addictive.  They first use
 @code{m4} for simple problems, then take bigger and bigger challenges,
-learning how to write complex @code{m4} sets of macros along the way.
+learning how to write complex sets of @code{m4} macros along the way.
 Once really addicted, users pursue writing of sophisticated @code{m4}
 applications even to solve simple problems, devoting more time
 debugging their @code{m4} scripts than doing real work.  Beware that
@@ -317,7 +318,7 @@
 @node History
 @section Historical references
 
address@hidden has been an important ancestor of @code{m4}.  See
address@hidden was an important ancestor of @code{m4}.  See
 C. Stratchey: ``A General Purpose Macro generator'', Computer Journal
 8,3 (1965), pp. 225 ff.  @code{GPM} is also succinctly described into
 David Gries classic ``Compiler Construction for Digital Computers''.
@@ -329,7 +330,7 @@
 
 Kernighan and Ritchie then joined forces to develop the original
 @code{m4}, as described in ``The M4 Macro Processor'', Bell
-Laboratories (1977) which had only 21 builtin macros.
+Laboratories (1977).  It had only 21 builtin macros.
 
 While @code{GPM} was more @emph{pure}, @code{m4} is meant to deal with
 the true intricacies of real life: macros can be recognized without
@@ -337,14 +338,14 @@
 more constructs are builtin instead of derived, etc.
 
 Originally, the Kernighan and Plauger macro-processor, and then
address@hidden formed the engine for the Rational FORTRAN preprocessor,
address@hidden, formed the engine for the Rational FORTRAN preprocessor,
 that is, the @code{Ratfor} equivalent of @code{cpp}.  Later, @code{m4}
 was used as a frontend for @code{Ratfor}, @code{C} and @code{Cobol}.
 
 Ren@'e Seindal released his implementation of @code{m4}, GNU @code{m4},
 in 1990, with the aim of removing the artificial limitations in many
-of the traditional @code{m4}'s: like maximum line length, macro size,
-number of macros and so on.
+of the traditional @code{m4} implementations, such as maximum line
+length, macro size, or number of macros.
 
 The late Professor A. Dain Samples described and implemented a further
 evolution in the form of @code{M5}: ``User's Guide to the M5 Macro
@@ -425,7 +426,7 @@
 @itemx address@hidden
 Use @var{REGEXP} as an alternative syntax for macro names.  This
 experimental option will not be present on all GNU @code{m4}
-implementations. (@pxref{Changeword}).
+implementations (@pxref{Changeword}).
 @end table
 
 @cindex macro definitions, on the command line
@@ -458,7 +459,7 @@
 front end to a compiler.  Source file name and line number information
 is conveyed by directives of the form @samp{#line @var{linenum}
 "@var{file}"}, which are inserted as needed into the middle of the
-input.  Such directives mean that the following line originated or was
+output.  Such directives mean that the following line originated or was
 expanded from the contents of input file @var{file} at line
 @var{linenum}.  The @samp{"@var{file}"} part is often omitted when
 the file name did not change from the previous directive.
@@ -576,7 +577,7 @@
 @itemx address@hidden
 This enables tracing for the macro @var{NAME}, at any point where it is
 defined.  @var{NAME} need not be defined when this option is given.
-This option may be given more than once.
+This option may be given more than once.  @xref{Trace}, for more details.
 @end table
 
 @cindex command line, file names on the
@@ -588,7 +589,7 @@
 
 The input files are read in the sequence given.  The standard input can
 only be read once, so the file name @file{-} should only appear once on
-the command line.  It is an error if a file ends in the middle of
+the command line.  It is an error if an input file ends in the middle of
 argument collection or a quoted string.
 
 If you need to read a file whose name starts with a @file{-}, you can
@@ -655,10 +656,25 @@
 call of the macro will be shown, giving descriptive names to the
 arguments, e.g.,
 
address@hidden ignore
address@hidden
-regexp(@var{string}, @var{regexp}, opt @var{replacement})
address@hidden example
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
@@ -670,11 +686,6 @@
 a number results in 0 rather than an error, although a warning will be
 issued.
 
-The @samp{opt} before the third argument shows that this argument is
-optional---if it is left out, it is taken to be the empty string.  An
-ellipsis (@samp{...}) last in the argument list indicates that any
-number of arguments may follow.
-
 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}.
@@ -714,8 +725,8 @@
 
 @cindex quoted string
 A quoted string is a sequence of characters surrounded by the quotes
address@hidden and @kbd{'}, where the number of start and end quotes within the
-string balances.  The value of a string token is the text, with one
address@hidden and @kbd{'}, where the nested start 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
 
 @comment ignore
@@ -793,7 +804,7 @@
 
 @comment ignore
 @example
-format(`Result is %d', `32768')
+format(`Result is %d', 32768)
 @end example
 
 @noindent
@@ -840,7 +851,7 @@
 
 @comment ignore
 @example
-name(arg1, arg2, ..., address@hidden)
+name(arg1, arg2, @dots{}, address@hidden)
 @end example
 
 @noindent
@@ -880,27 +891,28 @@
 parenthesis does not immediately follow their name, the builtin macro
 call is not triggered.  This solves the most usual cases, like for
 @samp{include} or @samp{eval}.  Later in this document, the sentence
-``This macro is recognized only when given arguments'' refers to this
+``This macro is recognized only with parameters'' refers to this
 specific provision.
 
-There is also a command call option (@option{--prefix-builtins}, or
+There is also a command line option (@option{--prefix-builtins}, or
 @option{-P}) which requires all builtin macro names to be prefixed
 by @samp{m4_} for them to be recognized.  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}.
 
 If your version of GNU @code{m4} has the @code{changeword} feature
-compiled in, there it offers far more flexibility in specifying the
+compiled in, it offers far more flexibility in specifying the
 syntax of macro names, both builtin or user-defined.  @xref{Changeword},
 for more information on this experimental feature.
 
-Of course, the simplest way to prevent a name to be interpreted
+Of course, the simplest way to prevent a name from being interpreted
 as a call to an existing macro is to quote it.  The remainder of
 this section studies a little more deeply how quoting affects macro
 invocation, and how quoting can be used to inhibit macro invocation.
 
 Even if quoting is usually done over the whole macro name, it can also
-be done over only a few characters of this name.  It is also possible
+be done over only a few characters of this name (provided, of course,
+that the unquoted portions are not also a macro).  It is also possible
 to quote the empty string, but this works only @emph{inside} the name.
 For example:
 
@@ -983,7 +995,9 @@
 
 If the name is followed by an opening parenthesis, the arguments will be
 collected before the macro is called.  If too few arguments are
-supplied, the missing arguments are taken to be the empty string.  If
+supplied, the missing arguments are taken to be the empty string.
+However, some builtins are documented to behave differently for a
+missing optional argument than for an explicit empty string.  If
 there are too many arguments, the excess arguments are ignored.
 
 Normally @code{m4} will issue warnings if a builtin macro is called
@@ -1038,7 +1052,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, @pxref{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
@@ -1087,8 +1101,8 @@
 @cindex macros, how to define new
 @cindex defining new macros
 Macros can be defined, redefined and deleted in several different ways.
-Also, it is possible to redefine a macro, without losing a previous
-value, which can be brought back at a later time.
+Also, it is possible to redefine a macro without losing a previous
+value, and bring back the original value at a later time.
 
 @menu
 * Define::                      Defining a new macro
@@ -1105,20 +1119,16 @@
 @node Define
 @section Defining a macro
 
address@hidden define
 The normal way to define or redefine macros is to use the builtin
 @code{define}:
 
address@hidden ignore
address@hidden
-define(@var{name} [, @var{expansion}])
address@hidden example
-
address@hidden
-which defines @var{name} to expand to @var{expansion}.  If
address@hidden Builtin define (@var{name}, @ovar{expansion})
+Defines @var{name} to expand to @var{expansion}.  If
 @var{expansion} is not given, it is taken to be empty.
 
 The expansion of @code{define} is void.
+The macro @code{define} is recognized only with parameters.
address@hidden deffn
 
 The following example defines the macro @var{foo} to expand to the text
 @samp{Hello World.}.
@@ -1149,7 +1159,8 @@
 @result{}two
 @end example
 
-The first argument to @code{define} does not have to be a simple word.
+As a GNU extension, the first argument to @code{define} does 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 recognised.  It can only be referenced by the builtins @ref{Indir}
@@ -1175,8 +1186,6 @@
 
 Change the @code{%d} to @code{%s} and it is an associative array.
 
-The macro @code{define} is recognized only with parameters.
-
 @node Arguments
 @section Arguments to macros
 
@@ -1355,19 +1364,15 @@
 @cindex macros, how to delete
 @cindex deleting macros
 @cindex undefining macros
address@hidden undefine
 A macro definition can be removed with @code{undefine}:
 
address@hidden ignore
address@hidden
-undefine(@var{name})
address@hidden example
-
address@hidden
-which removes the macro @var{name}.  The macro name must necessarily be
-quoted, since it will be expanded otherwise.
address@hidden Builtin undefine (@address@hidden)
+For each argument, remove the macro @var{name}.  The macro names must
+necessarily be quoted, since they will be expanded otherwise.
 
 The expansion of @code{undefine} is void.
+The macro @code{undefine} is recognized only with parameters.
address@hidden deffn
 
 @example
 foo bar blah
@@ -1401,24 +1406,16 @@
 It is not an error for @var{name} to have no macro definition.  In that
 case, @code{undefine} does nothing.
 
-The macro @code{undefine} is recognized only with parameters.
-
 @node Defn
 @section Renaming macros
 
 @cindex macros, how to rename
 @cindex renaming macros
address@hidden defn
 It is possible to rename an already defined macro.  To do this, you need
 the builtin @code{defn}:
 
address@hidden ignore
address@hidden
-defn(@var{name})
address@hidden example
-
address@hidden
-which expands to the @emph{quoted definition} of @var{name}.  If the
address@hidden Builtin defn (@var{name})
+Expands to the @emph{quoted definition} of @var{name}.  If the
 argument is not a defined macro, the expansion is void.
 
 If @var{name} is a user-defined macro, the quoted definition is simply
@@ -1428,6 +1425,7 @@
 @code{define} (and @code{pushdef}), and is ignored in any other context.
 
 The macro @code{defn} is recognized only with parameters.
address@hidden deffn
 
 Its normal use is best understood through an example, which shows how to
 rename @code{undefine} to @code{zap}:
@@ -1501,19 +1499,12 @@
 @cindex temporary redefinition of macros
 @cindex redefinition of macros, temporary
 It is possible to redefine a macro temporarily, reverting to the
-previous definition at a later time.
address@hidden popdef
address@hidden pushdef
-This is done with the builtins @code{pushdef} and @code{popdef}:
+previous definition at a later time.  This is done with the builtins
address@hidden and @code{popdef}:
 
address@hidden ignore
address@hidden
-pushdef(@var{name} [, @var{expansion}])
-popdef(@var{name})
address@hidden example
-
address@hidden
-which are quite analogous to @code{define} and @code{undefine}.
address@hidden Builtin pushdef (@var{name}, @ovar{expansion})
address@hidden Builtin popdef (@address@hidden)
+Analogous to @code{define} and @code{undefine}.
 
 These macros work in a stack-like fashion.  A macro is temporarily
 redefined with @code{pushdef}, which replaces an existing definition of
@@ -1525,6 +1516,11 @@
 the topmost definition can be removed with @code{popdef}.  If there is
 no previous definition, @code{popdef} behaves like @code{undefine}.
 
+The expansion of both @code{pushdef} and @code{popdef} is void.
+The macros @code{pushdef} and @code{popdef} are recognized only with
+parameters.
address@hidden deffn
+
 @example
 define(`foo', `Expansion one.')
 @result{}
@@ -1576,12 +1572,16 @@
 @result{}foo
 @end example
 
address@hidden local variables
address@hidden variables, local
+Local variables within macros are made with @code{pushdef} and
address@hidden  At the start of the macro a new definition is pushed,
+within the macro it is manipulated and at the end it is popped,
+revealing the former definition.
+
 It is possible to temporarily redefine a builtin with @code{pushdef}
 and @code{defn}.
 
-The macros @code{pushdef} and @code{popdef} are recognized only with
-parameters.
-
 @node Indir
 @section Indirect call of macros
 
@@ -1589,17 +1589,17 @@
 @cindex call of macros, indirect
 @cindex macros, indirect call of
 @cindex GNU extensions
address@hidden indir
 Any macro can be called indirectly with @code{indir}:
 
address@hidden ignore
address@hidden
-indir(@var{name}, ...)
address@hidden example
address@hidden Builtin indir (@var{name}, @dots{})
+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.
 
address@hidden
-which results in a call to the macro @var{name}, which is passed the
-rest of the arguments.  This can be used to call macros with ``invalid''
+The macro @code{indir} is recognized only with parameters.
address@hidden deffn
+
+This can be used to call macros with ``invalid''
 names (@code{define} allows such names to be defined):
 
 @example
@@ -1615,8 +1615,6 @@
 defined, that will not be called by accident.  They can @emph{only} be
 called through the builtin @code{indir}.
 
-The macro @code{indir} is recognized only with parameters.
-
 @node Builtin
 @section Indirect call of builtins
 
@@ -1624,20 +1622,60 @@
 @cindex call of builtins, indirect
 @cindex builtins, indirect call of
 @cindex GNU extensions
address@hidden builtin
 Builtin macros can be called indirectly with @code{builtin}:
 
address@hidden ignore
address@hidden Builtin builtin (@var{name}, @dots{})
+Results in a call to the builtin @var{name}, which is passed the
+rest of the arguments.  If @var{name} does not name a builtin, an error
+message is printed, and the expansion is void.
+
+The macro @code{builtin} is recognized only with parameters.
address@hidden deffn
+
+This can be used even if @var{name} has been given another definition
+that has covered the original, or been undefined so that no @var{name}
+maps to the builtin.
+
 @example
-builtin(@var{name}, ...)
+pushdef(`define', `hidden')
address@hidden
+undefine(`undefine')
address@hidden
+define(`foo', `bar')
address@hidden
+foo
address@hidden
+builtin(`define', `foo', `BAR')
address@hidden
+foo
address@hidden
+undefine(`foo')
address@hidden(foo)
+foo
address@hidden
+builtin(`undefine', `foo')
address@hidden
+foo
address@hidden
 @end example
 
address@hidden
-which results in a call to the builtin @var{name}, which is passed the
-rest of the arguments.  This can be used, if @var{name} has been given
-another definition that has covered the original.
+Note that this can be used to invoke builtins that normally require
+parameters without actually providing them; but it will provoke a
+warning, and usually result in a void expansion.
 
-The macro @code{builtin} is recognized only with parameters.
address@hidden
+builtin
address@hidden
+builtin()
address@hidden:2: m4: undefined builtin `'
address@hidden
+builtin(`builtin')
address@hidden:3: m4: Warning: too few arguments to builtin `builtin'
address@hidden
+builtin(`builtin',)
address@hidden:4: m4: undefined builtin `'
address@hidden
address@hidden example
 
 This can be used even if @var{name} has been given another definition
 that has covered the original, or been undefined so that no @var{name}
@@ -1689,7 +1727,7 @@
 
 Macros, expanding to plain text, perhaps with arguments, are not quite
 enough.  We would like to have macros expand to different things, based
-on decisions taken at run-time.  E.g., we need some kind of conditionals.
+on decisions taken at run-time.  For that, we need some kind of conditionals.
 Also, we would like to have some kind of loop construct, so we could do
 something a number of times, or while some condition is true.
 
@@ -1703,22 +1741,18 @@
 @section Testing macro definitions
 
 @cindex conditionals
address@hidden ifdef
 There are two different builtin conditionals in @code{m4}.  The first is
 @code{ifdef}:
 
address@hidden ignore
address@hidden
-ifdef(@var{name}, @var{string-1}, opt @var{string-2})
address@hidden example
-
address@hidden
-which makes it possible to test whether a macro is defined or not.  If
address@hidden is defined as a macro, @code{ifdef} expands to
address@hidden Builtin ifdef (@var{name}, @var{string-1}, @ovar{string-2})
+If @var{name} is defined as a macro, @code{ifdef} expands to
 @var{string-1}, otherwise to @var{string-2}.  If @var{string-2} is
 omitted, it is taken to be the empty string (according to the normal
 rules).
 
+The macro @code{ifdef} is recognized only with parameters.
address@hidden deffn
+
 @example
 ifdef(`foo', ``foo' is defined', ``foo' is not defined')
 @result{}foo is not defined
@@ -1731,26 +1765,35 @@
 @result{}no
 @end example
 
-The macro @code{ifdef} is recognized only with parameters.
-
 @node Ifelse
 @section Comparing strings
 
 @cindex comparing strings
address@hidden ifelse
 The other conditional, @code{ifelse}, is much more powerful.  It can be
 used as a way to introduce a long comment, as an if-else construct, or
 as a multibranch, depending on the number of arguments supplied:
 
address@hidden ignore
address@hidden
-ifelse(@var{comment})
-ifelse(@var{string-1}, @var{string-2}, @var{equal}, opt @var{not-equal})
-ifelse(@var{string-1}, @var{string-2}, @var{equal}, ...)
address@hidden example
-
address@hidden Builtin ifelse (@var{comment})
address@hidden Builtin ifelse (@var{string-1}, @var{string-2}, @var{equal}, @
+  @ovar{not-equal})
address@hidden Builtin ifelse (@var{string-1}, @var{string-2}, @var{equal-1}, @
+  @var{string-3}, @var{string-4}, @var{equal-2}, @dots{})
 Used with only one argument, the @code{ifelse} simply discards it and
-produces no output.  This is a common @code{m4} idiom for introducing a
+produces no output.
+
+If called with three or four arguments, @code{ifelse} expands into
address@hidden, if @var{string-1} and @var{string-2} are equal (character
+for character), otherwise it expands to @var{not-equal}.
+
+If called with six or more arguments, and @var{string-1} and
address@hidden are equal, @code{ifelse} expands into @var{equal},
+otherwise the first three arguments are discarded and the processing
+starts again.
+
+The macro @code{ifelse} is recognized only with parameters.
address@hidden deffn
+
+Using only one argument is a common @code{m4} idiom for introducing a
 block comment, as an alternative to repeatedly using @code{dnl}.  This
 special usage is recognized by GNU @code{m4}, so that in this case, the
 warning about missing arguments is never triggered.
@@ -1763,9 +1806,7 @@
 @result{}
 @end example
 
-If called with three or four arguments, @code{ifelse} expands into
address@hidden, if @var{string-1} and @var{string-2} are equal (character
-for character), otherwise it expands to @var{not-equal}.
+Using three or four arguments provides decision points.
 
 @example
 ifelse(`foo', `bar', `true')
@@ -1800,7 +1841,7 @@
 However, @code{ifelse} can take more than four arguments.  If given more
 than four arguments, @code{ifelse} works like a @code{case} or @code{switch}
 statement in traditional programming languages.  If @var{string-1} and
address@hidden are equal, @code{ifelse} expands into @var{equal}, otherwise
address@hidden are equal, @code{ifelse} expands into @var{equal-1}, otherwise
 the procedure is repeated with the first three arguments discarded.  This
 calls for an example:
 
@@ -1813,8 +1854,6 @@
 examples.  A common use of @code{ifelse} is in macros implementing loops
 of various kinds.
 
-The macro @code{ifelse} is recognized only with parameters.
-
 @node Loops
 @section Loops and recursion
 
@@ -1828,18 +1867,13 @@
 Loops can be programmed using recursion and the conditionals described
 previously.
 
address@hidden shift
 There is a builtin macro, @code{shift}, which can, among other things,
 be used for iterating through the actual arguments to a macro:
 
address@hidden ignore
address@hidden
-shift(...)
address@hidden example
-
address@hidden
-It takes any number of arguments, and expands to all but the first
address@hidden Builtin shift (@dots{})
+Takes any number of arguments, and expands to all but the first
 argument, separated by commas, with each argument quoted.
address@hidden deffn
 
 @example
 shift
@@ -1850,8 +1884,13 @@
 @result{}bar,baz
 @end example
 
-An example of the use of @code{shift} is this macro, which reverses the
-order of its arguments:
+An example of the use of @code{shift} is this macro:
+
address@hidden Composite reverse (@dots{})
+Takes any number of arguments, and reverse their order.
address@hidden deffn
+
+It is implemented as:
 
 @example
 define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'',
@@ -1871,8 +1910,18 @@
 @cindex for loops
 @cindex loops, counting
 @cindex counting loops
-Here is an example of a loop macro that implements a simple for loop.  It
-can, for example, be used for simple counting:
+Here is an example of a loop macro that implements a simple for loop.
+
address@hidden Composite forloop (@var{iterator}, @var{start}, @var{end}, 
@var{text})
+Takes the name in @var{iterator}, which must be a valid macro name, and
+successively assign it each integer value from @var{start} to @var{end},
+inclusive.  For each assignment to @var{iterator}, append @var{text} to
+the expansion of the @code{forloop}.  @var{text} may refer to
address@hidden  Any definition of @var{iterator} prior to this
+invocation is restored.
address@hidden deffn
+
+It can, for example, be used for simple counting:
 
 @example
 include(`forloop.m4')
@@ -1881,12 +1930,7 @@
 @result{}1 2 3 4 5 6 7 8 @comment
 @end example
 
-The arguments are a name for the iteration variable, the starting value,
-the final value, and the text to be expanded for each iteration.  With
-this macro, the macro @code{i} is defined only within the loop.  After
-the loop, it retains whatever value it might have had before.
-
-For-loops can be nested, like
+For-loops can be nested, like:
 
 @example
 include(`forloop.m4')
@@ -1957,22 +2001,18 @@
 @cindex displaying macro definitions
 @cindex macros, displaying definitions
 @cindex definitions, displaying macro
address@hidden dumpdef
 If you want to see what a name expands into, you can use the builtin
 @code{dumpdef}:
 
address@hidden ignore
address@hidden
-dumpdef(...)
address@hidden example
-
address@hidden
-which accepts any number of arguments.  If called without any arguments,
address@hidden Builtin dumpdef (@dots{})
+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.
+the definitions of the names given.  The output is printed to the
+current debug file (usually standard error), and is sorted by name.  If
+an unknown name is encountered, a warning is printed.
 
 The expansion of @code{dumpdef} is void.
address@hidden deffn
 
 @example
 define(`foo', `Hello world.')
@@ -2010,28 +2050,23 @@
 @cindex tracing macro expansion
 @cindex macro expansion, tracing
 @cindex expansion, tracing macro
address@hidden traceon
address@hidden traceoff
 It is possible to trace macro calls and expansions through the builtins
 @code{traceon} and @code{traceoff}:
 
address@hidden ignore
address@hidden
-traceon(...)
-traceoff(...)
address@hidden example
-
address@hidden
address@hidden Builtin traceon (@dots{})
address@hidden Builtin traceoff (@dots{})
 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.
+When called with arguments, only the named macros are affected, whether
+or not they are currently defined.
 
 The expansion of @code{traceon} and @code{traceoff} is void.
address@hidden deffn
 
 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 (usually standard error).
 
 @example
 define(`foo', `Hello World.')
@@ -2050,7 +2085,9 @@
 
 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}.
 
 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
@@ -2169,15 +2206,10 @@
 flags.
 
 @cindex GNU extensions
address@hidden debugmode
 There is a builtin macro @code{debugmode}, which allows on-the-fly control of
 the debugging output format:
 
address@hidden ignore
address@hidden
-debugmode(opt @var{flags})
address@hidden example
-
address@hidden Builtin 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
@@ -2185,6 +2217,9 @@
 (as if no @option{-d} was given), and with an empty argument the flags
 are reset to the default of @samp{aeq}.
 
+The expansion of @code{debugmode} is void.
address@hidden deffn
+
 @example
 define(`foo', `FOO')
 @result{}
@@ -2214,20 +2249,19 @@
 @cindex debugging output, saving
 @cindex output, saving debugging
 @cindex GNU extensions
address@hidden debugfile
 Debug and tracing output can be redirected to files using either the
 @option{-o} option to @code{m4}, or with the builtin macro @code{debugfile}:
 
address@hidden ignore
address@hidden
-debugfile(opt @var{file})
address@hidden example
-
address@hidden
-will send all further debug and trace output to @var{file}.  If
address@hidden is empty, debug and trace output are discarded and if
address@hidden Builtin debugfile (@ovar{file})
+Sends all further debug and trace output to @var{file}.  If
address@hidden is empty, debug and trace output are discarded.  If
 @code{debugfile} is called without any arguments, debug and trace output
-are sent to the standard error output.
+are sent to standard error.  This does not affect warnings, which are
+always sent to standard error.  If @var{file} cannot be opened, the
+current debug file is unchanged.
+
+The expansion of @code{debugfile} is void.
address@hidden deffn
 
 @example
 traceon(`divnum')
@@ -2266,18 +2300,17 @@
 @section Deleting whitespace in input
 
 @cindex deleting whitespace in input
address@hidden dnl
-The builtin @code{dnl} reads and discards all characters, up to and
-including the first newline:
+The builtin @code{dnl} stands for ``Discard to Next Line'':
 
address@hidden ignore
address@hidden
-dnl
address@hidden example
address@hidden Builtin dnl
+All characters, up to and including the next newline, are discarded
+without performing any macro expansion.
 
address@hidden
-and it is often used in connection with @code{define}, to remove the
-newline that follow the call to @code{define}.  Thus
+The expansion of @code{dnl} is void.
address@hidden deffn
+
+It is often used in connection with @code{define}, to remove the
+newline that follows the call to @code{define}.  Thus
 
 @example
 define(`foo', `Macro `foo'.')dnl A very simple macro, indeed.
@@ -2310,23 +2343,18 @@
 
 @cindex changing the quote delimiters
 @cindex quote delimiters, changing the
address@hidden changequote
 The default quote delimiters can be changed with the builtin
 @code{changequote}:
 
address@hidden ignore
address@hidden
-changequote(opt @var{start}, opt @var{end})
address@hidden example
-
address@hidden
-where @var{start} is the new start-quote delimiter and @var{end} is the
address@hidden Builtin changequote (@dvar{start, `}, @dvar{end, '})
+This sets @var{start} as the new start-quote delimiter and @var{end} as the
 new end-quote delimiter.  If any of the arguments are missing, the default
 quotes (@code{`} and @code{'}) are used instead of the void arguments.
 @comment FIXME POSIX requires that with one argument, the closing quote
 @comment be set to newline, not '.
 
 The expansion of @code{changequote} is void.
address@hidden deffn
 
 @example
 changequote(`[', `]')
@@ -2376,27 +2404,27 @@
 as they will be confused with names in the input.  Doing so disables
 the quoting mechanism.
 
+Changing the quotes to have the same start and end string disables
+nesting of quotes.  This makes it impossible to double-quote strings
+across macro expansions, so it is not done very often.
+
 @node Changecom
 @section Changing comment delimiters
 
 @cindex changing comment delimiters
 @cindex comment delimiters, changing
address@hidden changecom
 The default comment delimiters can be changed with the builtin
 macro @code{changecom}:
 
address@hidden ignore
address@hidden
-changecom(opt @var{start}, opt @var{end})
address@hidden example
-
address@hidden
-where @var{start} is the new start-comment delimiter and @var{end} is
address@hidden Builtin changecom (@ovar{start}, @ovar{end})
+This sets @var{start} as the new start-comment delimiter and @var{end} as
 the new end-comment delimiter.  If only one argument is provided,
 newline becomes the new end-comment delimiter.  The comment delimiters
-can be of any length.
+can be of any length.  Omitting the first argument, or using the empty
+string as the first argument, disables comments.
 
 The expansion of @code{changecom} is void.
address@hidden deffn
 
 @example
 define(`comment', `COMMENT')
@@ -2439,7 +2467,6 @@
 
 @cindex lexical structure of words
 @cindex words, lexical structure of
address@hidden changeword
 @quotation
 The macro @code{changeword} and all associated functionality is
 experimental.  It is only available if the @option{--enable-changeword}
@@ -2459,9 +2486,23 @@
 [_a-zA-Z][_a-zA-Z0-9]*
 @end example
 
-Using @code{changeword}, you can change this regular expression.  Relaxing
address@hidden's lexical rules might be useful (for example) if you wanted to
-apply translations to a file of numbers:
+Using @code{changeword}, you can change this regular expression:
+
address@hidden {Optional builtin} changeword (@var{regex})
+Changes the regular expression for recognizing macro names to be
address@hidden  If @var{regex} is empty, use
address@hidden  @var{regex} must obey the constraint
+that every prefix of the desired final pattern is also accepted by the
+regular expression.  If @var{regex} contains grouping parentheses, the
+macro invoked is the portion that matched the first group, rather than
+the entire matching string.
+
+The expansion of @code{changeword} is void.
+The macro @code{changeword} is recognized only with parameters.
address@hidden deffn
+
+Relaxing the lexical rules of @code{m4} might be useful (for example) if
+you wanted to apply translations to a file of numbers:
 
 @example
 ifdef(`changeword', `', `m4exit(`77')')
@@ -2516,10 +2557,10 @@
 scripts without getting @code{shift} commands swallowed, and plain
 text without losing various common words.
 
address@hidden's macro substitution is based on text, while @TeX{}'s is based
-on tokens.  @code{changeword} can throw this difference into relief.  For
-example, here is the same idea represented in @TeX{} and @code{m4}.
-First, the @TeX{} version:
+In @code{m4}, macro substitution is based on text, while in @TeX{}, it
+is based on tokens.  @code{changeword} can throw this difference into
+relief.  For example, here is the same idea represented in @TeX{} and
address@hidden  First, the @TeX{} version:
 
 @comment ignore
 @example
@@ -2563,15 +2604,11 @@
 with the empty string to restore the default word definition, and regain
 the parsing speed.
 
-The builtin macro @code{changeword} is recognized only when given
-arguments.
-
 @node M4wrap
 @section Saving input
 
 @cindex saving input
 @cindex input, saving
address@hidden m4wrap
 It is possible to `save' some text until the end of the normal input has
 been seen.  Text can be saved, to be read again by @code{m4} when the
 normal input has been exhausted.  This feature is normally used to
@@ -2580,14 +2617,13 @@
 
 To save input text, use the builtin @code{m4wrap}:
 
address@hidden ignore
address@hidden
-m4wrap(@var{string}, ...)
address@hidden example
address@hidden Builtin m4wrap (@ovar{string}, @dots{})
+Stores @var{string} in a safe place, to be reread when end of input is
+reached.  As a GNU extension, additional arguments are concatenated with
+a space to the @var{string}.
 
address@hidden
-which stores @var{string} and the rest of the arguments in a safe place,
-to be reread when end of input is reached.
+The expansion of @code{m4wrap} is void.
address@hidden deffn
 
 @example
 define(`cleanup', `This is the `cleanup' action.
@@ -2645,28 +2681,24 @@
 @node Include
 @section Including named files
 
address@hidden include
address@hidden sinclude
 There are two builtin macros in @code{m4} for including files:
 
address@hidden ignore
address@hidden
-include(@var{file})
-sinclude(@var{file})
address@hidden example
-
address@hidden
-both of which cause the file named @var{file} to be read by
address@hidden Builtin include (@var{file})
address@hidden Builtin sinclude (@var{file})
+Both macros cause the file named @var{file} to be read by
 @code{m4}.  When the end of the file is reached, input is resumed from
 the previous input file.
 
 The expansion of @code{include} and @code{sinclude} is therefore the
 contents of @var{file}.
 
-It is an error for an @code{include}d file not to exist.  If you do
-not want error messages about non-existent files, @code{sinclude} can
-be used to include a file, if it exists, expanding to nothing if it
-does not.  The empty string counts as a file that does not exist.
+If @var{file} does not exist (or cannot be read), the expansion is void,
+and @code{include} will fail with an error while @code{sinclude} is
+silent.  The empty string counts as a file that does not exist.
+
+The macros @code{include} and @code{sinclude} are recognized only with
+parameters.
address@hidden deffn
 
 @example
 include(`none')
@@ -2722,12 +2754,9 @@
 @end example
 
 This use of @code{include} is not trivial, though, as files can contain
-quotes, commas and parentheses, which can interfere with the way the
+quotes, commas, and parentheses, which can interfere with the way the
 @code{m4} parser works.
 
-The builtin macros @code{include} and @code{sinclude} are recognized
-only when given arguments.
-
 @node Search Path
 @section Searching for include files
 
@@ -2782,20 +2811,15 @@
 @cindex diverting output to files
 @cindex output, diverting to files
 @cindex files, diverting output to
address@hidden divert
 Output is diverted using @code{divert}:
 
address@hidden ignore
address@hidden
-divert(opt @var{number})
address@hidden example
-
address@hidden
-where @var{number} is the diversion to be used.  If @var{number} is left
address@hidden Builtin divert (@dvar{number, 0})
+The current diversion is changed to @var{number}.  If @var{number} is left
 out or empty, it is assumed to be zero.  If @var{number} cannot be
 parsed, the diversion is unchanged.
 
 The expansion of @code{divert} is void.
address@hidden deffn
 
 When all the @code{m4} input will have been processed, all existing
 diversions are automatically undiverted, in numerical order.
@@ -2846,21 +2870,17 @@
 @node Undivert
 @section Undiverting output
 
address@hidden undivert
 Diverted text can be undiverted explicitly using the builtin
 @code{undivert}:
 
address@hidden ignore
address@hidden
-undivert(opt @var{number}, ...)
address@hidden example
-
address@hidden
-which undiverts the diversions given by the arguments, in the order
address@hidden Builtin undivert (@address@hidden)
+Undiverts the diversions given by the arguments, in the order
 given.  If no arguments are supplied, all diversions are undiverted, in
-numerical order.
+numerical order.  As a GNU extension, if @var{number} is not numeric,
+treat it as a file name instead.
 
 The expansion of @code{undivert} is void.
address@hidden deffn
 
 @example
 divert(`1')
@@ -2951,20 +2971,18 @@
 @result{}
 @end example
 
+If the file is not found (or cannot be read), an error message is
+issued, and the expansion is void.
+
 @node Divnum
 @section Diversion numbers
 
 @cindex diversion numbers
address@hidden divnum
-The builtin @code{divnum}:
-
address@hidden ignore
address@hidden
-divnum
address@hidden example
+The current diversion is tracked by the builtin @code{divnum}:
 
address@hidden
-expands to the number of the current diversion.
address@hidden Builtin divnum
+Expands to the number of the current diversion.
address@hidden deffn
 
 @example
 Initial divnum
@@ -3007,6 +3025,10 @@
 
 Clearing selected diversions can be done with the following macro:
 
address@hidden Composite cleardivert (@address@hidden)
+Discard the contents of each listed diversion.
address@hidden deffn
+
 @example
 define(`cleardivert',
 `pushdef(`_n', divnum)divert(`-1')undivert($@@)divert(_n)popdef(`_n')')
@@ -3015,7 +3037,7 @@
 
 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.  @pxref{Answers})
 
 @node Text handling
 @chapter Macros for text handling
@@ -3038,16 +3060,13 @@
 
 @cindex length of strings
 @cindex strings, length of
address@hidden len
 The length of a string can be calculated by @code{len}:
 
address@hidden ignore
address@hidden
-len(@var{string})
address@hidden example
address@hidden Builtin len (@var{string})
+Expands to the length of @var{string}, as a decimal number.
 
address@hidden
-which expands to the length of @var{string}, as a decimal number.
+The macro @code{len} is recognized only with parameters.
address@hidden deffn
 
 @example
 len()
@@ -3056,25 +3075,20 @@
 @result{}6
 @end example
 
-The builtin macro @code{len} is recognized only when given arguments.
-
 @node Index macro
 @section Searching for substrings
 
address@hidden index
 Searching for substrings is done with @code{index}:
 
address@hidden ignore
address@hidden
-index(@var{string}, @var{substring})
address@hidden example
-
address@hidden
-which expands to the index of the first occurrence of @var{substring} in
address@hidden Builtin index (@var{string}, @var{substring})
+Expands to the index of the first occurrence of @var{substring} in
 @var{string}.  The first character in @var{string} has index 0.  If
 @var{substring} does not occur in @var{string}, @code{index} expands to
 @samp{-1}.
 
+The macro @code{index} is recognized only with parameters.
address@hidden deffn
+
 @example
 index(`gnus, gnats, and armadillos', `nat')
 @result{}7
@@ -3082,24 +3096,16 @@
 @result{}-1
 @end example
 
-The builtin macro @code{index} is recognized only when given arguments.
-
 @node Regexp
 @section Searching for regular expressions
 
 @cindex regular expressions
 @cindex GNU extensions
address@hidden regexp
 Searching for regular expressions is done with the builtin
 @code{regexp}:
 
address@hidden ignore
address@hidden
-regexp(@var{string}, @var{regexp}, opt @var{replacement})
address@hidden example
-
address@hidden
-which searches for @var{regexp} in @var{string}.  The syntax for regular
address@hidden Builtin regexp (@var{string}, @var{regexp}, @ovar{replacement})
+Searches for @var{regexp} in @var{string}.  The syntax for regular
 expressions is the same as in GNU Emacs.
 @ifnothtml
 @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
@@ -3125,7 +3131,8 @@
 @address@hidden requested, or if there is a trailing @samp{\}.  If there
 was no match, @code{regexp} expands to the empty string.
 
-The builtin macro @code{regexp} is recognized only when given arguments.
+The macro @code{regexp} is recognized only with parameters.
address@hidden deffn
 
 @example
 regexp(`GNUs not Unix', `\<[a-z]\w+')
@@ -3154,20 +3161,18 @@
 
 @cindex extracting substrings
 @cindex substrings, extracting
address@hidden substr
 Substrings are extracted with @code{substr}:
 
address@hidden ignore
address@hidden
-substr(@var{string}, @var{from}, opt @var{length})
address@hidden example
-
address@hidden
-which expands to the substring of @var{string}, which starts at index
address@hidden Builtin substr (@var{string}, @var{from}, @ovar{length})
+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 @var{length} is omitted.  The starting index of a string
 is always 0.  The expansion is empty if there is an error parsing
address@hidden or @var{length}.
address@hidden or @var{length}, if @var{from} is beyond the end of
address@hidden, or if @var{length} is negative.
+
+The macro @code{substr} is recognized only with parameters.
address@hidden deffn
 
 @example
 substr(`gnus, gnats, and armadillos', `6')
@@ -3176,32 +3181,25 @@
 @result{}gnats
 @end example
 
-The builtin macro @code{substr} is recognized only when given arguments.
-
 @node Translit
 @section Translating characters
 
 @cindex translating characters
 @cindex characters, translating
address@hidden translit
 Character translation is done with @code{translit}:
 
address@hidden ignore
address@hidden
-translit(@var{string}, @var{chars}, @var{replacement})
address@hidden example
-
address@hidden
-which expands to @var{string}, with each character that occurs in
address@hidden Builtin translit (@var{string}, @var{chars}, @ovar{replacement})
+Expands to @var{string}, with each character that occurs in
 @var{chars} translated into the character from @var{replacement} with
 the same index.
 
 If @var{replacement} is shorter than @var{chars}, the excess characters
 are deleted from the expansion.  If @var{replacement} is omitted, all
-characters in @var{string}, that are present in @var{chars} are deleted
+characters in @var{string} that are present in @var{chars} are deleted
 from the expansion.
 
-Both @var{chars} and @var{replacement} can contain character-ranges,
+As a GNU extension, both @var{chars} and @var{replacement} can contain
+character-ranges,
 e.g., @samp{a-z} (meaning all lowercase letters) or @samp{0-9} (meaning
 all digits).  To include a dash @samp{-} in @var{chars} or
 @var{replacement}, place it first or last.
@@ -3210,6 +3208,9 @@
 than the first.  In that case, the range runs backwards, i.e.,
 @samp{9-0} means the string @samp{9876543210}.
 
+The macro @code{translit} is recognized only with parameters.
address@hidden deffn
+
 @example
 translit(`GNUs not Unix', `A-Z')
 @result{}s not nix
@@ -3224,9 +3225,6 @@
 while converting them to lowercase.  The two first cases are by far the
 most common.
 
-The builtin macro @code{translit} is recognized only when given
-arguments.
-
 @node Patsubst
 @section Substituting text by regular expression
 
@@ -3234,18 +3232,12 @@
 @cindex pattern substitution
 @cindex substitution by regular expression
 @cindex GNU extensions
address@hidden patsubst
 Global substitution in a string is done by @code{patsubst}:
 
address@hidden ignore
address@hidden
-patsubst(@var{string}, @var{regexp}, opt @var{replacement})
address@hidden example
-
address@hidden
-which searches @var{string} for matches of @var{regexp}, and substitutes
address@hidden Builtin patsubst (@var{string}, @var{regexp}, @ovar{replacement})
+Searches @var{string} for matches of @var{regexp}, and substitutes
 @var{replacement} for each match.  The syntax for regular expressions
-is the same as in GNU Emacs.
+is the same as in GNU Emacs (@pxref{Regexp}).
 
 The parts of @var{string} that are not covered by any match of
 @var{regexp} are copied to the expansion.  Whenever a match is found, the
@@ -3266,8 +3258,8 @@
 The @var{replacement} argument can be omitted, in which case the text
 matched by @var{regexp} is deleted.
 
-The builtin macro @code{patsubst} is recognized only when given
-arguments.
+The macro @code{patsubst} is recognized only with parameters.
address@hidden deffn
 
 @example
 patsubst(`GNUs not Unix', `^', `OBS: ')
@@ -3289,6 +3281,15 @@
 word or whole sentences, by substituting calls of the macros
 @code{upcase} and @code{downcase} into the strings.
 
address@hidden Composite upcase (@var{text})
address@hidden Composite downcase (@var{text})
address@hidden Composite capitalize (@var{text})
+Expand to @var{text}, but with capitalization changed: @code{upcase}
+changes all letters to upper case, @code{downcase} changes all letters
+to lower case, and @code{capitalize} changes the first character of each
+word to upper case and the remaining characters to lower case.
address@hidden deffn
+
 @example
 define(`upcase', `translit(`$*', `a-z', `A-Z')')dnl
 define(`downcase', `translit(`$*', `A-Z', `a-z')')dnl
@@ -3323,18 +3324,16 @@
 @cindex formatted output
 @cindex output, formatted
 @cindex GNU extensions
address@hidden format
 Formatted output can be made with @code{format}:
 
address@hidden ignore
address@hidden
-format(@var{format-string}, ...)
address@hidden example
address@hidden Builtin format (@var{format-string}, @dots{})
+Works much like the C function @code{printf}.  The first argument
address@hidden can contain @samp{%} specifications which are
+satisfied by additional arguments, and the expansion of @code{format} is
+the formatted string.
 
address@hidden
-which works much like the C function @code{printf}.  The first argument
-is a format string, which can contain @samp{%} specifications, and the
-expansion of @code{format} is the formatted string.
+The macro @code{format} is recognized only with parameters.
address@hidden deffn
 
 Its use is best described by a few examples:
 
@@ -3380,9 +3379,8 @@
 
 For now, unrecognized specifiers are silently ignored, but it is
 anticipated that a future release of GNU @code{m4} will support more
-specifiers, and give warnings when problems are encountered.
-
-The macro @code{format} is recognized only with parameters.
+specifiers, and give warnings when problems are encountered.  Likewise,
+escape sequences are not yet recognized.
 
 @node Arithmetic
 @chapter Macros for doing arithmetic
@@ -3403,22 +3401,19 @@
 
 @cindex decrement operator
 @cindex increment operator
address@hidden incr
address@hidden decr
 Increment and decrement of integers are supported using the builtins
 @code{incr} and @code{decr}:
 
address@hidden ignore
address@hidden
-incr(@var{number})
-decr(@var{number})
address@hidden example
-
address@hidden
-which expand to the numerical value of @var{number}, incremented,
address@hidden Builtin incr (@var{number})
address@hidden Builtin decr (@var{number})
+Expand to the numerical value of @var{number}, incremented
 or decremented, respectively, by one.  Except for the empty string, the
 expansion is empty if @var{number} could not be parsed.
 
+The macros @code{incr} and @code{decr} are recognized only with
+parameters.
address@hidden deffn
+
 @example
 incr(`4')
 @result{}5
@@ -3432,26 +3427,21 @@
 @result{}-1
 @end example
 
-The builtin macros @code{incr} and @code{decr} are recognized only when
-given arguments.
-
 @node Eval
 @section Evaluating integer expressions
 
 @cindex integer expression evaluation
 @cindex evaluation, of integer expressions
 @cindex expressions, evaluation of integer
address@hidden eval
 Integer expressions are evaluated with @code{eval}:
 
address@hidden ignore
address@hidden
-eval(@var{expression}, opt @var{radix}, opt @var{width})
address@hidden example
address@hidden Builtin eval (@var{expression}, @dvar{radix, 10}, @ovar{width})
+Expands to the value of @var{expression}.  The expansion is empty
+if an error is encountered while parsing the arguments.  If specified,
address@hidden and @var{width} control the format of the output.
 
address@hidden
-which expands to the value of @var{expression}.  The expansion is empty
-if an error is encountered while parsing the arguments.
+The macro @code{eval} is recognized only with parameters.
address@hidden deffn
 
 Expressions can contain the following operators, listed in order of
 decreasing precedence.
@@ -3537,7 +3527,7 @@
 @result{}111
 @end example
 
-As the second to last example shows, @code{eval} does not handle macro
+As the last two lines show, @code{eval} does not handle macro
 names, even if they expand to a valid expression (or part of a valid
 expression).  Therefore all macros must be expanded before they are
 passed to @code{eval}.
@@ -3590,8 +3580,6 @@
 @result{}a
 @end example
 
-The builtin macro @code{eval} is recognized only when given arguments.
-
 @node Shell commands
 @chapter Running shell commands
 
@@ -3630,18 +3618,18 @@
 macros that are predefined to expand to the empty string; checking for
 their existence will confirm platform details.
 
address@hidden ignore
address@hidden
-__gnu__
-__os2__
-os2
-__unix__
-unix
-__windows__
-windows
address@hidden example
address@hidden {Optional builtin} __gnu__
address@hidden {Optional builtin} __os2__
address@hidden {Optional builtin} os2
address@hidden {Optional builtin} __unix__
address@hidden {Optional builtin} unix
address@hidden {Optional builtin} __windows__
address@hidden {Optional builtin} windows
+Each of these macros is conditionally defined as needed to describe the
+environment of @code{m4}.  If defined, each macro expands to the empty
+string.
address@hidden deffn
 
address@hidden gnu
 When GNU extensions are in effect (that is, when you did not use the
 @option{-G} option), GNU @code{m4} will define the macro @code{__gnu__} to
 expand to the empty string.
@@ -3653,21 +3641,15 @@
 @result{}Extensions are active
 @end example
 
address@hidden unix
 @cindex platform macro
-On UNIX systems, GNU @code{m4} without the @option{-G} option will define
-the macro @code{__unix__}, otherwise the macro @code{unix}.  Both will
-expand to the empty string.
+On UNIX systems, GNU @code{m4} will define @code{__unix__} by default,
+or @code{unix} when the @option{-G} option is specified.
 
address@hidden windows
-On native Windows systems, GNU @code{m4} without the @option{-G} option
-will define the macro @code{__windows__}, otherwise the macro
address@hidden  Both will expand to the empty string.
-
address@hidden os2
-On OS/2 systems, GNU @code{m4} without the @option{-G} option will define
-the macro @code{__os2__}, otherwise the macro @code{os2}.  Both will
-expand to the empty string.
+On native Windows systems, GNU @code{m4} will define @code{__windows__}
+by default, or @code{windows} when the @option{-G} option is specified.
+
+On OS/2 systems, GNU @code{m4} will define @code{__os2__} by default, or
address@hidden when the @option{-G} option is specified.
 
 If GNU @code{m4} does not provide a platform macro for your system,
 please report that as a bug.
@@ -3688,16 +3670,10 @@
 @node Syscmd
 @section Executing simple commands
 
address@hidden syscmd
 Any shell command can be executed, using @code{syscmd}:
 
address@hidden ignore
address@hidden
-syscmd(@var{shell-command})
address@hidden example
-
address@hidden
-which executes @var{shell-command} as a shell command.
address@hidden Builtin syscmd (@var{shell-command})
+Executes @var{shell-command} as a shell command.
 
 The expansion of @code{syscmd} is void, @emph{not} the output from
 @var{shell-command}!  Output or error messages from @var{shell-command}
@@ -3708,6 +3684,9 @@
 The default standard input, output and error of @var{shell-command} are
 the same as those of @code{m4}.
 
+The macro @code{syscmd} is recognized only with parameters.
address@hidden deffn
+
 @example
 define(`foo', `FOO')
 @result{}
@@ -3719,23 +3698,15 @@
 Note how the expansion of @code{syscmd} keeps the trailing newline of
 the command, as well as using the newline that appeared after the macro.
 
-The builtin macro @code{syscmd} is recognized only when given arguments.
-
 @node Esyscmd
 @section Reading the output of commands
 
address@hidden esyscmd
 @cindex GNU extensions
 If you want @code{m4} to read the output of a shell command, use
 @code{esyscmd}:
 
address@hidden ignore
address@hidden
-esyscmd(@var{shell-command})
address@hidden example
-
address@hidden
-which expands to the standard output of the shell command
address@hidden Builtin esyscmd (@var{shell-command})
+Expands to the standard output of the shell command
 @var{shell-command}.
 
 Prior to executing the command, @code{m4} flushes its output buffers.
@@ -3744,6 +3715,9 @@
 is not a part of the expansion: it will appear along with the error
 output of @code{m4}.
 
+The macro @code{esyscmd} is recognized only with parameters.
address@hidden deffn
+
 @example
 define(`foo', `FOO')
 @result{}
@@ -3755,9 +3729,6 @@
 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.
 
-The builtin macro @code{esyscmd} is recognized only when given
-arguments.
-
 @node Sysval
 @section Exit codes
 
@@ -3767,17 +3738,13 @@
 @cindex exit code from shell commands
 @cindex shell commands, exit code from
 @cindex commands, exit code from shell
address@hidden sysval
 To see whether a shell command succeeded, use @code{sysval}:
 
address@hidden ignore
address@hidden
-sysval
address@hidden example
-
address@hidden
-which expands to the exit status of the last shell command run with
address@hidden or @code{esyscmd}.
address@hidden Builtin sysval
+Expands to the exit status of the last shell command run with
address@hidden or @code{esyscmd}.  Expands to 0 if no command has been
+run yet.
address@hidden deffn
 
 @example
 syscmd(`false')
@@ -3835,23 +3802,19 @@
 
 @cindex temporary file names
 @cindex files, names of temporary
address@hidden maketemp
 Commands specified to @code{syscmd} or @code{esyscmd} might need a
 temporary file, for output or for some other purpose.
 There is a builtin macro, @code{maketemp}, for making temporary file
 names:
 
address@hidden ignore
address@hidden
-maketemp(@var{template})
address@hidden example
-
address@hidden
-which expands to a name of a new, empty file, made from the string
address@hidden Builtin maketemp (@var{template})
+Expands to a name of a new, empty file, made from the string
 @var{template}, which should end with the string @samp{XXXXXX}.  The six
address@hidden's are then replaced, usually with something that includes the
-process id of the @code{m4} process, in order to make the file name
-unique.
address@hidden characters are then replaced with random data, in order to make
+the file name unique.
+
+The macro @code{maketemp} is recognized only with parameters.
address@hidden deffn
 
 @comment ignore
 @example
@@ -3882,9 +3845,6 @@
 @end example
 @end ignore
 
-The builtin macro @code{maketemp} is recognized only when given
-arguments.
-
 @node Miscellaneous
 @chapter Miscellaneous builtin macros
 
@@ -3902,19 +3862,14 @@
 @cindex printing error messages
 @cindex error messages, printing
 @cindex messages, printing error
address@hidden errprint
 You can print error messages using @code{errprint}:
 
address@hidden ignore
address@hidden
-errprint(@var{message}, ...)
address@hidden example
-
address@hidden
-which simply prints @var{message} and the rest of the arguments on the
-standard error output.
address@hidden Builtin errprint (@var{message}, @dots{})
+Prints @var{message} and the rest of the arguments on the
+standard error output, separated by spaces.
 
 The expansion of @code{errprint} is void.
address@hidden deffn
 
 @example
 errprint(`Invalid arguments to forloop
@@ -3924,23 +3879,19 @@
 @end example
 
 A trailing newline is @emph{not} printed automatically, so it must be
-supplied as part of the argument, as in the example.  (BSD flavored
address@hidden's do append a trailing newline on each @code{errprint} call).
+supplied as part of the argument, as in the example.  BSD
+implementations of @code{m4} do append a trailing newline on each
address@hidden call, while some other implementations only print the
+first argument.
 
 To make it possible to specify the location of the error, two
 utility builtins exist:
 
address@hidden file
address@hidden line
address@hidden ignore
address@hidden
-__file__
-__line__
address@hidden example
-
address@hidden
-which expands to the quoted name of the current input file, and the
address@hidden Builtin __file__
address@hidden Builtin __line__
+Expand to the quoted name of the current input file, and the
 current input line number in that file.
address@hidden deffn
 
 @example
 errprint(`m4:'__file__:__line__: `input error
@@ -3953,18 +3904,22 @@
 @section Exiting from @code{m4}
 
 @cindex exiting from @code{m4}
address@hidden m4exit
 If you need to exit from @code{m4} before the entire input has been
 read, you can use @code{m4exit}:
 
address@hidden ignore
address@hidden
-m4exit(opt @var{code})
address@hidden example
-
address@hidden
-which causes @code{m4} to exit, with exit code @var{code}.  If
address@hidden is left out, the exit code is zero.
address@hidden Builtin m4exit (@dvar{code, 0})
+Causes @code{m4} to exit, with exit code @var{code}.  If @var{code} is
+left out, the exit code is zero.  No further input is read, and all
+wrapped and diverted text is discarded.
address@hidden deffn
+
+A common use of this is to abort processing:
+
address@hidden Composite fatal_error (@var{message})
+Abort processing with an error message and non-zero status.  Prefix
address@hidden with details about where the error occurred, and print the
+resulting string to standard error.
address@hidden deffn
 
 @example
 define(`fatal_error',
@@ -3996,7 +3951,7 @@
 containing hundreds of definitions and other costly initializations.
 Usually, the common base is kept in one or more declarative files,
 which files are listed on each @code{m4} invocation prior to the
-user's input file, or else, @code{include}'d from this input file.
+user's input file, or else each input file uses @code{include}.
 
 Reading the common base of a big application, over and over again, may
 be time consuming.  GNU @code{m4} offers some machinery to speed up
@@ -4045,15 +4000,15 @@
 
 @noindent
 with the varying input.  The first call, containing the @option{-F}
-option, only reads and executes file @file{base.m4}, so defining
-various application macros and computing other initializations.  Only
-once the input file @file{base.m4} has been completely processed, GNU
+option, only reads and executes file @file{base.m4}, defining
+various application macros and computing other initializations.
+Once the input file @file{base.m4} has been completely processed, GNU
 @code{m4} produces on @file{base.m4f} a @dfn{frozen} file, that is, a
 file which contains a kind of snapshot of the @code{m4} internal state.
 
 Later calls, containing the @option{-R} option, are able to reload
-the internal state of @code{m4}'s memory, from @file{base.m4f},
address@hidden to reading any other input files.  By this mean,
+the internal state of @code{m4}, from @file{base.m4f},
address@hidden to reading any other input files.  This means
 instead of starting with a virgin copy of @code{m4}, input will be
 read after having effectively recovered the effect of a prior run.
 In our example, the effect is the same as if file @file{base.m4} has
@@ -4086,10 +4041,10 @@
 this to work in all cases.  In particular, the trace attribute of
 macros is not handled, nor the current setting of @code{changeword}.
 Currently, @code{m4wrap} and @code{sysval} also have problems.
-Also, interactions for some options of @code{m4} being used in one call
-and not for the next, have not been fully analyzed yet.  On the other
-end, you may be confident that stacks of @code{pushdef}'ed definitions
-are handled correctly, so are @code{undefine}'d or renamed builtins,
+Also, interactions for some options of @code{m4}, being used in one call
+and not in the next, have not been fully analyzed yet.  On the other
+end, you may be confident that stacks of @code{pushdef} definitions
+are handled correctly, as well as undefined or renamed builtins, and
 changed strings for quotes or comments.  And future releases of GNU M4
 will improve on the utility of frozen files.
 
@@ -4109,13 +4064,14 @@
 Frozen files are sharable across architectures.  It is safe to write
 a frozen file on one machine and read it on another, given that the
 second machine uses the same, or a newer version of GNU @code{m4}.
-It is convention, but not required, to give a frozen file the suffix of
address@hidden
+It is conventional, but not required, to give a frozen file the suffix
+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.
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
 are always expressed in decimal.  There are no escape characters.  The
@@ -4133,8 +4089,9 @@
 number for a non-existing diversion.  To merely specify an active
 selection, use this command with an empty @var{str}.  With 0 as the
 diversion @var{number}, @var{str} will be issued on standard output
-at reload time, however @code{m4} will not produce the @samp{D}
-directive with non-zero length for diversion 0.  This directive may
+at reload time.  GNU @code{m4} will not produce the @samp{D}
+directive with non-zero length for diversion 0, but this can be done
+with manual edits.  This directive may
 appear more than once for the same diversion, in which case the
 diversion is the concatenation of the various uses.  If omitted, then
 diversion 0 is current.
@@ -4189,7 +4146,7 @@
 @section Extensions in GNU @code{m4}
 
 @cindex GNU extensions
-This version of @code{m4} contains a few facilities, that do not exist
+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, unless overridden by other
 command line options.
@@ -4352,12 +4309,11 @@
 arguments, giving @code{adefineb} for the above example.
 
 @item
-Traditional implementations treat @code{define(`f',`1')} (@pxref{Define})
-as though it were @code{undefine(`f')pushdef(`f',`1')}, effectively
-replacing the entire stack of previously pushdef'd definitions with a
-single definition.  GNU @code{m4} behaves as
address@hidden(`f')pushdef(`f',`1')}, keeping all previous definitions on
-the stack intact.
+Traditional implementations handle @code{define(`f',`1')} (@pxref{Define})
+by undefining the entire stack of previous definitions, and if doing
address@hidden(`f')} first.  GNU @code{m4} replaces just the top
+definition on the stack, as if doing @code{popdef(`f')} followed by
address@hidden(`f',`1')}.
 
 @item
 @acronym{POSIX} requires @code{syscmd} (@pxref{Syscmd}) to evaluate
@@ -4440,7 +4396,7 @@
 @code{undivert} call, whereas GNU @code{m4} regards the diverted text as
 being generated at the time it is diverted.
 
-I expect the sync line option to be used mostly when using @code{m4} as
+The sync line option is used mostly when using @code{m4} as
 a front end to a compiler.  If a diverted line causes a compiler error,
 the error messages should most probably refer to the place where the
 diversion were made, and not where it was inserted again.
@@ -4541,8 +4497,7 @@
 @appendixsec Macro index
 
 References are exclusively to the places where a builtin is introduced
-the first time.  Names starting and ending with @samp{__} have these
-characters removed in the index.
+the first time.
 
 @iftex
 @sp 1