X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/db8ab2be3337ef87629b761078ebc46a01e7f876..eb0e86ac80861525ab5d0c0dcb585290e1bd3f03:/doc/bison.texi

diff --git a/doc/bison.texi b/doc/bison.texi
index 75e80183..1351a6c1 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -33,7 +33,7 @@
 This manual (@value{UPDATED}) is for GNU Bison (version
 @value{VERSION}), the GNU parser generator.
 
-Copyright @copyright{} 1988-1993, 1995, 1998-2012 Free Software
+Copyright @copyright{} 1988-1993, 1995, 1998-2013 Free Software
 Foundation, Inc.
 
 @quotation
@@ -135,7 +135,8 @@ Writing GLR Parsers
 
 * Simple GLR Parsers::     Using GLR parsers on unambiguous grammars.
 * Merging GLR Parses::     Using GLR parsers to resolve ambiguities.
-* GLR Semantic Actions::   Deferred semantic actions have special concerns.
+* GLR Semantic Actions::   Considerations for semantic values and deferred actions.
+* Semantic Predicates::    Controlling a parse with arbitrary computations.
 * Compiler Requirements::  GLR parsers require a modern C compiler.
 
 Examples
@@ -162,9 +163,9 @@ Reverse Polish Notation Calculator
 
 Grammar Rules for @code{rpcalc}
 
-* Rpcalc Input::
-* Rpcalc Line::
-* Rpcalc Expr::
+* Rpcalc Input::            Explanation of the @code{input} nonterminal
+* Rpcalc Line::             Explanation of the @code{line} nonterminal
+* Rpcalc Expr::             Explanation of the @code{expr} nonterminal
 
 Location Tracking Calculator: @code{ltcalc}
 
@@ -177,13 +178,14 @@ Multi-Function Calculator: @code{mfcalc}
 * Mfcalc Declarations::    Bison declarations for multi-function calculator.
 * Mfcalc Rules::           Grammar rules for the calculator.
 * Mfcalc Symbol Table::    Symbol table management subroutines.
+* Mfcalc Lexer::           The lexical analyzer.
+* Mfcalc Main::            The controlling function.
 
 Bison Grammar Files
 
 * Grammar Outline::    Overall layout of the grammar file.
 * Symbols::            Terminal and nonterminal symbols.
 * Rules::              How to write grammar rules.
-* Recursion::          Writing recursive rules.
 * Semantics::          Semantic values and actions.
 * Tracking Locations:: Locations and actions.
 * Named References::   Using named references in actions.
@@ -198,6 +200,13 @@ Outline of a Bison Grammar
 * Grammar Rules::         Syntax and usage of the grammar rules section.
 * Epilogue::              Syntax and usage of the epilogue.
 
+Grammar Rules
+
+* Rules Syntax::   Syntax of the rules.
+* Empty Rules::    Symbols that can match the empty string.
+* Recursion::      Writing recursive rules.
+
+
 Defining Language Semantics
 
 * Value Type::        Specifying one data type for all semantic values.
@@ -208,6 +217,12 @@ Defining Language Semantics
                       This says when, why and how to use the exceptional
                         action in the middle of a rule.
 
+Actions in Mid-Rule
+
+* Using Mid-Rule Actions::       Putting an action in the middle of a rule.
+* Mid-Rule Action Translation::  How mid-rule actions are actually processed.
+* Mid-Rule Conflicts::           Mid-rule actions can cause conflicts.
+
 Tracking Locations
 
 * Location Type::               Specifying a data type for locations.
@@ -273,9 +288,11 @@ The Bison Parser Algorithm
 Operator Precedence
 
 * Why Precedence::    An example showing why precedence is needed.
-* Using Precedence::  How to specify precedence in Bison grammars.
+* Using Precedence::  How to specify precedence and associativity.
+* Precedence Only::   How to specify precedence only.
 * Precedence Examples::  How these features are used in the previous example.
 * How Precedence::    How they work.
+* Non Operators::     Using precedence for general conflicts.
 
 Tuning LR
 
@@ -294,6 +311,8 @@ Handling Context Dependencies
 Debugging Your Parser
 
 * Understanding::     Understanding the structure of your parser.
+* Graphviz::          Getting a visual representation of the parser.
+* Xml::               Getting a markup representation of the parser.
 * Tracing::           Tracing the execution of your parser.
 
 Tracing Your Parser
@@ -770,7 +789,8 @@ merged result.
 @menu
 * Simple GLR Parsers::     Using GLR parsers on unambiguous grammars.
 * Merging GLR Parses::     Using GLR parsers to resolve ambiguities.
-* GLR Semantic Actions::   Deferred semantic actions have special concerns.
+* GLR Semantic Actions::   Considerations for semantic values and deferred actions.
+* Semantic Predicates::    Controlling a parse with arbitrary computations.
 * Compiler Requirements::  GLR parsers require a modern C compiler.
 @end menu
 
@@ -888,10 +908,7 @@ parses a vastly simplified form of Pascal type declarations.
 @end group
 
 %%
-
-@group
 type_decl: TYPE ID '=' type ';' ;
-@end group
 
 @group
 type:
@@ -996,7 +1013,7 @@ Let's consider an example, vastly simplified from a C++ grammar.
 %%
 
 prog:
-  /* Nothing.  */
+  %empty
 | prog stmt   @{ printf ("\n"); @}
 ;
 
@@ -1138,6 +1155,10 @@ the offending merge.
 @node GLR Semantic Actions
 @subsection GLR Semantic Actions
 
+The nature of GLR parsing and the structure of the generated
+parsers give rise to certain restrictions on semantic values and actions.
+
+@subsubsection Deferred semantic actions
 @cindex deferred semantic actions
 By definition, a deferred semantic action is not performed at the same time as
 the associated reduction.
@@ -1171,6 +1192,7 @@ For example, if a semantic action might be deferred, you should never write it
 to invoke @code{yyclearin} (@pxref{Action Features}) or to attempt to free
 memory referenced by @code{yylval}.
 
+@subsubsection YYERROR
 @findex YYERROR
 @cindex GLR parsers and @code{YYERROR}
 Another Bison feature requiring special consideration is @code{YYERROR}
@@ -1178,11 +1200,78 @@ Another Bison feature requiring special consideration is @code{YYERROR}
 initiate error recovery.
 During deterministic GLR operation, the effect of @code{YYERROR} is
 the same as its effect in a deterministic parser.
-In a deferred semantic action, its effect is undefined.
-@c The effect is probably a syntax error at the split point.
+The effect in a deferred action is similar, but the precise point of the
+error is undefined;  instead, the parser reverts to deterministic operation,
+selecting an unspecified stack on which to continue with a syntax error.
+In a semantic predicate (see @ref{Semantic Predicates}) during nondeterministic
+parsing, @code{YYERROR} silently prunes
+the parse that invoked the test.
+
+@subsubsection Restrictions on semantic values and locations
+GLR parsers require that you use POD (Plain Old Data) types for
+semantic values and location types when using the generated parsers as
+C++ code.
+
+@node Semantic Predicates
+@subsection Controlling a Parse with Arbitrary Predicates
+@findex %?
+@cindex Semantic predicates in GLR parsers
+
+In addition to the @code{%dprec} and @code{%merge} directives,
+GLR parsers
+allow you to reject parses on the basis of arbitrary computations executed
+in user code, without having Bison treat this rejection as an error
+if there are alternative parses. (This feature is experimental and may
+evolve.  We welcome user feedback.)  For example,
+
+@example
+widget:
+  %?@{  new_syntax @} "widget" id new_args  @{ $$ = f($3, $4); @}
+| %?@{ !new_syntax @} "widget" id old_args  @{ $$ = f($3, $4); @}
+;
+@end example
+
+@noindent
+is one way to allow the same parser to handle two different syntaxes for
+widgets.  The clause preceded by @code{%?} is treated like an ordinary
+action, except that its text is treated as an expression and is always
+evaluated immediately (even when in nondeterministic mode).  If the
+expression yields 0 (false), the clause is treated as a syntax error,
+which, in a nondeterministic parser, causes the stack in which it is reduced
+to die.  In a deterministic parser, it acts like YYERROR.
+
+As the example shows, predicates otherwise look like semantic actions, and
+therefore you must be take them into account when determining the numbers
+to use for denoting the semantic values of right-hand side symbols.
+Predicate actions, however, have no defined value, and may not be given
+labels.
+
+There is a subtle difference between semantic predicates and ordinary
+actions in nondeterministic mode, since the latter are deferred.
+For example, we could try to rewrite the previous example as
+
+@example
+widget:
+  @{ if (!new_syntax) YYERROR; @}
+    "widget" id new_args  @{ $$ = f($3, $4); @}
+|  @{ if (new_syntax) YYERROR; @}
+    "widget" id old_args   @{ $$ = f($3, $4); @}
+;
+@end example
+
+@noindent
+(reversing the sense of the predicate tests to cause an error when they are
+false).  However, this
+does @emph{not} have the same effect if @code{new_args} and @code{old_args}
+have overlapping syntax.
+Since the mid-rule actions testing @code{new_syntax} are deferred,
+a GLR parser first encounters the unresolved ambiguous reduction
+for cases where @code{new_args} and @code{old_args} recognize the same string
+@emph{before} performing the tests of @code{new_syntax}.  It therefore
+reports an error.
 
-Also, see @ref{Location Default Action, ,Default Action for Locations}, which
-describes a special usage of @code{YYLLOC_DEFAULT} in GLR parsers.
+Finally, be careful in writing predicates: deferred actions have not been
+evaluated, so that using them in a predicate will have undefined effects.
 
 @node Compiler Requirements
 @subsection Considerations when Compiling GLR Parsers
@@ -1451,15 +1540,19 @@ The source code for this calculator is named @file{rpcalc.y}.  The
 Here are the C and Bison declarations for the reverse polish notation
 calculator.  As in C, comments are placed between @samp{/*@dots{}*/}.
 
+@comment file: rpcalc.y
 @example
 /* Reverse polish notation calculator.  */
 
+@group
 %@{
   #define YYSTYPE double
+  #include <stdio.h>
   #include <math.h>
   int yylex (void);
   void yyerror (char const *);
 %@}
+@end group
 
 %token NUM
 
@@ -1500,10 +1593,11 @@ type for numeric constants.
 
 Here are the grammar rules for the reverse polish notation calculator.
 
+@comment file: rpcalc.y
 @example
 @group
 input:
-  /* empty */
+  %empty
 | input line
 ;
 @end group
@@ -1548,9 +1642,9 @@ main job of most actions.  The semantic values of the components of the
 rule are referred to as @code{$1}, @code{$2}, and so on.
 
 @menu
-* Rpcalc Input::
-* Rpcalc Line::
-* Rpcalc Expr::
+* Rpcalc Input::            Explanation of the @code{input} nonterminal
+* Rpcalc Line::             Explanation of the @code{line} nonterminal
+* Rpcalc Expr::             Explanation of the @code{expr} nonterminal
 @end menu
 
 @node Rpcalc Input
@@ -1560,7 +1654,7 @@ Consider the definition of @code{input}:
 
 @example
 input:
-  /* empty */
+  %empty
 | input line
 ;
 @end example
@@ -1575,8 +1669,9 @@ The first alternative is empty because there are no symbols between the
 colon and the first @samp{|}; this means that @code{input} can match an
 empty string of input (no tokens).  We write the rules this way because it
 is legitimate to type @kbd{Ctrl-d} right after you start the calculator.
-It's conventional to put an empty alternative first and write the comment
-@samp{/* empty */} in it.
+It's conventional to put an empty alternative first and to use the
+(optional) @code{%empty} directive, or to write the comment @samp{/* empty
+*/} in it (@pxref{Empty Rules}).
 
 The second alternate rule (@code{input line}) handles all nontrivial input.
 It means, ``After reading any number of lines, read one more line if
@@ -1714,6 +1809,7 @@ A token type code of zero is returned if the end-of-input is encountered.
 
 Here is the code for the lexical analyzer:
 
+@comment file: rpcalc.y
 @example
 @group
 /* The lexical analyzer returns a double floating point
@@ -1762,6 +1858,7 @@ In keeping with the spirit of this example, the controlling function is
 kept to the bare minimum.  The only requirement is that it call
 @code{yyparse} to start the process of parsing.
 
+@comment file: rpcalc.y
 @example
 @group
 int
@@ -1782,10 +1879,9 @@ always @code{"syntax error"}).  It is up to the programmer to supply
 @code{yyerror} (@pxref{Interface, ,Parser C-Language Interface}), so
 here is the definition we will use:
 
+@comment file: rpcalc.y
 @example
-@group
 #include <stdio.h>
-@end group
 
 @group
 /* Called by yyparse on error.  */
@@ -1866,15 +1962,15 @@ example session using @code{rpcalc}.
 @example
 $ @kbd{rpcalc}
 @kbd{4 9 +}
-13
+@result{} 13
 @kbd{3 7 + 3 4 5 *+-}
--13
+@result{} -13
 @kbd{3 7 + 3 4 5 * + - n}              @r{Note the unary minus, @samp{n}}
-13
+@result{} 13
 @kbd{5 6 / 4 n +}
--3.166666667
+@result{} -3.166666667
 @kbd{3 4 ^}                            @r{Exponentiation}
-81
+@result{} 81
 @kbd{^D}                               @r{End-of-file indicator}
 $
 @end example
@@ -1908,14 +2004,14 @@ parentheses nested to arbitrary depth.  Here is the Bison code for
 %token NUM
 %left '-' '+'
 %left '*' '/'
-%left NEG     /* negation--unary minus */
-%right '^'    /* exponentiation */
+%precedence NEG   /* negation--unary minus */
+%right '^'        /* exponentiation */
 @end group
 
 %% /* The grammar follows.  */
 @group
 input:
-  /* empty */
+  %empty
 | input line
 ;
 @end group
@@ -1952,15 +2048,16 @@ In the second section (Bison declarations), @code{%left} declares token
 types and says they are left-associative operators.  The declarations
 @code{%left} and @code{%right} (right associativity) take the place of
 @code{%token} which is used to declare a token type name without
-associativity.  (These tokens are single-character literals, which
+associativity/precedence.  (These tokens are single-character literals, which
 ordinarily don't need to be declared.  We declare them here to specify
-the associativity.)
+the associativity/precedence.)
 
 Operator precedence is determined by the line ordering of the
 declarations; the higher the line number of the declaration (lower on
 the page or screen), the higher the precedence.  Hence, exponentiation
 has the highest precedence, unary minus (@code{NEG}) is next, followed
-by @samp{*} and @samp{/}, and so on.  @xref{Precedence, ,Operator
+by @samp{*} and @samp{/}, and so on.  Unary minus is not associative,
+only precedence matters (@code{%precedence}. @xref{Precedence, ,Operator
 Precedence}.
 
 The other important new feature is the @code{%prec} in the grammar
@@ -2064,7 +2161,7 @@ the same as the declarations for the infix notation calculator.
 
 %left '-' '+'
 %left '*' '/'
-%left NEG
+%precedence NEG
 %right '^'
 
 %% /* The grammar follows.  */
@@ -2094,7 +2191,7 @@ wrong expressions or subexpressions.
 @example
 @group
 input:
-  /* empty */
+  %empty
 | input line
 ;
 @end group
@@ -2265,19 +2362,23 @@ to create named variables, store values in them, and use them later.
 Here is a sample session with the multi-function calculator:
 
 @example
+@group
 $ @kbd{mfcalc}
 @kbd{pi = 3.141592653589}
-3.1415926536
+@result{} 3.1415926536
+@end group
+@group
 @kbd{sin(pi)}
-0.0000000000
+@result{} 0.0000000000
+@end group
 @kbd{alpha = beta1 = 2.3}
-2.3000000000
+@result{} 2.3000000000
 @kbd{alpha}
-2.3000000000
+@result{} 2.3000000000
 @kbd{ln(alpha)}
-0.8329091229
+@result{} 0.8329091229
 @kbd{exp(ln(beta1))}
-2.3000000000
+@result{} 2.3000000000
 $
 @end example
 
@@ -2287,6 +2388,8 @@ Note that multiple assignment and nested function calls are permitted.
 * Mfcalc Declarations::    Bison declarations for multi-function calculator.
 * Mfcalc Rules::           Grammar rules for the calculator.
 * Mfcalc Symbol Table::    Symbol table management subroutines.
+* Mfcalc Lexer::           The lexical analyzer.
+* Mfcalc Main::            The controlling function.
 @end menu
 
 @node Mfcalc Declarations
@@ -2298,8 +2401,9 @@ Here are the C and Bison declarations for the multi-function calculator.
 @example
 @group
 %@{
-  #include <math.h>  /* For math functions, cos(), sin(), etc.  */
-  #include "calc.h"  /* Contains definition of `symrec'.  */
+  #include <stdio.h>  /* For printf, etc. */
+  #include <math.h>   /* For pow, used in the grammar.  */
+  #include "calc.h"   /* Contains definition of 'symrec'.  */
   int yylex (void);
   void yyerror (char const *);
 %@}
@@ -2316,11 +2420,11 @@ Here are the C and Bison declarations for the multi-function calculator.
 %type  <val>  exp
 
 @group
-%right '='
+%precedence '='
 %left '-' '+'
 %left '*' '/'
-%left NEG     /* negation--unary minus */
-%right '^'    /* exponentiation */
+%precedence NEG /* negation--unary minus */
+%right '^'      /* exponentiation */
 @end group
 @end example
 
@@ -2358,7 +2462,7 @@ those which mention @code{VAR} or @code{FNCT}, are new.
 %% /* The grammar follows.  */
 @group
 input:
-  /* empty */
+  %empty
 | input line
 ;
 @end group
@@ -2428,7 +2532,7 @@ struct symrec
 @group
 typedef struct symrec symrec;
 
-/* The symbol table: a chain of `struct symrec'.  */
+/* The symbol table: a chain of 'struct symrec'.  */
 extern symrec *sym_table;
 
 symrec *putsym (char const *, int);
@@ -2436,23 +2540,11 @@ symrec *getsym (char const *);
 @end group
 @end example
 
-The new version of @code{main} includes a call to @code{init_table}, a
-function that initializes the symbol table.  Here it is, and
-@code{init_table} as well:
+The new version of @code{main} will call @code{init_table} to initialize
+the symbol table:
 
 @comment file: mfcalc.y: 3
 @example
-#include <stdio.h>
-
-@group
-/* Called by yyparse on error.  */
-void
-yyerror (char const *s)
-@{
-  printf ("%s\n", s);
-@}
-@end group
-
 @group
 struct init
 @{
@@ -2464,23 +2556,24 @@ struct init
 @group
 struct init const arith_fncts[] =
 @{
-  "sin",  sin,
-  "cos",  cos,
-  "atan", atan,
-  "ln",   log,
-  "exp",  exp,
-  "sqrt", sqrt,
-  0, 0
+  @{ "atan", atan @},
+  @{ "cos",  cos  @},
+  @{ "exp",  exp  @},
+  @{ "ln",   log  @},
+  @{ "sin",  sin  @},
+  @{ "sqrt", sqrt @},
+  @{ 0, 0 @},
 @};
 @end group
 
 @group
-/* The symbol table: a chain of `struct symrec'.  */
+/* The symbol table: a chain of 'struct symrec'.  */
 symrec *sym_table;
 @end group
 
 @group
 /* Put arithmetic functions in table.  */
+static
 void
 init_table (void)
 @{
@@ -2492,15 +2585,6 @@ init_table (void)
     @}
 @}
 @end group
-
-@group
-int
-main (void)
-@{
-  init_table ();
-  return yyparse ();
-@}
-@end group
 @end example
 
 By simply editing the initialization list and adding the necessary include
@@ -2540,13 +2624,16 @@ getsym (char const *sym_name)
   symrec *ptr;
   for (ptr = sym_table; ptr != (symrec *) 0;
        ptr = (symrec *)ptr->next)
-    if (strcmp (ptr->name,sym_name) == 0)
+    if (strcmp (ptr->name, sym_name) == 0)
       return ptr;
   return 0;
 @}
 @end group
 @end example
 
+@node Mfcalc Lexer
+@subsection The @code{mfcalc} Lexer
+
 The function @code{yylex} must now recognize variables, numeric values, and
 the single-character arithmetic operators.  Strings of alphanumeric
 characters with a leading letter are recognized as either variables or
@@ -2564,9 +2651,7 @@ operators in @code{yylex}.
 
 @comment file: mfcalc.y: 3
 @example
-@group
 #include <ctype.h>
-@end group
 
 @group
 int
@@ -2603,7 +2688,6 @@ yylex (void)
       symrec *s;
       int i;
 @end group
-
       if (!symbuf)
         symbuf = (char *) malloc (length + 1);
 
@@ -2644,6 +2728,9 @@ yylex (void)
 @end group
 @end example
 
+@node Mfcalc Main
+@subsection The @code{mfcalc} Main
+
 The error reporting function is unchanged, and the new version of
 @code{main} includes a call to @code{init_table} and sets the @code{yydebug}
 on user demand (@xref{Tracing, , Tracing Your Parser}, for details):
@@ -2709,7 +2796,6 @@ The Bison grammar file conventionally has a name ending in @samp{.y}.
 * Grammar Outline::    Overall layout of the grammar file.
 * Symbols::            Terminal and nonterminal symbols.
 * Rules::              How to write grammar rules.
-* Recursion::          Writing recursive rules.
 * Semantics::          Semantic values and actions.
 * Tracking Locations:: Locations and actions.
 * Named References::   Using named references in actions.
@@ -2719,6 +2805,9 @@ The Bison grammar file conventionally has a name ending in @samp{.y}.
 
 @node Grammar Outline
 @section Outline of a Bison Grammar
+@cindex comment
+@findex // @dots{}
+@findex /* @dots{} */
 
 A Bison grammar file has four main sections, shown here with the
 appropriate delimiters:
@@ -2738,8 +2827,8 @@ appropriate delimiters:
 @end example
 
 Comments enclosed in @samp{/* @dots{} */} may appear in any of the sections.
-As a GNU extension, @samp{//} introduces a comment that
-continues until end of line.
+As a GNU extension, @samp{//} introduces a comment that continues until end
+of line.
 
 @menu
 * Prologue::              Syntax and usage of the prologue.
@@ -2776,21 +2865,27 @@ can be done with two @var{Prologue} blocks, one before and one after the
 @code{%union} declaration.
 
 @example
+@group
 %@{
   #define _GNU_SOURCE
   #include <stdio.h>
   #include "ptypes.h"
 %@}
+@end group
 
+@group
 %union @{
   long int n;
   tree t;  /* @r{@code{tree} is defined in @file{ptypes.h}.} */
 @}
+@end group
 
+@group
 %@{
   static void print_token_value (FILE *, int, YYSTYPE);
   #define YYPRINT(F, N, L) print_token_value (F, N, L)
 %@}
+@end group
 
 @dots{}
 @end example
@@ -2822,21 +2917,27 @@ location, or it can be one of @code{requires}, @code{provides},
 Look again at the example of the previous section:
 
 @example
+@group
 %@{
   #define _GNU_SOURCE
   #include <stdio.h>
   #include "ptypes.h"
 %@}
+@end group
 
+@group
 %union @{
   long int n;
   tree t;  /* @r{@code{tree} is defined in @file{ptypes.h}.} */
 @}
+@end group
 
+@group
 %@{
   static void print_token_value (FILE *, int, YYSTYPE);
   #define YYPRINT(F, N, L) print_token_value (F, N, L)
 %@}
+@end group
 
 @dots{}
 @end example
@@ -2874,7 +2975,7 @@ Let's go ahead and add the new @code{YYLTYPE} definition and the
   #include <stdio.h>
 
   /* WARNING: The following code really belongs
-   * in a `%code requires'; see below.  */
+   * in a '%code requires'; see below.  */
 
   #include "ptypes.h"
   #define YYLTYPE YYLTYPE
@@ -2888,16 +2989,20 @@ Let's go ahead and add the new @code{YYLTYPE} definition and the
   @} YYLTYPE;
 @}
 
+@group
 %union @{
   long int n;
   tree t;  /* @r{@code{tree} is defined in @file{ptypes.h}.} */
 @}
+@end group
 
+@group
 %code @{
   static void print_token_value (FILE *, int, YYSTYPE);
   #define YYPRINT(F, N, L) print_token_value (F, N, L)
   static void trace_token (enum yytokentype token, YYLTYPE loc);
 @}
+@end group
 
 @dots{}
 @end example
@@ -3308,7 +3413,18 @@ value of the error token is 256, unless you explicitly assigned 256 to
 one of your tokens with a @code{%token} declaration.
 
 @node Rules
-@section Syntax of Grammar Rules
+@section Grammar Rules
+
+A Bison grammar is a list of rules.
+
+@menu
+* Rules Syntax::   Syntax of the rules.
+* Empty Rules::    Symbols that can match the empty string.
+* Recursion::      Writing recursive rules.
+@end menu
+
+@node Rules Syntax
+@subsection Syntax of Grammar Rules
 @cindex rule syntax
 @cindex grammar rule syntax
 @cindex syntax of grammar rules
@@ -3316,9 +3432,7 @@ one of your tokens with a @code{%token} declaration.
 A Bison grammar rule has the following general form:
 
 @example
-@group
 @var{result}: @var{components}@dots{};
-@end group
 @end example
 
 @noindent
@@ -3329,9 +3443,7 @@ are put together by this rule (@pxref{Symbols}).
 For example,
 
 @example
-@group
 exp: exp '+' exp;
-@end group
 @end example
 
 @noindent
@@ -3386,33 +3498,57 @@ be joined with the vertical-bar character @samp{|} as follows:
 @noindent
 They are still considered distinct rules even when joined in this way.
 
-If @var{components} in a rule is empty, it means that @var{result} can
-match the empty string.  For example, here is how to define a
-comma-separated sequence of zero or more @code{exp} groupings:
+@node Empty Rules
+@subsection Empty Rules
+@cindex empty rule
+@cindex rule, empty
+@findex %empty
+
+A rule is said to be @dfn{empty} if its right-hand side (@var{components})
+is empty.  It means that @var{result} can match the empty string.  For
+example, here is how to define an optional semicolon:
+
+@example
+semicolon.opt: | ";";
+@end example
+
+@noindent
+It is easy not to see an empty rule, especially when @code{|} is used.  The
+@code{%empty} directive allows to make explicit that a rule is empty on
+purpose:
 
 @example
 @group
-expseq:
-  /* empty */
-| expseq1
+semicolon.opt:
+  %empty
+| ";"
 ;
 @end group
+@end example
+
+Flagging a non-empty rule with @code{%empty} is an error.  If run with
+@option{-Wempty-rule}, @command{bison} will report empty rules without
+@code{%empty}.  Using @code{%empty} enables this warning, unless
+@option{-Wno-empty-rule} was specified.
 
+The @code{%empty} directive is a Bison extension, it does not work with
+Yacc.  To remain compatible with POSIX Yacc, it is customary to write a
+comment @samp{/* empty */} in each rule with no components:
+
+@example
 @group
-expseq1:
-  exp
-| expseq1 ',' exp
+semicolon.opt:
+  /* empty */
+| ";"
 ;
 @end group
 @end example
 
-@noindent
-It is customary to write a comment @samp{/* empty */} in each rule
-with no components.
 
 @node Recursion
-@section Recursive Rules
+@subsection Recursive Rules
 @cindex recursive rule
+@cindex rule, recursive
 
 A rule is called @dfn{recursive} when its @var{result} nonterminal
 appears also on its right hand side.  Nearly all Bison grammars need to
@@ -3635,9 +3771,7 @@ difference with tools like Flex, for which @samp{|} stands for either
 following example, the action is triggered only when @samp{b} is found:
 
 @example
-@group
 a-or-b: 'a'|'b'   @{ a_or_b_found = 1; @};
-@end group
 @end example
 
 @cindex default action
@@ -3664,7 +3798,7 @@ foo:
 
 @group
 bar:
-  /* empty */    @{ previous_expr = $0; @}
+  %empty    @{ previous_expr = $0; @}
 ;
 @end group
 @end example
@@ -3733,6 +3867,15 @@ Occasionally it is useful to put an action in the middle of a rule.
 These actions are written just like usual end-of-rule actions, but they
 are executed before the parser even recognizes the following components.
 
+@menu
+* Using Mid-Rule Actions::       Putting an action in the middle of a rule.
+* Mid-Rule Action Translation::  How mid-rule actions are actually processed.
+* Mid-Rule Conflicts::           Mid-rule actions can cause conflicts.
+@end menu
+
+@node Using Mid-Rule Actions
+@subsubsection Using Mid-Rule Actions
+
 A mid-rule action may refer to the components preceding it using
 @code{$@var{n}}, but it may not refer to subsequent components because
 it is run before they are parsed.
@@ -3765,10 +3908,16 @@ remove it afterward.  Here is how it is done:
 @example
 @group
 stmt:
-  LET '(' var ')'
-    @{ $<context>$ = push_context (); declare_variable ($3); @}
+  "let" '(' var ')'
+    @{
+      $<context>$ = push_context ();
+      declare_variable ($3);
+    @}
   stmt
-    @{ $$ = $6; pop_context ($<context>5); @}
+    @{
+      $$ = $6;
+      pop_context ($<context>5);
+    @}
 @end group
 @end example
 
@@ -3779,8 +3928,27 @@ list of accessible variables) as its semantic value, using alternative
 @code{context} in the data-type union.  Then it calls
 @code{declare_variable} to add the new variable to that list.  Once the
 first action is finished, the embedded statement @code{stmt} can be
-parsed.  Note that the mid-rule action is component number 5, so the
-@samp{stmt} is component number 6.
+parsed.
+
+Note that the mid-rule action is component number 5, so the @samp{stmt} is
+component number 6.  Named references can be used to improve the readability
+and maintainability (@pxref{Named References}):
+
+@example
+@group
+stmt:
+  "let" '(' var ')'
+    @{
+      $<context>let = push_context ();
+      declare_variable ($3);
+    @}[let]
+  stmt
+    @{
+      $$ = $6;
+      pop_context ($<context>let);
+    @}
+@end group
+@end example
 
 After the embedded statement is parsed, its semantic value becomes the
 value of the entire @code{let}-statement.  Then the semantic value from the
@@ -3807,20 +3975,24 @@ declare a destructor for that symbol:
 @group
 %type <context> let
 %destructor @{ pop_context ($$); @} let
+@end group
 
 %%
 
+@group
 stmt:
   let stmt
     @{
       $$ = $2;
-      pop_context ($1);
+      pop_context ($let);
     @};
+@end group
 
+@group
 let:
-  LET '(' var ')'
+  "let" '(' var ')'
     @{
-      $$ = push_context ();
+      $let = push_context ();
       declare_variable ($3);
     @};
 
@@ -3832,6 +4004,76 @@ Note that the action is now at the end of its rule.
 Any mid-rule action can be converted to an end-of-rule action in this way, and
 this is what Bison actually does to implement mid-rule actions.
 
+@node Mid-Rule Action Translation
+@subsubsection Mid-Rule Action Translation
+@vindex $@@@var{n}
+@vindex @@@var{n}
+
+As hinted earlier, mid-rule actions are actually transformed into regular
+rules and actions.  The various reports generated by Bison (textual,
+graphical, etc., see @ref{Understanding, , Understanding Your Parser})
+reveal this translation, best explained by means of an example.  The
+following rule:
+
+@example
+exp: @{ a(); @} "b" @{ c(); @} @{ d(); @} "e" @{ f(); @};
+@end example
+
+@noindent
+is translated into:
+
+@example
+$@@1: %empty @{ a(); @};
+$@@2: %empty @{ c(); @};
+$@@3: %empty @{ d(); @};
+exp: $@@1 "b" $@@2 $@@3 "e" @{ f(); @};
+@end example
+
+@noindent
+with new nonterminal symbols @code{$@@@var{n}}, where @var{n} is a number.
+
+A mid-rule action is expected to generate a value if it uses @code{$$}, or
+the (final) action uses @code{$@var{n}} where @var{n} denote the mid-rule
+action.  In that case its nonterminal is rather named @code{@@@var{n}}:
+
+@example
+exp: @{ a(); @} "b" @{ $$ = c(); @} @{ d(); @} "e" @{ f = $1; @};
+@end example
+
+@noindent
+is translated into
+
+@example
+@@1: %empty @{ a(); @};
+@@2: %empty @{ $$ = c(); @};
+$@@3: %empty @{ d(); @};
+exp: @@1 "b" @@2 $@@3 "e" @{ f = $1; @}
+@end example
+
+There are probably two errors in the above example: the first mid-rule
+action does not generate a value (it does not use @code{$$} although the
+final action uses it), and the value of the second one is not used (the
+final action does not use @code{$3}).  Bison reports these errors when the
+@code{midrule-value} warnings are enabled (@pxref{Invocation, ,Invoking
+Bison}):
+
+@example
+$ bison -fcaret -Wmidrule-value mid.y
+@group
+mid.y:2.6-13: warning: unset value: $$
+ exp: @{ a(); @} "b" @{ $$ = c(); @} @{ d(); @} "e" @{ f = $1; @};
+      ^^^^^^^^
+@end group
+@group
+mid.y:2.19-31: warning: unused value: $3
+ exp: @{ a(); @} "b" @{ $$ = c(); @} @{ d(); @} "e" @{ f = $1; @};
+                   ^^^^^^^^^^^^^
+@end group
+@end example
+
+
+@node Mid-Rule Conflicts
+@subsubsection Conflicts due to Mid-Rule Actions
 Taking action before a rule is completely recognized often leads to
 conflicts since the parser must commit to a parse in order to execute the
 action.  For example, the following two rules, without mid-rule actions,
@@ -3913,7 +4155,7 @@ serves as a subroutine:
 @example
 @group
 subroutine:
-  /* empty */  @{ prepare_for_local_variables (); @}
+  %empty  @{ prepare_for_local_variables (); @}
 ;
 @end group
 
@@ -3929,6 +4171,7 @@ compound:
 Now Bison can execute the action in the rule for @code{subroutine} without
 deciding which rule for @code{compound} it will eventually use.
 
+
 @node Tracking Locations
 @section Tracking Locations
 @cindex location
@@ -4301,7 +4544,8 @@ Bison will convert this into a @code{#define} directive in
 the parser, so that the function @code{yylex} (if it is in this file)
 can use the name @var{name} to stand for this token type's code.
 
-Alternatively, you can use @code{%left}, @code{%right}, or
+Alternatively, you can use @code{%left}, @code{%right},
+@code{%precedence}, or
 @code{%nonassoc} instead of @code{%token}, if you wish to specify
 associativity and precedence.  @xref{Precedence Decl, ,Operator
 Precedence}.
@@ -4377,7 +4621,8 @@ of ``$end'':
 @cindex declaring operator precedence
 @cindex operator precedence, declaring
 
-Use the @code{%left}, @code{%right} or @code{%nonassoc} declaration to
+Use the @code{%left}, @code{%right}, @code{%nonassoc}, or
+@code{%precedence} declaration to
 declare a token and specify its precedence and associativity, all at
 once.  These are called @dfn{precedence declarations}.
 @xref{Precedence, ,Operator Precedence}, for general information on
@@ -4413,6 +4658,10 @@ left-associativity (grouping @var{x} with @var{y} first) and
 means that @samp{@var{x} @var{op} @var{y} @var{op} @var{z}} is
 considered a syntax error.
 
+@code{%precedence} gives only precedence to the @var{symbols}, and
+defines no associativity at all.  Use this to define precedence only,
+and leave any potential conflict due to associativity enabled.
+
 @item
 The precedence of an operator determines how it nests with other operators.
 All the tokens declared in a single precedence declaration have equal
@@ -4878,11 +5127,11 @@ statically allocated variables for communication with @code{yylex},
 including @code{yylval} and @code{yylloc}.)
 
 Alternatively, you can generate a pure, reentrant parser.  The Bison
-declaration @code{%define api.pure} says that you want the parser to be
+declaration @samp{%define api.pure} says that you want the parser to be
 reentrant.  It looks like this:
 
 @example
-%define api.pure
+%define api.pure full
 @end example
 
 The result is that the communication variables @code{yylval} and
@@ -4891,7 +5140,7 @@ calling convention is used for the lexical analyzer function
 @code{yylex}.  @xref{Pure Calling, ,Calling Conventions for Pure
 Parsers}, for the details of this.  The variable @code{yynerrs}
 becomes local in @code{yyparse} in pull mode but it becomes a member
-of yypstate in push mode.  (@pxref{Error Reporting, ,The Error
+of @code{yypstate} in push mode.  (@pxref{Error Reporting, ,The Error
 Reporting Function @code{yyerror}}).  The convention for calling
 @code{yyparse} itself is unchanged.
 
@@ -4932,7 +5181,7 @@ compatibility with the impure Yacc pull mode interface.  Unless you know
 what you are doing, your declarations should look like this:
 
 @example
-%define api.pure
+%define api.pure full
 %define api.push-pull push
 @end example
 
@@ -4982,14 +5231,14 @@ for use by the next invocation of the @code{yypush_parse} function.
 
 Bison also supports both the push parser interface along with the pull parser
 interface in the same generated parser.  In order to get this functionality,
-you should replace the @code{%define api.push-pull push} declaration with the
-@code{%define api.push-pull both} declaration.  Doing this will create all of
+you should replace the @samp{%define api.push-pull push} declaration with the
+@samp{%define api.push-pull both} declaration.  Doing this will create all of
 the symbols mentioned earlier along with the two extra symbols, @code{yyparse}
 and @code{yypull_parse}.  @code{yyparse} can be used exactly as it normally
 would be used.  However, the user should note that it is implemented in the
 generated parser by calling @code{yypull_parse}.
 This makes the @code{yyparse} function that is generated with the
-@code{%define api.push-pull both} declaration slower than the normal
+@samp{%define api.push-pull both} declaration slower than the normal
 @code{yyparse} function.  If the user
 calls the @code{yypull_parse} function it will parse the rest of the input
 stream.  It is possible to @code{yypush_parse} tokens to select a subgrammar
@@ -5005,9 +5254,9 @@ yypull_parse (ps); /* Will call the lexer */
 yypstate_delete (ps);
 @end example
 
-Adding the @code{%define api.pure} declaration does exactly the same thing to
-the generated parser with @code{%define api.push-pull both} as it did for
-@code{%define api.push-pull push}.
+Adding the @samp{%define api.pure} declaration does exactly the same thing to
+the generated parser with @samp{%define api.push-pull both} as it did for
+@samp{%define api.push-pull push}.
 
 @node Decl Summary
 @subsection Bison Declaration Summary
@@ -5080,10 +5329,8 @@ default location or at the location specified by @var{qualifier}.
 @end deffn
 
 @deffn {Directive} %debug
-In the parser implementation file, define the macro @code{YYDEBUG} (or
-@code{@var{prefix}DEBUG} with @samp{%define api.prefix @var{prefix}}, see
-@ref{Multiple Parsers, ,Multiple Parsers in the Same Program}) to 1 if it is
-not already defined, so that the debugging facilities are compiled.
+Instrument the parser for traces.  Obsoleted by @samp{%define
+parse.trace}.
 @xref{Tracing, ,Tracing Your Parser}.
 @end deffn
 
@@ -5149,7 +5396,7 @@ For instance with @samp{%define api.prefix "calc"} and @samp{%defines
 @end deffn
 
 @deffn {Directive} %defines @var{defines-file}
-Same as above, but save in the file @var{defines-file}.
+Same as above, but save in the file @file{@var{defines-file}}.
 @end deffn
 
 @deffn {Directive} %destructor
@@ -5167,8 +5414,6 @@ Specify the programming language for the generated parser.  Currently
 supported languages include C, C++, and Java.
 @var{language} is case-insensitive.
 
-This directive is experimental and its effect may be modified in future
-releases.
 @end deffn
 
 @deffn {Directive} %locations
@@ -5179,6 +5424,22 @@ grammar does not use it, using @samp{%locations} allows for more
 accurate syntax error messages.
 @end deffn
 
+@deffn {Directive} %name-prefix "@var{prefix}"
+Rename the external symbols used in the parser so that they start with
+@var{prefix} instead of @samp{yy}.  The precise list of symbols renamed
+in C parsers
+is @code{yyparse}, @code{yylex}, @code{yyerror}, @code{yynerrs},
+@code{yylval}, @code{yychar}, @code{yydebug}, and
+(if locations are used) @code{yylloc}.  If you use a push parser,
+@code{yypush_parse}, @code{yypull_parse}, @code{yypstate},
+@code{yypstate_new} and @code{yypstate_delete} will
+also be renamed.  For example, if you use @samp{%name-prefix "c_"}, the
+names become @code{c_parse}, @code{c_lex}, and so on.
+For C++ parsers, see the @samp{%define api.namespace} documentation in this
+section.
+@xref{Multiple Parsers, ,Multiple Parsers in the Same Program}.
+@end deffn
+
 @ifset defaultprec
 @deffn {Directive} %no-default-prec
 Do not assign a precedence to rules lacking an explicit @code{%prec}
@@ -5198,11 +5459,11 @@ own right.
 @end deffn
 
 @deffn {Directive} %output "@var{file}"
-Specify @var{file} for the parser implementation file.
+Generate the parser implementation in @file{@var{file}}.
 @end deffn
 
 @deffn {Directive} %pure-parser
-Deprecated version of @code{%define api.pure} (@pxref{%define
+Deprecated version of @samp{%define api.pure} (@pxref{%define
 Summary,,api.pure}), for which Bison is more careful to warn about
 unreasonable usage.
 @end deffn
@@ -5323,15 +5584,64 @@ values, depend on the selected target language and/or the parser
 skeleton (@pxref{Decl Summary,,%language}, @pxref{Decl
 Summary,,%skeleton}).
 Unaccepted @var{variable}s produce an error.
-Some of the accepted @var{variable}s are:
+Some of the accepted @var{variable}s are described below.
+
+@deffn Directive {%define api.namespace} @{@var{namespace}@}
+@itemize
+@item Languages(s): C++
+
+@item Purpose: Specify the namespace for the parser class.
+For example, if you specify:
+
+@example
+%define api.namespace @{foo::bar@}
+@end example
+
+Bison uses @code{foo::bar} verbatim in references such as:
+
+@example
+foo::bar::parser::semantic_type
+@end example
+
+However, to open a namespace, Bison removes any leading @code{::} and then
+splits on any remaining occurrences:
+
+@example
+namespace foo @{ namespace bar @{
+  class position;
+  class location;
+@} @}
+@end example
+
+@item Accepted Values:
+Any absolute or relative C++ namespace reference without a trailing
+@code{"::"}.  For example, @code{"foo"} or @code{"::foo::bar"}.
+
+@item Default Value:
+The value specified by @code{%name-prefix}, which defaults to @code{yy}.
+This usage of @code{%name-prefix} is for backward compatibility and can
+be confusing since @code{%name-prefix} also specifies the textual prefix
+for the lexical analyzer function.  Thus, if you specify
+@code{%name-prefix}, it is best to also specify @samp{%define
+api.namespace} so that @code{%name-prefix} @emph{only} affects the
+lexical analyzer function.  For example, if you specify:
+
+@example
+%define api.namespace @{foo@}
+%name-prefix "bar::"
+@end example
+
+The parser namespace is @code{foo} and @code{yylex} is referenced as
+@code{bar::lex}.
+@end itemize
+@end deffn
+@c api.namespace
 
-@itemize @bullet
 @c ================================================== api.location.type
-@item @code{api.location.type}
-@findex %define api.location.type
+@deffn {Directive} {%define api.location.type} @var{type}
 
 @itemize @bullet
-@item Language(s): C++
+@item Language(s): C++, Java
 
 @item Purpose: Define the location type.
 @xref{User Defined Location Type}.
@@ -5340,12 +5650,14 @@ Some of the accepted @var{variable}s are:
 
 @item Default Value: none
 
-@item History: introduced in Bison 2.7
+@item History:
+Introduced in Bison 2.7 for C, C++ and Java.  Introduced under the name
+@code{location_type} for C++ in Bison 2.5 and for Java in Bison 2.4.
 @end itemize
+@end deffn
 
 @c ================================================== api.prefix
-@item @code{api.prefix}
-@findex %define api.prefix
+@deffn {Directive} {%define api.prefix} @var{prefix}
 
 @itemize @bullet
 @item Language(s): All
@@ -5359,10 +5671,10 @@ Some of the accepted @var{variable}s are:
 
 @item History: introduced in Bison 2.6
 @end itemize
+@end deffn
 
 @c ================================================== api.pure
-@item @code{api.pure}
-@findex %define api.pure
+@deffn Directive {%define api.pure}
 
 @itemize @bullet
 @item Language(s): C
@@ -5370,15 +5682,50 @@ Some of the accepted @var{variable}s are:
 @item Purpose: Request a pure (reentrant) parser program.
 @xref{Pure Decl, ,A Pure (Reentrant) Parser}.
 
-@item Accepted Values: Boolean
+@item Accepted Values: @code{true}, @code{false}, @code{full}
+
+The value may be omitted: this is equivalent to specifying @code{true}, as is
+the case for Boolean values.
+
+When @code{%define api.pure full} is used, the parser is made reentrant. This
+changes the signature for @code{yylex} (@pxref{Pure Calling}), and also that of
+@code{yyerror} when the tracking of locations has been activated, as shown
+below.
+
+The @code{true} value is very similar to the @code{full} value, the only
+difference is in the signature of @code{yyerror} on Yacc parsers without
+@code{%parse-param}, for historical reasons.
+
+I.e., if @samp{%locations %define api.pure} is passed then the prototypes for
+@code{yyerror} are:
+
+@example
+void yyerror (char const *msg);                 // Yacc parsers.
+void yyerror (YYLTYPE *locp, char const *msg);  // GLR parsers.
+@end example
+
+But if @samp{%locations %define api.pure %parse-param @{int *nastiness@}} is
+used, then both parsers have the same signature:
+
+@example
+void yyerror (YYLTYPE *llocp, int *nastiness, char const *msg);
+@end example
+
+(@pxref{Error Reporting, ,The Error
+Reporting Function @code{yyerror}})
 
 @item Default Value: @code{false}
+
+@item History:
+the @code{full} value was introduced in Bison 2.7
 @end itemize
+@end deffn
+@c api.pure
 
-@c ================================================== api.push-pull
 
-@item @code{api.push-pull}
-@findex %define api.push-pull
+
+@c ================================================== api.push-pull
+@deffn Directive {%define api.push-pull} @var{kind}
 
 @itemize @bullet
 @item Language(s): C (deterministic parsers only)
@@ -5392,45 +5739,146 @@ More user feedback will help to stabilize it.)
 
 @item Default Value: @code{pull}
 @end itemize
+@end deffn
+@c api.push-pull
 
-@c ================================================== lr.default-reductions
 
-@item @code{lr.default-reductions}
-@findex %define lr.default-reductions
+
+@c ================================================== api.token.constructor
+@deffn Directive {%define api.token.constructor}
 
 @itemize @bullet
-@item Language(s): all
+@item Language(s):
+C++
 
-@item Purpose: Specify the kind of states that are permitted to
-contain default reductions.  @xref{Default Reductions}.  (The ability to
-specify where default reductions should be used is experimental.  More user
-feedback will help to stabilize it.)
+@item Purpose:
+When variant-based semantic values are enabled (@pxref{C++ Variants}),
+request that symbols be handled as a whole (type, value, and possibly
+location) in the scanner.  @xref{Complete Symbols}, for details.
+
+@item Accepted Values:
+Boolean.
 
-@item Accepted Values: @code{most}, @code{consistent}, @code{accepting}
 @item Default Value:
-@itemize
-@item @code{accepting} if @code{lr.type} is @code{canonical-lr}.
-@item @code{most} otherwise.
-@end itemize
+@code{false}
+@item History:
+introduced in Bison 2.8
 @end itemize
+@end deffn
+@c api.token.constructor
 
-@c ============================================ lr.keep-unreachable-states
 
-@item @code{lr.keep-unreachable-states}
-@findex %define lr.keep-unreachable-states
+@c ================================================== api.token.prefix
+@deffn Directive {%define api.token.prefix} @var{prefix}
 
-@itemize @bullet
-@item Language(s): all
-@item Purpose: Request that Bison allow unreachable parser states to
-remain in the parser tables.  @xref{Unreachable States}.
-@item Accepted Values: Boolean
-@item Default Value: @code{false}
-@end itemize
+@itemize
+@item Languages(s): all
 
-@c ================================================== lr.type
+@item Purpose:
+Add a prefix to the token names when generating their definition in the
+target language.  For instance
 
-@item @code{lr.type}
-@findex %define lr.type
+@example
+%token FILE for ERROR
+%define api.token.prefix "TOK_"
+%%
+start: FILE for ERROR;
+@end example
+
+@noindent
+generates the definition of the symbols @code{TOK_FILE}, @code{TOK_for},
+and @code{TOK_ERROR} in the generated source files.  In particular, the
+scanner must use these prefixed token names, while the grammar itself
+may still use the short names (as in the sample rule given above).  The
+generated informational files (@file{*.output}, @file{*.xml},
+@file{*.dot}) are not modified by this prefix.  See @ref{Calc++ Parser}
+and @ref{Calc++ Scanner}, for a complete example.
+
+@item Accepted Values:
+Any string.  Should be a valid identifier prefix in the target language,
+in other words, it should typically be an identifier itself (sequence of
+letters, underscores, and ---not at the beginning--- digits).
+
+@item Default Value:
+empty
+@item History:
+introduced in Bison 2.8
+@end itemize
+@end deffn
+@c api.token.prefix
+
+
+@c ================================================== api.value.type
+@deffn Directive {%define api.value.type} @var{type}
+@itemize @bullet
+@item Language(s):
+C++
+
+@item Purpose:
+Request variant-based semantic values.
+@xref{C++ Variants}.
+
+@item Default Value:
+FIXME:
+@item History:
+introduced in Bison 2.8.  Was introduced for Java only in 2.3b as
+@code{stype}.
+@end itemize
+@end deffn
+@c api.value.type
+
+
+@c ================================================== location_type
+@deffn Directive {%define location_type}
+Obsoleted by @code{api.location.type} since Bison 2.7.
+@end deffn
+
+
+@c ================================================== lr.default-reduction
+
+@deffn Directive {%define lr.default-reduction} @var{when}
+
+@itemize @bullet
+@item Language(s): all
+
+@item Purpose: Specify the kind of states that are permitted to
+contain default reductions.  @xref{Default Reductions}.  (The ability to
+specify where default reductions should be used is experimental.  More user
+feedback will help to stabilize it.)
+
+@item Accepted Values: @code{most}, @code{consistent}, @code{accepting}
+@item Default Value:
+@itemize
+@item @code{accepting} if @code{lr.type} is @code{canonical-lr}.
+@item @code{most} otherwise.
+@end itemize
+@item History:
+introduced as @code{lr.default-reduction} in 2.5, renamed as
+@code{lr.default-reduction} in 2.8.
+@end itemize
+@end deffn
+
+@c ============================================ lr.keep-unreachable-state
+
+@deffn Directive {%define lr.keep-unreachable-state}
+
+@itemize @bullet
+@item Language(s): all
+@item Purpose: Request that Bison allow unreachable parser states to
+remain in the parser tables.  @xref{Unreachable States}.
+@item Accepted Values: Boolean
+@item Default Value: @code{false}
+@item History:
+introduced as @code{lr.keep_unreachable_states} in 2.3b, renamed as
+@code{lr.keep-unreachable-states} in 2.5, and as
+@code{lr.keep-unreachable-state} in 2.8.
+@end itemize
+@end deffn
+@c lr.keep-unreachable-state
+
+@c ================================================== lr.type
+
+@deffn Directive {%define lr.type} @var{type}
 
 @itemize @bullet
 @item Language(s): all
@@ -5443,64 +5891,62 @@ More user feedback will help to stabilize it.)
 
 @item Default Value: @code{lalr}
 @end itemize
+@end deffn
 
 @c ================================================== namespace
+@deffn Directive %define namespace @{@var{namespace}@}
+Obsoleted by @code{api.namespace}
+@c namespace
+@end deffn
 
-@item @code{namespace}
-@findex %define namespace
+@c ================================================== parse.assert
+@deffn Directive {%define parse.assert}
 
 @itemize
 @item Languages(s): C++
 
-@item Purpose: Specify the namespace for the parser class.
-For example, if you specify:
-
-@smallexample
-%define namespace "foo::bar"
-@end smallexample
-
-Bison uses @code{foo::bar} verbatim in references such as:
+@item Purpose: Issue runtime assertions to catch invalid uses.
+In C++, when variants are used (@pxref{C++ Variants}), symbols must be
+constructed and
+destroyed properly.  This option checks these constraints.
 
-@smallexample
-foo::bar::parser::semantic_type
-@end smallexample
+@item Accepted Values: Boolean
 
-However, to open a namespace, Bison removes any leading @code{::} and then
-splits on any remaining occurrences:
+@item Default Value: @code{false}
+@end itemize
+@end deffn
+@c parse.assert
 
-@smallexample
-namespace foo @{ namespace bar @{
-  class position;
-  class location;
-@} @}
-@end smallexample
-
-@item Accepted Values: Any absolute or relative C++ namespace reference without
-a trailing @code{"::"}.
-For example, @code{"foo"} or @code{"::foo::bar"}.
-
-@item Default Value: The value specified by @code{%name-prefix}, which defaults
-to @code{yy}.
-This usage of @code{%name-prefix} is for backward compatibility and can be
-confusing since @code{%name-prefix} also specifies the textual prefix for the
-lexical analyzer function.
-Thus, if you specify @code{%name-prefix}, it is best to also specify
-@code{%define namespace} so that @code{%name-prefix} @emph{only} affects the
-lexical analyzer function.
-For example, if you specify:
 
-@smallexample
-%define namespace "foo"
-%name-prefix "bar::"
-@end smallexample
+@c ================================================== parse.error
+@deffn Directive {%define parse.error}
+@itemize
+@item Languages(s):
+all
+@item Purpose:
+Control the kind of error messages passed to the error reporting
+function.  @xref{Error Reporting, ,The Error Reporting Function
+@code{yyerror}}.
+@item Accepted Values:
+@itemize
+@item @code{simple}
+Error messages passed to @code{yyerror} are simply @w{@code{"syntax
+error"}}.
+@item @code{verbose}
+Error messages report the unexpected token, and possibly the expected ones.
+However, this report can often be incorrect when LAC is not enabled
+(@pxref{LAC}).
+@end itemize
 
-The parser namespace is @code{foo} and @code{yylex} is referenced as
-@code{bar::lex}.
+@item Default Value:
+@code{simple}
 @end itemize
+@end deffn
+@c parse.error
+
 
 @c ================================================== parse.lac
-@item @code{parse.lac}
-@findex %define parse.lac
+@deffn Directive {%define parse.lac}
 
 @itemize
 @item Languages(s): C (deterministic parsers only)
@@ -5510,8 +5956,30 @@ syntax error handling.  @xref{LAC}.
 @item Accepted Values: @code{none}, @code{full}
 @item Default Value: @code{none}
 @end itemize
-@end itemize
+@end deffn
+@c parse.lac
+
+@c ================================================== parse.trace
+@deffn Directive {%define parse.trace}
+
+@itemize
+@item Languages(s): C, C++, Java
+
+@item Purpose: Require parser instrumentation for tracing.
+@xref{Tracing, ,Tracing Your Parser}.
+
+In C/C++, define the macro @code{YYDEBUG} (or @code{@var{prefix}DEBUG} with
+@samp{%define api.prefix @var{prefix}}), see @ref{Multiple Parsers,
+,Multiple Parsers in the Same Program}) to 1 in the parser implementation
+file if it is not already defined, so that the debugging facilities are
+compiled.
+
+@item Accepted Values: Boolean
 
+@item Default Value: @code{false}
+@end itemize
+@end deffn
+@c parse.trace
 
 @node %code Summary
 @subsection %code Summary
@@ -5556,7 +6024,7 @@ file.
 Not all qualifiers are accepted for all target languages.  Unaccepted
 qualifiers produce an error.  Some of the accepted qualifiers are:
 
-@itemize @bullet
+@table @code
 @item requires
 @findex %code requires
 
@@ -5620,7 +6088,7 @@ parser implementation file.  For example:
 @item Location(s): The parser Java file after any Java package directive and
 before any class definitions.
 @end itemize
-@end itemize
+@end table
 
 Though we say the insertion locations are language-dependent, they are
 technically skeleton-dependent.  Writers of non-standard skeletons
@@ -5692,7 +6160,7 @@ parsers.  To comply with this tradition, when @code{api.prefix} is used,
 @code{YYDEBUG} (not renamed) is used as a default value:
 
 @example
-/* Enabling traces.  */
+/* Debug traces.  */
 #ifndef CDEBUG
 # if defined YYDEBUG
 #  if YYDEBUG
@@ -5782,10 +6250,10 @@ If you use a reentrant parser, you can optionally pass additional
 parameter information to it in a reentrant way.  To do so, use the
 declaration @code{%parse-param}:
 
-@deffn {Directive} %parse-param @{@var{argument-declaration}@}
+@deffn {Directive} %parse-param @{@var{argument-declaration}@} @dots{}
 @findex %parse-param
-Declare that an argument declared by the braced-code
-@var{argument-declaration} is an additional @code{yyparse} argument.
+Declare that one or more
+@var{argument-declaration} are additional @code{yyparse} arguments.
 The @var{argument-declaration} is used when declaring
 functions or prototypes.  The last identifier in
 @var{argument-declaration} must be the argument name.
@@ -5794,8 +6262,7 @@ functions or prototypes.  The last identifier in
 Here's an example.  Write this in the parser:
 
 @example
-%parse-param @{int *nastiness@}
-%parse-param @{int *randomness@}
+%parse-param @{int *nastiness@} @{int *randomness@}
 @end example
 
 @noindent
@@ -5817,6 +6284,27 @@ In the grammar actions, use expressions like this to refer to the data:
 exp: @dots{}    @{ @dots{}; *randomness += 1; @dots{} @}
 @end example
 
+@noindent
+Using the following:
+@example
+%parse-param @{int *randomness@}
+@end example
+
+Results in these signatures:
+@example
+void yyerror (int *randomness, const char *msg);
+int  yyparse (int *randomness);
+@end example
+
+@noindent
+Or, if both @code{%define api.pure full} (or just @code{%define api.pure})
+and @code{%locations} are used:
+
+@example
+void yyerror (YYLTYPE *llocp, int *randomness, const char *msg);
+int  yyparse (int *randomness);
+@end example
+
 @node Push Parser Function
 @section The Push Parser Function @code{yypush_parse}
 @findex yypush_parse
@@ -5825,11 +6313,11 @@ exp: @dots{}    @{ @dots{}; *randomness += 1; @dots{} @}
 More user feedback will help to stabilize it.)
 
 You call the function @code{yypush_parse} to parse a single token.  This
-function is available if either the @code{%define api.push-pull push} or
-@code{%define api.push-pull both} declaration is used.
+function is available if either the @samp{%define api.push-pull push} or
+@samp{%define api.push-pull both} declaration is used.
 @xref{Push Decl, ,A Push Parser}.
 
-@deftypefun int yypush_parse (yypstate *yyps)
+@deftypefun int yypush_parse (yypstate *@var{yyps})
 The value returned by @code{yypush_parse} is the same as for yyparse with
 the following exception: it returns @code{YYPUSH_MORE} if more input is
 required to finish parsing the grammar.
@@ -5843,11 +6331,11 @@ required to finish parsing the grammar.
 More user feedback will help to stabilize it.)
 
 You call the function @code{yypull_parse} to parse the rest of the input
-stream.  This function is available if the @code{%define api.push-pull both}
+stream.  This function is available if the @samp{%define api.push-pull both}
 declaration is used.
 @xref{Push Decl, ,A Push Parser}.
 
-@deftypefun int yypull_parse (yypstate *yyps)
+@deftypefun int yypull_parse (yypstate *@var{yyps})
 The value returned by @code{yypull_parse} is the same as for @code{yyparse}.
 @end deftypefun
 
@@ -5859,8 +6347,8 @@ The value returned by @code{yypull_parse} is the same as for @code{yyparse}.
 More user feedback will help to stabilize it.)
 
 You call the function @code{yypstate_new} to create a new parser instance.
-This function is available if either the @code{%define api.push-pull push} or
-@code{%define api.push-pull both} declaration is used.
+This function is available if either the @samp{%define api.push-pull push} or
+@samp{%define api.push-pull both} declaration is used.
 @xref{Push Decl, ,A Push Parser}.
 
 @deftypefun {yypstate*} yypstate_new (void)
@@ -5878,11 +6366,11 @@ allocated.
 More user feedback will help to stabilize it.)
 
 You call the function @code{yypstate_delete} to delete a parser instance.
-function is available if either the @code{%define api.push-pull push} or
-@code{%define api.push-pull both} declaration is used.
+function is available if either the @samp{%define api.push-pull push} or
+@samp{%define api.push-pull both} declaration is used.
 @xref{Push Decl, ,A Push Parser}.
 
-@deftypefun void yypstate_delete (yypstate *yyps)
+@deftypefun void yypstate_delete (yypstate *@var{yyps})
 This function will reclaim the memory associated with a parser instance.
 After this call, you should no longer attempt to use the parser instance.
 @end deftypefun
@@ -5947,7 +6435,7 @@ yylex (void)
     return 0;
   @dots{}
   if (c == '+' || c == '-')
-    return c;      /* Assume token type for `+' is '+'.  */
+    return c;      /* Assume token type for '+' is '+'.  */
   @dots{}
   return INT;      /* Return the type of the token.  */
   @dots{}
@@ -6068,7 +6556,7 @@ The data type of @code{yylloc} has the name @code{YYLTYPE}.
 @node Pure Calling
 @subsection Calling Conventions for Pure Parsers
 
-When you use the Bison declaration @code{%define api.pure} to request a
+When you use the Bison declaration @code{%define api.pure full} to request a
 pure, reentrant parser, the global communication variables @code{yylval}
 and @code{yylloc} cannot be used.  (@xref{Pure Decl, ,A Pure (Reentrant)
 Parser}.)  In such parsers the two global variables are replaced by
@@ -6092,46 +6580,59 @@ textual locations, then the type @code{YYLTYPE} will not be defined.  In
 this case, omit the second argument; @code{yylex} will be called with
 only one argument.
 
-
-If you wish to pass the additional parameter data to @code{yylex}, use
+If you wish to pass additional arguments to @code{yylex}, use
 @code{%lex-param} just like @code{%parse-param} (@pxref{Parser
-Function}).
+Function}).  To pass additional arguments to both @code{yylex} and
+@code{yyparse}, use @code{%param}.
 
-@deffn {Directive} lex-param @{@var{argument-declaration}@}
+@deffn {Directive} %lex-param @{@var{argument-declaration}@} @dots{}
 @findex %lex-param
-Declare that the braced-code @var{argument-declaration} is an
-additional @code{yylex} argument declaration.
+Specify that @var{argument-declaration} are additional @code{yylex} argument
+declarations.  You may pass one or more such declarations, which is
+equivalent to repeating @code{%lex-param}.
+@end deffn
+
+@deffn {Directive} %param @{@var{argument-declaration}@} @dots{}
+@findex %param
+Specify that @var{argument-declaration} are additional
+@code{yylex}/@code{yyparse} argument declaration.  This is equivalent to
+@samp{%lex-param @{@var{argument-declaration}@} @dots{} %parse-param
+@{@var{argument-declaration}@} @dots{}}.  You may pass one or more
+declarations, which is equivalent to repeating @code{%param}.
 @end deffn
 
+@noindent
 For instance:
 
 @example
-%parse-param @{int *nastiness@}
-%lex-param   @{int *nastiness@}
-%parse-param @{int *randomness@}
+%lex-param   @{scanner_mode *mode@}
+%parse-param @{parser_mode *mode@}
+%param       @{environment_type *env@}
 @end example
 
 @noindent
 results in the following signatures:
 
 @example
-int yylex   (int *nastiness);
-int yyparse (int *nastiness, int *randomness);
+int yylex   (scanner_mode *mode, environment_type *env);
+int yyparse (parser_mode *mode, environment_type *env);
 @end example
 
-If @code{%define api.pure} is added:
+If @samp{%define api.pure full} is added:
 
 @example
-int yylex   (YYSTYPE *lvalp, int *nastiness);
-int yyparse (int *nastiness, int *randomness);
+int yylex   (YYSTYPE *lvalp, scanner_mode *mode, environment_type *env);
+int yyparse (parser_mode *mode, environment_type *env);
 @end example
 
 @noindent
-and finally, if both @code{%define api.pure} and @code{%locations} are used:
+and finally, if both @samp{%define api.pure full} and @code{%locations} are
+used:
 
 @example
-int yylex   (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);
-int yyparse (int *nastiness, int *randomness);
+int yylex   (YYSTYPE *lvalp, YYLTYPE *llocp,
+             scanner_mode *mode, environment_type *env);
+int yyparse (parser_mode *mode, environment_type *env);
 @end example
 
 @node Error Reporting
@@ -6141,7 +6642,7 @@ int yyparse (int *nastiness, int *randomness);
 @cindex parse error
 @cindex syntax error
 
-The Bison parser detects a @dfn{syntax error} or @dfn{parse error}
+The Bison parser detects a @dfn{syntax error} (or @dfn{parse error})
 whenever it reads a token which cannot satisfy any syntax rule.  An
 action in the grammar can also explicitly proclaim an error, using the
 macro @code{YYERROR} (@pxref{Action Features, ,Special Features for Use
@@ -6153,8 +6654,8 @@ called by @code{yyparse} whenever a syntax error is found, and it
 receives one argument.  For a syntax error, the string is normally
 @w{@code{"syntax error"}}.
 
-@findex %error-verbose
-If you invoke the directive @code{%error-verbose} in the Bison declarations
+@findex %define parse.error
+If you invoke @samp{%define parse.error verbose} in the Bison declarations
 section (@pxref{Bison Declarations, ,The Bison Declarations Section}), then
 Bison provides a more verbose and specific error message string instead of
 just plain @w{@code{"syntax error"}}.  However, that message sometimes
@@ -6191,50 +6692,16 @@ error recovery if you have written suitable error recovery grammar rules
 immediately return 1.
 
 Obviously, in location tracking pure parsers, @code{yyerror} should have
-an access to the current location.
-This is indeed the case for the GLR
-parsers, but not for the Yacc parser, for historical reasons.  I.e., if
-@samp{%locations %define api.pure} is passed then the prototypes for
-@code{yyerror} are:
-
-@example
-void yyerror (char const *msg);                 /* Yacc parsers.  */
-void yyerror (YYLTYPE *locp, char const *msg);  /* GLR parsers.   */
-@end example
-
-If @samp{%parse-param @{int *nastiness@}} is used, then:
-
-@example
-void yyerror (int *nastiness, char const *msg);  /* Yacc parsers.  */
-void yyerror (int *nastiness, char const *msg);  /* GLR parsers.   */
-@end example
-
-Finally, GLR and Yacc parsers share the same @code{yyerror} calling
-convention for absolutely pure parsers, i.e., when the calling
-convention of @code{yylex} @emph{and} the calling convention of
-@code{%define api.pure} are pure.
-I.e.:
-
-@example
-/* Location tracking.  */
-%locations
-/* Pure yylex.  */
-%define api.pure
-%lex-param   @{int *nastiness@}
-/* Pure yyparse.  */
-%parse-param @{int *nastiness@}
-%parse-param @{int *randomness@}
-@end example
+an access to the current location. With @code{%define api.pure}, this is
+indeed the case for the GLR parsers, but not for the Yacc parser, for
+historical reasons, and this is the why @code{%define api.pure full} should be
+prefered over @code{%define api.pure}.
 
-@noindent
-results in the following signatures for all the parser kinds:
+When @code{%locations %define api.pure full} is used, @code{yyerror} has the
+following signature:
 
 @example
-int yylex (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);
-int yyparse (int *nastiness, int *randomness);
-void yyerror (YYLTYPE *locp,
-              int *nastiness, int *randomness,
-              char const *msg);
+void yyerror (YYLTYPE *locp, char const *msg);
 @end example
 
 @noindent
@@ -6376,7 +6843,6 @@ Actions}).
 @end deffn
 
 @deffn {Value} @@$
-@findex @@$
 Acts like a structure variable containing information on the textual
 location of the grouping made by the current rule.  @xref{Tracking
 Locations}.
@@ -6435,7 +6901,7 @@ GNU Automake.
 @item
 @cindex bison-i18n.m4
 Into the directory containing the GNU Autoconf macros used
-by the package---often called @file{m4}---copy the
+by the package ---often called @file{m4}--- copy the
 @file{bison-i18n.m4} file installed by Bison under
 @samp{share/aclocal/bison-i18n.m4} in Bison's installation directory.
 For example:
@@ -6596,7 +7062,7 @@ expr:
 term:
   '(' expr ')'
 | term '!'
-| NUMBER
+| "number"
 ;
 @end group
 @end example
@@ -6635,20 +7101,20 @@ statements, with a pair of rules like this:
 @example
 @group
 if_stmt:
-  IF expr THEN stmt
-| IF expr THEN stmt ELSE stmt
+  "if" expr "then" stmt
+| "if" expr "then" stmt "else" stmt
 ;
 @end group
 @end example
 
 @noindent
-Here we assume that @code{IF}, @code{THEN} and @code{ELSE} are
-terminal symbols for specific keyword tokens.
+Here @code{"if"}, @code{"then"} and @code{"else"} are terminal symbols for
+specific keyword tokens.
 
-When the @code{ELSE} token is read and becomes the lookahead token, the
+When the @code{"else"} token is read and becomes the lookahead token, the
 contents of the stack (assuming the input is valid) are just right for
 reduction by the first rule.  But it is also legitimate to shift the
-@code{ELSE}, because that would lead to eventual reduction by the second
+@code{"else"}, because that would lead to eventual reduction by the second
 rule.
 
 This situation, where either a shift or a reduction would be valid, is
@@ -6657,14 +7123,14 @@ these conflicts by choosing to shift, unless otherwise directed by
 operator precedence declarations.  To see the reason for this, let's
 contrast it with the other alternative.
 
-Since the parser prefers to shift the @code{ELSE}, the result is to attach
+Since the parser prefers to shift the @code{"else"}, the result is to attach
 the else-clause to the innermost if-statement, making these two inputs
 equivalent:
 
 @example
-if x then if y then win (); else lose;
+if x then if y then win; else lose;
 
-if x then do; if y then win (); else lose; end;
+if x then do; if y then win; else lose; end;
 @end example
 
 But if the parser chose to reduce when possible rather than shift, the
@@ -6672,9 +7138,9 @@ result would be to attach the else-clause to the outermost if-statement,
 making these two inputs equivalent:
 
 @example
-if x then if y then win (); else lose;
+if x then if y then win; else lose;
 
-if x then do; if y then win (); end; else lose;
+if x then do; if y then win; end; else lose;
 @end example
 
 The conflict exists because the grammar as written is ambiguous: either
@@ -6687,11 +7153,16 @@ This particular ambiguity was first encountered in the specifications of
 Algol 60 and is called the ``dangling @code{else}'' ambiguity.
 
 To avoid warnings from Bison about predictable, legitimate shift/reduce
-conflicts, use the @code{%expect @var{n}} declaration.
+conflicts, you can use the @code{%expect @var{n}} declaration.
 There will be no warning as long as the number of shift/reduce conflicts
 is exactly @var{n}, and Bison will report an error if there is a
 different number.
-@xref{Expect Decl, ,Suppressing Conflict Warnings}.
+@xref{Expect Decl, ,Suppressing Conflict Warnings}.  However, we don't
+recommend the use of @code{%expect} (except @samp{%expect 0}!), as an equal
+number of conflicts does not mean that they are the @emph{same}.  When
+possible, you should rather use precedence directives to @emph{fix} the
+conflicts explicitly (@pxref{Non Operators,, Using Precedence For Non
+Operators}).
 
 The definition of @code{if_stmt} above is solely to blame for the
 conflict, but the conflict does not actually appear without additional
@@ -6699,10 +7170,7 @@ rules.  Here is a complete Bison grammar file that actually manifests
 the conflict:
 
 @example
-@group
-%token IF THEN ELSE variable
 %%
-@end group
 @group
 stmt:
   expr
@@ -6712,13 +7180,13 @@ stmt:
 
 @group
 if_stmt:
-  IF expr THEN stmt
-| IF expr THEN stmt ELSE stmt
+  "if" expr "then" stmt
+| "if" expr "then" stmt "else" stmt
 ;
 @end group
 
 expr:
-  variable
+  "identifier"
 ;
 @end example
 
@@ -6734,9 +7202,11 @@ shift and when to reduce.
 
 @menu
 * Why Precedence::    An example showing why precedence is needed.
-* Using Precedence::  How to specify precedence in Bison grammars.
+* Using Precedence::  How to specify precedence and associativity.
+* Precedence Only::   How to specify precedence only.
 * Precedence Examples::  How these features are used in the previous example.
 * How Precedence::    How they work.
+* Non Operators::     Using precedence for general conflicts.
 @end menu
 
 @node Why Precedence
@@ -6790,8 +7260,9 @@ makes right-associativity.
 @node Using Precedence
 @subsection Specifying Operator Precedence
 @findex %left
-@findex %right
 @findex %nonassoc
+@findex %precedence
+@findex %right
 
 Bison allows you to specify these choices with the operator precedence
 declarations @code{%left} and @code{%right}.  Each such declaration
@@ -6801,13 +7272,63 @@ those operators left-associative and the @code{%right} declaration makes
 them right-associative.  A third alternative is @code{%nonassoc}, which
 declares that it is a syntax error to find the same operator twice ``in a
 row''.
+The last alternative, @code{%precedence}, allows to define only
+precedence and no associativity at all.  As a result, any
+associativity-related conflict that remains will be reported as an
+compile-time error.  The directive @code{%nonassoc} creates run-time
+error: using the operator in a associative way is a syntax error.  The
+directive @code{%precedence} creates compile-time errors: an operator
+@emph{can} be involved in an associativity-related conflict, contrary to
+what expected the grammar author.
 
 The relative precedence of different operators is controlled by the
-order in which they are declared.  The first @code{%left} or
-@code{%right} declaration in the file declares the operators whose
+order in which they are declared.  The first precedence/associativity
+declaration in the file declares the operators whose
 precedence is lowest, the next such declaration declares the operators
 whose precedence is a little higher, and so on.
 
+@node Precedence Only
+@subsection Specifying Precedence Only
+@findex %precedence
+
+Since POSIX Yacc defines only @code{%left}, @code{%right}, and
+@code{%nonassoc}, which all defines precedence and associativity, little
+attention is paid to the fact that precedence cannot be defined without
+defining associativity.  Yet, sometimes, when trying to solve a
+conflict, precedence suffices.  In such a case, using @code{%left},
+@code{%right}, or @code{%nonassoc} might hide future (associativity
+related) conflicts that would remain hidden.
+
+The dangling @code{else} ambiguity (@pxref{Shift/Reduce, , Shift/Reduce
+Conflicts}) can be solved explicitly.  This shift/reduce conflicts occurs
+in the following situation, where the period denotes the current parsing
+state:
+
+@example
+if @var{e1} then if  @var{e2} then @var{s1} . else @var{s2}
+@end example
+
+The conflict involves the reduction of the rule @samp{IF expr THEN
+stmt}, which precedence is by default that of its last token
+(@code{THEN}), and the shifting of the token @code{ELSE}.  The usual
+disambiguation (attach the @code{else} to the closest @code{if}),
+shifting must be preferred, i.e., the precedence of @code{ELSE} must be
+higher than that of @code{THEN}.  But neither is expected to be involved
+in an associativity related conflict, which can be specified as follows.
+
+@example
+%precedence THEN
+%precedence ELSE
+@end example
+
+The unary-minus is another typical example where associativity is
+usually over-specified, see @ref{Infix Calc, , Infix Notation
+Calculator: @code{calc}}.  The @code{%left} directive is traditionally
+used to declare the precedence of @code{NEG}, which is more than needed
+since it also defines its associativity.  While this is harmless in the
+traditional example, who knows how @code{NEG} might be used in future
+evolutions of the grammar@dots{}
+
 @node Precedence Examples
 @subsection Precedence Examples
 
@@ -6824,16 +7345,11 @@ would declare them in groups of equal precedence.  For example, @code{'+'} is
 declared with @code{'-'}:
 
 @example
-%left '<' '>' '=' NE LE GE
+%left '<' '>' '=' "!=" "<=" ">="
 %left '+' '-'
 %left '*' '/'
 @end example
 
-@noindent
-(Here @code{NE} and so on stand for the operators for ``not equal''
-and so on.  We assume that these tokens are more than one character long
-and therefore are represented by names, not character literals.)
-
 @node How Precedence
 @subsection How Precedence Works
 
@@ -6856,6 +7372,44 @@ resolved.
 Not all rules and not all tokens have precedence.  If either the rule or
 the lookahead token has no precedence, then the default is to shift.
 
+@node Non Operators
+@subsection Using Precedence For Non Operators
+
+Using properly precedence and associativity directives can help fixing
+shift/reduce conflicts that do not involve arithmetics-like operators.  For
+instance, the ``dangling @code{else}'' problem (@pxref{Shift/Reduce, ,
+Shift/Reduce Conflicts}) can be solved elegantly in two different ways.
+
+In the present case, the conflict is between the token @code{"else"} willing
+to be shifted, and the rule @samp{if_stmt: "if" expr "then" stmt}, asking
+for reduction.  By default, the precedence of a rule is that of its last
+token, here @code{"then"}, so the conflict will be solved appropriately
+by giving @code{"else"} a precedence higher than that of @code{"then"}, for
+instance as follows:
+
+@example
+@group
+%precedence "then"
+%precedence "else"
+@end group
+@end example
+
+Alternatively, you may give both tokens the same precedence, in which case
+associativity is used to solve the conflict.  To preserve the shift action,
+use right associativity:
+
+@example
+%right "then" "else"
+@end example
+
+Neither solution is perfect however.  Since Bison does not provide, so far,
+``scoped'' precedence, both force you to declare the precedence
+of these keywords with respect to the other operators your grammar.
+Therefore, instead of being warned about new conflicts you would be unaware
+of (e.g., a shift/reduce conflict due to @samp{if test then 1 else 2 + 3}
+being ambiguous: @samp{if test then 1 else (2 + 3)} or @samp{(if test then 1
+else 2) + 3}?), the conflict will be already ``fixed''.
+
 @node Contextual Precedence
 @section Context-Dependent Precedence
 @cindex context-dependent precedence
@@ -6869,8 +7423,8 @@ outlandish at first, but it is really very common.  For example, a minus
 sign typically has a very high precedence as a unary operator, and a
 somewhat lower precedence (lower than multiplication) as a binary operator.
 
-The Bison precedence declarations, @code{%left}, @code{%right} and
-@code{%nonassoc}, can only be used once for a given token; so a token has
+The Bison precedence declarations
+can only be used once for a given token; so a token has
 only one precedence declared in this way.  For context-dependent
 precedence, you need to use an additional mechanism: the @code{%prec}
 modifier for rules.
@@ -6978,7 +7532,7 @@ of zero or more @code{word} groupings.
 @example
 @group
 sequence:
-  /* empty */    @{ printf ("empty sequence\n"); @}
+  %empty         @{ printf ("empty sequence\n"); @}
 | maybeword
 | sequence word  @{ printf ("added word %s\n", $2); @}
 ;
@@ -6986,8 +7540,8 @@ sequence:
 
 @group
 maybeword:
-  /* empty */   @{ printf ("empty maybeword\n"); @}
-| word          @{ printf ("single word %s\n", $1); @}
+  %empty    @{ printf ("empty maybeword\n"); @}
+| word      @{ printf ("single word %s\n", $1); @}
 ;
 @end group
 @end example
@@ -7016,30 +7570,38 @@ reduce/reduce conflict must be studied and usually eliminated.  Here is the
 proper way to define @code{sequence}:
 
 @example
+@group
 sequence:
-  /* empty */    @{ printf ("empty sequence\n"); @}
+  %empty         @{ printf ("empty sequence\n"); @}
 | sequence word  @{ printf ("added word %s\n", $2); @}
 ;
+@end group
 @end example
 
 Here is another common error that yields a reduce/reduce conflict:
 
 @example
+@group
 sequence:
-  /* empty */
+  %empty
 | sequence words
 | sequence redirects
 ;
+@end group
 
+@group
 words:
-  /* empty */
+  %empty
 | words word
 ;
+@end group
 
+@group
 redirects:
-  /* empty */
+  %empty
 | redirects redirect
 ;
+@end group
 @end example
 
 @noindent
@@ -7059,7 +7621,7 @@ of sequence:
 
 @example
 sequence:
-  /* empty */
+  %empty
 | sequence word
 | sequence redirect
 ;
@@ -7071,7 +7633,7 @@ from being empty:
 @example
 @group
 sequence:
-  /* empty */
+  %empty
 | sequence words
 | sequence redirects
 ;
@@ -7092,6 +7654,58 @@ redirects:
 @end group
 @end example
 
+Yet this proposal introduces another kind of ambiguity!  The input
+@samp{word word} can be parsed as a single @code{words} composed of two
+@samp{word}s, or as two one-@code{word} @code{words} (and likewise for
+@code{redirect}/@code{redirects}).  However this ambiguity is now a
+shift/reduce conflict, and therefore it can now be addressed with precedence
+directives.
+
+To simplify the matter, we will proceed with @code{word} and @code{redirect}
+being tokens: @code{"word"} and @code{"redirect"}.
+
+To prefer the longest @code{words}, the conflict between the token
+@code{"word"} and the rule @samp{sequence: sequence words} must be resolved
+as a shift.  To this end, we use the same techniques as exposed above, see
+@ref{Non Operators,, Using Precedence For Non Operators}.  One solution
+relies on precedences: use @code{%prec} to give a lower precedence to the
+rule:
+
+@example
+%precedence "word"
+%precedence "sequence"
+%%
+@group
+sequence:
+  %empty
+| sequence word      %prec "sequence"
+| sequence redirect  %prec "sequence"
+;
+@end group
+
+@group
+words:
+  word
+| words "word"
+;
+@end group
+@end example
+
+Another solution relies on associativity: provide both the token and the
+rule with the same precedence, but make them right-associative:
+
+@example
+%right "word" "redirect"
+%%
+@group
+sequence:
+  %empty
+| sequence word      %prec "word"
+| sequence redirect  %prec "redirect"
+;
+@end group
+@end example
+
 @node Mysterious Conflicts
 @section Mysterious Conflicts
 @cindex Mysterious Conflicts
@@ -7101,8 +7715,6 @@ Here is an example:
 
 @example
 @group
-%token ID
-
 %%
 def: param_spec return_spec ',';
 param_spec:
@@ -7110,17 +7722,18 @@ param_spec:
 | name_list ':' type
 ;
 @end group
+
 @group
 return_spec:
   type
 | name ':' type
 ;
 @end group
+
+type: "id";
+
 @group
-type: ID;
-@end group
-@group
-name: ID;
+name: "id";
 name_list:
   name
 | name ',' name_list
@@ -7128,16 +7741,16 @@ name_list:
 @end group
 @end example
 
-It would seem that this grammar can be parsed with only a single token
-of lookahead: when a @code{param_spec} is being read, an @code{ID} is
-a @code{name} if a comma or colon follows, or a @code{type} if another
-@code{ID} follows.  In other words, this grammar is LR(1).
+It would seem that this grammar can be parsed with only a single token of
+lookahead: when a @code{param_spec} is being read, an @code{"id"} is a
+@code{name} if a comma or colon follows, or a @code{type} if another
+@code{"id"} follows.  In other words, this grammar is LR(1).
 
 @cindex LR
 @cindex LALR
 However, for historical reasons, Bison cannot by default handle all
 LR(1) grammars.
-In this grammar, two contexts, that after an @code{ID} at the beginning
+In this grammar, two contexts, that after an @code{"id"} at the beginning
 of a @code{param_spec} and likewise at the beginning of a
 @code{return_spec}, are similar enough that Bison assumes they are the
 same.
@@ -7168,41 +7781,43 @@ distinct.  In the above example, adding one rule to
 
 @example
 @group
-%token BOGUS
-@dots{}
-%%
 @dots{}
 return_spec:
   type
 | name ':' type
-| ID BOGUS       /* This rule is never used.  */
+| "id" "bogus"       /* This rule is never used.  */
 ;
 @end group
 @end example
 
 This corrects the problem because it introduces the possibility of an
-additional active rule in the context after the @code{ID} at the beginning of
+additional active rule in the context after the @code{"id"} at the beginning of
 @code{return_spec}.  This rule is not active in the corresponding context
 in a @code{param_spec}, so the two contexts receive distinct parser states.
-As long as the token @code{BOGUS} is never generated by @code{yylex},
+As long as the token @code{"bogus"} is never generated by @code{yylex},
 the added rule cannot alter the way actual input is parsed.
 
 In this particular example, there is another way to solve the problem:
-rewrite the rule for @code{return_spec} to use @code{ID} directly
+rewrite the rule for @code{return_spec} to use @code{"id"} directly
 instead of via @code{name}.  This also causes the two confusing
 contexts to have different sets of active rules, because the one for
 @code{return_spec} activates the altered rule for @code{return_spec}
 rather than the one for @code{name}.
 
 @example
+@group
 param_spec:
   type
 | name_list ':' type
 ;
+@end group
+
+@group
 return_spec:
   type
-| ID ':' type
+| "id" ':' type
 ;
+@end group
 @end example
 
 For a more detailed exposition of LALR(1) parsers and parser
@@ -7215,9 +7830,9 @@ The default behavior of Bison's LR-based parsers is chosen mostly for
 historical reasons, but that behavior is often not robust.  For example, in
 the previous section, we discussed the mysterious conflicts that can be
 produced by LALR(1), Bison's default parser table construction algorithm.
-Another example is Bison's @code{%error-verbose} directive, which instructs
-the generated parser to produce verbose syntax error messages, which can
-sometimes contain incorrect information.
+Another example is Bison's @code{%define parse.error verbose} directive,
+which instructs the generated parser to produce verbose syntax error
+messages, which can sometimes contain incorrect information.
 
 In this section, we explore several modern features of Bison that allow you
 to tune fundamental aspects of the generated LR-based parsers.  Some of
@@ -7259,9 +7874,9 @@ mysterious behavior altogether.  You simply need to activate a more powerful
 parser table construction algorithm by using the @code{%define lr.type}
 directive.
 
-@deffn {Directive} {%define lr.type @var{TYPE}}
+@deffn {Directive} {%define lr.type} @var{type}
 Specify the type of parser tables within the LR(1) family.  The accepted
-values for @var{TYPE} are:
+values for @var{type} are:
 
 @itemize
 @item @code{lalr} (default)
@@ -7307,7 +7922,8 @@ There are at least two scenarios where LALR can be worthwhile:
 
 @cindex GLR with LALR
 When employing GLR parsers (@pxref{GLR Parsers}), if you do not resolve any
-conflicts statically (for example, with @code{%left} or @code{%prec}), then
+conflicts statically (for example, with @code{%left} or @code{%precedence}),
+then
 the parser explores all potential parses of any given input.  In this case,
 the choice of parser table construction algorithm is guaranteed not to alter
 the language accepted by the parser.  LALR parser tables are the smallest
@@ -7364,7 +7980,7 @@ and the benefits of IELR, @pxref{Bibliography,,Denny 2008 March}, and
 @node Default Reductions
 @subsection Default Reductions
 @cindex default reductions
-@findex %define lr.default-reductions
+@findex %define lr.default-reduction
 @findex %nonassoc
 
 After parser table construction, Bison identifies the reduction with the
@@ -7446,11 +8062,11 @@ token for which there is a conflict.  The correct action in this case is to
 split the parse instead.
 
 To adjust which states have default reductions enabled, use the
-@code{%define lr.default-reductions} directive.
+@code{%define lr.default-reduction} directive.
 
-@deffn {Directive} {%define lr.default-reductions @var{WHERE}}
+@deffn {Directive} {%define lr.default-reduction} @var{where}
 Specify the kind of states that are permitted to contain default reductions.
-The accepted values of @var{WHERE} are:
+The accepted values of @var{where} are:
 @itemize
 @item @code{most} (default for LALR and IELR)
 @item @code{consistent}
@@ -7488,7 +8104,7 @@ that solves these problems for canonical LR, IELR, and LALR without
 sacrificing @code{%nonassoc}, default reductions, or state merging.  You can
 enable LAC with the @code{%define parse.lac} directive.
 
-@deffn {Directive} {%define parse.lac @var{VALUE}}
+@deffn {Directive} {%define parse.lac} @var{value}
 Enable LAC to improve syntax error handling.
 @itemize
 @item @code{none} (default)
@@ -7571,7 +8187,7 @@ parser community for years, for the publication that introduces LAC,
 
 @node Unreachable States
 @subsection Unreachable States
-@findex %define lr.keep-unreachable-states
+@findex %define lr.keep-unreachable-state
 @cindex unreachable states
 
 If there exists no sequence of transitions from the parser's start state to
@@ -7584,9 +8200,9 @@ resolution because they are useless in the generated parser.  However,
 keeping unreachable states is sometimes useful when trying to understand the
 relationship between the parser and the grammar.
 
-@deffn {Directive} {%define lr.keep-unreachable-states @var{VALUE}}
+@deffn {Directive} {%define lr.keep-unreachable-state} @var{value}
 Request that Bison allow unreachable states to remain in the parser tables.
-@var{VALUE} must be a Boolean.  The default is @code{false}.
+@var{value} must be a Boolean.  The default is @code{false}.
 @end deffn
 
 There are a few caveats to consider:
@@ -7741,12 +8357,14 @@ that allows variable-length arrays.  The default is 200.
 
 Do not allow @code{YYINITDEPTH} to be greater than @code{YYMAXDEPTH}.
 
-@c FIXME: C++ output.
-Because of semantic differences between C and C++, the deterministic
-parsers in C produced by Bison cannot grow when compiled
-by C++ compilers.  In this precise case (compiling a C parser as C++) you are
-suggested to grow @code{YYINITDEPTH}.  The Bison maintainers hope to fix
-this deficiency in a future release.
+You can generate a deterministic parser containing C++ user code from
+the default (C) skeleton, as well as from the C++ skeleton
+(@pxref{C++ Parsers}).  However, if you do use the default skeleton
+and want to allow the parsing stack to grow,
+be careful not to use semantic types or location types that require
+non-trivial copy constructors.
+The C skeleton bypasses these constructors when copying data to
+new, larger stacks.
 
 @node Error Recovery
 @chapter Error Recovery
@@ -7778,7 +8396,7 @@ For example:
 
 @example
 stmts:
-  /* empty string */
+  %empty
 | stmts '\n'
 | stmts exp '\n'
 | stmts error '\n'
@@ -8088,11 +8706,31 @@ clear the flag.
 
 Developing a parser can be a challenge, especially if you don't understand
 the algorithm (@pxref{Algorithm, ,The Bison Parser Algorithm}).  This
-chapter explains how to generate and read the detailed description of the
-automaton, and how to enable and understand the parser run-time traces.
+chapter explains how understand and debug a parser.
+
+The first sections focus on the static part of the parser: its structure.
+They explain how to generate and read the detailed description of the
+automaton.  There are several formats available:
+@itemize @minus
+@item
+as text, see @ref{Understanding, , Understanding Your Parser};
+
+@item
+as a graph, see @ref{Graphviz,, Visualizing Your Parser};
+
+@item
+or as a markup report that can be turned, for instance, into HTML, see
+@ref{Xml,, Visualizing your parser in multiple formats}.
+@end itemize
+
+The last section focuses on the dynamic part of the parser: how to enable
+and understand the parser run-time traces (@pxref{Tracing, ,Tracing Your
+Parser}).
 
 @menu
 * Understanding::     Understanding the structure of your parser.
+* Graphviz::          Getting a visual representation of the parser.
+* Xml::               Getting a markup representation of the parser.
 * Tracing::           Tracing the execution of your parser.
 @end menu
 
@@ -8102,8 +8740,7 @@ automaton, and how to enable and understand the parser run-time traces.
 As documented elsewhere (@pxref{Algorithm, ,The Bison Parser Algorithm})
 Bison parsers are @dfn{shift/reduce automata}.  In some cases (much more
 frequent than one would hope), looking at this automaton is required to
-tune or simply fix a parser.  Bison provides two different
-representation of it, either textually or graphically (as a DOT file).
+tune or simply fix a parser.
 
 The textual file is generated when the options @option{--report} or
 @option{--verbose} are specified, see @ref{Invocation, , Invoking
@@ -8117,9 +8754,12 @@ The following grammar file, @file{calc.y}, will be used in the sequel:
 
 @example
 %token NUM STR
+@group
 %left '+' '-'
 %left '*'
+@end group
 %%
+@group
 exp:
   exp '+' exp
 | exp '-' exp
@@ -8127,6 +8767,7 @@ exp:
 | exp '/' exp
 | NUM
 ;
+@end group
 useless: STR;
 %%
 @end example
@@ -8136,8 +8777,8 @@ useless: STR;
 @example
 calc.y: warning: 1 nonterminal useless in grammar
 calc.y: warning: 1 rule useless in grammar
-calc.y:11.1-7: warning: nonterminal useless in grammar: useless
-calc.y:11.10-12: warning: rule useless in grammar: useless: STR
+calc.y:12.1-7: warning: nonterminal useless in grammar: useless
+calc.y:12.10-12: warning: rule useless in grammar: useless: STR
 calc.y: conflicts: 7 shift/reduce
 @end example
 
@@ -8231,7 +8872,7 @@ item is a production rule together with a point (@samp{.}) marking
 the location of the input cursor.
 
 @example
-state 0
+State 0
 
     0 $accept: . exp $end
 
@@ -8261,7 +8902,7 @@ you want to see more detail you can invoke @command{bison} with
 @option{--report=itemset} to list the derived items as well:
 
 @example
-state 0
+State 0
 
     0 $accept: . exp $end
     1 exp: . exp '+' exp
@@ -8279,7 +8920,7 @@ state 0
 In the state 1@dots{}
 
 @example
-state 1
+State 1
 
     5 exp: NUM .
 
@@ -8289,11 +8930,11 @@ state 1
 @noindent
 the rule 5, @samp{exp: NUM;}, is completed.  Whatever the lookahead token
 (@samp{$default}), the parser will reduce it.  If it was coming from
-state 0, then, after this reduction it will return to state 0, and will
+State 0, then, after this reduction it will return to state 0, and will
 jump to state 2 (@samp{exp: go to state 2}).
 
 @example
-state 2
+State 2
 
     0 $accept: exp . $end
     1 exp: exp . '+' exp
@@ -8321,7 +8962,7 @@ The state 3 is named the @dfn{final state}, or the @dfn{accepting
 state}:
 
 @example
-state 3
+State 3
 
     0 $accept: exp $end .
 
@@ -8336,7 +8977,7 @@ The interpretation of states 4 to 7 is straightforward, and is left to
 the reader.
 
 @example
-state 4
+State 4
 
     1 exp: exp '+' . exp
 
@@ -8345,7 +8986,7 @@ state 4
     exp  go to state 8
 
 
-state 5
+State 5
 
     2 exp: exp '-' . exp
 
@@ -8354,7 +8995,7 @@ state 5
     exp  go to state 9
 
 
-state 6
+State 6
 
     3 exp: exp '*' . exp
 
@@ -8363,7 +9004,7 @@ state 6
     exp  go to state 10
 
 
-state 7
+State 7
 
     4 exp: exp '/' . exp
 
@@ -8376,7 +9017,7 @@ As was announced in beginning of the report, @samp{State 8 conflicts:
 1 shift/reduce}:
 
 @example
-state 8
+State 8
 
     1 exp: exp . '+' exp
     1    | exp '+' exp .
@@ -8419,7 +9060,7 @@ with some set of possible lookahead tokens.  When run with
 @option{--report=lookahead}, Bison specifies these lookahead tokens:
 
 @example
-state 8
+State 8
 
     1 exp: exp . '+' exp
     1    | exp '+' exp .  [$end, '+', '-', '/']
@@ -8451,7 +9092,7 @@ The remaining states are similar:
 
 @example
 @group
-state 9
+State 9
 
     1 exp: exp . '+' exp
     2    | exp . '-' exp
@@ -8467,7 +9108,7 @@ state 9
 @end group
 
 @group
-state 10
+State 10
 
     1 exp: exp . '+' exp
     2    | exp . '-' exp
@@ -8482,7 +9123,7 @@ state 10
 @end group
 
 @group
-state 11
+State 11
 
     1 exp: exp . '+' exp
     2    | exp . '-' exp
@@ -8505,44 +9146,214 @@ state 11
 
 @noindent
 Observe that state 11 contains conflicts not only due to the lack of
-precedence of @samp{/} with respect to @samp{+}, @samp{-}, and
-@samp{*}, but also because the
-associativity of @samp{/} is not specified.
+precedence of @samp{/} with respect to @samp{+}, @samp{-}, and @samp{*}, but
+also because the associativity of @samp{/} is not specified.
 
+Bison may also produce an HTML version of this output, via an XML file and
+XSLT processing (@pxref{Xml,,Visualizing your parser in multiple formats}).
 
-@node Tracing
-@section Tracing Your Parser
-@findex yydebug
-@cindex debugging
-@cindex tracing the parser
+@c ================================================= Graphical Representation
 
-When a Bison grammar compiles properly but parses ``incorrectly'', the
-@code{yydebug} parser-trace feature helps figuring out why.
+@node Graphviz
+@section Visualizing Your Parser
+@cindex dot
 
-@menu
-* Enabling Traces::    Activating run-time trace support
-* Mfcalc Traces::      Extending @code{mfcalc} to support traces
-* The YYPRINT Macro::  Obsolete interface for semantic value reports
-@end menu
+As another means to gain better understanding of the shift/reduce
+automaton corresponding to the Bison parser, a DOT file can be generated. Note
+that debugging a real grammar with this is tedious at best, and impractical
+most of the times, because the generated files are huge (the generation of
+a PDF or PNG file from it will take very long, and more often than not it will
+fail due to memory exhaustion). This option was rather designed for beginners,
+to help them understand LR parsers.
 
-@node Enabling Traces
-@subsection  Enabling Traces
-There are several means to enable compilation of trace facilities:
+This file is generated when the @option{--graph} option is specified
+(@pxref{Invocation, , Invoking Bison}).  Its name is made by removing
+@samp{.tab.c} or @samp{.c} from the parser implementation file name, and
+adding @samp{.dot} instead.  If the grammar file is @file{foo.y}, the
+Graphviz output file is called @file{foo.dot}.  A DOT file may also be
+produced via an XML file and XSLT processing (@pxref{Xml,,Visualizing your
+parser in multiple formats}).
 
-@table @asis
-@item the macro @code{YYDEBUG}
-@findex YYDEBUG
-Define the macro @code{YYDEBUG} to a nonzero value when you compile the
-parser.  This is compliant with POSIX Yacc.  You could use
-@samp{-DYYDEBUG=1} as a compiler option or you could put @samp{#define
-YYDEBUG 1} in the prologue of the grammar file (@pxref{Prologue, , The
-Prologue}).
 
-If the @code{%define} variable @code{api.prefix} is used (@pxref{Multiple
-Parsers, ,Multiple Parsers in the Same Program}), for instance @samp{%define
-api.prefix x}, then if @code{CDEBUG} is defined, its value controls the
-tracing feature (enabled if and only if nonzero); otherwise tracing is
-enabled if and only if @code{YYDEBUG} is nonzero.
+The following grammar file, @file{rr.y}, will be used in the sequel:
+
+@example
+%%
+@group
+exp: a ";" | b ".";
+a: "0";
+b: "0";
+@end group
+@end example
+
+The graphical output
+@ifnotinfo
+(see @ref{fig:graph})
+@end ifnotinfo
+is very similar to the textual one, and as such it is easier understood by
+making direct comparisons between them.  @xref{Debugging, , Debugging Your
+Parser}, for a detailled analysis of the textual report.
+
+@ifnotinfo
+@float Figure,fig:graph
+@image{figs/example, 430pt}
+@caption{A graphical rendering of the parser.}
+@end float
+@end ifnotinfo
+
+@subheading Graphical Representation of States
+
+The items (pointed rules) for each state are grouped together in graph nodes.
+Their numbering is the same as in the verbose file. See the following points,
+about transitions, for examples
+
+When invoked with @option{--report=lookaheads}, the lookahead tokens, when
+needed, are shown next to the relevant rule between square brackets as a
+comma separated list. This is the case in the figure for the representation of
+reductions, below.
+
+@sp 1
+
+The transitions are represented as directed edges between the current and
+the target states.
+
+@subheading Graphical Representation of Shifts
+
+Shifts are shown as solid arrows, labelled with the lookahead token for that
+shift. The following describes a reduction in the @file{rr.output} file:
+
+@example
+@group
+State 3
+
+    1 exp: a . ";"
+
+    ";"  shift, and go to state 6
+@end group
+@end example
+
+A Graphviz rendering of this portion of the graph could be:
+
+@center @image{figs/example-shift, 100pt}
+
+@subheading Graphical Representation of Reductions
+
+Reductions are shown as solid arrows, leading to a diamond-shaped node
+bearing the number of the reduction rule. The arrow is labelled with the
+appropriate comma separated lookahead tokens. If the reduction is the default
+action for the given state, there is no such label.
+
+This is how reductions are represented in the verbose file @file{rr.output}:
+@example
+State 1
+
+    3 a: "0" .  [";"]
+    4 b: "0" .  ["."]
+
+    "."       reduce using rule 4 (b)
+    $default  reduce using rule 3 (a)
+@end example
+
+A Graphviz rendering of this portion of the graph could be:
+
+@center @image{figs/example-reduce, 120pt}
+
+When unresolved conflicts are present, because in deterministic parsing
+a single decision can be made, Bison can arbitrarily choose to disable a
+reduction, see @ref{Shift/Reduce, , Shift/Reduce Conflicts}.  Discarded actions
+are distinguished by a red filling color on these nodes, just like how they are
+reported between square brackets in the verbose file.
+
+The reduction corresponding to the rule number 0 is the acceptation
+state. It is shown as a blue diamond, labelled ``Acc''.
+
+@subheading Graphical representation of go tos
+
+The @samp{go to} jump transitions are represented as dotted lines bearing
+the name of the rule being jumped to.
+
+@c ================================================= XML
+
+@node Xml
+@section Visualizing your parser in multiple formats
+@cindex xml
+
+Bison supports two major report formats: textual output
+(@pxref{Understanding, ,Understanding Your Parser}) when invoked
+with option @option{--verbose}, and DOT
+(@pxref{Graphviz,, Visualizing Your Parser}) when invoked with
+option @option{--graph}. However,
+another alternative is to output an XML file that may then be, with
+@command{xsltproc}, rendered as either a raw text format equivalent to the
+verbose file, or as an HTML version of the same file, with clickable
+transitions, or even as a DOT. The @file{.output} and DOT files obtained via
+XSLT have no difference whatsoever with those obtained by invoking
+@command{bison} with options @option{--verbose} or @option{--graph}.
+
+The XML file is generated when the options @option{-x} or
+@option{--xml[=FILE]} are specified, see @ref{Invocation,,Invoking Bison}.
+If not specified, its name is made by removing @samp{.tab.c} or @samp{.c}
+from the parser implementation file name, and adding @samp{.xml} instead.
+For instance, if the grammar file is @file{foo.y}, the default XML output
+file is @file{foo.xml}.
+
+Bison ships with a @file{data/xslt} directory, containing XSL Transformation
+files to apply to the XML file. Their names are non-ambiguous:
+
+@table @file
+@item xml2dot.xsl
+Used to output a copy of the DOT visualization of the automaton.
+@item xml2text.xsl
+Used to output a copy of the @samp{.output} file.
+@item xml2xhtml.xsl
+Used to output an xhtml enhancement of the @samp{.output} file.
+@end table
+
+Sample usage (requires @command{xsltproc}):
+@example
+$ bison -x gr.y
+@group
+$ bison --print-datadir
+/usr/local/share/bison
+@end group
+$ xsltproc /usr/local/share/bison/xslt/xml2xhtml.xsl gr.xml >gr.html
+@end example
+
+@c ================================================= Tracing
+
+@node Tracing
+@section Tracing Your Parser
+@findex yydebug
+@cindex debugging
+@cindex tracing the parser
+
+When a Bison grammar compiles properly but parses ``incorrectly'', the
+@code{yydebug} parser-trace feature helps figuring out why.
+
+@menu
+* Enabling Traces::    Activating run-time trace support
+* Mfcalc Traces::      Extending @code{mfcalc} to support traces
+* The YYPRINT Macro::  Obsolete interface for semantic value reports
+@end menu
+
+@node Enabling Traces
+@subsection  Enabling Traces
+There are several means to enable compilation of trace facilities:
+
+@table @asis
+@item the macro @code{YYDEBUG}
+@findex YYDEBUG
+Define the macro @code{YYDEBUG} to a nonzero value when you compile the
+parser.  This is compliant with POSIX Yacc.  You could use
+@samp{-DYYDEBUG=1} as a compiler option or you could put @samp{#define
+YYDEBUG 1} in the prologue of the grammar file (@pxref{Prologue, , The
+Prologue}).
+
+If the @code{%define} variable @code{api.prefix} is used (@pxref{Multiple
+Parsers, ,Multiple Parsers in the Same Program}), for instance @samp{%define
+api.prefix x}, then if @code{CDEBUG} is defined, its value controls the
+tracing feature (enabled if and only if nonzero); otherwise tracing is
+enabled if and only if @code{YYDEBUG} is nonzero.
 
 @item the option @option{-t} (POSIX Yacc compliant)
 @itemx the option @option{--debug} (Bison extension)
@@ -8553,12 +9364,19 @@ otherwise it defines @code{YYDEBUG} to 1.
 @item the directive @samp{%debug}
 @findex %debug
 Add the @code{%debug} directive (@pxref{Decl Summary, ,Bison Declaration
-Summary}).  This is a Bison extension, especially useful for languages that
-don't use a preprocessor.  Unless POSIX and Yacc portability matter to you,
-this is the preferred solution.
+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{%define
+Summary,,parse.trace}), 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 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.
 
 @findex YYFPRINTF
