doc patch

[Eric Blake]

I liked my use of sample command lines on head, and now that the branch also 
supports command line options in the testsuite, I decided to backport it (and 
add a few tests in the process):

2007-05-25  Eric Blake  <address@hidden>

        Backport prompts in examples from head.
        * src/macro.c (expand_macro): Shorten message.
        * doc/m4.texinfo (Manual, Command line files, Comments)
        (Inhibiting Invocation, Macro Arguments, Macro expansion, Indir)
        (Builtin, Shift, Forloop, Foreach, Dumpdef, Trace, Debug Levels)
        (Debug Output, Include, Format, Syscmd, Mkstemp, Location)
        (Using frozen files, Improved forloop, Improved foreach): Add
        prompts to examples.
        * checks/get-them: Ignore prompts in examples.

Index: checks/get-them
===================================================================
RCS file: /sources/m4/m4/checks/Attic/get-them,v
retrieving revision 1.1.1.1.2.10
diff -u -p -r1.1.1.1.2.10 get-them
--- checks/get-them     25 May 2007 12:58:49 -0000      1.1.1.1.2.10
+++ checks/get-them     25 May 2007 20:26:28 -0000
@@ -77,6 +77,8 @@ BEGIN {
   }
   if ($0 ~ /^\^D$/)
     next;
+  if ($0 ~ /^\$ @kbd/)
+    next;
   if ($0 ~ /address@hidden/ || $0 ~ /address@hidden/)
     prefix = "dnl ";
   else
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.125
diff -u -p -r1.1.1.1.2.125 m4.texinfo
--- doc/m4.texinfo      25 May 2007 17:27:36 -0000      1.1.1.1.2.125
+++ doc/m4.texinfo      25 May 2007 20:26:28 -0000
@@ -437,10 +437,14 @@ This is an example of an example!
 
 To distinguish input from output, all output from @code{m4} is prefixed
 by the string @address@hidden, and all error messages by the string
address@hidden@error{}}.  Thus
address@hidden@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 @@ file.  The sequence @address@hidden refe
 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 @@ string.
 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 @@ As @code{m4} reads its input, it separat
 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 @@ the comment.  The commenting effect of t
 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 @@ implementations simply invoke the builti
 empty argument instead.
 
 @example
