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>      07/05/25 20:29:18

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.125
retrieving revision 1.1.1.1.2.126
diff -u -b -r1.1.1.1.2.125 -r1.1.1.1.2.126
--- doc/m4.texinfo      25 May 2007 17:27:36 -0000      1.1.1.1.2.125
+++ doc/m4.texinfo      25 May 2007 20:29:17 -0000      1.1.1.1.2.126
@@ -437,10 +437,14 @@
 
 To distinguish input from output, all output from @code{m4} is prefixed
 by the string @address@hidden, and all error messages by the string
address@hidden@error{}}.  Thus
address@hidden@error{}}.  When showing how command line options affect matters,
+the command line is shown with a prompt @samp{$ @kbd{like this}},
+otherwise, you can assume that a simple @kbd{m4} invocation will work.
+Thus:
 
 @comment ignore
 @example
+$ @kbd{command line to invoke m4}
 Example of input line
 @result{}Output line from m4
 @error{}and an error message
@@ -451,7 +455,14 @@
 The majority of these examples are self-contained, and you can run them
 with similar results by invoking @kbd{m4 -d}.  In fact, the testsuite
 that is bundled in the @acronym{GNU} M4 package consists of the examples
-in this document!
+in this document!  Some of the examples assume that your current
+directory is located where you unpacked the installation, so if you plan
+on following along, you may find it helpful to do this now:
+
address@hidden ignore
address@hidden
+$ @kbd{cd address@hidden
address@hidden example
 
 As each of the predefined macros in @code{m4} is described, a prototype
 call of the macro will be shown, giving descriptive names to the
@@ -859,7 +870,24 @@
 The options @option{--define} (@option{-D}), @option{--undefine}
 (@option{-U}), @option{--synclines} (@option{-s}), and @option{--trace}
 (@option{-t}) only take effect after processing input from any file
-names that occur earlier on the command line.
+names that occur earlier on the command line.  For example, assume the
+file @file{foo} contains:
+
address@hidden ignore
address@hidden
+$ @kbd{cat foo}
+bar
address@hidden example
+
+The text @samp{bar} can then be redefined over multiple uses of
address@hidden:
+
address@hidden options: -Dbar=hello foo -Dbar=world foo
address@hidden
+$ @kbd{m4 -Dbar=hello foo -Dbar=world foo}
address@hidden
address@hidden
address@hidden example
 
 If none of the input files invoked @code{m4exit} (@pxref{M4exit}), the
 exit status of @code{m4} will be 0 for success, 1 for general failure
@@ -879,7 +907,7 @@
 token is either a name, a quoted string, or any single character, that
 is not a part of either a name or a string.  Input to @code{m4} can also
 contain comments.  @acronym{GNU} @code{m4} does not yet understand
-locales; all operations are byte-oriented rather than
+multibyte locales; all operations are byte-oriented rather than
 character-oriented (although if your locale uses a single byte
 encoding, such as @sc{ISO-8859-1}, you will not notice a difference).
 However, @code{m4} is eight-bit clean, so you can
@@ -951,6 +979,7 @@
 can be inhibited by quoting it.
 
 @example
+$ @kbd{m4}
 `quoted text' # `commented text'
 @result{}quoted text # `commented text'
 `quoting inhibits' `#' `comments'
@@ -1237,6 +1266,7 @@
 empty argument instead.
 
 @example
+$ @kbd{m4}
 eval
 @result{}eval
 eval(`1')
@@ -1250,6 +1280,19 @@
 one has to write @code{m4_dnl} and even @code{m4_m4exit}.  It also has
 no effect on whether a macro requires parameters.
 
address@hidden options: -P
address@hidden
+$ @kbd{m4 -P}
+eval
address@hidden
+eval(`1')
address@hidden(1)
+m4_eval
address@hidden
+m4_eval(`1')
address@hidden
address@hidden example
+
 Another alternative is to redefine problematic macros to a name less
 likely to cause conflicts, @xref{Definitions}.
 
@@ -1384,6 +1427,29 @@
 @option{-Q}, @pxref{Operation modes, , Invoking m4}).  For user
 defined macros, there is no check of the number of arguments given.
 
address@hidden
+$ @kbd{m4}
+index(`abc')
address@hidden:stdin:1: Warning: too few arguments to builtin `index'
address@hidden
+index(`abc',)
address@hidden
+index(`abc', `b', `ignored')
address@hidden:stdin:3: Warning: excess arguments to builtin `index' ignored
address@hidden
address@hidden example
+
address@hidden options: -Q
address@hidden
+$ @kbd{m4 -Q}
+index(`abc')
address@hidden
+index(`abc',)
address@hidden
+index(`abc', `b', `ignored')
address@hidden
address@hidden example
+
 Macros are expanded normally during argument collection, and whatever
 commas, quotes and parentheses that might show up in the resulting
 expanded text will serve to define the arguments as well.  Thus, if
@@ -1500,16 +1566,18 @@
 completely or partially, in the first macro calls' expansion.
 
 Taking a very simple example, if @var{foo} expands to @samp{bar}, and
address@hidden expands to @samp{Hello world}, the input
address@hidden expands to @samp{Hello}, the input
 
address@hidden ignore
address@hidden options: -Dbar=Hello -Dfoo=bar
 @example
+$ @kbd{m4 -Dbar=Hello -Dfoo=bar}
 foo
address@hidden
 @end example
 
 @noindent
 will expand first to @samp{bar}, and when this is reread and
-expanded, into @samp{Hello world}.
+expanded, into @samp{Hello}.
 
 @node Definitions
 @chapter How to define new macros
@@ -2183,6 +2251,7 @@
 used.
 
 @example
+$ @kbd{m4 -d}
 define(`f', `1')
 @result{}
 f(define(`f', `2'))
@@ -2200,6 +2269,7 @@
 string.
 
 @example
+$ @kbd{m4 -d}
 indir(defn(`defn'), `divnum')
 @error{}m4:stdin:1: Warning: indir: invalid macro name ignored
 @result{}
@@ -2268,6 +2338,21 @@
 @pxref{Operation modes, , Invoking m4}) is in effect.  This is different
 from @code{indir}, which only tracks current macro names.
 
address@hidden options: -P
address@hidden
+$ @kbd{m4 -P}
+m4_builtin(`divnum')
address@hidden
+m4_builtin(`m4_divnum')
address@hidden:stdin:2: undefined builtin `m4_divnum'
address@hidden
+m4_indir(`divnum')
address@hidden:stdin:3: undefined macro `divnum'
address@hidden
+m4_indir(`m4_divnum')
address@hidden
address@hidden example
+
 Note that @code{indir} and @code{builtin} can be used to invoke builtins
 without arguments, even when they normally require parameters to be
 recognized; but it will provoke a warning, and result in a void expansion.
@@ -2508,6 +2593,7 @@
 let's examine their usage:
 
 @example
+$ @kbd{m4 -I examples}
 include(`quote.m4')
 @result{}
 -quote-dquote-dquote_elt-
@@ -2539,6 +2625,7 @@
 resulting string.
 
 @example
+$ @kbd{m4 -I examples}
 undivert(`quote.m4')dnl
 @result{}divert(`-1')
 @result{}# quote(args) - convert args to single-quoted string
@@ -2599,6 +2686,7 @@
 It can, for example, be used for simple counting:
 
 @example
+$ @kbd{m4 -I examples}
 include(`forloop.m4')
 @result{}
 forloop(`i', `1', `8', `i ')
@@ -2608,6 +2696,7 @@
 For-loops can be nested, like:
 
 @example
+$ @kbd{m4 -I examples}
 include(`forloop.m4')
 @result{}
 forloop(`i', `1', `4', `forloop(`j', `1', `8', ` (i, j)')
@@ -2634,6 +2723,7 @@
 @address@hidden/@/examples/@/forloop.m4} in this package:
 
 @example
+$ @kbd{m4 -I examples}
 undivert(`forloop.m4')dnl
 @result{}divert(`-1')
 @result{}# forloop(var, from, to, stmt) - simple version
@@ -2679,6 +2769,7 @@
 in @address@hidden/@/examples/@/foreachq.m4}.
 
 @example
+$ @kbd{m4 -I examples}
 include(`foreach.m4')
 @result{}
 foreach(`x', (foo, bar, foobar), `Word was: x
@@ -2700,6 +2791,7 @@
 to a helper macro.  This example generates a shell case statement:
 
 @example
+$ @kbd{m4 -I examples}
 include(`foreach.m4')
 @result{}
 define(`_case', `  $1)
@@ -2728,6 +2820,7 @@
 @code{foreach}:
 
 @example
+$ @kbd{m4 -I examples}
 undivert(`foreach.m4')dnl
 @result{}divert(`-1')
 @result{}# foreach(x, (item_1, item_2, ..., item_n), stmt)
@@ -2753,6 +2846,7 @@
 rescan:
 
 @example
+$ @kbd{m4 -I examples}
 define(`a', `1')define(`b', `2')define(`c', `3')
 @result{}
 include(`foreach.m4')
@@ -2776,6 +2870,7 @@
 Obviously, @code{foreachq} did a better job; here is its implementation:
 
 @example
+$ @kbd{m4 -I examples}
 undivert(`foreachq.m4')dnl
 @result{}include(`quote.m4')dnl
 @result{}divert(`-1')
@@ -2838,6 +2933,7 @@
 @end deffn
 
 @example
+$ @kbd{m4 -d}
 define(`foo', `Hello world.')
 @result{}
 dumpdef(`foo')
@@ -2854,6 +2950,7 @@
 still live due to redefining a macro during argument collection.
 
 @example
+$ @kbd{m4 -d}
 pushdef(`f', ``$0'1')pushdef(`f', ``$0'2')
 @result{}
 f(popdef(`f')dumpdef(`f'))
@@ -2896,6 +2993,7 @@
 Output}).
 
 @example
+$ @kbd{m4 -d}
 define(`foo', `Hello World.')
 @result{}
 define(`echo', `$@@')
@@ -2914,13 +3012,33 @@
 of the time, signifying an expansion at the outermost level, but it
 increases when macro arguments contain unquoted macro calls.  The
 maximum number that will appear between dashes is controlled by the
-option @option{--nesting-limit} (@pxref{Limits control, , Invoking m4}).
+option @option{--nesting-limit} (or @option{-L}, @pxref{Limits control,
+, Invoking m4}).  Additionally, the option @option{--trace} (or
address@hidden) can be used to invoke @code{traceon(@var{name})} before
+parsing input.
+
address@hidden options: -dp -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 @option{-t} option to select macros to
-trace before those macros are defined.
+defined or not.  This allows the selection of macros to trace before
+those macros are defined.
 
 @example
+$ @kbd{m4 -d}
 traceoff(`foo')
 @result{}
 traceon(`foo')
@@ -2954,6 +3072,7 @@
 does not transfer tracing status.
 
 @example
+$ @kbd{m4 -d}
 traceon(`eval', `m4_divnum')
 @result{}
 define(`m4_eval', defn(`eval'))
@@ -3060,7 +3179,9 @@
 The expansion of @code{debugmode} is void.
 @end deffn
 
address@hidden options: -dp
 @example
+$ @kbd{m4}
 define(`foo', `FOO')
 @result{}
 traceon(`foo')
@@ -3106,6 +3227,7 @@
 @end deffn
 
 @example
+$ @kbd{m4}
 traceon(`divnum')
 @result{}
 divnum(`extra')
@@ -3913,9 +4035,10 @@
 
 @comment ignore
 @example
-Include file start
-foo
-Include file end
+$ @kbd{cat examples/incl.m4}
address@hidden file start
address@hidden
address@hidden file end
 @end example
 
 Normally file inclusion is used to insert the contents of a file
@@ -3923,6 +4046,7 @@
 @code{m4} and macro calls in the file will be expanded:
 
 @example
+$ @kbd{m4 -I examples}
 define(`foo', `FOO')
 @result{}
 include(`incl.m4')
@@ -3938,6 +4062,7 @@
 of @file{incl.m4}:
 
 @example
+$ @kbd{m4 -I examples}
 define(`bar', include(`incl.m4'))
 @result{}
 This is `bar':  >>bar<<
@@ -4276,11 +4401,19 @@
 @cindex file inclusion
 @cindex inclusion, of files
 @acronym{GNU} @code{m4} allows named files to be undiverted.  Given a
-non-numeric
-argument, the contents of the file named will be copied, uninterpreted, to
-the current output.  This complements the builtin @code{include}
-(@pxref{Include}).  To illustrate the difference, the file
address@hidden@value{VERSION}/@/examples/@/foo} contains the word @samp{bar}:
+non-numeric argument, the contents of the file named will be copied,
+uninterpreted, to the current output.  This complements the builtin
address@hidden (@pxref{Include}).  To illustrate the difference, assume
+the file @file{foo} contains:
+
address@hidden ignore
address@hidden
+$ @kbd{cat foo}
+bar
address@hidden example
+
address@hidden
+then
 
 @example
 define(`bar', `BAR')
@@ -4294,7 +4427,20 @@
 @end example
 
 If the file is not found (or cannot be read), an error message is
-issued, and the expansion is void.
+issued, and the expansion is void.  It is possible to intermix files
+and diversion numbers.
+
address@hidden
+divert(`1')diversion one
+divert(`2')undivert(`foo')dnl
+divert(`3')diversion three
+divert`'dnl
+undivert(`1', `2', `foo', `3')dnl
address@hidden one
address@hidden
address@hidden
address@hidden three
address@hidden example
 
 @node Divnum
 @section Diversion numbers
@@ -4756,6 +4902,7 @@
 example shows how @code{format} can be used to produce tabular output.
 
 @example
+$ @kbd{m4 -I examples}
 include(`forloop.m4')
 @result{}
 forloop(`i', `1', `10', `format(`%6d squared is %10d
@@ -5214,20 +5361,14 @@
 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.
 
-As an example of @var{shell-command} using the same standard input as
address@hidden, the command line @kbd{echo "m4wrap(\`syscmd(\`cat')')" | m4}
-will tell @code{m4} to read all of its input before executing the
-wrapped text, then hand a valid (albeit emptied) pipe as standard input
-for the @code{cat} subcommand.  Therefore, you should be careful when
-using standard input (either by specifying no files, or by passing
address@hidden as a file name on the command line, @pxref{Command line files,
-, Invoking m4}), and
-also invoking subcommands via @code{syscmd} or @code{esyscmd} that
-consume data from standard input.  When standard input is a seekable
-file, the subprocess will pick up with the next character not yet
-processed by @code{m4}; when it is a pipe or other non-seekable file,
-there is no guarantee how much data will already be buffered by
address@hidden and thus unavailable to the child.
+The following is an example of @var{shell-command} using the same
+standard input as @code{m4}:
+
address@hidden ignore
address@hidden
+$ @kbd{echo "m4wrap(\`syscmd(\`cat')')" | m4}
address@hidden
address@hidden example
 
 @ignore
 @comment If the user types the example below with stdin being an
@@ -5245,6 +5386,18 @@
 @end example
 @end ignore
 
+It tells @code{m4} to read all of its input before executing the wrapped
+text, then hand a valid (albeit emptied) pipe as standard input for the
address@hidden subcommand.  Therefore, you should be careful when using
+standard input (either by specifying no files, or by passing @samp{-} as
+a file name on the command line, @pxref{Command line files, , Invoking
+m4}), and also invoking subcommands via @code{syscmd} or @code{esyscmd}
+that consume data from standard input.  When standard input is a
+seekable file, the subprocess will pick up with the next character not
+yet processed by @code{m4}; when it is a pipe or other non-seekable
+file, there is no guarantee how much data will already be buffered by
address@hidden and thus unavailable to the child.
+
 @node Esyscmd
 @section Reading the output of commands
 
@@ -5411,6 +5564,7 @@
 
 @comment ignore
 @example
+$ @kbd{m4}
 maketemp(`/tmp/fooXXXXXX')
 @result{}/tmp/fooa07346
 ifdef(`mkstemp', `define(`maketemp', defn(`mkstemp'))',
@@ -5431,6 +5585,7 @@
 @acronym{GNU} M4 1.4.8, which is secure even in traditional mode.
 
 @example
+$ @kbd{m4}
 syscmd(`echo foo??????')dnl
 @result{}foo??????
 define(`file1', maketemp(`fooXXXXXX'))dnl
@@ -5531,13 +5686,14 @@
 @pxref{Preprocessor features, , Invoking m4}), and the
 @samp{f} and @samp{l} flags of @code{debugmode} (@pxref{Debug Levels}),
 also use this notion of current file and line.  Redefining the three
-location macros has no effect on syncline, debug, or warning message
-output.  Assume this example is run in the
address@hidden@value{VERSION}/@/checks} directory of the @acronym{GNU} M4
-package, using @samp{--include=../examples} in the command line to find
-the file @file{incl.m4} mentioned earlier:
+location macros has no effect on syncline, debug, warning, or error
+message output.
+
+This example reuses the file @file{incl.m4} mentioned earlier
+(@pxref{Include}):
 
 @example
+$ @kbd{m4 -I examples}
 define(`foo', ``$0' called at __file__:__line__')
 @result{}
 foo
@@ -5686,9 +5842,9 @@
 
 @comment ignore
 @example
-m4 base.m4 input1.m4
-m4 base.m4 input2.m4
-m4 base.m4 input3.m4
+$ @kbd{m4 base.m4 input1.m4}
+$ @kbd{m4 base.m4 input2.m4}
+$ @kbd{m4 base.m4 input3.m4}
 @end example
 
 Rather than spending time parsing the fixed contents of @file{base.m4}
@@ -5696,7 +5852,7 @@
 
 @comment ignore
 @example
-m4 -F base.m4f base.m4
+$ @kbd{m4 -F base.m4f base.m4}
 @end example
 
 @noindent
@@ -5704,9 +5860,9 @@
 
 @comment ignore
 @example
-m4 -R base.m4f input1.m4
-m4 -R base.m4f input2.m4
-m4 -R base.m4f input3.m4
+$ @kbd{m4 -R base.m4f input1.m4}
+$ @kbd{m4 -R base.m4f input2.m4}
+$ @kbd{m4 -R base.m4f input3.m4}
 @end example
 
 @noindent
@@ -5733,7 +5889,7 @@
 
 @comment ignore
 @example
-m4 file1.m4 file2.m4 file3.m4 file4.m4
+$ @kbd{m4 file1.m4 file2.m4 file3.m4 file4.m4}
 @end example
 
 @noindent
@@ -5742,10 +5898,10 @@
 
 @comment ignore
 @example
-m4 -F file1.m4f file1.m4
-m4 -R file1.m4f -F file2.m4f file2.m4
-m4 -R file2.m4f -F file3.m4f file3.m4
-m4 -R file3.m4f file4.m4
+$ @kbd{m4 -F file1.m4f file1.m4}
+$ @kbd{m4 -R file1.m4f -F file2.m4f file2.m4}
+$ @kbd{m4 -R file2.m4f -F file3.m4f file3.m4}
+$ @kbd{m4 -R file3.m4f file4.m4}
 @end example
 
 Some care is necessary because not every effort has been made for
@@ -6268,6 +6424,7 @@
 not need to be passed to the helper @address@hidden
 
 @example
+$ @kbd{m4 -I examples}
 undivert(`forloop2.m4')dnl
 @result{}divert(`-1')
 @result{}# forloop(var, from, to, stmt) - improved version:
@@ -6307,6 +6464,7 @@
 quadratic behavior of @code{foreachq}:
 
 @example
+$ @kbd{m4 -I examples}
 include(`foreachq.m4')
 @result{}
 traceon(`shift')debugmode(`aq')
@@ -6347,6 +6505,7 @@
 be found in @address@hidden/@/examples/@/foreachq2.m4}:
 
 @example
+$ @kbd{m4 -I examples}
 include(`foreachq2.m4')
 @result{}
 undivert(`foreachq2.m4')dnl
@@ -6388,6 +6547,7 @@
 front:
 
 @example
+$ @kbd{m4 -I examples}
 include(`foreach2.m4')
 @result{}
 undivert(`foreach2.m4')dnl
@@ -6432,6 +6592,7 @@
 detrimental effects.
 
 @example
+$ @kbd{m4 -I examples}
 include(`foreach2.m4')
 @result{}
 include(`foreachq2.m4')