* src/m4.c (usage, long_options, main, DEBUGFILE_OPTION): Rename

-o/--error-output to --debugfile, and deprecate the former.  This
will allow a future release to be more consistent with other GNU
tools, with -o/--output affecting stdout, not debug.
* doc/m4.texinfo (Invoking m4, Debug Output): Document this.
* NEWS: Document this.

4 files changed, 49 insertions, 23 deletions

diff --git a/ChangeLog b/ChangeLog
index c94551a0..d4049407 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2006-09-19  Eric Blake  <ebb9@byu.net>
+
+	* src/m4.c (usage, long_options, main, DEBUGFILE_OPTION): Rename
+	-o/--error-output to --debugfile, and deprecate the former.  This
+	will allow a future release to be more consistent with other GNU
+	tools, with -o/--output affecting stdout, not debug.
+	* doc/m4.texinfo (Invoking m4, Debug Output): Document this.
+	* NEWS: Document this.
+
 2006-09-14  Eric Blake  <ebb9@byu.net>
 
 	* src/m4.c (main): Warn on deprecated options -B, -S, -T, -N,
diff --git a/NEWS b/NEWS
index 3aae9b96..95cb387b 100644
--- a/NEWS
+++ b/NEWS
@@ -16,8 +16,13 @@ Version 1.4.7 - ?? ??? 2006, by ??  (CVS version 1.4.6a)
   macros now restore the current position to the next unread byte rather
   than discarding an arbitrary amount of buffered data.
 * The no-op compatibility command line options -B, -N, -S, -T, and
-  --diversions may be withdrawn or assigned new meanings in M4 2.0, so
-  they now issue a warning.
+  --diversions may be withdrawn or assigned new meanings in future
+  releases, so they now issue a warning if used.
+* A new command line option --debugfile replaces the options -o and
+  --error-output as the preferred spelling.  The old options were
+  misleading in their names and inconsistent with other GNU tools; they are
+  still silently accepted, but no longer documented in --help, and may
+  assigned new meanings in future releases.
 
 Version 1.4.6 - 25 August 2006, by Eric Blake  (CVS version 1.4.5a)
 
diff --git a/doc/m4.texinfo b/doc/m4.texinfo
index c96d18bb..43618e35 100644
--- a/doc/m4.texinfo
+++ b/doc/m4.texinfo
@@ -561,19 +561,24 @@ 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}.
 
-@item -l @var{NUM}
-@itemx --arglength=@var{NUM}
-Restrict the size of the output generated by macro tracing to @var{NUM}
-characters per trace line.  If unspecified or zero, output is
-unlimited.  @xref{Debug Levels}, for more details.
-
-@item -o @var{FILE}
+@item --debugfile=@var{FILE}
+@itemx -o @var{FILE}
 @itemx --error-output=@var{FILE}
 Redirect @code{dumpdef} output, debug messages, and trace output to the
 named @var{FILE}.  Warnings, error messages, and @code{errprint} output
 are still printed to standard error.  If unspecified, debug output goes
 to standard error; if empty, debug output is discarded.  @xref{Debug
-Output}, for more details.
+Output}, for more details.  The spellings @option{-o} and
+@option{--error-output} are misleading and inconsistent with other
+@acronym{GNU} tools; for now they are silently accepted as synonyms of
+@option{--debugfile}, but in a future version of M4, using them will
+cause a warning to be issued.
+
+@item -l @var{NUM}
+@itemx --arglength=@var{NUM}
+Restrict the size of the output generated by macro tracing to @var{NUM}
+characters per trace line.  If unspecified or zero, output is
+unlimited.  @xref{Debug Levels}, for more details.
 
 @item -t @var{NAME}
 @itemx --trace=@var{NAME}
@@ -2337,7 +2342,7 @@ foo
 @cindex output, saving debugging
 @cindex @acronym{GNU} extensions
 Debug and tracing output can be redirected to files using either the
-@option{-o} option to @code{m4} (@pxref{Invoking m4}), or with the
+@option{--debugfile} option to @code{m4} (@pxref{Invoking m4}), or with the
 builtin macro @code{debugfile}:
 
 @deffn Builtin debugfile (@ovar{file})
@@ -4761,7 +4766,7 @@ The destination of trace and debug output can be controlled with
 In addition to the above extensions, @acronym{GNU} @code{m4} implements the
 following command line options: @option{-F}, @option{-G}, @option{-I},
 @option{-L}, @option{-R}, @option{-V}, @option{-W}, @option{-d},
-@option{-l}, @option{-o} and @option{-t}.  @xref{Invoking m4}, for a
+@option{-l}, @option{--debugfile} and @option{-t}.  @xref{Invoking m4}, for a
 description of these options.
 
 Also, the debugging and tracing facilities in @acronym{GNU} @code{m4} are much
diff --git a/src/m4.c b/src/m4.c
index 676bbc9a..03195555 100644
--- a/src/m4.c
+++ b/src/m4.c
@@ -151,7 +151,7 @@ Operation modes:\n\
       fputs ("\
 \n\
 Preprocessor features:\n\
-  -D, --define=NAME[=VALUE]    define NAME has having VALUE, or empty\n\
+  -D, --define=NAME[=VALUE]    define NAME as having VALUE, or empty\n\
   -I, --include=DIRECTORY      append DIRECTORY to include path\n\
   -s, --synclines              generate `#line NUM \"FILE\"' lines\n\
   -U, --undefine=NAME          undefine NAME\n\
@@ -173,9 +173,9 @@ Frozen state files:\n\
 \n\
 Debugging:\n\
   -d, --debug[=FLAGS]          set debug level (no FLAGS implies `aeq')\n\
+      --debugfile=FILE         redirect debug and trace output\n\
   -l, --arglength=NUM          restrict macro tracing size\n\
-  -o, --error-output=FILE      redirect debug and trace output\n\
-  -t, --trace=NAME             trace NAME when it will be defined\n\
+  -t, --trace=NAME             trace NAME when it is defined\n\
 ", stdout);
       fputs ("\
 \n\
@@ -218,7 +218,8 @@ mismatch, or whatever value was passed to the m4exit macro.\n\
    non-character as a pseudo short option, starting with CHAR_MAX + 1.  */
 enum
 {
-  DIVERSIONS_OPTION = CHAR_MAX + 1,	/* not quite -N, because of message */
+  DEBUGFILE_OPTION = CHAR_MAX + 1,	/* no short opt */
+  DIVERSIONS_OPTION,			/* not quite -N, because of message */
 
   HELP_OPTION,				/* no short opt */
   VERSION_OPTION			/* no short opt */
@@ -229,7 +230,7 @@ static const struct option long_options[] =
   {"arglength", required_argument, NULL, 'l'},
   {"debug", optional_argument, NULL, 'd'},
   {"define", required_argument, NULL, 'D'},
-  {"error-output", required_argument, NULL, 'o'},
+  {"error-output", required_argument, NULL, 'o'}, /* FIXME: deprecate in 2.0 */
   {"fatal-warnings", no_argument, NULL, 'E'},
   {"freeze-state", required_argument, NULL, 'F'},
   {"hashsize", required_argument, NULL, 'H'},
@@ -246,6 +247,7 @@ static const struct option long_options[] =
   {"undefine", required_argument, NULL, 'U'},
   {"word-regexp", required_argument, NULL, 'W'},
 
+  {"debugfile", required_argument, NULL, DEBUGFILE_OPTION},
   {"diversions", required_argument, NULL, DIVERSIONS_OPTION},
 
   {"help", no_argument, NULL, HELP_OPTION},
@@ -312,7 +314,7 @@ main (int argc, char *const *argv, char *const *envp)
 
       case 'N':
       case DIVERSIONS_OPTION:
-         /* -N became an obsolete no-op in 1.4.x.  */
+	/* -N became an obsolete no-op in 1.4.x.  */
 	error (0, 0, "Warning: `m4 %s' is deprecated",
 	       optchar == 'N' ? "-N" : "--diversions");
 
@@ -399,6 +401,11 @@ main (int argc, char *const *argv, char *const *envp)
 	break;
 
       case 'o':
+	/* -o/--error-output are deprecated synonyms of --debugfile,
+	   but don't issue a deprecation warning until autoconf 2.61
+	   or later is more widely established, as such a warning
+	   would interfere with all earlier versions of autoconf.  */
+      case DEBUGFILE_OPTION:
 	if (!debug_set_output (optarg))
 	  error (0, errno, "%s", optarg);
 	break;
@@ -408,8 +415,8 @@ main (int argc, char *const *argv, char *const *envp)
 	break;
 
       case VERSION_OPTION:
-         printf ("%s\n", PACKAGE_STRING);
-         fputs ("\
+	 printf ("%s\n", PACKAGE_STRING);
+	 fputs ("\
 Copyright (C) 2006 Free Software Foundation, Inc.\n\
 This is free software; see the source for copying conditions.  There is NO\n\
 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n\
@@ -417,9 +424,9 @@ warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n\
 Written by Rene' Seindal.\n\
 ", stdout);
 
-         if (close_stream (stdout) != 0)
-            M4ERROR ((EXIT_FAILURE, errno, "write error"));
-         exit (EXIT_SUCCESS);
+	 if (close_stream (stdout) != 0)
+	    M4ERROR ((EXIT_FAILURE, errno, "write error"));
+	 exit (EXIT_SUCCESS);
 	break;
 
       case HELP_OPTION: