deprecate --error-output [was: traceon behavior in head]

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Gary,

According to Gary V. Vaughan on 9/18/2006 6:23 PM:
> Hi Eric,
> 
> Nice work!  Do you ever sleep? ;-)

Is that rhetorical? :)

> 
> One of the big things I wanted to push for with 2.0 was consistency between
> the options and builtins, particularly where something was possible with
> one
> but not the other.  In respect of that mantra, --debugfile is the right
> option.
> Since we don't want to break backwards compatibility so gratuitously, lets
> continue to support -o and --error-output too, but perhaps give a
> deprecation
> warning for the next several releases.

For now, I left -o as is, added --debugfile as a synonym, and added a
deprecation warning to --error-output.  But for consistency with other
programs, perhaps a future release of m4 (post 2.1) should treat -o like
other GNU tools, where it redirects stdout (and is named --output); but
that would mean we need to start issuing a deprecation warning for -o
right now in order to phase out existing uses first.  I don't know if
- --debugfile needs a replacement short option, or if the long option is
good enough; but -f is still available (-d and -D are both taken, and -o
doesn't really mesh with --debugfile).  Thoughts?

Also, I found that your move from global variables to a context broke -o
back in 2003.

2006-09-19  Eric Blake  <address@hidden>

        * m4/debug.c (set_debug_file): Fix regression in -o when stdout
        and stderr are same file, introduced 2003-07-23.
        * tests/options.at (--debugfile): New test, to catch the bug.
        (deprecated options): Test --error-output.
        * src/main.c (usage, main, long_options, ERROR_OUTPUT_OPTION):
        Deprecate --error-output, and replace it with --debugfile.
        * doc/m4.texinfo (Invoking m4, Debug Output, Dumpdef, Errprint):
        Document this change.
        * NEWS: Likewise.

- --
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

iD8DBQFFD+2S84KuGfSFAYARAlxnAJ9JHNEvEqYzB4b95QWXWTcW1C9rygCfQOEb
XDDE4cRpJZt7Kd0kWe6qeok=
=ajTS
-----END PGP SIGNATURE-----

Index: NEWS
===================================================================
RCS file: /sources/m4/m4/NEWS,v
retrieving revision 1.15
diff -u -p -r1.15 NEWS
--- NEWS        19 Sep 2006 11:41:25 -0000      1.15
+++ NEWS        19 Sep 2006 13:13:02 -0000
@@ -68,12 +68,13 @@ promoted to 2.0.
   representation and to catch any more missing state; once 2.0 is released,
   any further changes would introduce format 3.
 
+* New `--debugfile' option is a synonym for the misnamed `--error-output',
+  using the old spelling will print a warning and may break in future
+  versions.
+
 * The `dumpdef' macro now always outputs to standard error, rather than
-  the debug file specified by `-o'/`--error-output' or option or
+  the debug file specified by the `-o'/`--debugfile' option or
   `debugfile' macro.
-  - FIXME: the name --error-output is a bit misleading, since it really
-  affects only debugmode and traceon output; we should probably deprecate
-  the --error-output, and rename it something like --trace-output.
 
 * The builtins `modules' and `symbols', introduced in previous betas,
   have been renamed `m4modules' and `m4symbols', in order to minimize
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.46
diff -u -p -r1.46 m4.texinfo
--- doc/m4.texinfo      19 Sep 2006 11:41:25 -0000      1.46
+++ doc/m4.texinfo      19 Sep 2006 13:13:04 -0000
@@ -656,16 +656,14 @@ characters per trace line.  If unspecifi
 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 @@ If you want to see what a name expands i
 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 @@ foo
 @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 @@ Although the @option{--safer} option cri
 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 @@ any of the previous chapters.
 @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
Index: src/main.c
===================================================================
RCS file: /sources/m4/m4/src/main.c,v
retrieving revision 1.83
diff -u -p -r1.83 main.c
--- src/main.c  18 Sep 2006 13:16:44 -0000      1.83
+++ src/main.c  19 Sep 2006 13:13:04 -0000
@@ -130,7 +130,7 @@ Frozen state files:\n\
 Debugging:\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\
+  -o, --debugfile=FILE         redirect debug and trace output\n\
   -t, --trace=NAME             trace NAME when it will be defined\n\
 "), stdout);
       fputs (_("\
@@ -173,6 +173,7 @@ mismatch, or whatever value was passed t
 enum
 {
   DIVERSIONS_OPTION = CHAR_MAX + 1,    /* not quite -N, because of message */
+  ERROR_OUTPUT_OPTION,                 /* deprecated form of -o */
   IMPORT_ENVIRONMENT_OPTION,           /* no short opt */
   PREPEND_INCLUDE_OPTION,              /* not quite -B, because of message */
   SAFER_OPTION,                                /* -S still has old no-op 
semantics */
@@ -187,9 +188,9 @@ static const struct option long_options[
   {"arglength", required_argument, NULL, 'l'},
   {"batch", no_argument, NULL, 'b'},
   {"debug", optional_argument, NULL, 'd'},
+  {"debugfile", required_argument, NULL, 'o'},
   {"define", required_argument, NULL, 'D'},
   {"discard-comments", no_argument, NULL, 'c'},
-  {"error-output", required_argument, NULL, 'o'},
   {"fatal-warnings", no_argument, NULL, 'E'},
   {"freeze-state", required_argument, NULL, 'F'},
   {"hashsize", required_argument, NULL, 'H'},
@@ -210,6 +211,7 @@ static const struct option long_options[
   {"word-regexp", required_argument, NULL, 'W'},
 
   {"diversions", required_argument, NULL, DIVERSIONS_OPTION},
+  {"error-output", required_argument, NULL, ERROR_OUTPUT_OPTION},
   {"import-environment", no_argument, NULL, IMPORT_ENVIRONMENT_OPTION},
   {"prepend-include", required_argument, NULL, PREPEND_INCLUDE_OPTION},
   {"safer", no_argument, NULL, SAFER_OPTION},
@@ -416,6 +418,10 @@ main (int argc, char *const *argv, char 
          m4_set_max_debug_arg_length_opt (context, 0);
        break;
 
+      case ERROR_OUTPUT_OPTION:
+       error (0, 0, _("\
+Warning: --error-output is deprecated, use --debugfile instead"));
+       /* fall through */
       case 'o':
        if (!m4_debug_set_output (context, optarg))
          error (0, errno, "%s", optarg);
Index: m4/debug.c
===================================================================
RCS file: /sources/m4/m4/m4/debug.c,v
retrieving revision 1.24
diff -u -p -r1.24 debug.c
--- m4/debug.c  5 Sep 2006 23:16:39 -0000       1.24
+++ m4/debug.c  19 Sep 2006 13:13:04 -0000
@@ -140,9 +140,10 @@ set_debug_file (m4 *context, FILE *fp)
   assert (context);
 
   debug_file = m4_get_debug_file (context);
-
   if (debug_file != NULL && debug_file != stderr && debug_file != stdout)
     fclose (debug_file);
+
+  debug_file = fp;
   m4_set_debug_file (context, fp);
 
   if (debug_file != NULL && debug_file != stdout)
Index: tests/options.at
===================================================================
RCS file: /sources/m4/m4/tests/options.at,v
retrieving revision 1.8
diff -u -p -r1.8 options.at
--- tests/options.at    15 Sep 2006 03:37:54 -0000      1.8
+++ tests/options.at    19 Sep 2006 13:13:04 -0000
@@ -155,6 +155,12 @@ AT_CHECK_M4([-B1 -B./1 --prepend-include
 [[m4: Warning: recommend using `m4 -B ./1' instead
 ]])
 
+dnl --error-output is a misleading name
+AT_CHECK_M4([--error-output=trace], [0], [],
+[[m4: Warning: --error-output is deprecated, use --debugfile instead
+]])
+AT_CHECK([rm trace])
+
 AT_CLEANUP
 
 
@@ -274,3 +280,26 @@ AT_CHECK([echo foo*], [0], [foo*
 ])
 
 AT_CLEANUP
+
+
+## --------- ##
+## debugfile ##
+## --------- ##
+
+AT_SETUP([--debugfile])
+
+dnl For a while, CVS m4 mistakenly replaced debug output with stdout
+dnl when stdout and stderr were the same file.
+
+AT_DATA([[in]], [[foo
+]])
+
+AT_CHECK_M4([-otrace1 -tfoo -Dfoo=bar in 2>&1], [0], [[bar
+]])
+
+AT_CHECK_M4([--debugfile=trace2 -tfoo -Dfoo=bar in], [0], [[bar
+]])
+
+AT_CHECK([cmp trace1 trace2])
+
+AT_CLEANUP