@@ -8696,7 +9514,7 @@ Entering state 24
 
 @noindent
 The previous reduction demonstrates the @code{%printer} directive for
-@code{<val>}: both the token @code{NUM} and the resulting non-terminal
+@code{<val>}: both the token @code{NUM} and the resulting nonterminal
 @code{exp} have @samp{1} as value.
 
 @example
@@ -8880,7 +9698,7 @@ Here is a list of options that can be used with Bison, alphabetized by
 short option.  It is followed by a cross key alphabetized by long
 option.
 
-@c Please, keep this ordered as in `bison --help'.
+@c Please, keep this ordered as in 'bison --help'.
 @noindent
 Operations modes:
 @table @option
@@ -8957,6 +9775,76 @@ unexpected number of conflicts is an error, and an expected number of
 conflicts is not reported, so @option{-W} and @option{--warning} then have
 no effect on the conflict report.
 
+@item deprecated
+Deprecated constructs whose support will be removed in future versions of
+Bison.
+
+@item empty-rule
+Empty rules without @code{%empty}.  @xref{Empty Rules}.  Disabled by
+default, but enabled by uses of @code{%empty}, unless
+@option{-Wno-empty-rule} was specified.
+
+@item precedence
+Useless precedence and associativity directives.  Disabled by default.
+
+Consider for instance the following grammar:
+
+@example
+@group
+%nonassoc "="
+%left "+"
+%left "*"
+%precedence "("
+@end group
+%%
+@group
+stmt:
+  exp
+| "var" "=" exp
+;
+@end group
+
+@group
+exp:
+  exp "+" exp
+| exp "*" "num"
+| "(" exp ")"
+| "num"
+;
+@end group
+@end example
+
+Bison reports:
+
+@c cannot leave the location and the [-Wprecedence] for lack of
+@c width in PDF.
+@example
+@group
+warning: useless precedence and associativity for "="
+ %nonassoc "="
+           ^^^
+@end group
+@group
+warning: useless associativity for "*", use %precedence
+ %left "*"
+       ^^^
+@end group
+@group
+warning: useless precedence for "("
+ %precedence "("
+             ^^^
+@end group
+@end example
+
+One would get the exact same parser with the following directives instead:
+
+@example
+@group
+%left "+"
+%precedence "*"
+@end group
+@end example
+
 @item other
 All warnings not categorized above.  These warnings are enabled by default.
 
@@ -8965,16 +9853,103 @@ releases of Bison may move warnings from this category to new, more specific
 categories.
 
 @item all
-All the warnings.
+All the warnings except @code{yacc}.
+
 @item none
 Turn off all the warnings.
+
 @item error
-Treat warnings as errors.
+See @option{-Werror}, below.
 @end table
 
 A category can be turned off by prefixing its name with @samp{no-}.  For
 instance, @option{-Wno-yacc} will hide the warnings about
 POSIX Yacc incompatibilities.
+
+@item -Werror[=@var{category}]
+@itemx -Wno-error[=@var{category}]
+Enable warnings falling in @var{category}, and treat them as errors.  If no
+@var{category} is given, it defaults to making all enabled warnings into errors.
+
+@var{category} is the same as for @option{--warnings}, with the exception that
+it may not be prefixed with @samp{no-} (see above).
+
+Prefixed with @samp{no}, it deactivates the error treatment for this
+@var{category}. However, the warning itself won't be disabled, or enabled, by
+this option.
+
+Note that the precedence of the @samp{=} and @samp{,} operators is such that
+the following commands are @emph{not} equivalent, as the first will not treat
+S/R conflicts as errors.
+
+@example
+$ bison -Werror=yacc,conflicts-sr input.y
+$ bison -Werror=yacc,error=conflicts-sr input.y
+@end example
+
+@item -f [@var{feature}]
+@itemx --feature[=@var{feature}]
+Activate miscellaneous @var{feature}. @var{feature} can be one of:
+@table @code
+@item caret
+@itemx diagnostics-show-caret
+Show caret errors, in a manner similar to GCC's
+@option{-fdiagnostics-show-caret}, or Clang's @option{-fcaret-diagnotics}. The
+location provided with the message is used to quote the corresponding line of
+the source file, underlining the important part of it with carets (^). Here is
+an example, using the following file @file{in.y}:
+
+@example
+%type <ival> exp
+%%
+exp: exp '+' exp @{ $exp = $1 + $2; @};
+@end example
+
+When invoked with @option{-fcaret} (or nothing), Bison will report:
+
+@example
+@group
+in.y:3.20-23: error: ambiguous reference: '$exp'
+ exp: exp '+' exp @{ $exp = $1 + $2; @};
+                    ^^^^
+@end group
+@group
+in.y:3.1-3:       refers to: $exp at $$
+ exp: exp '+' exp @{ $exp = $1 + $2; @};
+ ^^^
+@end group
+@group
+in.y:3.6-8:       refers to: $exp at $1
+ exp: exp '+' exp @{ $exp = $1 + $2; @};
+      ^^^
+@end group
+@group
+in.y:3.14-16:     refers to: $exp at $3
+ exp: exp '+' exp @{ $exp = $1 + $2; @};
+              ^^^
+@end group
+@group
+in.y:3.32-33: error: $2 of 'exp' has no declared type
+ exp: exp '+' exp @{ $exp = $1 + $2; @};
+                                ^^
+@end group
+@end example
+
+Whereas, when invoked with @option{-fno-caret}, Bison will only report:
+
+@example
+@group
+in.y:3.20-23: error: ambiguous reference: ‘$exp’
+in.y:3.1-3:       refers to: $exp at $$
+in.y:3.6-8:       refers to: $exp at $1
+in.y:3.14-16:     refers to: $exp at $3
+in.y:3.32-33: error: $2 of ‘exp’ has no declared type
+@end group
+@end example
+
+This option is activated by default.
+
+@end table
 @end table
 
 @noindent
@@ -9023,9 +9998,6 @@ Specify the programming language for the generated parser, as if
 Summary}).  Currently supported languages include C, C++, and Java.
 @var{language} is case-insensitive.
 
-This option is experimental and its effect may be modified in future
-releases.
-
 @item --locations
 Pretend that @code{%locations} was specified.  @xref{Decl Summary}.
 
@@ -9220,17 +10192,18 @@ The C++ deterministic parser is selected using the skeleton directive,
 
 When run, @command{bison} will create several entities in the @samp{yy}
 namespace.
-@findex %define namespace
-Use the @samp{%define namespace} directive to change the namespace
-name, see @ref{%define Summary,,namespace}.  The various classes are
-generated in the following files:
+@findex %define api.namespace
+Use the @samp{%define api.namespace} directive to change the namespace name,
+see @ref{%define Summary,,api.namespace}.  The various classes are generated
+in the following files:
 
 @table @file
 @item position.hh
 @itemx location.hh
 The definition of the classes @code{position} and @code{location}, used for
-location tracking.  These files are not generated if the @code{%define}
-variable @code{api.location.type} is defined.  @xref{C++ Location Values}.
+location tracking when enabled.  These files are not generated if the
+@code{%define} variable @code{api.location.type} is defined.  @xref{C++
+Location Values}.
 
 @item stack.hh
 An auxiliary class @code{stack} used by the parser.
@@ -9256,11 +10229,22 @@ for a complete and accurate documentation.
 @c - YYSTYPE
 @c - Printer and destructor
 
+Bison supports two different means to handle semantic values in C++.  One is
+alike the C interface, and relies on unions (@pxref{C++ Unions}).  As C++
+practitioners know, unions are inconvenient in C++, therefore another
+approach is provided, based on variants (@pxref{C++ Variants}).
+
+@menu
+* C++ Unions::             Semantic values cannot be objects
+* C++ Variants::           Using objects as semantic values
+@end menu
+
+@node C++ Unions
+@subsubsection C++ Unions
+
 The @code{%union} directive works as for C, see @ref{Union Decl, ,The
 Collection of Value Types}.  In particular it produces a genuine
-@code{union}@footnote{In the future techniques to allow complex types
-within pseudo-unions (similar to Boost variants) might be implemented to
-alleviate these issues.}, which have a few specific features in C++.
+@code{union}, which have a few specific features in C++.
 @itemize @minus
 @item
 The type @code{YYSTYPE} is defined but its use is discouraged: rather
@@ -9277,6 +10261,89 @@ reclaimed automatically: using the @code{%destructor} directive is the
 only means to avoid leaks.  @xref{Destructor Decl, , Freeing Discarded
 Symbols}.
 
+@node C++ Variants
+@subsubsection C++ Variants
+
+Bison provides a @emph{variant} based implementation of semantic values for
+C++.  This alleviates all the limitations reported in the previous section,
+and in particular, object types can be used without pointers.
+
+To enable variant-based semantic values, set @code{%define} variable
+@code{variant} (@pxref{%define Summary,, variant}).  Once this defined,
+@code{%union} is ignored, and instead of using the name of the fields of the
+@code{%union} to ``type'' the symbols, use genuine types.
+
+For instance, instead of
+
+@example
+%union
+@{
+  int ival;
+  std::string* sval;
+@}
+%token <ival> NUMBER;
+%token <sval> STRING;
+@end example
+
+@noindent
+write
+
+@example
+%token <int> NUMBER;
+%token <std::string> STRING;
+@end example
+
+@code{STRING} is no longer a pointer, which should fairly simplify the user
+actions in the grammar and in the scanner (in particular the memory
+management).
+
+Since C++ features destructors, and since it is customary to specialize
+@code{operator<<} to support uniform printing of values, variants also
+typically simplify Bison printers and destructors.
+
+Variants are stricter than unions.  When based on unions, you may play any
+dirty game with @code{yylval}, say storing an @code{int}, reading a
+@code{char*}, and then storing a @code{double} in it.  This is no longer
+possible with variants: they must be initialized, then assigned to, and
+eventually, destroyed.
+
+@deftypemethod {semantic_type} {T&} build<T> ()
+Initialize, but leave empty.  Returns the address where the actual value may
+be stored.  Requires that the variant was not initialized yet.
+@end deftypemethod
+
+@deftypemethod {semantic_type} {T&} build<T> (const T& @var{t})
+Initialize, and copy-construct from @var{t}.
+@end deftypemethod
+
+
+@strong{Warning}: We do not use Boost.Variant, for two reasons.  First, it
+appeared unacceptable to require Boost on the user's machine (i.e., the
+machine on which the generated parser will be compiled, not the machine on
+which @command{bison} was run).  Second, for each possible semantic value,
+Boost.Variant not only stores the value, but also a tag specifying its
+type.  But the parser already ``knows'' the type of the semantic value, so
+that would be duplicating the information.
+
+Therefore we developed light-weight variants whose type tag is external (so
+they are really like @code{unions} for C++ actually).  But our code is much
+less mature that Boost.Variant.  So there is a number of limitations in
+(the current implementation of) variants:
+@itemize
+@item
+Alignment must be enforced: values should be aligned in memory according to
+the most demanding type.  Computing the smallest alignment possible requires
+meta-programming techniques that are not currently implemented in Bison, and
+therefore, since, as far as we know, @code{double} is the most demanding
+type on all platforms, alignments are enforced for @code{double} whatever
+types are actually used.  This may waste space in some cases.
+
+@item
+There might be portability issues we are not aware of.
+@end itemize
+
+As far as we know, these limitations @emph{can} be alleviated.  All it takes
+is some time and/or some talented C++ hacker willing to contribute to Bison.
 
 @node C++ Location Values
 @subsection C++ Location Values
@@ -9299,8 +10366,8 @@ In this section @code{uint} is an abbreviation for @code{unsigned int}: in
 genuine code only the latter is used.
 
 @menu
-* C++ position::                One point in the source file
-* C++ location::                Two points in the source file
+* C++ position::         One point in the source file
+* C++ location::         Two points in the source file
 * User Defined Location Type::  Required interface for locations
 @end menu
 
@@ -9458,7 +10525,7 @@ to generate the @file{master/position.hh} and @file{master/location.hh}
 files, reused by other parsers as follows:
 
 @example
-%define location_type "master::location"
+%define api.location.type "master::location"
 %code requires @{ #include <master/location.hh> @}
 @end example
 
@@ -9481,7 +10548,7 @@ additional argument for its constructor.
 
 @defcv {Type} {parser} {semantic_type}
 @defcvx {Type} {parser} {location_type}
-The types for semantics value and locations.
+The types for semantic values and locations (if enabled).
 @end defcv
 
 @defcv {Type} {parser} {token}
@@ -9492,11 +10559,27 @@ use @code{yy::parser::token::FOO}.  The scanner can use
 (@pxref{Calc++ Scanner}).
 @end defcv
 
+@defcv {Type} {parser} {syntax_error}
+This class derives from @code{std::runtime_error}.  Throw instances of it
+from the scanner or from the user actions to raise parse errors.  This is
+equivalent with first
+invoking @code{error} to report the location and message of the syntax
+error, and then to invoke @code{YYERROR} to enter the error-recovery mode.
+But contrary to @code{YYERROR} which can only be invoked from user actions
+(i.e., written in the action itself), the exception can be thrown from
+function invoked from the user action.
+@end defcv
+
 @deftypemethod {parser} {} parser (@var{type1} @var{arg1}, ...)
 Build a new parser object.  There are no arguments by default, unless
 @samp{%parse-param @{@var{type1} @var{arg1}@}} was used.
 @end deftypemethod
 
+@deftypemethod {syntax_error} {} syntax_error (const location_type& @var{l}, const std::string& @var{m})
+@deftypemethodx {syntax_error} {} syntax_error (const std::string& @var{m})
+Instantiate a syntax-error exception.
+@end deftypemethod
+
 @deftypemethod {parser} {int} parse ()
 Run the syntactic analysis, and return 0 on success, 1 otherwise.
 
@@ -9519,9 +10602,11 @@ or nonzero, full tracing.
 @end deftypemethod
 
 @deftypemethod {parser} {void} error (const location_type& @var{l}, const std::string& @var{m})
+@deftypemethodx {parser} {void} error (const std::string& @var{m})
 The definition for this member function must be supplied by the user:
 the parser uses it to report a parser error occurring at @var{l},
-described by @var{m}.
+described by @var{m}.  If location tracking is not enabled, the second
+signature is used.
 @end deftypemethod
 
 
@@ -9533,25 +10618,144 @@ described by @var{m}.
 
 The parser invokes the scanner by calling @code{yylex}.  Contrary to C
 parsers, C++ parsers are always pure: there is no point in using the
-@code{%define api.pure} directive.  Therefore the interface is as follows.
+@samp{%define api.pure} directive.  The actual interface with @code{yylex}
+depends whether you use unions, or variants.
+
+@menu
+* Split Symbols::         Passing symbols as two/three components
+* Complete Symbols::      Making symbols a whole
+@end menu
+
+@node Split Symbols
+@subsubsection Split Symbols
+
+The interface is as follows.
 
 @deftypemethod {parser} {int} yylex (semantic_type* @var{yylval}, location_type* @var{yylloc}, @var{type1} @var{arg1}, ...)
-Return the next token.  Its type is the return value, its semantic
-value and location being @var{yylval} and @var{yylloc}.  Invocations of
+@deftypemethodx {parser} {int} yylex (semantic_type* @var{yylval}, @var{type1} @var{arg1}, ...)
+Return the next token.  Its type is the return value, its semantic value and
+location (if enabled) being @var{yylval} and @var{yylloc}.  Invocations of
 @samp{%lex-param @{@var{type1} @var{arg1}@}} yield additional arguments.
 @end deftypemethod
 
+Note that when using variants, the interface for @code{yylex} is the same,
+but @code{yylval} is handled differently.
+
+Regular union-based code in Lex scanner typically look like:
+
+@example
+[0-9]+   @{
+           yylval.ival = text_to_int (yytext);
+           return yy::parser::INTEGER;
+         @}
+[a-z]+   @{
+           yylval.sval = new std::string (yytext);
+           return yy::parser::IDENTIFIER;
+         @}
+@end example
+
+Using variants, @code{yylval} is already constructed, but it is not
+initialized.  So the code would look like:
+
+@example
+[0-9]+   @{
+           yylval.build<int>() = text_to_int (yytext);
+           return yy::parser::INTEGER;
+         @}
+[a-z]+   @{
+           yylval.build<std::string> = yytext;
+           return yy::parser::IDENTIFIER;
+         @}
+@end example
+
+@noindent
+or
+
+@example
+[0-9]+   @{
+           yylval.build(text_to_int (yytext));
+           return yy::parser::INTEGER;
+         @}
+[a-z]+   @{
+           yylval.build(yytext);
+           return yy::parser::IDENTIFIER;
+         @}
+@end example
+
+
+@node Complete Symbols
+@subsubsection Complete Symbols
+
+If you specified both @code{%define api.value.type variant} and
+@code{%define api.token.constructor},
+the @code{parser} class also defines the class @code{parser::symbol_type}
+which defines a @emph{complete} symbol, aggregating its type (i.e., the
+traditional value returned by @code{yylex}), its semantic value (i.e., the
+value passed in @code{yylval}, and possibly its location (@code{yylloc}).
+
+@deftypemethod {symbol_type} {} symbol_type (token_type @var{type},  const semantic_type& @var{value}, const location_type& @var{location})
+Build a complete terminal symbol which token type is @var{type}, and which
+semantic value is @var{value}.  If location tracking is enabled, also pass
+the @var{location}.
+@end deftypemethod
+
+This interface is low-level and should not be used for two reasons.  First,
+it is inconvenient, as you still have to build the semantic value, which is
+a variant, and second, because consistency is not enforced: as with unions,
+it is still possible to give an integer as semantic value for a string.
+
+So for each token type, Bison generates named constructors as follows.
+
+@deftypemethod {symbol_type} {} make_@var{token} (const @var{value_type}& @var{value}, const location_type& @var{location})
+@deftypemethodx {symbol_type} {} make_@var{token} (const location_type& @var{location})
+Build a complete terminal symbol for the token type @var{token} (not
+including the @code{api.token.prefix}) whose possible semantic value is
+@var{value} of adequate @var{value_type}.  If location tracking is enabled,
+also pass the @var{location}.
+@end deftypemethod
+
+For instance, given the following declarations:
+
+@example
+%define api.token.prefix "TOK_"
+%token <std::string> IDENTIFIER;
+%token <int> INTEGER;
+%token COLON;
+@end example
+
+@noindent
+Bison generates the following functions:
+
+@example
+symbol_type make_IDENTIFIER(const std::string& v,
+                            const location_type& l);
+symbol_type make_INTEGER(const int& v,
+                         const location_type& loc);
+symbol_type make_COLON(const location_type& loc);
+@end example
+
+@noindent
+which should be used in a Lex-scanner as follows.
+
+@example
+[0-9]+   return yy::parser::make_INTEGER(text_to_int (yytext), loc);
+[a-z]+   return yy::parser::make_IDENTIFIER(yytext, loc);
+":"      return yy::parser::make_COLON(loc);
+@end example
+
+Tokens that do not have an identifier are not accessible: you cannot simply
+use characters such as @code{':'}, they must be declared with @code{%token}.
 
 @node A Complete C++ Example
 @subsection A Complete C++ Example
 
 This section demonstrates the use of a C++ parser with a simple but
 complete example.  This example should be available on your system,
-ready to compile, in the directory @dfn{../bison/examples/calc++}.  It
+ready to compile, in the directory @dfn{.../bison/examples/calc++}.  It
 focuses on the use of Bison, therefore the design of the various C++
 classes is very naive: no accessors, no encapsulation of members etc.
 We will use a Lex scanner, and more precisely, a Flex scanner, to
-demonstrate the various interaction.  A hand written scanner is
+demonstrate the various interactions.  A hand-written scanner is
 actually easier to interface with.
 
 @menu
@@ -9615,11 +10819,8 @@ factor both as follows.
 @comment file: calc++-driver.hh
 @example
 // Tell Flex the lexer's prototype ...
-# define YY_DECL                                        \
-  yy::calcxx_parser::token_type                         \
-  yylex (yy::calcxx_parser::semantic_type* yylval,      \
-         yy::calcxx_parser::location_type* yylloc,      \
-         calcxx_driver& driver)
+# define YY_DECL \
+  yy::calcxx_parser::symbol_type yylex (calcxx_driver& driver)
 // ... and declare it for the parser's sake.
 YY_DECL;
 @end example
@@ -9643,8 +10844,8 @@ public:
 @end example
 
 @noindent
-To encapsulate the coordination with the Flex scanner, it is useful to
-have two members function to open and close the scanning phase.
+To encapsulate the coordination with the Flex scanner, it is useful to have
+member functions to open and close the scanning phase.
 
 @comment file: calc++-driver.hh
 @example
@@ -9659,9 +10860,13 @@ Similarly for the parser itself.
 
 @comment file: calc++-driver.hh
 @example
-  // Run the parser.  Return 0 on success.
+  // Run the parser on file F.
+  // Return 0 on success.
   int parse (const std::string& f);
+  // The name of the file being parsed.
+  // Used later to pass the file name to the location tracker.
   std::string file;
+  // Whether parser traces should be generated.
   bool trace_parsing;
 @end example
 
@@ -9743,19 +10948,35 @@ the grammar for.
 %define parser_class_name "calcxx_parser"
 @end example
 
+@noindent
+@findex %define api.token.constructor
+@findex %define api.value.type variant
+This example will use genuine C++ objects as semantic values, therefore, we
+require the variant-based interface.  To make sure we properly use it, we
+enable assertions.  To fully benefit from type-safety and more natural
+definition of ``symbol'', we enable @code{api.token.constructor}.
+
+@comment file: calc++-parser.yy
+@example
+%define api.token.constructor
+%define api.value.type variant
+%define parse.assert
+@end example
+
 @noindent
 @findex %code requires
-Then come the declarations/inclusions needed to define the
-@code{%union}.  Because the parser uses the parsing driver and
-reciprocally, both cannot include the header of the other.  Because the
+Then come the declarations/inclusions needed by the semantic values.
+Because the parser uses the parsing driver and reciprocally, both would like
+to include the header of the other, which is, of course, insane.  This
+mutual dependency will be broken using forward declarations.  Because the
 driver's header needs detailed knowledge about the parser class (in
-particular its inner types), it is the parser's header which will simply
-use a forward declaration of the driver.
-@xref{%code Summary}.
+particular its inner types), it is the parser's header which will use a
+forward declaration of the driver.  @xref{%code Summary}.
 
 @comment file: calc++-parser.yy
 @example
-%code requires @{
+%code requires
+@{
 # include <string>
 class calcxx_driver;
 @}
@@ -9769,15 +10990,14 @@ global variables.
 @comment file: calc++-parser.yy
 @example
 // The parsing context.
-%parse-param @{ calcxx_driver& driver @}
-%lex-param   @{ calcxx_driver& driver @}
+%param @{ calcxx_driver& driver @}
 @end example
 
 @noindent
-Then we request the location tracking feature, and initialize the
+Then we request location tracking, and initialize the
 first location's file name.  Afterward new locations are computed
 relatively to the previous locations: the file name will be
-automatically propagated.
+propagated.
 
 @comment file: calc++-parser.yy
 @example
@@ -9790,28 +11010,14 @@ automatically propagated.
 @end example
 
 @noindent
-Use the two following directives to enable parser tracing and verbose error
+Use the following two directives to enable parser tracing and verbose error
 messages.  However, verbose error messages can contain incorrect information
 (@pxref{LAC}).
 
 @comment file: calc++-parser.yy
 @example
-%debug
-%error-verbose
-@end example
-
-@noindent
-Semantic values cannot use ``real'' objects, but only pointers to
-them.
-
-@comment file: calc++-parser.yy
-@example
-// Symbols.
-%union
-@{
-  int          ival;
-  std::string *sval;
-@};
+%define parse.trace
+%define parse.error verbose
 @end example
 
 @noindent
@@ -9821,7 +11027,8 @@ The code between @samp{%code @{} and @samp{@}} is output in the
 
 @comment file: calc++-parser.yy
 @example
-%code @{
+%code
+@{
 # include "calc++-driver.hh"
 @}
 @end example
@@ -9829,35 +11036,52 @@ The code between @samp{%code @{} and @samp{@}} is output in the
 
 @noindent
 The token numbered as 0 corresponds to end of file; the following line
-allows for nicer error messages referring to ``end of file'' instead
-of ``$end''.  Similarly user friendly named are provided for each
-symbol.  Note that the tokens names are prefixed by @code{TOKEN_} to
-avoid name clashes.
+allows for nicer error messages referring to ``end of file'' instead of
+``$end''.  Similarly user friendly names are provided for each symbol.  To
+avoid name clashes in the generated files (@pxref{Calc++ Scanner}), prefix
+tokens with @code{TOK_} (@pxref{%define Summary,,api.token.prefix}).
 
 @comment file: calc++-parser.yy
 @example
-%token        END      0 "end of file"
-%token        ASSIGN     ":="
-%token <sval> IDENTIFIER "identifier"
-%token <ival> NUMBER     "number"
-%type  <ival> exp
+%define api.token.prefix "TOK_"
+%token
+  END  0  "end of file"
+  ASSIGN  ":="
+  MINUS   "-"
+  PLUS    "+"
+  STAR    "*"
+  SLASH   "/"
+  LPAREN  "("
+  RPAREN  ")"
+;
 @end example
 
 @noindent
-To enable memory deallocation during error recovery, use
-@code{%destructor}.
+Since we use variant-based semantic values, @code{%union} is not used, and
+both @code{%type} and @code{%token} expect genuine types, as opposed to type
+tags.
 
-@c FIXME: Document %printer, and mention that it takes a braced-code operand.
 @comment file: calc++-parser.yy
 @example
-%printer    @{ yyoutput << *$$; @} "identifier"
-%destructor @{ delete $$; @} "identifier"
+%token <std::string> IDENTIFIER "identifier"
+%token <int> NUMBER "number"
+%type  <int> exp
+@end example
+
+@noindent
+No @code{%destructor} is needed to enable memory deallocation during error
+recovery; the memory, for strings for instance, will be reclaimed by the
+regular destructors.  All the values are printed using their
+@code{operator<<} (@pxref{Printer Decl, , Printing Semantic Values}).
 
-%printer    @{ yyoutput << $$; @} <ival>
+@comment file: calc++-parser.yy
+@example
+%printer @{ yyoutput << $$; @} <*>;
 @end example
 
 @noindent
-The grammar itself is straightforward.
+The grammar itself is straightforward (@pxref{Location Tracking Calc, ,
+Location Tracking Calculator: @code{ltcalc}}).
 
 @comment file: calc++-parser.yy
 @example
@@ -9866,21 +11090,22 @@ The grammar itself is straightforward.
 unit: assignments exp  @{ driver.result = $2; @};
 
 assignments:
-  /* Nothing.  */        @{@}
+  %empty                 @{@}
 | assignments assignment @{@};
 
 assignment:
-     "identifier" ":=" exp
-       @{ driver.variables[*$1] = $3; delete $1; @};
-
-%left '+' '-';
-%left '*' '/';
-exp: exp '+' exp   @{ $$ = $1 + $3; @}
-   | exp '-' exp   @{ $$ = $1 - $3; @}
-   | exp '*' exp   @{ $$ = $1 * $3; @}
-   | exp '/' exp   @{ $$ = $1 / $3; @}
-   | "identifier"  @{ $$ = driver.variables[*$1]; delete $1; @}
-   | "number"      @{ $$ = $1; @};
+  "identifier" ":=" exp @{ driver.variables[$1] = $3; @};
+
+%left "+" "-";
+%left "*" "/";
+exp:
+  exp "+" exp   @{ $$ = $1 + $3; @}
+| exp "-" exp   @{ $$ = $1 - $3; @}
+| exp "*" exp   @{ $$ = $1 * $3; @}
+| exp "/" exp   @{ $$ = $1 / $3; @}
+| "(" exp ")"   @{ std::swap ($$, $2); @}
+| "identifier"  @{ $$ = driver.variables[$1]; @}
+| "number"      @{ std::swap ($$, $1); @};
 %%
 @end example
 
@@ -9891,7 +11116,7 @@ driver.
 @comment file: calc++-parser.yy
 @example
 void
-yy::calcxx_parser::error (const yy::calcxx_parser::location_type& l,
+yy::calcxx_parser::error (const location_type& l,
                           const std::string& m)
 @{
   driver.error (l, m);
@@ -9907,24 +11132,22 @@ parser's to get the set of defined tokens.
 @comment file: calc++-scanner.ll
 @example
 %@{ /* -*- C++ -*- */
-# include <cstdlib>
 # include <cerrno>
 # include <climits>
+# include <cstdlib>
 # include <string>
 # include "calc++-driver.hh"
 # include "calc++-parser.hh"
 
-/* Work around an incompatibility in flex (at least versions
-   2.5.31 through 2.5.33): it generates code that does
-   not conform to C89.  See Debian bug 333231
-   <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=333231>.  */
+// Work around an incompatibility in flex (at least versions
+// 2.5.31 through 2.5.33): it generates code that does
+// not conform to C89.  See Debian bug 333231
+// <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=333231>.
 # undef yywrap
 # define yywrap() 1
 
-/* By default yylex returns int, we use token_type.
-   Unfortunately yyterminate by default returns 0, which is
-   not of token_type.  */
-#define yyterminate() return token::END
+// The location of the current token.
+static yy::location loc;
 %@}
 @end example
 
@@ -9932,11 +11155,11 @@ parser's to get the set of defined tokens.
 Because there is no @code{#include}-like feature we don't need
 @code{yywrap}, we don't need @code{unput} either, and we parse an
 actual file, this is not an interactive session with the user.
-Finally we enable the scanner tracing features.
+Finally, we enable scanner tracing.
 
 @comment file: calc++-scanner.ll
 @example
-%option noyywrap nounput batch debug
+%option noyywrap nounput batch debug noinput
 @end example
 
 @noindent
@@ -9952,8 +11175,8 @@ blank [ \t]
 @noindent
 The following paragraph suffices to track locations accurately.  Each
 time @code{yylex} is invoked, the begin position is moved onto the end
-position.  Then when a pattern is matched, the end position is
-advanced of its width.  In case it matched ends of lines, the end
+position.  Then when a pattern is matched, its width is added to the end
+column.  When matching ends of lines, the end
 cursor is adjusted, and each time blanks are matched, the begin cursor
 is moved onto the end cursor to effectively ignore the blanks
 preceding tokens.  Comments would be treated equally.
@@ -9962,46 +11185,51 @@ preceding tokens.  Comments would be treated equally.
 @example
 @group
 %@{
-# define YY_USER_ACTION  yylloc->columns (yyleng);
+  // Code run each time a pattern is matched.
+  # define YY_USER_ACTION  loc.columns (yyleng);
 %@}
 @end group
 %%
+@group
 %@{
-  yylloc->step ();
+  // Code run each time yylex is called.
+  loc.step ();
 %@}
-@{blank@}+   yylloc->step ();
-[\n]+      yylloc->lines (yyleng); yylloc->step ();
+@end group
+@{blank@}+   loc.step ();
+[\n]+      loc.lines (yyleng); loc.step ();
 @end example
 
 @noindent
-The rules are simple, just note the use of the driver to report errors.
-It is convenient to use a typedef to shorten
-@code{yy::calcxx_parser::token::identifier} into
-@code{token::identifier} for instance.
+The rules are simple.  The driver is used to report errors.
 
 @comment file: calc++-scanner.ll
 @example
-%@{
-  typedef yy::calcxx_parser::token token;
-%@}
-           /* Convert ints to the actual type of tokens.  */
-[-+*/]     return yy::calcxx_parser::token_type (yytext[0]);
-":="       return token::ASSIGN;
+"-"      return yy::calcxx_parser::make_MINUS(loc);
+"+"      return yy::calcxx_parser::make_PLUS(loc);
+"*"      return yy::calcxx_parser::make_STAR(loc);
+"/"      return yy::calcxx_parser::make_SLASH(loc);
+"("      return yy::calcxx_parser::make_LPAREN(loc);
+")"      return yy::calcxx_parser::make_RPAREN(loc);
+":="     return yy::calcxx_parser::make_ASSIGN(loc);
+
+@group
 @{int@}      @{
   errno = 0;
   long n = strtol (yytext, NULL, 10);
   if (! (INT_MIN <= n && n <= INT_MAX && errno != ERANGE))
-    driver.error (*yylloc, "integer is out of range");
-  yylval->ival = n;
-  return token::NUMBER;
+    driver.error (loc, "integer is out of range");
+  return yy::calcxx_parser::make_NUMBER(n, loc);
 @}
-@{id@}       yylval->sval = new std::string (yytext); return token::IDENTIFIER;
-.          driver.error (*yylloc, "invalid character");
+@end group
+@{id@}       return yy::calcxx_parser::make_IDENTIFIER(yytext, loc);
+.          driver.error (loc, "invalid character");
+<<EOF>>    return yy::calcxx_parser::make_END(loc);
 %%
 @end example
 
 @noindent
-Finally, because the scanner related driver's member function depend
+Finally, because the scanner-related driver's member-functions depend
 on the scanner's data, it is simpler to implement them in this file.
 
 @comment file: calc++-scanner.ll
@@ -10044,6 +11272,7 @@ The top level file, @file{calc++.cc}, poses no problem.
 int
 main (int argc, char *argv[])
 @{
+  int res = 0;
   calcxx_driver driver;
   for (int i = 1; i < argc; ++i)
     if (argv[i] == std::string ("-p"))
@@ -10052,6 +11281,9 @@ main (int argc, char *argv[])
       driver.trace_scanning = true;
     else if (!driver.parse (argv[i]))
       std::cout << driver.result << std::endl;
+    else
+      res = 1;
+  return res;
 @}
 @end group
 @end example
@@ -10096,8 +11328,7 @@ You can create documentation for generated parsers using Javadoc.
 Contrary to C parsers, Java parsers do not use global variables; the
 state of the parser is always local to an instance of the parser class.
 Therefore, all Java parsers are ``pure'', and the @code{%pure-parser}
-and @code{%define api.pure} directives does not do anything when used in
-Java.
+and @code{%define api.pure} directives do nothing when used in Java.
 
 Push parsers are currently unsupported in Java and @code{%define
 api.push-pull} have no effect.
@@ -10109,15 +11340,23 @@ 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 and verbose errors are 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
-unused code in the generated parser, so use @code{%debug} and
-@code{%verbose-error} explicitly if needed.  Also, in the future the
+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.
 
+Getting a ``code too large'' error from the Java compiler means the code
+hit the 64KB bytecode per method limitation of the Java class file.
+Try reducing the amount of code in actions and static initializers;
+otherwise, report a bug so that the parser skeleton will be improved.
+
+
 @node Java Semantic Values
 @subsection Java Semantic Values
 @c - No %union, specify type in %type/%token.
@@ -10136,11 +11375,11 @@ semantic values' types (class names) should be specified in the
 By default, the semantic stack is declared to have @code{Object} members,
 which means that the class types you specify can be of any class.
 To improve the type safety of the parser, you can declare the common
-superclass of all the semantic values using the @code{%define stype}
+superclass of all the semantic values using the @samp{%define api.value.type}
 directive.  For example, after the following declaration:
 
 @example
-%define stype "ASTNode"
+%define api.value.type "ASTNode"
 @end example
 
 @noindent
@@ -10175,11 +11414,11 @@ class defines a @dfn{position}, a single point in a file; Bison itself
 defines a class representing a @dfn{location}, a range composed of a pair of
 positions (possibly spanning several files).  The location class is an inner
 class of the parser; the name is @code{Location} by default, and may also be
-renamed using @code{%define location_type "@var{class-name}"}.
+renamed using @code{%define api.location.type "@var{class-name}"}.
 
 The location class treats the position as a completely opaque value.
 By default, the class name is @code{Position}, but this can be changed
-with @code{%define position_type "@var{class-name}"}.  This class must
+with @code{%define api.position.type "@var{class-name}"}.  This class must
 be supplied by the user.
 
 
@@ -10214,20 +11453,22 @@ properly, the position class should override the @code{equals} and
 The name of the generated parser class defaults to @code{YYParser}.  The
 @code{YY} prefix may be changed using the @code{%name-prefix} directive
 or the @option{-p}/@option{--name-prefix} option.  Alternatively, use
-@code{%define parser_class_name "@var{name}"} to give a custom name to
+@samp{%define parser_class_name "@var{name}"} to give a custom name to
 the class.  The interface of this class is detailed below.
 
 By default, the parser class has package visibility.  A declaration
-@code{%define public} will change to public visibility.  Remember that,
+@samp{%define public} will change to public visibility.  Remember that,
 according to the Java language specification, the name of the @file{.java}
 file should match the name of the class in this case.  Similarly, you can
 use @code{abstract}, @code{final} and @code{strictfp} with the
 @code{%define} declaration to add other modifiers to the parser class.
+A single @samp{%define annotations "@var{annotations}"} directive can
+be used to add any number of annotations to the parser class.
 
 The Java package name of the parser class can be specified using the
-@code{%define package} directive.  The superclass and the implemented
+@samp{%define package} directive.  The superclass and the implemented
 interfaces of the parser class can be specified with the @code{%define
-extends} and @code{%define implements} directives.
+extends} and @samp{%define implements} directives.
 
 The parser class defines an inner class, @code{Location}, that is used
 for location tracking (see @ref{Java Location Values}), and a inner
@@ -10236,30 +11477,33 @@ these inner class/interface, and the members described in the interface
 below, all the other members and fields are preceded with a @code{yy} or
 @code{YY} prefix to avoid clashes with user code.
 
-@c FIXME: The following constants and variables are still undocumented:
-@c @code{bisonVersion}, @code{bisonSkeleton} and @code{errorVerbose}.
-
 The parser class can be extended using the @code{%parse-param}
 directive. Each occurrence of the directive will add a @code{protected
 final} field to the parser class, and an argument to its constructor,
 which initialize them automatically.
 
-Token names defined by @code{%token} and the predefined @code{EOF} token
-name are added as constant fields to the parser class.
-
 @deftypeop {Constructor} {YYParser} {} YYParser (@var{lex_param}, @dots{}, @var{parse_param}, @dots{})
 Build a new parser object with embedded @code{%code lexer}.  There are
-no parameters, unless @code{%parse-param}s and/or @code{%lex-param}s are
-used.
+no parameters, unless @code{%param}s and/or @code{%parse-param}s and/or
+@code{%lex-param}s are used.
+
+Use @code{%code init} for code added to the start of the constructor
+body. This is especially useful to initialize superclasses. Use
+@samp{%define init_throws} to specify any uncaught exceptions.
 @end deftypeop
 
 @deftypeop {Constructor} {YYParser} {} YYParser (Lexer @var{lexer}, @var{parse_param}, @dots{})
 Build a new parser object using the specified scanner.  There are no
-additional parameters unless @code{%parse-param}s are used.
+additional parameters unless @code{%param}s and/or @code{%parse-param}s are
+used.
 
 If the scanner is defined by @code{%code lexer}, this constructor is
 declared @code{protected} and is called automatically with a scanner
-created with the correct @code{%lex-param}s.
+created with the correct @code{%param}s and/or @code{%lex-param}s.
+
+Use @code{%code init} for code added to the start of the constructor
+body. This is especially useful to initialize superclasses. Use
+@samp{%define init_throws} to specify any uncaught exceptions.
 @end deftypeop
 
 @deftypemethod {YYParser} {boolean} parse ()
@@ -10267,6 +11511,21 @@ Run the syntactic analysis, and return @code{true} on success,
 @code{false} otherwise.
 @end deftypemethod
 
+@deftypemethod {YYParser} {boolean} getErrorVerbose ()
+@deftypemethodx {YYParser} {void} setErrorVerbose (boolean @var{verbose})
+Get or set the option to produce verbose error messages.  These are only
+available with @samp{%define parse.error verbose}, which also turns on
+verbose error messages.
+@end deftypemethod
+
+@deftypemethod {YYParser} {void} yyerror (String @var{msg})
+@deftypemethodx {YYParser} {void} yyerror (Position @var{pos}, String @var{msg})
+@deftypemethodx {YYParser} {void} yyerror (Location @var{loc}, String @var{msg})
+Print an error message using the @code{yyerror} method of the scanner
+instance in use. The @code{Location} and @code{Position} parameters are
+available only if location tracking is active.
+@end deftypemethod
+
 @deftypemethod {YYParser} {boolean} recovering ()
 During the syntactic analysis, return @code{true} if recovering
 from a syntax error.
@@ -10285,6 +11544,11 @@ Get or set the tracing level.  Currently its value is either 0, no trace,
 or nonzero, full tracing.
 @end deftypemethod
 
+@deftypecv {Constant} {YYParser} {String} {bisonVersion}
+@deftypecvx {Constant} {YYParser} {String} {bisonSkeleton}
+Identify the Bison version and skeleton used to generate this parser.
+@end deftypecv
+
 
 @node Java Scanner Interface
 @subsection Java Scanner Interface
@@ -10295,7 +11559,9 @@ or nonzero, full tracing.
 There are two possible ways to interface a Bison-generated Java parser
 with a scanner: the scanner may be defined by @code{%code lexer}, or
 defined elsewhere.  In either case, the scanner has to implement the
-@code{Lexer} inner interface of the parser class.
+@code{Lexer} inner interface of the parser class.  This interface also
+contain constants for all user-defined token names and the predefined
+@code{EOF} token.
 
 In the first case, the body of the scanner class is placed in
 @code{%code lexer} blocks.  If you want to pass parameters from the
@@ -10314,7 +11580,7 @@ In both cases, the scanner has to implement the following methods.
 @deftypemethod {Lexer} {void} yyerror (Location @var{loc}, String @var{msg})
 This method is defined by the user to emit an error message.  The first
 parameter is omitted if location tracking is not active.  Its type can be
-changed using @code{%define location_type "@var{class-name}".}
+changed using @code{%define api.location.type "@var{class-name}".}
 @end deftypemethod
 
 @deftypemethod {Lexer} {int} yylex ()
@@ -10322,7 +11588,7 @@ Return the next token.  Its type is the return value, its semantic
 value and location are saved and returned by the their methods in the
 interface.
 
-Use @code{%define lex_throws} to specify any uncaught exceptions.
+Use @samp{%define lex_throws} to specify any uncaught exceptions.
 Default is @code{java.io.IOException}.
 @end deftypemethod
 
@@ -10332,14 +11598,14 @@ Return respectively the first position of the last token that
 @code{yylex} returned, and the first position beyond it.  These
 methods are not needed unless location tracking is active.
 
-The return type can be changed using @code{%define position_type
+The return type can be changed using @code{%define api.position.type
 "@var{class-name}".}
 @end deftypemethod
 
 @deftypemethod {Lexer} {Object} getLVal ()
 Return the semantic value of the last token that yylex returned.
 
-The return type can be changed using @code{%define stype
+The return type can be changed using @samp{%define api.value.type
 "@var{class-name}".}
 @end deftypemethod
 
@@ -10350,7 +11616,7 @@ The return type can be changed using @code{%define stype
 The following special constructs can be uses in Java actions.
 Other analogous C action features are currently unavailable for Java.
 
-Use @code{%define throws} to specify any uncaught exceptions from parser
+Use @samp{%define throws} to specify any uncaught exceptions from parser
 actions, and initial actions specified by @code{%initial-action}.
 
 @defvar $@var{n}
@@ -10367,7 +11633,7 @@ Like @code{$@var{n}} but specifies a alternative type @var{typealt}.
 @defvar $$
 The semantic value for the grouping made by the current rule.  As a
 value, this is in the base type (@code{Object} or as specified by
-@code{%define stype}) as in not cast to the declared subtype because
+@samp{%define api.value.type}) as in not cast to the declared subtype because
 casts are not allowed on the left-hand side of Java assignments.
 Use an explicit Java cast if the correct subtype is needed.
 @xref{Java Semantic Values}.
@@ -10414,11 +11680,12 @@ operation.
 @xref{Error Recovery}.
 @end deftypefn
 
-@deftypefn  {Function} {protected void} yyerror (String msg)
-@deftypefnx {Function} {protected void} yyerror (Position pos, String msg)
-@deftypefnx {Function} {protected void} yyerror (Location loc, String msg)
+@deftypefn  {Function} {void} yyerror (String @var{msg})
+@deftypefnx {Function} {void} yyerror (Position @var{loc}, String @var{msg})
+@deftypefnx {Function} {void} yyerror (Location @var{loc}, String @var{msg})
 Print an error message using the @code{yyerror} method of the scanner
-instance in use.
+instance in use. The @code{Location} and @code{Position} parameters are
+available only if location tracking is active.
 @end deftypefn
 
 
@@ -10448,7 +11715,7 @@ corresponds to these C macros.}.
 @item
 Java lacks unions, so @code{%union} has no effect.  Instead, semantic
 values have a common base type: @code{Object} or as specified by
-@samp{%define stype}.  Angle brackets on @code{%token}, @code{type},
+@samp{%define api.value.type}.  Angle brackets on @code{%token}, @code{type},
 @code{$@var{n}} and @code{$$} specify subtypes rather than fields of
 an union.  The type of @code{$$}, even with angle brackets, is the base
 type since Java casts are not allow on the left-hand side of assignments.
@@ -10462,7 +11729,7 @@ The prologue declarations have a different meaning than in C/C++ code.
 @item @code{%code imports}
 blocks are placed at the beginning of the Java source code.  They may
 include copyright notices.  For a @code{package} declarations, it is
-suggested to use @code{%define package} instead.
+suggested to use @samp{%define package} instead.
 
 @item unqualified @code{%code}
 blocks are placed inside the parser class.
@@ -10503,7 +11770,7 @@ constructor that @emph{creates} a lexer.  Default is none.
 
 @deffn {Directive} %name-prefix "@var{prefix}"
 The prefix of the parser class name @code{@var{prefix}Parser} if
-@code{%define parser_class_name} is not used.  Default is @code{YY}.
+@samp{%define parser_class_name} is not used.  Default is @code{YY}.
 @xref{Java Bison Interface}.
 @end deffn
 
@@ -10534,6 +11801,11 @@ Code inserted just after the @code{package} declaration.
 @xref{Java Differences}.
 @end deffn
 
+@deffn {Directive} {%code init} @{ @var{code} @dots{} @}
+Code inserted at the beginning of the parser constructor body.
+@xref{Java Parser Interface}.
+@end deffn
+
 @deffn {Directive} {%code lexer} @{ @var{code} @dots{} @}
 Code added to the body of a inner lexer class within the parser class.
 @xref{Java Scanner Interface}.
@@ -10546,7 +11818,7 @@ Code (after the second @code{%%}) appended to the end of the file,
 @end deffn
 
 @deffn {Directive} %@{ @var{code} @dots{} %@}
-Not supported.  Use @code{%code import} instead.
+Not supported.  Use @code{%code imports} instead.
 @xref{Java Differences}.
 @end deffn
 
@@ -10555,6 +11827,11 @@ Whether the parser class is declared @code{abstract}.  Default is false.
 @xref{Java Bison Interface}.
 @end deffn
 
+@deffn {Directive} {%define annotations} "@var{annotations}"
+The Java annotations for the parser class.  Default is none.
+@xref{Java Bison Interface}.
+@end deffn
+
 @deffn {Directive} {%define extends} "@var{superclass}"
 The superclass of the parser class.  Default is none.
 @xref{Java Bison Interface}.
@@ -10571,16 +11848,23 @@ Default is none.
 @xref{Java Bison Interface}.
 @end deffn
 
+@deffn {Directive} {%define init_throws} "@var{exceptions}"
+The exceptions thrown by @code{%code init} from the parser class
+constructor.  Default is none.
+@xref{Java Parser Interface}.
+@end deffn
+
 @deffn {Directive} {%define lex_throws} "@var{exceptions}"
 The exceptions thrown by the @code{yylex} method of the lexer, a
 comma-separated list.  Default is @code{java.io.IOException}.
 @xref{Java Scanner Interface}.
 @end deffn
 
-@deffn {Directive} {%define location_type} "@var{class}"
+@deffn {Directive} {%define api.location.type} "@var{class}"
 The name of the class used for locations (a range between two
 positions).  This class is generated as an inner class of the parser
 class by @command{bison}.  Default is @code{Location}.
+Formerly named @code{location_type}.
 @xref{Java Location Values}.
 @end deffn
 
@@ -10595,9 +11879,10 @@ The name of the parser class.  Default is @code{YYParser} or
 @xref{Java Bison Interface}.
 @end deffn
 
-@deffn {Directive} {%define position_type} "@var{class}"
+@deffn {Directive} {%define api.position.type} "@var{class}"
 The name of the class used for positions. This class must be supplied by
 the user.  Default is @code{Position}.
+Formerly named @code{position_type}.
 @xref{Java Location Values}.
 @end deffn
 
@@ -10606,7 +11891,7 @@ Whether the parser class is declared @code{public}.  Default is false.
 @xref{Java Bison Interface}.
 @end deffn
 
-@deffn {Directive} {%define stype} "@var{class}"
+@deffn {Directive} {%define api.value.type} "@var{class}"
 The base type of semantic values.  Default is @code{Object}.
 @xref{Java Semantic Values}.
 @end deffn
@@ -10677,7 +11962,7 @@ or
 @quotation
 My parser includes support for an @samp{#include}-like feature, in
 which case I run @code{yyparse} from @code{yyparse}.  This fails
-although I did specify @samp{%define api.pure}.
+although I did specify @samp{%define api.pure full}.
 @end quotation
 
 These problems typically come not from Bison itself, but from
@@ -10980,7 +12265,7 @@ operating system's name and version and your compiler's name and
 version.  If you have trouble compiling, you should also include a
 transcript of the build session, starting with the invocation of
 `configure'.  Depending on the nature of the bug, you may be asked to
-send additional files as well (such as `config.h' or `config.cache').
+send additional files as well (such as @file{config.h} or @file{config.cache}).
 
 Patches are most welcome, but not required.  That is, do not hesitate to
 send a bug report just because you cannot provide a fix.
@@ -11040,18 +12325,23 @@ In an action, the location of the left-hand side of the rule.
 @end deffn
 
 @deffn {Variable} @@@var{n}
+@deffnx {Symbol} @@@var{n}
 In an action, the location of the @var{n}-th symbol of the right-hand side
 of the rule.  @xref{Tracking Locations}.
+
+In a grammar, the Bison-generated nonterminal symbol for a mid-rule action
+with a semantical value.  @xref{Mid-Rule Action Translation}.
 @end deffn
 
 @deffn {Variable} @@@var{name}
-In an action, the location of a symbol addressed by name.  @xref{Tracking
-Locations}.
+@deffnx {Variable} @@[@var{name}]
+In an action, the location of a symbol addressed by @var{name}.
+@xref{Tracking Locations}.
 @end deffn
 
-@deffn {Variable} @@[@var{name}]
-In an action, the location of a symbol addressed by name.  @xref{Tracking
-Locations}.
+@deffn {Symbol} $@@@var{n}
+In a grammar, the Bison-generated nonterminal symbol for a mid-rule action
+with no semantical value.  @xref{Mid-Rule Action Translation}.
 @end deffn
 
 @deffn {Variable} $$
@@ -11065,12 +12355,8 @@ right-hand side of the rule.  @xref{Actions}.
 @end deffn
 
 @deffn {Variable} $@var{name}
-In an action, the semantic value of a symbol addressed by name.
-@xref{Actions}.
-@end deffn
-
-@deffn {Variable} $[@var{name}]
-In an action, the semantic value of a symbol addressed by name.
+@deffnx {Variable} $[@var{name}]
+In an action, the semantic value of a symbol addressed by @var{name}.
 @xref{Actions}.
 @end deffn
 
@@ -11088,8 +12374,22 @@ the grammar file.  @xref{Grammar Outline, ,Outline of a Bison
 Grammar}.
 @end deffn
 
-@deffn {Construct} /*@dots{}*/
-Comment delimiters, as in C.
+@deffn {Directive} %?@{@var{expression}@}
+Predicate actions.  This is a type of action clause that may appear in
+rules. The expression is evaluated, and if false, causes a syntax error.  In
+GLR parsers during nondeterministic operation,
+this silently causes an alternative parse to die.  During deterministic
+operation, it is the same as the effect of YYERROR.
+@xref{Semantic Predicates}.
+
+This feature is experimental.
+More user feedback will help to determine whether it should become a permanent
+feature.
+@end deffn
+
+@deffn {Construct} /* @dots{} */
+@deffnx {Construct} // @dots{}
+Comments, as in C/C++.
 @end deffn
 
 @deffn {Delimiter} :
@@ -11180,6 +12480,11 @@ time to resolve reduce/reduce conflicts.  @xref{GLR Parsers, ,Writing
 GLR Parsers}.
 @end deffn
 
+@deffn {Directive} %empty
+Bison declaration to declare make explicit that a rule has an empty
+right-hand side.  @xref{Empty Rules}.
+@end deffn
+
 @deffn {Symbol} $end
 The predefined token marking the end of the token stream.  It cannot be
 used in the grammar.
@@ -11197,8 +12502,8 @@ token is reset to the token that originally caused the violation.
 @end deffn
 
 @deffn {Directive} %error-verbose
-Bison declaration to request verbose, specific error message strings
-when @code{yyerror} is called.  @xref{Error Reporting}.
+An obsolete directive standing for @samp{%define parse.error verbose}
+(@pxref{Error Reporting, ,The Error Reporting Function @code{yyerror}}).
 @end deffn
 
 @deffn {Directive} %file-prefix "@var{prefix}"
@@ -11221,12 +12526,12 @@ Specify the programming language for the generated parser.
 @end deffn
 
 @deffn {Directive} %left
-Bison declaration to assign left associativity to token(s).
+Bison declaration to assign precedence and left associativity to token(s).
 @xref{Precedence Decl, ,Operator Precedence}.
 @end deffn
 
-@deffn {Directive} %lex-param @{@var{argument-declaration}@}
-Bison declaration to specifying an additional parameter that
+@deffn {Directive} %lex-param @{@var{argument-declaration}@} @dots{}
+Bison declaration to specifying additional arguments that
 @code{yylex} should accept.  @xref{Pure Calling,, Calling Conventions
 for Pure Parsers}.
 @end deffn
@@ -11271,7 +12576,7 @@ parser implementation file.  @xref{Decl Summary}.
 @end deffn
 
 @deffn {Directive} %nonassoc
-Bison declaration to assign nonassociativity to token(s).
+Bison declaration to assign precedence and nonassociativity to token(s).
 @xref{Precedence Decl, ,Operator Precedence}.
 @end deffn
 
@@ -11280,10 +12585,15 @@ Bison declaration to set the name of the parser implementation file.
 @xref{Decl Summary}.
 @end deffn
 
-@deffn {Directive} %parse-param @{@var{argument-declaration}@}
-Bison declaration to specifying an additional parameter that
-@code{yyparse} should accept.  @xref{Parser Function,, The Parser
-Function @code{yyparse}}.
+@deffn {Directive} %param @{@var{argument-declaration}@} @dots{}
+Bison declaration to specify additional arguments that both
+@code{yylex} and @code{yyparse} should accept.  @xref{Parser Function,, The
+Parser Function @code{yyparse}}.
+@end deffn
+
+@deffn {Directive} %parse-param @{@var{argument-declaration}@} @dots{}
+Bison declaration to specify additional arguments that @code{yyparse}
+should accept.  @xref{Parser Function,, The Parser Function @code{yyparse}}.
 @end deffn
 
 @deffn {Directive} %prec
@@ -11291,8 +12601,13 @@ Bison declaration to assign a precedence to a specific rule.
 @xref{Contextual Precedence, ,Context-Dependent Precedence}.
 @end deffn
 
+@deffn {Directive} %precedence
+Bison declaration to assign precedence to token(s), but no associativity
+@xref{Precedence Decl, ,Operator Precedence}.
+@end deffn
+
 @deffn {Directive} %pure-parser
-Deprecated version of @code{%define api.pure} (@pxref{%define
+Deprecated version of @samp{%define api.pure} (@pxref{%define
 Summary,,api.pure}), for which Bison is more careful to warn about
 unreasonable usage.
 @end deffn
@@ -11303,7 +12618,7 @@ Require a Version of Bison}.
 @end deffn
 
 @deffn {Directive} %right
-Bison declaration to assign right associativity to token(s).
+Bison declaration to assign precedence and right associativity to token(s).
 @xref{Precedence Decl, ,Operator Precedence}.
 @end deffn
 
@@ -11408,17 +12723,16 @@ instead.
 
 @deffn {Function} yyerror
 User-supplied function to be called by @code{yyparse} on error.
-@xref{Error Reporting, ,The Error
-Reporting Function @code{yyerror}}.
+@xref{Error Reporting, ,The Error Reporting Function @code{yyerror}}.
 @end deffn
 
 @deffn {Macro} YYERROR_VERBOSE
-An obsolete macro that you define with @code{#define} in the prologue
-to request verbose, specific error message strings
-when @code{yyerror} is called.  It doesn't matter what definition you
-use for @code{YYERROR_VERBOSE}, just whether you define it.
-Supported by the C skeletons only; using
-@code{%error-verbose} is preferred.  @xref{Error Reporting}.
+An obsolete macro used in the @file{yacc.c} skeleton, that you define
+with @code{#define} in the prologue to request verbose, specific error
+message strings when @code{yyerror} is called.  It doesn't matter what
+definition you use for @code{YYERROR_VERBOSE}, just whether you define
+it.  Using @samp{%define parse.error verbose} is preferred
+(@pxref{Error Reporting, ,The Error Reporting Function @code{yyerror}}).
 @end deffn
 
 @deffn {Macro} YYFPRINTF
@@ -11437,13 +12751,6 @@ the next token.  @xref{Lexical, ,The Lexical Analyzer Function
 @code{yylex}}.
 @end deffn
 
-@deffn {Macro} YYLEX_PARAM
-An obsolete macro for specifying an extra argument (or list of extra
-arguments) for @code{yyparse} to pass to @code{yylex}.  The use of this
-macro is deprecated, and is supported only for Yacc like parsers.
-@xref{Pure Calling,, Calling Conventions for Pure Parsers}.
-@end deffn
-
 @deffn {Variable} yylloc
 External variable in which @code{yylex} should place the line and column
 numbers associated with a token.  (In a pure parser, it is a local
@@ -11479,7 +12786,7 @@ Management}.
 @deffn {Variable} yynerrs
 Global variable which Bison increments each time it reports a syntax error.
 (In a pure parser, it is a local variable within @code{yyparse}. In a
-pure push parser, it is a member of yypstate.)
+pure push parser, it is a member of @code{yypstate}.)
 @xref{Error Reporting, ,The Error Reporting Function @code{yyerror}}.
 @end deffn
 
@@ -11529,13 +12836,6 @@ parse a single token.  @xref{Push Parser Function, ,The Push Parser Function
 More user feedback will help to stabilize it.)
 @end deffn
 
-@deffn {Macro} YYPARSE_PARAM
-An obsolete macro for specifying the name of a parameter that
-@code{yyparse} should accept.  The use of this macro is deprecated, and
-is supported only for Yacc like parsers.  @xref{Pure Calling,, Calling
-Conventions for Pure Parsers}.
-@end deffn
-
 @deffn {Macro} YYRECOVERING
 The expression @code{YYRECOVERING ()} yields 1 when the parser
 is recovering from a syntax error, and 0 otherwise.
@@ -11572,7 +12872,7 @@ Data type of semantic values; @code{int} by default.
 @item Accepting state
 A state whose only action is the accept action.
 The accepting state is thus a consistent state.
-@xref{Understanding,,}.
+@xref{Understanding, ,Understanding Your Parser}.
 
 @item Backus-Naur Form (BNF; also called ``Backus Normal Form'')
 Formal method of specifying context-free grammars originally proposed
@@ -11881,7 +13181,11 @@ London, Department of Computer Science, TR-00-12 (December 2000).
 @c LocalWords: getLVal defvar deftypefn deftypefnx gotos msgfmt Corbett LALR's
 @c LocalWords: subdirectory Solaris nonassociativity perror schemas Malloy ints
 @c LocalWords: Scannerless ispell american ChangeLog smallexample CSTYPE CLTYPE
-@c LocalWords: clval CDEBUG cdebug deftypeopx yyterminate
+@c LocalWords: clval CDEBUG cdebug deftypeopx yyterminate LocationType
+@c LocalWords: parsers parser's
+@c LocalWords: associativity subclasses precedences unresolvable runnable
+@c LocalWords: allocators subunit initializations unreferenced untyped
+@c LocalWords: errorVerbose subtype subtypes
 
 @c Local Variables:
 @c ispell-dictionary: "american"