variables: use parse.assert' instead of debug'.

* src/getargs.c (getargs): Map -t to %define trace.parse.
	* src/scan-gram.l (%debug): Map to %define trace.parse.
	* data/bison.m4 (b4_percent_define_if_define): Map `.' in variable
	names to `_' in macro names.
	(b4_debug_if): Replace with...
	(b4_parse_trace_if): this.
	* data/glr.c, data/glr.cc, data/lalr1.cc, data/lalr1.java,
	* data/yacc.c: Adjust.
	* doc/bison.texinfo (Decl Summary): Document %debug as obsoleted.
	Use @code to label the variable list.
	Document the variable parse.trace.
	(Tracing): Promote the parse.trace variable.
	* TODO: %printer is not documented.

ChangeLog

@@ -1,3 +1,20 @@
+2009-04-14  Akim Demaille  <demaille@gostai.com>
+
+	variables: use `parse.assert' instead of `debug'.
+	* src/getargs.c (getargs): Map -t to %define trace.parse.
+	* src/scan-gram.l (%debug): Map to %define trace.parse.
+	* data/bison.m4 (b4_percent_define_if_define): Map `.' in variable
+	names to `_' in macro names.
+	(b4_debug_if): Replace with...
+	(b4_parse_trace_if): this.
+	* data/glr.c, data/glr.cc, data/lalr1.cc, data/lalr1.java,
+	* data/yacc.c: Adjust.
+	* doc/bison.texinfo (Decl Summary): Document %debug as obsoleted.
+	Use @code to label the variable list.
+	Document the variable parse.trace.
+	(Tracing): Promote the parse.trace variable.
+	* TODO: %printer is not documented.
+
 2009-04-14  Akim Demaille  <demaille@gostai.com>
 
 	doc: minor fixes.

TODO

@@ -15,8 +15,6 @@ I have seen messages like the following from GCC.
 <built-in>:0: fatal error: opening dependency file .deps/libltdl/argz.Tpo: No such file or directory
 
 
-** Document %define assert
-
 ** Discuss about %printer/%destroy in the case of C++.
 It would be very nice to provide the symbol classes with an operator<<
 and a destructor.  Unfortunately the syntax we have chosen for
@@ -292,7 +290,10 @@ this issue.  Does anybody have it?
 Some history of Bison and some bibliography would be most welcome.
 Are there any Texinfo standards for bibliography?
 
+** %printer
+Wow, %printer is not documented.  Clearly mark YYPRINT as obsolete.
 
+** %define assert
 
 * Java, Fortran, etc.
 

data/bison.m4

@@ -668,22 +668,23 @@ m4_define([b4_percent_define_default],
 # b4_percent_define_if_define(VARIABLE)
 # -------------------------------------
 # Define b4_VARIABLE_if that executes its $1 or $2 depending whether
-# VARIABLE was %defined.
+# VARIABLE was %defined.  The character `.' in VARIABLE is mapped to `_'.
 m4_define([b4_percent_define_if_define_],
-[m4_define([b4_$1_if], [b4_percent_define_flag_if([$1], [$2], [$3])])])
+[m4_define(m4_bpatsubst([b4_$1_if], [[.]], [_]),
+           [b4_percent_define_flag_if([$1], [$2], [$3])])])
 m4_define([b4_percent_define_if_define],
 [b4_percent_define_default([[$1]], [[false]])
 b4_percent_define_if_define_([$1], $[1], $[2])])
 
 
 # b4_assert_if([IF-ASSERTIONS-ARE-USED], [IF-NOT])
-# b4_debug_if([IF-DEBUG-TRACES-ARE-ENABLED], [IF-NOT])
+# b4_parse_trace_if([IF-DEBUG-TRACES-ARE-ENABLED], [IF-NOT])
 # b4_error_verbose_if([IF-ERRORS-ARE-VERBOSE], [IF-NOT])
 # b4_lex_symbol_if([IF-YYLEX-RETURNS-A-COMPLETE-SYMBOL], [IF-NOT])
 # b4_variant_if([IF-VARIANT-ARE-USED], [IF-NOT])
 # ----------------------------------------------
 b4_percent_define_if_define([assert])
-b4_percent_define_if_define([debug])
+b4_percent_define_if_define([parse.trace])
 b4_percent_define_if_define([error_verbose])
 b4_percent_define_if_define([lex_symbol])
 b4_percent_define_if_define([locations])     # Whether locations are tracked.

data/glr.c

@@ -224,7 +224,7 @@ b4_defines_if([[#include "@basename(]b4_spec_defines_file[@)"]],
 
 /* Enabling traces.  */
 #ifndef YYDEBUG
-# define YYDEBUG ]b4_debug_if([1], [0])[
+# define YYDEBUG ]b4_parse_trace_if([1], [0])[
 #endif
 
 /* Enabling verbose error messages.  */

data/glr.cc

@@ -239,7 +239,7 @@ b4_copyright([Skeleton interface for Bison GLR parsers in C++],
 
 /* Enabling traces.  */
 #ifndef YYDEBUG
-# define YYDEBUG ]b4_debug_if([1], [0])[
+# define YYDEBUG ]b4_parse_trace_if([1], [0])[
 #endif
 
 /* YYLLOC_DEFAULT -- Set CURRENT to span from RHS[1] to RHS[N].

data/lalr1.cc

@@ -161,7 +161,7 @@ dnl FIXME: This is wrong, we want computed header guards.
 
 /* Enabling traces.  */
 #ifndef YYDEBUG
-# define YYDEBUG ]b4_debug_if([1], [0])[
+# define YYDEBUG ]b4_parse_trace_if([1], [0])[
 #endif
 
 /* Enabling verbose error messages.  */

data/lalr1.java

@@ -21,7 +21,7 @@ b4_defines_if([b4_fatal([%s: %%defines does not make sense in Java],
               [b4_skeleton])])
 
 # We don't depend on %debug in Java, but pacify warnings about non-used flags.
-b4_debug_if([0], [0])
+b4_parse_trace_if([0], [0])
 
 m4_define([b4_symbol_no_destructor_assert],
 [b4_symbol_if([$1], [has_destructor],

data/yacc.c

@@ -192,7 +192,7 @@ m4_if(b4_prefix, [yy], [],
 
 /* Enabling traces.  */
 #ifndef YYDEBUG
-# define YYDEBUG ]b4_debug_if([1], [0])[
+# define YYDEBUG ]b4_parse_trace_if([1], [0])[
 #endif
 
 /* Enabling verbose error messages.  */

doc/bison.texinfo

@@ -4840,8 +4840,8 @@ traditional Yacc prologue for C/C++, see @ref{Prologue Alternatives}.
 @end deffn
 
 @deffn {Directive} %debug
-In the parser file, define the macro @code{YYDEBUG} to 1 if it is not
+Instrument the output parser for traces.  Obsoleted by @samp{%define
-already defined, so that the debugging facilities are compiled.
+parse.trace}.
 @xref{Tracing, ,Tracing Your Parser}.
 @end deffn
 
@@ -4876,7 +4876,7 @@ target language and/or parser skeleton.
 
 Some of the accepted @var{variable}s are:
 
-@itemize @bullet
+@table @code
 @item api.pure
 @findex %define api.pure
 
@@ -5001,9 +5001,27 @@ For example, if you specify:
 The parser namespace is @code{foo} and @code{yylex} is referenced as
 @code{bar::lex}.
 @end itemize
-@end itemize
+@c namespace
 
+@item parse.trace
+@findex %define parse.trace
+
+@itemize
+@item Languages(s): C, C++
+
+@item Purpose: Require parser instrumentation for tracing.
+In C/C++, define the macro @code{YYDEBUG} to 1 in the parser file if it
+is not already defined, so that the debugging facilities are compiled.
+@xref{Tracing, ,Tracing Your Parser}.
+
+@item Accepted Values: Boolean
+
+@item Default Value: @code{false}
+@end itemize
+@end table
+@c parse.trace
 @end deffn
+@c %define
 
 @deffn {Directive} %defines
 Write a header file containing macro definitions for the token type
@@ -7650,15 +7668,21 @@ Use the @samp{-t} option when you run Bison (@pxref{Invocation,
 
 @item the directive @samp{%debug}
 @findex %debug
-Add the @code{%debug} directive (@pxref{Decl Summary, ,Bison
+Add the @code{%debug} directive (@pxref{Decl Summary, ,Bison Declaration
-Declaration Summary}).  This is a Bison extension, which will prove
+Summary}).  This Bison extension is maintained for backward
-useful when Bison will output parsers for languages that don't use a
+compatibility with previous versions of Bison.
-preprocessor.  Unless @acronym{POSIX} and Yacc portability matter to
+
-you, this is
+@item the variable @samp{parse.trace}
-the preferred solution.
+@findex %define parse.trace
+Add the @samp{%define parse.trace} directive (@pxref{Decl Summary,
+,Bison Declaration Summary}), or pass the @option{-Dparse.trace} option
+(@pxref{Bison Options}).  This is a Bison extension, which is especially
+useful for languages that don't use a preprocessor.  Unless
+@acronym{POSIX} and Yacc portability matter to you, this is the
+preferred solution.
 @end table
 
-We suggest that you always enable the debug option so that debugging is
+We suggest that you always enable the trace option so that debugging is
 always possible.
 
 The trace facility outputs messages with macro calls of the form
@@ -8539,7 +8563,7 @@ error messages.
 
 @comment file: calc++-parser.yy
 @example
-%debug
+%define parse.trace
 %error-verbose
 @end example
 
@@ -8847,11 +8871,13 @@ No header file can be generated for Java parsers.  Do not use the
 @code{%defines} directive or the @option{-d}/@option{--defines} options.
 
 @c FIXME: Possible code change.
-Currently, support for debugging is always compiled
+Currently, support for tracing is always compiled
-in.  Thus the @code{%debug} and @code{%token-table} directives and the
+in.  Thus the @samp{%define parse.trace} and @samp{%token-table}
+directives and the
 @option{-t}/@option{--debug} and @option{-k}/@option{--token-table}
 options have no effect.  This may change in the future to eliminate
-unused code in the generated parser, so use @code{%debug} explicitly
+unused code in the generated parser, so use @samp{%define parse.trace}
+explicitly
 if needed.  Also, in the future the
 @code{%token-table} directive might enable a public interface to
 access the token names and codes.

src/getargs.c

@@ -288,7 +288,8 @@ Parser:\n\
   -L, --language=LANGUAGE    specify the output programming language\n\
                              (this is an experimental feature)\n\
   -S, --skeleton=FILE        specify the skeleton to use\n\
-  -t, --debug                instrument the parser for debugging\n\
+  -t, --debug                instrument the parser for tracing\n\
+                             same as `-Dparse.trace'\n\
       --locations            enable location support\n\
   -D, --define=NAME[=VALUE]  same as `%define NAME \"VALUE\"'\n\
   -p, --name-prefix=PREFIX   prepend PREFIX to the external symbols\n\
@@ -616,7 +617,8 @@ getargs (int argc, char *argv[])
 	break;
 
       case 't':
-        muscle_percent_define_insert ("debug", command_line_location (), "");
+        muscle_percent_define_insert ("parse.trace",
+                                      command_line_location (), "");
 	break;
 
       case 'v':

src/scan-gram.l

@@ -175,7 +175,7 @@ splice	 (\\[ \f\t\v]*\n)*
 {
   "%binary"                         return PERCENT_NONASSOC;
   "%code"                           return PERCENT_CODE;
-  "%debug"                          RETURN_PERCENT_FLAG("debug");
+  "%debug"                          RETURN_PERCENT_FLAG("parse.trace");
   "%default"[-_]"prec"              return PERCENT_DEFAULT_PREC;
   "%define"                         return PERCENT_DEFINE;
   "%defines"                        return PERCENT_DEFINES;