Changes to m4/doc/m4.texinfo,v

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Eric Blake <ericb>      06/09/19 13:16:08

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.46
retrieving revision 1.47
diff -u -b -r1.46 -r1.47
--- doc/m4.texinfo      19 Sep 2006 11:41:25 -0000      1.46
+++ doc/m4.texinfo      19 Sep 2006 13:16:08 -0000      1.47
@@ -656,16 +656,14 @@
 unlimited.  @xref{Debug Levels}, for more details.
 
 @item -o @var{FILE}
address@hidden address@hidden
 @itemx address@hidden
 Redirect debug and trace output to the named @var{FILE}.  Warnings,
 error messages, and the output of @code{errprint} and @code{dumpdef},
 are still printed to standard error.  @xref{Debug Output}, for more
-details.
address@hidden FIXME the name --error-output is misleading, since errprint
address@hidden and errors still prints to stderr in spite of this option.  We
address@hidden should rename the option; perhaps --trace-output or
address@hidden --debug-output, or perhaps --debugfile to match the macro
address@hidden name.
+details.  The name @option{--error-output} is misleading; using it
+instead of the other spellings will evoke a warning, and it may be
+withdrawn in a future release.
 
 @item -t @var{NAME}
 @itemx address@hidden
@@ -2555,7 +2553,7 @@
 Accepts any number of arguments.  If called without any arguments,
 it displays the definitions of all known names, otherwise it displays
 the definitions of the @var{names} given.  The output is printed
-directly to standard error, independently of the @option{--error-output}
+directly to standard error, independently of the @option{--debugfile}
 option (or @option{-o}, @pxref{Invoking m4}), or @code{debugfile} macro.
 The output is sorted by name.  If an unknown name is encountered, a
 warning is printed.
@@ -2919,8 +2917,8 @@
 @cindex output, saving debugging
 @cindex @acronym{GNU} extensions
 Debug and tracing output can be redirected to files using either the
address@hidden option to @code{m4} (@pxref{Invoking m4}), or with the
-builtin macro @code{debugfile}:
address@hidden option to @code{m4} (or @option{-o},
address@hidden m4}), or with the builtin macro @code{debugfile}:
 
 @deffn {Builtin (gnu)} debugfile (@ovar{file})
 Send all further debug and trace output to @var{file}, opened in append
@@ -2962,17 +2960,29 @@
 limited subset of capabilities, you may still use the @option{-o}
 option from the command line with no restrictions.
 
address@hidden options: --safer
address@hidden options: --safer -otrace -tfoo -Dfoo=bar -d+l
 @comment status: 1
 @example
-$ @kbd{m4 --safer}
-debugfile(`foo')
address@hidden:stdin:1: debugfile: disabled by --safer
+$ @kbd{m4 --safer -o trace -t foo -D foo=bar -daelq}
+foo # traced to `trace'
address@hidden # traced to `trace'
+debugfile(`file')
address@hidden:stdin:2: debugfile: disabled by --safer
 @result{}
+foo # traced to `trace'
address@hidden # traced to `trace'
 debugfile()
 @result{}
+foo # trace discarded
address@hidden # trace discarded
 debugfile
 @result{}
+foo # traced to stderr
address@hidden:7: -1- foo -> `bar'
address@hidden # traced to stderr
+undivert(`trace')dnl
address@hidden:1: -1- foo -> `bar'
address@hidden:3: -1- foo -> `bar'
 @end example
 
 @node Input Control
@@ -4866,7 +4876,8 @@
 @deffn {Builtin (m4)} errprint (@var{message}, @dots{})
 You can print error messages using @code{errprint}, which simply prints
 @var{message} and the rest of the arguments on standard error,
-independently of @option{--error-output}.
+independently of the @option{--debugfile} option (or @option{-o},
address@hidden m4}).
 
 The expansion of @code{errprint} is void.
 @end deffn