+$ @kbd{m4}
 eval
 @result{}eval
 eval(`1')
@@ -1250,6 +1280,19 @@ no effect whatsoever on user defined mac
 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 @@ the @option{--quiet} command line option
 @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 @@ therefore result in more macros being ca
 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 @@ where the definition that was in effect 
 used.
 
 @example
+$ @kbd{m4 -d}
 define(`f', `1')
 @result{}
 f(define(`f', `2'))
@@ -2200,6 +2269,7 @@ token representing a builtin is recogniz
 string.
 
 @example
+$ @kbd{m4 -d}
 indir(defn(`defn'), `divnum')
 @error{}m4:stdin:1: Warning: indir: invalid macro name ignored
 @result{}
@@ -2268,6 +2338,21 @@ even when the @option{--prefix-builtins}
 @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 @@ An actual implementation of these three 
 let's examine their usage:
 
 @example
+$ @kbd{m4 -I examples}
 include(`quote.m4')
 @result{}
 -quote-dquote-dquote_elt-
@@ -2539,6 +2625,7 @@ possible to tell whether it was invoked 
 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 @@ invocation is restored.
 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 @@ forloop(`i', `1', `8', `i ')
 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 @@ Here is an actual implementation of @cod
 @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 @@ using an implementation of @code{foreach
 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 @@ or @var{quote-list} can itself be a list
 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 @@ through the original list.  Here is a si
 @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 @@ during list iteration and the final laye
 rescan:
 
 @example
+$ @kbd{m4 -I examples}
 define(`a', `1')define(`b', `2')define(`c', `3')
 @result{}
 include(`foreach.m4')
@@ -2776,6 +2870,7 @@ foreachq(`x', ```a'', ``(b'', ``c)''', `
 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 @@ The expansion of @code{dumpdef} is void.
 @end deffn
 
 @example
+$ @kbd{m4 -d}
 define(`foo', `Hello world.')
 @result{}
 dumpdef(`foo')
@@ -2854,6 +2950,7 @@ macro were to be called at that point, e
 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 @@ to the current debug file (defaulting to
 Output}).
 
 @example
+$ @kbd{m4 -d}
 define(`foo', `Hello World.')
 @result{}
 define(`echo', `$@@')
@@ -2914,13 +3012,33 @@ The number between dashes is the depth o
 of the time, signifying an expansion at the outermost level, but it
 increases when macro arguments contain unquoted macro calls.  The
 maximum number that will appear between dashes is controlled by the
-option @option{--nesting-limit} (@pxref{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 @@ Tracing even works on builtins.  However
 does not transfer tracing status.
 
 @example
+$ @kbd{m4 -d}
 traceon(`eval', `m4_divnum')
 @result{}
 define(`m4_eval', defn(`eval'))
@@ -3060,7 +3179,9 @@ are reset to the default of @samp{aeq}.
 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 @@ The expansion of @code{debugfile} is voi
 @end deffn
 
 @example
+$ @kbd{m4}
 traceon(`divnum')
 @result{}
 divnum(`extra')
@@ -3913,9 +4035,10 @@ contains the lines:
 
 @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 @@ into the input stream.  The contents of 
 @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 @@ Here is an example, which defines @samp{
 of @file{incl.m4}:
 
 @example
+$ @kbd{m4 -I examples}
 define(`bar', include(`incl.m4'))
 @result{}
 This is `bar':  >>bar<<
@@ -4276,11 +4401,19 @@ divert`'undivert`'dnl
 @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 @@ include(`foo')
 @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 @@ Using the @code{forloop} macro defined e
 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 @@ syscmd(`echo foo')
 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 @@ m4wrap(`syscmd(`cat')')
 @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 @@ chosen:
 
 @comment ignore
 @example
+$ @kbd{m4}
 maketemp(`/tmp/fooXXXXXX')
 @result{}/tmp/fooa07346
 ifdef(`mkstemp', `define(`maketemp', defn(`mkstemp'))',
@@ -5431,6 +5585,7 @@ recommend that you use the new @code{mks
 @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 @@ reflected in the file name.  The synclin
 @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 @@ Suppose a user has a library of @code{m4
 
 @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 @@ every time, the user might rather execut
 
 @comment ignore
 @example
-m4 -F base.m4f base.m4
+$ @kbd{m4 -F base.m4f base.m4}
 @end example
 
 @noindent
@@ -5704,9 +5860,9 @@ once, and further execute, as often as n
 
 @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 @@ some care is taken, the command:
 
 @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 @@ output:
 
 @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 @@ version also optimizes based on the fact
 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 @@ presented earlier each have flaws.  Firs
 quadratic behavior of @code{foreachq}:
 
 @example
+$ @kbd{m4 -I examples}
 include(`foreachq.m4')
 @result{}
 traceon(`shift')debugmode(`aq')
@@ -6347,6 +6505,7 @@ importantly, performs faster.  The fixed
 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 @@ overquotes the arguments to @address@hidden
 front:
 
 @example
+$ @kbd{m4 -I examples}
 include(`foreach2.m4')
 @result{}
 undivert(`foreach2.m4')dnl
@@ -6432,6 +6592,7 @@ repeating the side effects of unquoted l
 detrimental effects.
 
 @example
+$ @kbd{m4 -I examples}
 include(`foreach2.m4')
 @result{}
 include(`foreachq2.m4')
Index: src/macro.c
===================================================================
RCS file: /sources/m4/m4/src/Attic/macro.c,v
retrieving revision 1.1.1.1.2.17
diff -u -p -r1.1.1.1.2.17 macro.c
--- src/macro.c 25 May 2007 17:27:37 -0000      1.1.1.1.2.17
+++ src/macro.c 25 May 2007 20:26:28 -0000
@@ -327,7 +327,7 @@ expand_macro (symbol *sym)
   expansion_level++;
   if (nesting_limit > 0 && expansion_level > nesting_limit)
     M4ERROR ((EXIT_FAILURE, 0,
-             "ERROR: recursion limit of %d exceeded, use -L<N> to change it",
+             "recursion limit of %d exceeded, use -L<N> to change it",
              nesting_limit));
 
   macro_call_id++;