CVSROOT: /sources/m4
Module name: m4
Changes by: Eric Blake <ericb> 07/01/23 14:28:23
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.93
retrieving revision 1.94
diff -u -b -r1.93 -r1.94
--- doc/m4.texinfo 15 Jan 2007 14:04:26 -0000 1.93
+++ doc/m4.texinfo 23 Jan 2007 14:28:22 -0000 1.94
@@ -1706,12 +1706,13 @@
or more digits, allowing macros to have any number of arguments. This
is not so in UNIX implementations of @code{m4}, which only recognize
one digit.
[EMAIL PROTECTED] FIXME - See Austin group XCU ERN 111. This is controversial,
[EMAIL PROTECTED] and POSIX is moving to reserve ${ for implementation use. We
[EMAIL PROTECTED] should phase out $10 and replace it with ${10}, and consider
[EMAIL PROTECTED] other extensions like ${1-default}. There are existing m4
[EMAIL PROTECTED] scripts that depend on $10 being the first parameter
[EMAIL PROTECTED] concatenated with 0, not the tenth argument.
[EMAIL PROTECTED] FIXME - See Austin group XCU ERN 111. POSIX says that $11
must
[EMAIL PROTECTED] be the first argument concatenated with 1, and instead
reserves
[EMAIL PROTECTED] ${11} for implementation use. Once this is implemented, the
[EMAIL PROTECTED] documentation needs to reflect how these extended arguments
[EMAIL PROTECTED] are handled, as well as backwards compatibility issues with
[EMAIL PROTECTED] 1.4.x. Also, consider adding further extensions such as
[EMAIL PROTECTED] ${1-default}, which expands to `default' if $1 is empty.
As a special case, the zeroth argument, @code{$0}, is always the name
of the macro being expanded.
@@ -4154,6 +4155,15 @@
Characters that can introduce an argument reference in the body of a
macro. The default is the single character @samp{$}.
[EMAIL PROTECTED] Left brace
+Characters that introduce an extended argument reference in the body of
+a macro immediately after a character in the Dollar category. The
+default is the single character @[EMAIL PROTECTED]
+
[EMAIL PROTECTED] Right brace
+Characters that conclude an extended argument reference in the body of a
+macro. The default is the single character @[EMAIL PROTECTED]
+
@item Left quote
The set of characters that can start a single-character quoted string.
The default is the single character @samp{`}. For multiple-character
@@ -4523,11 +4533,54 @@
The saved input is only reread when the end of normal input is seen, and
not if @code{m4exit} is used to exit @code{m4}.
[EMAIL PROTECTED] FIXME: this contradicts POSIX, which requires that "If the
[EMAIL PROTECTED] m4wrap macro is used multiple times, the arguments specified
[EMAIL PROTECTED] shall be processed in the order in which the m4wrap macros
were
[EMAIL PROTECTED] processed."
It is safe to call @code{m4wrap} from saved text, but then the order in
which the saved text is reread is undefined. If @code{m4wrap} is not used
recursively, the saved pieces of text are reread in the opposite order
in which they were saved (LIFO---last in, first out).
+Here is an example of implementing a factorial function using
[EMAIL PROTECTED]:
+
[EMAIL PROTECTED]
+define(`f', `ifelse(`$1', `0', `Answer: 0!=1
+', eval(`$1>1'), `0', `Answer: $2$1=eval(`$2$1')
+', `m4wrap(`f(decr(`$1'), `$2$1*')')')')
[EMAIL PROTECTED]
+f(`10')
[EMAIL PROTECTED]
+^D
[EMAIL PROTECTED]: 10*9*8*7*6*5*4*3*2*1=3628800
[EMAIL PROTECTED] example
+
+Invocations of @code{m4wrap} at the same recursion level are
+concatenated and rescanned as usual:
+
[EMAIL PROTECTED]
+define(`aa', `AA
+')
[EMAIL PROTECTED]
+m4wrap(`a')m4wrap(`a')
[EMAIL PROTECTED]
+^D
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED]
+however, the transition between recursion levels behaves like an end of
+file condition between two input files.
+
[EMAIL PROTECTED] status: 1
[EMAIL PROTECTED]
+m4wrap(`m4wrap(`)')len(abc')
[EMAIL PROTECTED]
+^D
[EMAIL PROTECTED]:stdin:1: end of file in argument list
[EMAIL PROTECTED] example
+
@node File Inclusion
@chapter File inclusion
@@ -6739,7 +6792,11 @@
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. @acronym{GNU} @code{m4} offers some machinery to
+speed up the start of an application using lengthy common bases.
@menu
* Using frozen files:: Using frozen files
@@ -6756,23 +6813,22 @@
@cindex dumping into frozen file
@cindex reloading a frozen file
@cindex @acronym{GNU} extensions
-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
-the start of an application using lengthy common bases. Presume the
-user repeatedly uses:
+Suppose a user has a library of @code{m4} initializations in
[EMAIL PROTECTED], which is then used with multiple input files:
@comment ignore
@example
-m4 base.m4 input.m4
+$ @kbd{m4 base.m4 input1.m4}
+$ @kbd{m4 base.m4 input2.m4}
+$ @kbd{m4 base.m4 input3.m4}
@end example
[EMAIL PROTECTED]
-with a varying contents of @file{input.m4}, but a rather fixed contents
-for @file{base.m4}. Then, the user might rather execute:
+Rather than spending time parsing the fixed contents of @file{base.m4}
+every time, the user might rather execute:
@comment ignore
@example
-m4 -F base.m4f base.m4
+$ @kbd{m4 -F base.m4f base.m4}
@end example
@noindent
@@ -6780,20 +6836,22 @@
@comment ignore
@example
-m4 -R base.m4f input.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
with the varying input. The first call, containing the @code{-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
[EMAIL PROTECTED] produces on @file{base.m4f} a @dfn{frozen} file, that is, a
+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, @acronym{GNU}
[EMAIL PROTECTED] produces in @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 @code{-R} option, are able to reload
-the internal state of @code{m4}'s memory, from @file{base.m4f},
[EMAIL PROTECTED] to reading any other input files. By this mean,
+the internal state of @code{m4}, from @file{base.m4f},
[EMAIL PROTECTED] 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
@@ -6807,7 +6865,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
@@ -6816,20 +6874,13 @@
@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
[EMAIL PROTECTED] example
-
-This could also be done in a simple way, if everything has been prepared
-before:
-
[EMAIL PROTECTED] ignore
[EMAIL PROTECTED]
-m4 -F file1.m4f file1.m4 file2.m4 file3.m4 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
[EMAIL PROTECTED] FIXME - merge the rest of this section.
Some care is necessary because not every effort has been made for
this to work in all cases. In particular, the trace attribute of
macros is not handled.
@@ -6855,6 +6906,13 @@
this text is not removed before a release.
FIXME - split out the two formats into separate nodes.
+When loading format 1, the syntax categories @[EMAIL PROTECTED] and @[EMAIL
PROTECTED] are
+disabled (reverting braces to be treated like plain characters). This
+is because frozen files created with M4 1.4.x did not understand
[EMAIL PROTECTED]@[EMAIL PROTECTED]@}} extended argument notation, and a frozen
macro that
+contained this character sequence should not behave differently just
+because a newer version of M4 reloaded the file.
+
@node Frozen file format 2
@section Frozen file format 2
