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

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index f760c292f6cc73aff85d7397b74b07dc0a3a1ad5..fbe9ac9d35990e45af2de3fc9391d551b0a6d27b 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -34,8 +34,8 @@ This manual (@value{UPDATED}) is for @acronym{GNU} Bison (version
 @value{VERSION}), the @acronym{GNU} parser generator.
 
 Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998,
 @value{VERSION}), the @acronym{GNU} parser generator.
 
 Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998,

-1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software
-Foundation, Inc.
+1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free
+Software Foundation, Inc.

 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document


@@ -4840,10 +4840,10 @@ traditional Yacc prologue for C/C++, see @ref{Prologue Alternatives}.
 @end deffn
 
 @deffn {Directive} %debug
 @end deffn
 
 @deffn {Directive} %debug

-In the parser file, define the macro @code{YYDEBUG} to 1 if it is not
-already defined, so that the debugging facilities are compiled.
-@end deffn
+Instrument the output parser for traces.  Obsoleted by @samp{%define
+parse.trace}.

 @xref{Tracing, ,Tracing Your Parser}.
 @xref{Tracing, ,Tracing Your Parser}.

+@end deffn

 
 @deffn {Directive} %define @var{variable}
 @deffnx {Directive} %define @var{variable} "@var{value}"
 
 @deffn {Directive} %define @var{variable}
 @deffnx {Directive} %define @var{variable} "@var{value}"


@@ -4876,7 +4876,7 @@ target language and/or parser skeleton.
 
 Some of the accepted @var{variable}s are:
 
 
 Some of the accepted @var{variable}s are:
 

-@itemize @bullet
+@table @code

 @item api.pure
 @findex %define api.pure
 
 @item api.pure
 @findex %define api.pure
 


@@ -5001,9 +5001,43 @@ For example, if you specify:
 The parser namespace is @code{foo} and @code{yylex} is referenced as
 @code{bar::lex}.
 @end itemize
 The parser namespace is @code{foo} and @code{yylex} is referenced as
 @code{bar::lex}.
 @end itemize

+@c namespace
+
+@item parse.assert
+@findex %define parse.assert
+
+@itemize
+@item Languages(s): C++
+
+@item Purpose: Issue runtime assertions to catch invalid uses.
+In C++, when variants are used, symbols must be constructed and
+destroyed properly.  This option checks these constraints.
+
+@item Accepted Values: Boolean
+
+@item Default Value: @code{false}

 @end itemize
 @end itemize

+@c parse.assert

 
 

+@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
 @end deffn

+@c %define

 
 @deffn {Directive} %defines
 Write a header file containing macro definitions for the token type
 
 @deffn {Directive} %defines
 Write a header file containing macro definitions for the token type


