Changes to m4/doc/m4.texinfo,v

[Eric Blake]

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
address@hidden is set in the environment.
 
address@hidden -r @var{RESYNTAX-SPEC}
address@hidden address@hidden
address@hidden address@hidden@address@hidden
address@hidden address@hidden@address@hidden
 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,
address@hidden M4 uses emacs compatible regular expressions.
address@hidden, for more details on the format and meaning of
address@hidden  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.
+
address@hidden -W
address@hidden --warnings
+Enable warnings.  Warnings are on by default unless
address@hidden was set in the environment; this option exists to
+allow overriding @option{--silent}.
address@hidden FIXME should we accept -Wall, -Wnone, -Wcategory,
address@hidden -Wno-category...?
 @end table
 
 @node Dynamic loading features
@@ -673,14 +683,19 @@
 
 @item -m @var{MODULE}
 @itemx address@hidden
-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
address@hidden are preloaded, although this can be controlled during
+configuration with the @option{--with-modules} option to
 @address@hidden/@/configure}.  This option may be given more
 than once, and order with respect to file names is significant.
+
address@hidden address@hidden
+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
address@hidden --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 address@hidden
 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.
 
address@hidden --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 address@hidden
 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.
 
address@hidden address@hidden
+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.
+
address@hidden -p @address@hidden@address@hidden
address@hidden address@hidden@address@hidden@r{]}
+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 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.
+
address@hidden address@hidden@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
address@hidden; if @var{TRUTH} is omitted, or @option{--syncoutput}
+is not used, synchronization lines are disabled.
 
 @item -U @var{NAME}
 @itemx address@hidden
@@ -766,16 +804,18 @@
 @code{m4}.
 
 @table @code
address@hidden FIXME - clean this up.  POSIXLY_CORRECT should imply -G (as
address@hidden well as -Q), such that POSIX and traditional are identical.
address@hidden We should also provide -g, to match BSD implementations, which
address@hidden enables GNU mode and overrides POSIXLY_CORRECT in the
address@hidden environment.
address@hidden -g
address@hidden --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 address@hidden
@@ -808,14 +848,17 @@
 
 @item -H @var{NUM}
 @itemx address@hidden
address@hidden -N @var{NUM}
address@hidden -N @var{NUM}
 @itemx address@hidden
-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.
address@hidden address@hidden
+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.
 
address@hidden -S @var{NUM}
address@hidden -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 address@hidden
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, and order is significant with
 respect to file names.  @xref{Trace}, for more details.
+
address@hidden address@hidden
+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
address@hidden (@option{-m}) only take effect after processing
address@hidden (@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: