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 @[EMAIL PROTECTED], and all error messages by the string
[EMAIL PROTECTED]@error{}}. Thus
[EMAIL PROTECTED]@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:
+
[EMAIL PROTECTED] ignore
[EMAIL PROTECTED]
+$ @kbd{cd [EMAIL PROTECTED]
[EMAIL PROTECTED] 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:
+
[EMAIL PROTECTED] ignore
[EMAIL PROTECTED]
+$ @kbd{cat foo}
+bar
[EMAIL PROTECTED] example
+
+The text @samp{bar} can then be redefined over multiple uses of
[EMAIL PROTECTED]:
+
[EMAIL PROTECTED] options: -Dbar=hello foo -Dbar=world foo
[EMAIL PROTECTED]
+$ @kbd{m4 -Dbar=hello foo -Dbar=world foo}
[EMAIL PROTECTED]
[EMAIL PROTECTED]
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] options: -P
[EMAIL PROTECTED]
+$ @kbd{m4 -P}
+eval
[EMAIL PROTECTED]
+eval(`1')
[EMAIL PROTECTED](1)
+m4_eval
[EMAIL PROTECTED]
+m4_eval(`1')
[EMAIL PROTECTED]
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED]
+$ @kbd{m4}
+index(`abc')
[EMAIL PROTECTED]:stdin:1: Warning: too few arguments to builtin `index'
[EMAIL PROTECTED]
+index(`abc',)
[EMAIL PROTECTED]
+index(`abc', `b', `ignored')
[EMAIL PROTECTED]:stdin:3: Warning: excess arguments to builtin `index' ignored
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED] options: -Q
[EMAIL PROTECTED]
+$ @kbd{m4 -Q}
+index(`abc')
[EMAIL PROTECTED]
+index(`abc',)
[EMAIL PROTECTED]
+index(`abc', `b', `ignored')
[EMAIL PROTECTED]
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] expands to @samp{Hello world}, the input
[EMAIL PROTECTED] expands to @samp{Hello}, the input
[EMAIL PROTECTED] ignore
[EMAIL PROTECTED] options: -Dbar=Hello -Dfoo=bar
@example
+$ @kbd{m4 -Dbar=Hello -Dfoo=bar}
foo
[EMAIL PROTECTED]
@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.
[EMAIL PROTECTED] options: -P
[EMAIL PROTECTED]
+$ @kbd{m4 -P}
+m4_builtin(`divnum')
[EMAIL PROTECTED]
+m4_builtin(`m4_divnum')
[EMAIL PROTECTED]:stdin:2: undefined builtin `m4_divnum'
[EMAIL PROTECTED]
+m4_indir(`divnum')
[EMAIL PROTECTED]:stdin:3: undefined macro `divnum'
[EMAIL PROTECTED]
+m4_indir(`m4_divnum')
[EMAIL PROTECTED]
[EMAIL PROTECTED] 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 @@
@[EMAIL PROTECTED]/@/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 @[EMAIL PROTECTED]/@/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
[EMAIL PROTECTED]) can be used to invoke @code{traceon(@var{name})} before
+parsing input.
+
[EMAIL PROTECTED] options: -dp -L3 -tifelse
[EMAIL PROTECTED] status: 1
[EMAIL PROTECTED]
+$ @kbd{m4 -L 3 -t ifelse}
+ifelse(`one level')
[EMAIL PROTECTED]: -1- ifelse
[EMAIL PROTECTED]
+ifelse(ifelse(ifelse(`three levels')))
[EMAIL PROTECTED]: -3- ifelse
[EMAIL PROTECTED]: -2- ifelse
[EMAIL PROTECTED]: -1- ifelse
[EMAIL PROTECTED]
+ifelse(ifelse(ifelse(ifelse(`four levels'))))
[EMAIL PROTECTED]:stdin:3: recursion limit of 3 exceeded, use -L<N> to change it
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] 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}
[EMAIL PROTECTED] file start
[EMAIL PROTECTED]
[EMAIL PROTECTED] 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
[EMAIL PROTECTED]@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
[EMAIL PROTECTED] (@pxref{Include}). To illustrate the difference, assume
+the file @file{foo} contains:
+
[EMAIL PROTECTED] ignore
[EMAIL PROTECTED]
+$ @kbd{cat foo}
+bar
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED]
+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.
+
[EMAIL PROTECTED]
+divert(`1')diversion one
+divert(`2')undivert(`foo')dnl
+divert(`3')diversion three
+divert`'dnl
+undivert(`1', `2', `foo', `3')dnl
[EMAIL PROTECTED] one
[EMAIL PROTECTED]
[EMAIL PROTECTED]
[EMAIL PROTECTED] three
[EMAIL PROTECTED] 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
[EMAIL PROTECTED], 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
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] and thus unavailable to the child.
+The following is an example of @var{shell-command} using the same
+standard input as @code{m4}:
+
[EMAIL PROTECTED] ignore
[EMAIL PROTECTED]
+$ @kbd{echo "m4wrap(\`syscmd(\`cat')')" | m4}
[EMAIL PROTECTED]
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] 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
[EMAIL PROTECTED]@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 @[EMAIL PROTECTED]
@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 @[EMAIL PROTECTED]/@/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')
