CVSROOT: /sources/m4
Module name: m4
Changes by: Eric Blake <ericb> 06/11/14 05:58:01
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.78
retrieving revision 1.79
diff -u -b -r1.78 -r1.79
--- doc/m4.texinfo 11 Nov 2006 14:00:28 -0000 1.78
+++ doc/m4.texinfo 14 Nov 2006 05:58:01 -0000 1.79
@@ -607,8 +607,8 @@
@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.
+Stop execution and exit @code{m4} once the first warning or error has
+been issued, considering all of them to be fatal.
@item -i
@itemx --interactive
@@ -639,15 +639,17 @@
calls, or treating the empty string as zero. Error messages are still
printed. The distinction between error and warning is fuzzy, and if
you encounter a situation where the message output did not match your
-expectations, please report that as a bug.
+expectations, please report that as a bug. This option is implied if
[EMAIL PROTECTED] is set in the environment.
[EMAIL PROTECTED] -r @var{RESYNTAX-SPEC}
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] [EMAIL PROTECTED]@[EMAIL PROTECTED]
[EMAIL PROTECTED] [EMAIL PROTECTED]@[EMAIL PROTECTED]
Set the regular expression syntax according to @var{RESYNTAX-SPEC}.
-When this option is not given, @acronym{GNU} M4 uses emacs compatible
-regular expressions. @xref{Changeresyntax}, for more details on the
-format and meaning of @var{RESYNTAX-SPEC}. This option may be given
-more than once, and order with respect to file names is significant.
+When this option is not given, @var{RESYNTAX-SPEC} is omitted,
[EMAIL PROTECTED] M4 uses emacs compatible regular expressions.
[EMAIL PROTECTED], for more details on the format and meaning of
[EMAIL PROTECTED] This option may be given more than once, and order
+with respect to file names is significant.
@item --safer
Cripple the builtins @code{maketemp}, @code{mkstemp} (@pxref{Mkstemp}),
@@ -656,6 +658,14 @@
since they can perform potentially unsafe actions. An attempt to use
these macros will result in an error. This option is intended to make
it safer to preprocess an input file of unknown origin.
+
[EMAIL PROTECTED] -W
[EMAIL PROTECTED] --warnings
+Enable warnings. Warnings are on by default unless
[EMAIL PROTECTED] was set in the environment; this option exists to
+allow overriding @option{--silent}.
[EMAIL PROTECTED] FIXME should we accept -Wall, -Wnone, -Wcategory,
[EMAIL PROTECTED] -Wno-category...?
@end table
@node Dynamic loading features
@@ -673,14 +683,19 @@
@item -m @var{MODULE}
@itemx [EMAIL PROTECTED]
-Load @var{MODULE} before parsing input files. @var{MODULE} is searched
-for in each directory of the module search path, until the first match
-is found or the list is exhausted. @xref{Modules}, for more details.
-By default, the modules @samp{m4}, @samp{traditional}, and @samp{gnu}
-are preloaded, although this can be controlled during configuration
-with the @option{--with-modules} option to
+Load @var{MODULE} before parsing more input files. @var{MODULE} is
+searched for in each directory of the module search path, until the
+first match is found or the list is exhausted. @xref{Modules}, for more
+details. By default, the modules @samp{m4}, @samp{traditional}, and
[EMAIL PROTECTED] are preloaded, although this can be controlled during
+configuration with the @option{--with-modules} option to
@[EMAIL PROTECTED]/@/configure}. This option may be given more
than once, and order with respect to file names is significant.
+
[EMAIL PROTECTED] [EMAIL PROTECTED]
+Unload @var{MODULE} before parsing more input files. @xref{Modules},
+for more details. This option may be given more than once, and order
+with respect to file names is significant.
@end table
@node Preprocessor features
@@ -694,11 +709,6 @@
input came from. These features occur with the following options:
@table @code
[EMAIL PROTECTED] --import-environment
-Imports every variable in the environment as a macro. This is done
-before @option{-D} and @option{-U}, so they can override the
-environment.
-
@item -B @var{DIRECTORY}
@itemx [EMAIL PROTECTED]
Make @code{m4} search @var{DIRECTORY} for included files, prior to
@@ -722,15 +732,41 @@
file names is significant, and redefining the same @var{NAME} loses the
previous value.
[EMAIL PROTECTED] --import-environment
+Imports every variable in the environment as a macro. This is done
+before @option{-D} and @option{-U}, so they can override the
+environment.
+
@item -I @var{DIRECTORY}
@itemx [EMAIL PROTECTED]
Make @code{m4} search @var{DIRECTORY} 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.
[EMAIL PROTECTED] [EMAIL PROTECTED]
+This deletes the top-most meaning @var{NAME} might have. Obviously,
+only predefined macros can be deleted in this way. This option may be
+given more than once; popping a @var{NAME} that does not have a
+definition is silently ignored. Order is significant with respect to
+file names.
+
[EMAIL PROTECTED] -p @[EMAIL PROTECTED]@[EMAIL PROTECTED]
[EMAIL PROTECTED] [EMAIL PROTECTED]@[EMAIL PROTECTED]@r{]}
+This enters @var{NAME} into the symbol table, before any input files are
+read. If @[EMAIL PROTECTED] 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 with respect to
+file names is significant, and redefining the same @var{NAME} adds
+another definition to its stack.
+
@item -s
@itemx --synclines
-Generate synchronization lines, for use by the C preprocessor or other
+Short for @option{--syncoutput=1}, turning synchronization lines on.
+
[EMAIL PROTECTED] [EMAIL PROTECTED]@r{]}
+Control the generation of synchronization lines from the command line.
+Synchronization lines are for use by the C preprocessor or other
similar tools. Order is significant with respect to file names. This
option is useful, for example, when @code{m4} is used as a
front end to a compiler. Source file name and line number information
@@ -745,7 +781,9 @@
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. @xref{Syncoutput}, for
-runtime control.
+runtime control. @var{TRUTH} is interpreted the same as the argument to
[EMAIL PROTECTED]; if @var{TRUTH} is omitted, or @option{--syncoutput}
+is not used, synchronization lines are disabled.
@item -U @var{NAME}
@itemx [EMAIL PROTECTED]
@@ -766,16 +804,18 @@
@code{m4}.
@table @code
[EMAIL PROTECTED] FIXME - clean this up. POSIXLY_CORRECT should imply -G (as
[EMAIL PROTECTED] well as -Q), such that POSIX and traditional are identical.
[EMAIL PROTECTED] We should also provide -g, to match BSD implementations, which
[EMAIL PROTECTED] enables GNU mode and overrides POSIXLY_CORRECT in the
[EMAIL PROTECTED] environment.
[EMAIL PROTECTED] -g
[EMAIL PROTECTED] --gnu
+Enable all the extensions in this implementation. This is on by
+default unless @env{POSIXLY_CORRECT} is set in the environment; it
+exists to allow overriding @option{--traditional}.
+
@item -G
@itemx --traditional
Suppress all the extensions made in this implementation, compared to the
System V version. @xref{Compatibility}, for a list of these. This
loads the @samp{traditional} module in place of the @samp{gnu} module.
+It is implied if @env{POSIXLY_CORRECT} is set in the environment.
@item -L @var{NUM}
@itemx [EMAIL PROTECTED]
@@ -808,14 +848,17 @@
@item -H @var{NUM}
@itemx [EMAIL PROTECTED]
[EMAIL PROTECTED] -N @var{NUM}
[EMAIL PROTECTED] -N @var{NUM}
@itemx [EMAIL PROTECTED]
-These options are present only for compatibility with previous
-versions of GNU @code{m4}. They do nothing except issue a warning,
-because the symbol table size and number of diversions are not fixed
-anymore. They will eventually disappear in future releases.
[EMAIL PROTECTED] [EMAIL PROTECTED]
+These options are present only for compatibility with previous versions
+of GNU @code{m4}. They do nothing except issue a warning, because the
+symbol table size and number of diversions are not fixed anymore, and
+because the new @code{changesyntax} feature is more efficient than the
+withdrawn experimental @code{changeword}. These options will eventually
+disappear in future releases.
[EMAIL PROTECTED] -S @var{NUM}
[EMAIL PROTECTED] -S @var{NUM}
@itemx -T @var{NUM}
These options are present for compatibility with System V @code{m4}, but
do nothing in this implementation. They may disappear in future
@@ -896,10 +939,17 @@
@item -t @var{NAME}
@itemx [EMAIL PROTECTED]
[EMAIL PROTECTED] [EMAIL PROTECTED]
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, and order is significant with
respect to file names. @xref{Trace}, for more details.
+
[EMAIL PROTECTED] [EMAIL PROTECTED]
+This disables 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, and order is significant with
+respect to file names. @xref{Trace}, for more details.
@end table
@node Command line files
@@ -923,10 +973,10 @@
@comment interactive use when switching to stdin in a non-default parse
@comment state.
-The options @option{--define} (@option{-D}), @option{--undefine}
+Various options, such as @option{--define} (@option{-D}), @option{--undefine}
(@option{-U}), @option{--synclines} (@option{-s}), @option{--trace}
(@option{-t}), @option{--regexp-syntax} (@option{-r}), and
[EMAIL PROTECTED] (@option{-m}) only take effect after processing
[EMAIL PROTECTED] (@option{-m}), only take effect after processing
input from any file names that occur earlier on the command line. For
example, assume the file @file{foo} contains:
