[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: branch-1_4 doc improvements
|
From: |
Eric Blake |
|
Subject: |
Re: branch-1_4 doc improvements |
|
Date: |
Wed, 12 Jul 2006 07:14:02 -0600 |
|
User-agent: |
Thunderbird 1.5.0.4 (Windows/20060516) |
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
According to Eric Blake on 7/11/2006 8:16 AM:
> Eric Blake writes:
>
>> Here's another round of doc improvements.
Next round - sort the 'm4 --help' output, then sort the various tables in
the documentation (and add more details to frozen file format). When I
port to CVS head, I intend to have two nodes for frozen file format - one
each for format version 1 and 2. I also raised the -L option from 250 to
1024, to match autom4te's use.
2006-07-12 Eric Blake <address@hidden>
* src/m4.c (nesting_limit): Raise default from 250 to 1024.
* NEWS: Document raised -L limit.
2006-07-12 Eric Blake <address@hidden>
* src/m4.c (usage): Sort within sections.
* doc/m4.texinfo: Use file name, not filename, per GNU coding
standard. Use @option where appropriate.
(Invoking m4): Sort to match --help output.
(Debug Levels): Sort.
(Frozen files): Sort and break into two nodes.
- --
Life is short - so eat dessert first!
Eric Blake address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.1 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
iD4DBQFEtPWa84KuGfSFAYARAi2oAJ9NZIXLCsF2r3xvXm/THV5KytGzoQCXfSIR
Q5dcGY9AcmyivSjdI6eVnw==
=L1ee
-----END PGP SIGNATURE-----
Index: ChangeLog
===================================================================
RCS file: /sources/m4/m4/ChangeLog,v
retrieving revision 1.1.1.1.2.105
diff -u -p -r1.1.1.1.2.105 ChangeLog
--- ChangeLog 11 Jul 2006 14:17:40 -0000 1.1.1.1.2.105
+++ ChangeLog 12 Jul 2006 13:11:52 -0000
@@ -1,3 +1,7 @@
+2006-07-12 Eric Blake <address@hidden>
+
+ * src/m4.c (nesting_limit): Raise default from 250 to 1024.
+
2006-07-11 Eric Blake <address@hidden>
* Makefile.am (DISTCHECK_CONFIGURE_FLAGS): New macro, to
Index: NEWS
===================================================================
RCS file: /sources/m4/m4/NEWS,v
retrieving revision 1.1.1.1.2.33
diff -u -p -r1.1.1.1.2.33 NEWS
--- NEWS 11 Jul 2006 14:17:40 -0000 1.1.1.1.2.33
+++ NEWS 12 Jul 2006 13:11:52 -0000
@@ -24,7 +24,7 @@ Version 1.4.5 - ?? 2006, by ??? (CVS ve
zeroes on integers printed with %.0f. On systems without these
functions, format is no longer subject to a buffer overflow that
permitted arbitrary code execution.
-* On Windows builds, the macro __windows__ is provided instead of
+* On native Windows builds, the macro __windows__ is provided instead of
__unix__. Likewise, on OS/2 builds, the macro __os2__ is provided. This
allows input files to determine when syscmd might behave differently.
* Fix bug in 1.4.3 patch to use \n line-endings that did not work for
@@ -34,6 +34,8 @@ Version 1.4.5 - ?? 2006, by ??? (CVS ve
to read a directory as a file.
* Many documentation improvements. Also, the manual is now distributed
under FDL 1.2, rather than a stricter verbatim-only license.
+* Raise the -L (--nesting-limit) command line option limit from 250 to
+ 1024.
Version 1.4.4b - 17 June 2006, by Eric Blake (CVS version 1.4.4a)
Index: src/m4.c
===================================================================
RCS file: /sources/m4/m4/src/Attic/m4.c,v
retrieving revision 1.1.1.1.2.14
diff -u -p -r1.1.1.1.2.14 m4.c
--- src/m4.c 10 Jul 2006 01:44:10 -0000 1.1.1.1.2.14
+++ src/m4.c 12 Jul 2006 13:11:53 -0000
@@ -54,7 +54,7 @@ int suppress_warnings = 0;
int warning_status = 0;
/* Artificial limit for expansion_level in macro.c. */
-int nesting_limit = 250;
+int nesting_limit = 1024;
#ifdef ENABLE_CHANGEWORD
/* User provided regexp for describing m4 words. */
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.36
diff -u -p -r1.1.1.1.2.36 m4.texinfo
--- doc/m4.texinfo 11 Jul 2006 14:17:40 -0000 1.1.1.1.2.36
+++ doc/m4.texinfo 12 Jul 2006 13:13:44 -0000
@@ -1,4 +1,4 @@
-\input texinfo @c -*-texinfo-*-
+\input texinfo @c -*- texinfo -*-
@comment ========================================================
@comment %**start of header
@setfilename m4.info
@@ -19,7 +19,7 @@
@ @c
@end macro
address@hidden @ovar(ARG)
address@hidden @ovar{ARG}
@c -------------------
@c The ARG is an optional argument. To be used for macro arguments in
@c their documentation.
@@ -27,7 +27,7 @@
@address@hidden@r{]}
@end macro
address@hidden @dvar(ARG, DEFAULT)
address@hidden @dvar{ARG, DEFAULT}
@c -------------------
@c The ARG is an optional argument, defaulting to DEFAULT. To be used
@c for macro arguments in their documentation.
@@ -115,7 +115,7 @@ if you want this feature compiled in. T
slows down @code{m4} considerably and is hardly acceptable. In the
future, @code{m4} 2.0 will come with a different set of new features
that provide similar capabilities, but without the inefficiencies, so
-changeword will go away and you should not count on it.
+changeword will go away and @emph{you should not count on it}.
@menu
* Preliminaries:: Introduction and preliminaries
@@ -123,7 +123,7 @@ changeword will go away and you should n
* Macros:: How to invoke macros
* Definitions:: How to define new macros
-* Conditionals:: Conditionals and loops
+* Conditionals:: Conditionals, loops, and recursion
* Debugging:: How to debug macros and input
@@ -135,10 +135,10 @@ changeword will go away and you should n
* Arithmetic:: Macros for doing arithmetic
* Shell commands:: Macros for running shell commands
* Miscellaneous:: Miscellaneous builtin macros
-* Frozen files:: Fast loading of frozen states
+* Frozen files:: Fast loading of frozen state
* Compatibility:: Compatibility with other versions of m4
-* Answers:: Answers
+* Answers:: Correct version of some examples
* Copying This Manual:: How to make copies of this manual
* Indices:: Indices of concepts and macros
@@ -149,7 +149,6 @@ Introduction and preliminaries
* Intro:: Introduction to @code{m4}
* History:: Historical references
-
* Invoking m4:: Invoking @code{m4}
* Bugs:: Problems and bugs
* Manual:: Using this manual
@@ -182,7 +181,7 @@ How to define new macros
* Indir:: Indirect call of macros
* Builtin:: Indirect call of builtins
-Conditionals, loops and recursion
+Conditionals, loops, and recursion
* Ifdef:: Testing if a macro is defined
* Ifelse:: If-else construct, or multibranch
@@ -243,6 +242,11 @@ Miscellaneous builtin macros
* Errprint:: Printing error messages
* M4exit:: Exiting from m4
+Fast loading of frozen state
+
+* Using frozen files:: Using frozen files
+* Frozen file format:: Frozen file format
+
Compatibility with other versions of @code{m4}
* Extensions:: Extensions in GNU M4
@@ -264,9 +268,9 @@ Indices
@node Preliminaries
@chapter Introduction and preliminaries
-This first chapter explains what is GNU @code{m4}, where @code{m4}
+This first chapter explains what GNU @code{m4} is, where @code{m4}
comes from, how to read and use this documentation, how to call the
address@hidden program and how to report bugs about it. It concludes by
address@hidden program, and how to report bugs about it. It concludes by
giving tips for reading the remainder of the manual.
The following chapters then detail all the features of the @code{m4}
@@ -294,7 +298,7 @@ macro processor in its own right.
The @code{m4} macro processor is widely available on all UNIXes.
Usually, only a small percentage of users are aware of its existence.
-However, those who do often become committed users. The growing
+However, those who find it often become committed users. The
popularity of GNU Autoconf, which requires GNU @code{m4} for
@emph{generating} the @file{configure} scripts, is an incentive
for many to install it, while these people will not themselves
@@ -302,7 +306,7 @@ program in @code{m4}. GNU @code{m4} is
System V, Release 3 version, except for some minor differences.
@xref{Compatibility}, for more details.
-Some people found @code{m4} to be fairly addictive. They first use
+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.
Once really addicted, users pursue writing of sophisticated @code{m4}
@@ -371,105 +375,129 @@ The format of the @code{m4} command is:
@comment ignore
@example
address@hidden address@hidden@dots{}] address@hidden@dots{}]
address@hidden@dots{}]
address@hidden address@hidden@dots{}] address@hidden@dots{}]
@end example
@cindex command line, options
@cindex options, command line
All options begin with @samp{-}, or if long option names are used, with
-a @samp{--}. A long option name need not be written completely, and
-unambiguous prefix is sufficient. @code{m4} understands the following
-options:
+a @samp{--}. A long option name need not be written completely, any
+unambiguous prefix is sufficient. Options may be intermixed with files,
+use @option{--} as a marker to denote the end of options. @code{m4}
+understands the following options, grouped by functionality.
address@hidden @code
address@hidden --version
-Print the version number of the program on standard output, then
-immediately exit @code{m4} without reading any @var{input-files}.
+Several options control the overall operation of @code{m4}:
address@hidden @code
@item --help
Print a help summary on standard output, then immediately exit
address@hidden without reading any @var{input-files}.
address@hidden without reading any input files.
address@hidden -G
address@hidden --traditional
-Suppress all the extensions made in this implementation, compared to the
-System V version. @xref{Compatibility}, for a list of these.
address@hidden --version
+Print the version number of the program on standard output, then
+immediately exit @code{m4} without reading any input files.
@item -E
@itemx --fatal-warnings
Stop execution and exit @code{m4} once the first warning has been
issued, considering all of them to be fatal.
address@hidden address@hidden
address@hidden address@hidden
-Set the debug-level according to the flags @var{flags}. The debug-level
-controls the format and amount of information presented by the debugging
-functions. @xref{Debug Levels}, for more details on the format and
-meaning of @var{flags}.
-
address@hidden address@hidden
address@hidden address@hidden
-Restrict the size of the output generated by macro tracing. @xref{Debug
-Levels}, for more details.
-
address@hidden address@hidden
address@hidden address@hidden
-Redirect debug and trace output to the named file. Error messages are
-still printed on the standard error output. @xref{Debug Output}, for
-more details.
-
address@hidden address@hidden
address@hidden address@hidden
-Make @code{m4} search @var{dir} for included files that are not found in
-the current working directory. @xref{Search Path}, for more details.
-
@item -e
@itemx --interactive
Makes this invocation of @code{m4} interactive. This means that all
output will be unbuffered, and interrupts will be ignored.
address@hidden -P
address@hidden --prefix-builtins
+Internally modify @emph{all} builtin macro names so they all start with
+the prefix @samp{m4_}. For example, using this option, one should write
address@hidden instead of @samp{define}, and @samp{m4___file__}
+instead of @samp{__file__}. This option has no effect if @option{-R} is
+also specified.
+
address@hidden -Q
address@hidden --quiet
address@hidden --silent
+Suppress warnings about missing or superfluous arguments in macro calls.
+
address@hidden -W @var{REGEXP}
address@hidden 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}).
address@hidden table
+
address@hidden macro definitions, on the command line
address@hidden command line, macro definitions on the
+Several options allow @code{m4} to behave more like a preprocessor.
+Macro definitions and deletions can be made on the command line, the
+search path can be altered, and the output file can track where the
+input came from. These features occur with the following options:
+
address@hidden @code
address@hidden -D @address@hidden
address@hidden address@hidden@var{VALUE}]
+This enters @var{NAME} into the symbol table, before any input files are
+read. If @address@hidden is missing, the value is taken to be the
+empty string. The @var{VALUE} can be any string, and the macro can be
+defined to take arguments, just as if it was defined from within the
+input. This option may be given more than once; order is significant,
+and redefining the same @var{NAME} loses the previous value.
+
address@hidden -I @var{DIR}
address@hidden address@hidden
+Make @code{m4} search @var{DIR} for included files that are not found in
+the current working directory. @xref{Search Path}, for more details.
+This option may be given more than once.
+
@item -s
@itemx --synclines
Generate synchronization lines, for use by the C preprocessor or other
similar tools. This is useful, for example, when @code{m4} is used as a
front end to a compiler. Source file name and line number information
is conveyed by directives of the form @samp{#line @var{linenum}
-"@var{filename}"}, which are inserted as needed into the middle of the
+"@var{file}"}, which are inserted as needed into the middle of the
input. Such directives mean that the following line originated or was
-expanded from the contents of input file @var{filename} at line
address@hidden The @samp{"@var{filename}"} part is often omitted when
+expanded from the contents of input file @var{file} at line
address@hidden The @samp{"@var{file}"} part is often omitted when
the file name did not change from the previous directive.
-Synchronization directives are always given on complete lines per
+Synchronization directives are always given on complete lines by
themselves. When a synchronization discrepancy occurs in the middle of
an output line, the associated synchronization directive is delayed
until the beginning of the next generated line.
address@hidden -P
address@hidden --prefix-builtins
-Internally modify @emph{all} builtin macro names so they all start with
-the prefix @samp{m4_}. For example, using this option, one should write
address@hidden instead of @samp{define}, and @samp{m4___file__}
-instead of @samp{__file__}.
address@hidden -U @var{NAME}
address@hidden address@hidden
+This deletes any predefined meaning @var{NAME} might have. Obviously,
+only predefined macros can be deleted in this way. This option may be
+given more than once; undefining a @var{NAME} that does not have a
+definition is silently ignored.
address@hidden table
address@hidden address@hidden
address@hidden address@hidden
-Use an alternative syntax for macro names. This experimental
-option might not be present on all GNU @code{m4} implementations.
-(@pxref{Changeword}).
-
address@hidden address@hidden
address@hidden address@hidden
-Make the internal hash table for symbol lookup be @var{n} entries big.
-The number should be prime. The default is 509 entries. It should not
-be necessary to increase this value, unless you define an excessive
-number of macros.
-
address@hidden address@hidden
address@hidden address@hidden
-Artificially limit the nesting of macro calls to @var{n} levels,
+There are some limits within @code{m4} that can be tuned. For
+compatibility, @code{m4} also accepts some options that control limits
+in other implementations, but which are automatically unbounded (limited
+only by your hardware constraints) in GNU @code{m4}.
+
address@hidden @code
address@hidden -G
address@hidden --traditional
+Suppress all the extensions made in this implementation, compared to the
+System V version. @xref{Compatibility}, for a list of these.
+
address@hidden -H @var{NUM}
address@hidden address@hidden
+Make the internal hash table for symbol lookup be @var{NUM} entries big.
+For better performance, the number should be prime, but this is not
+checked. The default is 509 entries. It should not be necessary to
+increase this value, unless you define an excessive number of macros.
+
address@hidden -L @var{NUM}
address@hidden address@hidden
+Artificially limit the nesting of macro calls to @var{NUM} levels,
stopping program execution if this limit is ever exceeded. When not
-specified, nesting is limited to 250 levels.
+specified, nesting is limited to 1024 levels.
The precise effect of this option might be more correctly associated
with textual nesting than dynamic recursion. It has been useful
@@ -488,74 +516,83 @@ only the simplest example (but @pxref{Co
system to detect and diagnose endless loops: it is a quite @emph{hard}
problem in general, if not undecidable!
address@hidden -Q
address@hidden --quiet
address@hidden --silent
-Suppress warnings about missing or superfluous arguments in macro calls.
-
address@hidden address@hidden
address@hidden address@hidden
address@hidden address@hidden
address@hidden -B @var{NUM}
address@hidden -S @var{NUM}
address@hidden -T @var{NUM}
These options are present for compatibility with System V @code{m4}, but
do nothing in this implementation.
address@hidden address@hidden
address@hidden address@hidden
address@hidden -N @var{NUM}
address@hidden address@hidden
These options are present only for compatibility with previous
versions of GNU @code{m4}, and were controlling the number of possible
diversions which could be used at the same time. They do nothing,
because there is no fixed limit anymore.
-
@end table
address@hidden macro definitions, on the command line
address@hidden command line, macro definitions on the
-Macro definitions and deletions can be made on the command line, by
-using the @samp{-D} and @samp{-U} options. They have the following
-format:
+GNU @code{m4} comes with a feature of freezing internal state
+(@pxref{Frozen files}). This can be used to speed up @code{m4}
+execution when reusing a common initialization script.
@table @code
address@hidden address@hidden
address@hidden address@hidden@var{value}
address@hidden address@hidden
address@hidden address@hidden@var{value}
-This enters @var{name} into the symbol table, before any input files are
-read. If @address@hidden is missing, the value is taken to be the
-empty string. The @var{value} can be any string, and the macro can be
-defined to take arguments, just as if it was defined from within the
-input.
-
address@hidden address@hidden
address@hidden address@hidden
-This deletes any predefined meaning @var{name} might have. Obviously,
-only predefined macros can be deleted in this way.
-
address@hidden address@hidden
address@hidden address@hidden
-This enters @var{name} into the symbol table, as undefined but traced.
-The macro will consequently be traced from the point it is defined.
-
address@hidden address@hidden
address@hidden --freeze-state @var{file}
address@hidden -F @var{FILE}
address@hidden --freeze-state @var{FILE}
Once execution is finished, write out the frozen state on the specified
address@hidden (@pxref{Frozen files}).
address@hidden It is conventional, but not required, for @var{FILE} to end
+in @samp{.m4f}.
address@hidden address@hidden
address@hidden --reload-state @var{file}
address@hidden -R @var{FILE}
address@hidden --reload-state @var{FILE}
Before execution starts, recover the internal state from the specified
-frozen @var{file} (@pxref{Frozen files}).
+frozen @var{FILE}. The options @option{-D}, @option{-U}, and
address@hidden take effect after state is reloaded, but before the input
+files are read.
address@hidden table
+Finally, there are several options for aiding in debugging @code{m4}
+scripts.
+
address@hidden @code
address@hidden address@hidden
address@hidden address@hidden
+Set the debug-level according to the flags @var{FLAGS}. The debug-level
+controls the format and amount of information presented by the debugging
+functions. @xref{Debug Levels}, for more details on the format and
+meaning of @var{FLAGS}. If omitted, @var{FLAGS} defaults to @samp{aeq}.
+
address@hidden -l @var{NUM}
address@hidden address@hidden
+Restrict the size of the output generated by macro tracing to @var{NUM}
+characters per trace line. @xref{Debug Levels}, for more details.
+
address@hidden -o @var{FILE}
address@hidden address@hidden
+Redirect debug and trace output to the named @var{FILE}. Error messages
+are still printed on the standard error output. @xref{Debug Output},
+for more details.
+
address@hidden -t @var{NAME}
address@hidden 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.
@end table
address@hidden command line, filenames on the
address@hidden filenames, on the command line
address@hidden command line, file names on the
address@hidden file names, on the command line
The remaining arguments on the command line are taken to be input file
names. If no names are present, the standard input is read. A file
-name of @file{-} is taken to mean the standard input.
+name of @file{-} is taken to mean the standard input. It is
+conventional, but not required, for input files to end in @samp{.m4}.
The input files are read in the sequence given. The standard input can
-only be read once, so the filename @file{-} should only appear once on
-the command line.
+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
+argument collection or a quoted string.
+
+If you need to read a file whose name starts with a @file{-}, you can
+specify it as @samp{./-file}, or use @option{--} to mark the end of
+options.
@node Bugs
@section Problems and bugs
@@ -576,7 +613,8 @@ problem was really in the documentation.
Once you've got a precise problem, send e-mail to (Internet)
@email{bug-m4@@gnu.org}. Please include the version number of @code{m4}
you are using. You can get this information with the command @samp{m4
---version}.
+--version}. Also provide details about the platform you are executing
+on.
Non-bug suggestions are always welcome as well. If you have questions
about things that are unclear in the documentation or are just obscure
@@ -606,6 +644,11 @@ Example of input line
@error{}and an error message
@end example
+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 GNU M4 package consists of the examples in this
+document!
+
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
arguments, e.g.,
@@ -616,7 +659,7 @@ regexp(@var{string}, @var{regexp}, opt @
@end example
All macro arguments in @code{m4} are strings, but some are given special
-interpretation, e.g., as numbers, filenames, regular expressions, etc.
+interpretation, e.g., as numbers, file names, regular expressions, etc.
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
@@ -635,7 +678,8 @@ primitive is spelled within @code{m4}.
As @code{m4} reads its input, it separates it into @dfn{tokens}. A
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.
+contain comments. GNU @code{m4} does not yet understand locales; all
+operations are byte-oriented rather than character-oriented.
@menu
* Names:: Macro names
@@ -830,8 +874,8 @@ call is not triggered. This solves the
``This macro is recognized only when given arguments'' refers to this
specific provision.
-There is also a command call option (@code{--prefix-builtins}, or
address@hidden) which requires all builtin macro names to be prefixed
+There is also a command call option (@option{--prefix-builtins}, or
address@hidden) 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}.
@@ -935,7 +979,7 @@ there are too many arguments, the excess
Normally @code{m4} will issue warnings if a builtin macro is called
with an inappropriate number of arguments, but it can be suppressed with
-the @samp{-Q} command line option. For user defined macros, there is no
+the @option{-Q} command line option. For user defined macros, there is no
check of the number of arguments given.
Macros are expanded normally during argument collection, and whatever
@@ -1553,7 +1597,7 @@ another definition that has covered the
The macro @code{builtin} is recognized only with parameters.
@node Conditionals
address@hidden Conditionals, loops and recursion
address@hidden Conditionals, loops, and recursion
Macros, expanding to plain text, perhaps with arguments, are not quite
enough. We would like to have macros expand to different things, based
@@ -1918,7 +1962,7 @@ of the time, signifying an expansion at
increases when macro arguments contain unquoted macro calls.
Tracing by name is an attribute that is preserved whether the macro is
-defined or not. This allows the @samp{-t} option to select macros to
+defined or not. This allows the @option{-t} option to select macros to
trace before those macros are defined.
@example
@@ -1977,61 +2021,61 @@ display.
@cindex controlling debugging output
@cindex debugging output, controlling
-The @samp{-d} option to @code{m4} controls the amount of details
+The @option{-d} option to @code{m4} controls the amount of details
presented, when using the macros described in the preceding sections.
The @var{flags} following the option can be one or more of the
following:
@table @code
address@hidden t
-Trace all macro calls made in this invocation of @code{m4}.
-
@item a
Show the actual arguments in each macro call. This applies to all macro
calls if the @samp{t} flag is used, otherwise only the macros covered by
calls of @code{traceon}.
address@hidden e
-Show the expansion of each macro call, if it is not void. This applies
-to all macro calls if the @samp{t} flag is used, otherwise only the
-macros covered by calls of @code{traceon}.
-
address@hidden q
-Quote actual arguments and macro expansions in the display with the
-current quotes.
-
@item c
Show several trace lines for each macro call. A line is shown when the
macro is seen, but before the arguments are collected; a second line
when the arguments have been collected and a third line after the call
has completed.
address@hidden x
-Add a unique `macro call id' to each line of the trace output. This is
-useful in connection with the @samp{c} flag above.
address@hidden e
+Show the expansion of each macro call, if it is not void. This applies
+to all macro calls if the @samp{t} flag is used, otherwise only the
+macros covered by calls of @code{traceon}.
@item f
Show the name of the current input file in each trace output line.
address@hidden i
+Print a message each time the current input file is changed, giving file
+name and input line number.
+
@item l
Show the current input line number in each trace output line.
@item p
Print a message when a named file is found through the path search
-mechanism (@pxref{Search Path}), giving the actual filename used.
+mechanism (@pxref{Search Path}), giving the actual file name used.
address@hidden i
-Print a message each time the current input file is changed, giving file
-name and input line number.
address@hidden q
+Quote actual arguments and macro expansions in the display with the
+current quotes.
+
address@hidden t
+Trace all macro calls made in this invocation of @code{m4}.
+
address@hidden x
+Add a unique `macro call id' to each line of the trace output. This is
+useful in connection with the @samp{c} flag above.
@item V
A shorthand for all of the above flags.
@end table
-If no flags are specified with the @samp{-d} option, the default is
address@hidden The examples in the previous two sections assumed the
-default flags.
+If no flags are specified with the @option{-d} option, the default is
address@hidden The examples throughout this manual assume the default
+flags.
@cindex GNU extensions
@findex debugmode
@@ -2047,7 +2091,7 @@ The argument @var{flags} should be a sub
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
are removed. If no argument is present, the debugging flags are set to
-zero (as if no @samp{-d} was given), and with an empty argument the flags
+zero (as if no @option{-d} was given), and with an empty argument the flags
are reset to the default.
@node Debug Output
@@ -2059,16 +2103,16 @@ are reset to the default.
@cindex GNU extensions
@findex debugfile
Debug and tracing output can be redirected to files using either the
address@hidden option to @code{m4}, or with the builtin macro @code{debugfile}:
address@hidden option to @code{m4}, or with the builtin macro @code{debugfile}:
@comment ignore
@example
-debugfile(opt @var{filename})
+debugfile(opt @var{file})
@end example
@noindent
-will send all further debug and trace output to @var{filename}. If
address@hidden is empty, debug and trace output are discarded and if
+will send all further debug and trace output to @var{file}. If
address@hidden is empty, debug and trace output are discarded and if
@code{debugfile} is called without any arguments, debug and trace output
are sent to the standard error output.
@@ -2260,7 +2304,7 @@ changecom
@findex changeword
@quotation
The macro @code{changeword} and all associated functionality is
-experimental. It is only available if the @code{--enable-changeword}
+experimental. It is only available if the @option{--enable-changeword}
option was given to @code{configure}, at GNU @code{m4} installation
time. The functionality will go away in the future, to be replaced by
other new features that are more efficient at providing the same
@@ -2464,17 +2508,17 @@ There are two builtin macros in @code{m4
@comment ignore
@example
-include(@var{filename})
-sinclude(@var{filename})
+include(@var{file})
+sinclude(@var{file})
@end example
@noindent
-both of which cause the file named @var{filename} to be read by
+both of which 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{filename}.
+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
@@ -2495,7 +2539,7 @@ sinclude()
@end example
The rest of this section assumes that @code{m4} is invoked with the
address@hidden option pointing to the @file{examples} directory shipped as
address@hidden option pointing to the @file{examples} directory shipped as
part of the GNU @code{m4} package. The file @file{examples/@/incl.m4} in
the distribution contains the lines:
@comment ignore
@@ -2552,9 +2596,9 @@ than the current working directory.
If a file is not found in the current working directory, and the file
name is not absolute, the file will be looked for in a specified search
-path. First, the directories specified with the @samp{-I} option will
+path. First, the directories specified with the @option{-I} option will
be searched, in the order found on the command line. Second, if the
address@hidden environment variable is set, it is expected to contain a
address@hidden environment variable is set, it is expected to contain a
colon-separated list of directories, which will be searched in order.
If the automatic search for include-files causes trouble, the @samp{p}
@@ -3394,7 +3438,7 @@ windows
@findex gnu
When GNU extensions are in effect (that is, when you did not use the
address@hidden option), GNU @code{m4} will define the macro @code{__gnu__} to
address@hidden option), GNU @code{m4} will define the macro @code{__gnu__} to
expand to the empty string.
@example
@@ -3406,17 +3450,17 @@ ifdef(`__gnu__', `Extensions are active'
@findex unix
@cindex platform macro
-On UNIX systems, GNU @code{m4} without the @samp{-G} option will define
+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.
@findex windows
-On native Windows systems, GNU @code{m4} without the @samp{-G} option
+On native Windows systems, GNU @code{m4} without the @option{-G} option
will define the macro @code{__windows__}, otherwise the macro
@code{windows}. Both will expand to the empty string.
@findex os2
-On OS/2 systems, GNU @code{m4} without the @samp{-G} option will define
+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.
@@ -3584,7 +3628,7 @@ sysval
@node Maketemp
@section Making names for temporary files
address@hidden temporary filenames
address@hidden temporary file names
@cindex files, names of temporary
@findex maketemp
Commands specified to @code{syscmd} or @code{esyscmd} might need a
@@ -3601,7 +3645,8 @@ maketemp(@var{template})
which 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
@code{X}'s are then replaced, usually with something that includes the
-process id of the @code{m4} process, in order to make the filename unique.
+process id of the @code{m4} process, in order to make the file name
+unique.
@comment ignore
@example
@@ -3740,14 +3785,8 @@ m4exit
@end example
@node Frozen files
address@hidden Fast loading of frozen states
address@hidden Fast loading of frozen state
address@hidden fast loading of frozen files
address@hidden frozen files for fast loading
address@hidden initialization, frozen states
address@hidden dumping into frozen file
address@hidden reloading a frozen file
address@hidden GNU extensions
Some bigger @code{m4} applications may be built over a common base
containing hundreds of definitions and other costly initializations.
Usually, the common base is kept in one or more declarative files,
@@ -3756,17 +3795,33 @@ user's input file, or else, @code{includ
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:
+the start of an application using lengthy common bases.
+
address@hidden
+* Using frozen files:: Using frozen files
+* Frozen file format:: Frozen file format
address@hidden menu
+
address@hidden Using frozen files
address@hidden Using frozen files
address@hidden fast loading of frozen files
address@hidden frozen files for fast loading
address@hidden initialization, frozen states
address@hidden dumping into frozen file
address@hidden reloading a frozen file
address@hidden GNU extensions
+Suppose a user has a library of @code{m4} initializations in
address@hidden, which is then used with multiple input files:
@comment ignore
@example
-m4 base.m4 input.m4
+m4 base.m4 input1.m4
+m4 base.m4 input2.m4
+m4 base.m4 input3.m4
@end example
address@hidden
-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
@@ -3778,18 +3833,20 @@ once, and further execute, as often as n
@comment ignore
@example
-m4 -R base.m4f input.m4
+m4 -R base.m4f input1.m4
+m4 -R base.m4f input2.m4
+m4 -R base.m4f input3.m4
@end example
@noindent
-with the varying input. The first call, containing the @code{-F}
+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
@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 @code{-R} option, are able to reload
+Later calls, containing the @option{-R} option, are able to reload
the internal state of @code{m4}'s memory, from @file{base.m4f},
@emph{prior} to reading any other input files. By this mean,
instead of starting with a virgin copy of @code{m4}, input will be
@@ -3800,7 +3857,7 @@ been read anew. However, this effect is
Only one frozen file may be created or read in any one @code{m4}
invocation. It is not possible to recover two frozen files at once.
However, frozen files may be updated incrementally, through using
address@hidden and @code{-F} options simultaneously. For example, if
address@hidden and @option{-F} options simultaneously. For example, if
some care is taken, the command:
@comment ignore
@@ -3840,53 +3897,70 @@ A frozen file to be reloaded need not re
It is looked up the same way as an @code{include} file (@pxref{Search
Path}).
address@hidden Frozen file format
address@hidden Frozen file format
address@hidden frozen file format
address@hidden file format, frozen file
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
+
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
@kbd{#} introduces a comment line, empty lines are also ignored.
-In the following descriptions, @var{length}s always refer to
-corresponding @var{string}s. Numbers are always expressed in decimal.
-The directives are:
+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
+directives are:
@table @code
address@hidden V @var{number} @key{NL}
-Confirms the format of the file. @code{m4} @value{VERSION} only creates
-and understands frozen files where @var{number} is 1. This directive
-must be the first non-comment in the file, and may not appear more than
-once.
address@hidden C @var{len1} , @var{len2} @key{NL} @var{str1} @var{str2} @key{NL}
+Uses @var{str1} and @var{str2} as the beginning comment and
+end comment strings. If omitted, then @samp{#} and @key{NL} are the
+comment delimiters.
address@hidden C @var{length1} , @var{length2} @key{NL} @var{string1}
@var{string2} @key{NL}
-Uses @var{string1} and @var{string2} as the beginning comment and
-end comment strings.
-
address@hidden Q @var{length1} , @var{length2} @key{NL} @var{string1}
@var{string2} @key{NL}
-Uses @var{string1} and @var{string2} as the beginning quote and end quote
-strings.
-
address@hidden F @var{length1} , @var{length2} @key{NL} @var{string1}
@var{string2} @key{NL}
-Defines, through @code{pushdef}, a definition for @var{string1}
-expanding to the function whose builtin name is @var{string2}. If the
address@hidden D @var{number}, @var{len} @key{NL} @var{str} @key{NL}
+Selects diversion @var{number}, making it current, then copy
address@hidden in the current diversion. @var{number} may be a negative
+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
+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.
+
address@hidden F @var{len1} , @var{len2} @key{NL} @var{str1} @var{str2} @key{NL}
+Defines, through @code{pushdef}, a definition for @var{str1}
+expanding to the function whose builtin name is @var{str2}. If the
builtin does not exist (for example, if the frozen file was produced by
a copy of @code{m4} compiled with changeword support, but the version
of @code{m4} reloading was compiled without it), the reload is silent,
-but any subsequent use of the definition of @var{string1} will result in
-a warning.
-
address@hidden T @var{length1} , @var{length2} @key{NL} @var{string1}
@var{string2} @key{NL}
-Defines, though @code{pushdef}, a definition for @var{string1}
-expanding to the text given by @var{string2}.
-
address@hidden D @var{number}, @var{length} @key{NL} @var{string} @key{NL}
-Selects diversion @var{number}, making it current, then copy
address@hidden in the current diversion. @var{number} may be a negative
-number for a non-existing diversion. To merely specify an active
-selection, use this command with an empty @var{string}. With 0 as the
-diversion @var{number}, @var{string} will be issued on standard output
-at reload time, however this may not be produced from within @code{m4}.
+but any subsequent use of the definition of @var{str1} will result in
+a warning. This directive may appear more than once for the same name,
+and its order, along with @samp{T}, is important. If omitted, you will
+have no access to any builtins.
+
address@hidden Q @var{len1} , @var{len2} @key{NL} @var{str1} @var{str2} @key{NL}
+Uses @var{str1} and @var{str2} as the beginning quote and end quote
+strings. If omitted, then @samp{`} and @samp{'} are the quote
+delimiters.
+
address@hidden T @var{len1} , @var{len2} @key{NL} @var{str1} @var{str2} @key{NL}
+Defines, though @code{pushdef}, a definition for @var{str1}
+expanding to the text given by @var{str2}. This directive may appear
+more than once for the same name, and its order, along with @samp{F}, is
+important.
address@hidden V @var{number} @key{NL}
+Confirms the format of the file. @code{m4} @value{VERSION} only creates
+and understands frozen files where @var{number} is 1. This directive
+must be the first non-comment in the file, and may not appear more than
+once.
@end table
@node Compatibility
@@ -3912,7 +3986,7 @@ is made to summarize these here.
@cindex GNU extensions
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 @samp{-G} command line option, unless overridden by other
+using the @option{-G} command line option, unless overridden by other
command line options.
@itemize @bullet
@@ -3930,8 +4004,8 @@ diversions, rather than discarding diver
@item
Files included with @code{include} and @code{sinclude} are sought in a
user specified search path, if they are not found in the working
-directory. The search path is specified by the @samp{-I} option and the
address@hidden environment variable (@pxref{Search Path}).
+directory. The search path is specified by the @option{-I} option and the
address@hidden environment variable (@pxref{Search Path}).
@item
Arguments to @code{undivert} can be non-numeric, in which case the named
@@ -3972,9 +4046,9 @@ The destination of trace and debug outpu
@end itemize
In addition to the above extensions, GNU @code{m4} implements the
-following command line options: @samp{-F}, @samp{-G}, @samp{-I},
address@hidden, @samp{-R}, @samp{-V}, @samp{-W}, @samp{-d},
address@hidden, @samp{-o} and @samp{-t}. @xref{Invoking m4}, for a
+following command line options: @option{-F}, @option{-G}, @option{-I},
address@hidden, @option{-R}, @option{-V}, @option{-W}, @option{-d},
address@hidden, @option{-o} and @option{-t}. @xref{Invoking m4}, for a
description of these options.
Also, the debugging and tracing facilities in GNU @code{m4} are much
@@ -4088,7 +4162,7 @@ On the other hand, when GNU @code{m4} en
arguments, it turns tracing on for all existing definitions at the time,
but does not trace future definitions; @code{traceoff} without arguments
turns tracing off for all definitions regardless of whether they were
-also traced by name; and tracing by name, such as with @samp{-tfoo} at
+also traced by name; and tracing by name, such as with @option{-tfoo} at
the command line or @code{traceon(`foo')} in the input, is an attribute
that is preserved even if the macro is currently undefined.
@@ -4125,7 +4199,7 @@ when text is being diverted. GNU @code{
the text is being diverted, and System V @code{m4} when the diverted
text is being brought back.
-The problem is which lines and filenames should be attached to text that
+The problem is which lines and file names should be attached to text that
is being, or has been, diverted. System V @code{m4} regards all the
diverted text as being generated by the source line containing the
@code{undivert} call, whereas GNU @code{m4} regards the diverted text as
@@ -4143,7 +4217,9 @@ like:
@comment ignore
@example
define(`x', `x')
address@hidden
define(`x', `x ')
address@hidden
@end example
There is nothing inherently wrong with defining @samp{x} to
@@ -4165,7 +4241,7 @@ in traditional programming languages.
@end itemize
@node Answers
address@hidden Answers
address@hidden Correct version of some examples
Some of the examples in this manuals are buggy, for demonstration
purposes. Correctly working macros are presented here.
Index: src/m4.c
===================================================================
RCS file: /sources/m4/m4/src/Attic/m4.c,v
retrieving revision 1.1.1.1.2.15
diff -u -p -r1.1.1.1.2.15 m4.c
--- src/m4.c 12 Jul 2006 13:12:40 -0000 1.1.1.1.2.15
+++ src/m4.c 12 Jul 2006 13:13:44 -0000
@@ -152,69 +152,69 @@ for short options too.\n\
Operation modes:\n\
--help display this help and exit\n\
--version output version information and exit\n\
- -e, --interactive unbuffer output, ignore interrupts\n\
-E, --fatal-warnings stop execution after first warning\n\
+ -e, --interactive unbuffer output, ignore interrupts\n\
+ -P, --prefix-builtins force a `m4_' prefix to all builtins\n\
-Q, --quiet, --silent suppress some warnings for builtins\n\
- -P, --prefix-builtins force a `m4_' prefix to all builtins\n",
- stdout);
+", stdout);
#ifdef ENABLE_CHANGEWORD
fputs ("\
- -W, --word-regexp=REGEXP use REGEXP for macro name syntax\n",
- stdout);
+ -W, --word-regexp=REGEXP use REGEXP for macro name syntax\n\
+", stdout);
#endif
fputs ("\
\n\
Preprocessor features:\n\
- -I, --include=DIRECTORY search this directory second for includes\n\
-D, --define=NAME[=VALUE] enter NAME has having VALUE, or empty\n\
+ -I, --include=DIRECTORY append this directory to include path\n\
+ -s, --synclines generate `#line NO \"FILE\"' lines\n\
-U, --undefine=NAME delete builtin NAME\n\
- -s, --synclines generate `#line NO \"FILE\"' lines\n",
- stdout);
+", stdout);
fputs ("\
\n\
Limits control:\n\
-G, --traditional suppress all GNU extensions\n\
- -H, --hashsize=PRIME set symbol lookup hash table size\n\
- -L, --nesting-limit=NUMBER change artificial nesting limit\n",
- stdout);
+ -H, --hashsize=PRIME set symbol lookup hash table size [509]\n\
+ -L, --nesting-limit=NUMBER change artificial nesting limit [1024]\n\
+", stdout);
fputs ("\
\n\
Frozen state files:\n\
-F, --freeze-state=FILE produce a frozen state on FILE at end\n\
- -R, --reload-state=FILE reload a frozen state from FILE at start\n",
- stdout);
+ -R, --reload-state=FILE reload a frozen state from FILE at start\n\
+", stdout);
fputs ("\
\n\
Debugging:\n\
- -d, --debug=[FLAGS] set debug level (no FLAGS implies `aeq')\n\
- -t, --trace=NAME trace NAME when it will be defined\n\
+ -d, --debug[=FLAGS] set debug level (no FLAGS implies `aeq')\n\
-l, --arglength=NUM restrict macro tracing size\n\
- -o, --error-output=FILE redirect debug and trace output\n",
- stdout);
+ -o, --error-output=FILE redirect debug and trace output\n\
+ -t, --trace=NAME trace NAME when it will be defined\n\
+", stdout);
fputs ("\
\n\
FLAGS is any of:\n\
- t trace for all macro calls, not only traceon'ed\n\
a show actual arguments\n\
- e show expansion\n\
- q quote values as necessary, with a or e flag\n\
c show before collect, after collect and after call\n\
- x add a unique macro call id, useful with c flag\n\
+ e show expansion\n\
f say current input file name\n\
+ i show changes in input files\n\
l say current input line number\n\
p show results of path searches\n\
- i show changes in input files\n\
- V shorthand for all of the above flags\n",
- stdout);
+ q quote values as necessary, with a or e flag\n\
+ t trace for all macro calls, not only traceon'ed\n\
+ V shorthand for all of the other flags\n\
+ x add a unique macro call id, useful with c flag\n\
+", stdout);
fputs ("\
\n\
If defined, the environment variable `M4PATH' is a colon-separated list\n\
-of directories included after any specified by `-I'.\n",
- stdout);
+of directories included after any specified by `-I'.\n\
+", stdout);
fputs ("\
\n\
-If no FILE or if FILE is `-', standard input is read.\n",
- stdout);
+If no FILE or if FILE is `-', standard input is read.\n\
+", stdout);
}
exit (status);
}