@@ -7650,15 +7684,21 @@ Use the @samp{-t} option when you run Bison (@pxref{Invocation,
 
 @item the directive @samp{%debug}
 @findex %debug
 
 @item the directive @samp{%debug}
 @findex %debug

-Add the @code{%debug} directive (@pxref{Decl Summary, ,Bison
-Declaration Summary}).  This is a Bison extension, which will prove
-useful when Bison will output parsers for languages that don't use a
-preprocessor.  Unless @acronym{POSIX} and Yacc portability matter to
-you, this is
-the preferred solution.
+Add the @code{%debug} directive (@pxref{Decl Summary, ,Bison Declaration
+Summary}).  This Bison extension is maintained for backward
+compatibility with previous versions of Bison.
+
+@item the variable @samp{parse.trace}
+@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
 
 @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
 always possible.
 
 The trace facility outputs messages with macro calls of the form


@@ -7843,8 +7883,8 @@ traditional Yacc grammars.  If your grammar uses a Bison extension
 like @samp{%glr-parser}, Bison might not be Yacc-compatible even if
 this option is specified.
 
 like @samp{%glr-parser}, Bison might not be Yacc-compatible even if
 this option is specified.
 

-@item -W
-@itemx --warnings
+@item -W [@var{category}]
+@itemx --warnings[=@var{category}]

 Output warnings falling in @var{category}.  @var{category} can be one
 of:
 @table @code
 Output warnings falling in @var{category}.  @var{category} can be one
 of:
 @table @code


@@ -8001,7 +8041,7 @@ Specify the @var{file} for the parser file.
 The other output files' names are constructed from @var{file} as
 described under the @samp{-v} and @samp{-d} options.
 
 The other output files' names are constructed from @var{file} as
 described under the @samp{-v} and @samp{-d} options.
 

-@item -g[@var{file}]
+@item -g [@var{file}]

 @itemx --graph[=@var{file}]
 Output a graphical representation of the @acronym{LALR}(1) grammar
 automaton computed by Bison, in @uref{http://www.graphviz.org/, Graphviz}
 @itemx --graph[=@var{file}]
 Output a graphical representation of the @acronym{LALR}(1) grammar
 automaton computed by Bison, in @uref{http://www.graphviz.org/, Graphviz}


@@ -8010,7 +8050,7 @@ automaton computed by Bison, in @uref{http://www.graphviz.org/, Graphviz}
 If omitted and the grammar file is @file{foo.y}, the output file will be
 @file{foo.dot}.
 
 If omitted and the grammar file is @file{foo.y}, the output file will be
 @file{foo.dot}.
 

-@item -x[@var{file}]
+@item -x [@var{file}]

 @itemx --xml[=@var{file}]
 Output an XML report of the @acronym{LALR}(1) automaton computed by Bison.
 @code{@var{file}} is optional.
 @itemx --xml[=@var{file}]
 Output an XML report of the @acronym{LALR}(1) automaton computed by Bison.
 @code{@var{file}} is optional.


@@ -8023,12 +8063,11 @@ More user feedback will help to stabilize it.)
 @node Option Cross Key
 @section Option Cross Key
 
 @node Option Cross Key
 @section Option Cross Key
 

-@c FIXME: How about putting the directives too?

 Here is a list of options, alphabetized by long option, to help you find
 the corresponding short option.
 
 Here is a list of options, alphabetized by long option, to help you find
 the corresponding short option.
 

-@multitable {@option{--defines=@var{defines-file}}} {@option{-b @var{file-prefix}XXX}}
-@headitem Long Option @tab Short Option
+@multitable {@option{--defines=@var{defines-file}}} {@option{-D @var{name}[=@var{value}]}} {@code{%nondeterministic-parser}}
+@headitem Long Option @tab Short Option @tab Bison Directive

 @include cross-options.texi
 @end multitable
 
 @include cross-options.texi
 @end multitable
 


@@ -8540,7 +8579,7 @@ error messages.
 
 @comment file: calc++-parser.yy
 @example
 
 @comment file: calc++-parser.yy
 @example

-%debug
+%define parse.trace

 %error-verbose
 @end example
 
 %error-verbose
 @end example
 


@@ -8848,11 +8887,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.
 @code{%defines} directive or the @option{-d}/@option{--defines} options.
 
 @c FIXME: Possible code change.

-Currently, support for debugging is always compiled
-in.  Thus the @code{%debug} and @code{%token-table} directives and the
+Currently, support for tracing is always compiled
+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
 @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.
 if needed.  Also, in the future the
 @code{%token-table} directive might enable a public interface to
 access the token names and codes.


@@ -8935,7 +8976,7 @@ The first, inclusive, position of the range, and the first beyond.
 @end deftypeivar
 
 @deftypeop {Constructor} {Location} {} Location (Position @var{loc})
 @end deftypeivar
 
 @deftypeop {Constructor} {Location} {} Location (Position @var{loc})

-Create a @code{Location} denoting an empty range located at a given point. 
+Create a @code{Location} denoting an empty range located at a given point.

 @end deftypeop
 
 @deftypeop {Constructor} {Location} {} Location (Position @var{begin}, Position @var{end})
 @end deftypeop
 
 @deftypeop {Constructor} {Location} {} Location (Position @var{begin}, Position @var{end})


@@ -9175,12 +9216,12 @@ Return immediately from the parser, indicating success.
 @end deffn
 
 @deffn {Statement} {return YYERROR;}
 @end deffn
 
 @deffn {Statement} {return YYERROR;}

-Start error recovery without printing an error message. 
+Start error recovery without printing an error message.

 @xref{Error Recovery}.
 @end deffn
 
 @deffn {Statement} {return YYFAIL;}
 @xref{Error Recovery}.
 @end deffn
 
 @deffn {Statement} {return YYFAIL;}

-Print an error message and start error recovery. 
+Print an error message and start error recovery.

 @xref{Error Recovery}.
 @end deffn
 
 @xref{Error Recovery}.
 @end deffn
 


@@ -9897,10 +9938,6 @@ Insert @var{code} verbatim into output parser source.
 Equip the parser for debugging.  @xref{Decl Summary}.
 @end deffn
 
 Equip the parser for debugging.  @xref{Decl Summary}.
 @end deffn
 

-@deffn {Directive} %debug
-Equip the parser for debugging.  @xref{Decl Summary}.
-@end deffn
-

 @ifset defaultprec
 @deffn {Directive} %default-prec
 Assign a precedence to rules that lack an explicit @samp{%prec}
 @ifset defaultprec
 @deffn {Directive} %default-prec
 Assign a precedence to rules that lack an explicit @samp{%prec}