doc: introduce api.pure full, rearrange some examples

[bison.git] / doc / bison.texi

diff --git a/doc/bison.texi b/doc/bison.texi
index 8f98aa5e421744eb0f9089a148a2200a5f6120b3..32396a89e7f500e894b1d49665c21c965571172e 100644 (file)
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -276,6 +276,7 @@ Operator Precedence
 * Using Precedence::  How to specify precedence in Bison grammars.
 * Precedence Examples::  How these features are used in the previous example.
 * How Precedence::    How they work.
 * Using Precedence::  How to specify precedence in Bison grammars.
 * 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
 
 
 Tuning LR
 


@@ -295,6 +296,7 @@ Debugging Your Parser
 
 * Understanding::     Understanding the structure of your parser.
 * Graphviz::          Getting a visual representation of the 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
 * Tracing::           Tracing the execution of your parser.
 
 Tracing Your Parser


@@ -4864,6 +4866,7 @@ may override this restriction with the @code{%start} declaration as follows:
 @cindex reentrant parser
 @cindex pure parser
 @findex %define api.pure
 @cindex reentrant parser
 @cindex pure parser
 @findex %define api.pure

+@findex %define api.pure full

 
 A @dfn{reentrant} program is one which does not alter in the course of
 execution; in other words, it consists entirely of @dfn{pure} (read-only)
 
 A @dfn{reentrant} program is one which does not alter in the course of
 execution; in other words, it consists entirely of @dfn{pure} (read-only)


@@ -4883,7 +4886,7 @@ declaration @code{%define api.pure} says that you want the parser to be
 reentrant.  It looks like this:
 
 @example
 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
 @end example
 
 The result is that the communication variables @code{yylval} and


@@ -4933,7 +4936,7 @@ compatibility with the impure Yacc pull mode interface.  Unless you know
 what you are doing, your declarations should look like this:
 
 @example
 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
 
 %define api.push-pull push
 @end example
 


@@ -5006,8 +5009,8 @@ yypull_parse (ps); /* Will call the lexer */
 yypstate_delete (ps);
 @end example
 
 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
+Adding the @code{%define api.pure full} 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}.
 
 @node Decl Summary
 @code{%define api.push-pull push}.
 
 @node Decl Summary


@@ -5371,9 +5374,40 @@ Some of the accepted @var{variable}s are:
 @item Purpose: Request a pure (reentrant) parser program.
 @xref{Pure Decl, ,A Pure (Reentrant) Parser}.
 
 @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 yylex (@pxref{Pure Calling}), and also that of
+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 Default Value: @code{false}

+
+@item History: the @code{full} value was introduced in Bison 2.7

 @end itemize
 
 @c ================================================== api.push-pull
 @end itemize
 
 @c ================================================== api.push-pull


@@ -5818,6 +5852,27 @@ In the grammar actions, use expressions like this to refer to the data:
 exp: @dots{}    @{ @dots{}; *randomness += 1; @dots{} @}
 @end example
 
 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
 @node Push Parser Function
 @section The Push Parser Function @code{yypush_parse}
 @findex yypush_parse


@@ -6069,7 +6124,7 @@ The data type of @code{yylloc} has the name @code{YYLTYPE}.
 @node Pure Calling
 @subsection Calling Conventions for Pure Parsers
 
 @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
 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


@@ -6104,35 +6159,25 @@ Declare that the braced-code @var{argument-declaration} is an
 additional @code{yylex} argument declaration.
 @end deffn
 
 additional @code{yylex} argument declaration.
 @end deffn
 

+@noindent

 For instance:
 
 @example
 For instance:
 
 @example

-%parse-param @{int *nastiness@}

 %lex-param   @{int *nastiness@}
 %lex-param   @{int *nastiness@}

-%parse-param @{int *randomness@}

 @end example
 
 @noindent
 @end example
 
 @noindent

-results in the following signatures:
-
-@example
-int yylex   (int *nastiness);
-int yyparse (int *nastiness, int *randomness);
-@end example
-
-If @code{%define api.pure} is added:
+results in the following signature:

 
 @example
 
 @example

-int yylex   (YYSTYPE *lvalp, int *nastiness);
-int yyparse (int *nastiness, int *randomness);
+int yylex (int *nastiness);

 @end example
 
 @noindent
 @end example
 
 @noindent

-and finally, if both @code{%define api.pure} and @code{%locations} are used:
+If @code{%define api.pure full} (or just @code{%define api.pure}) is added:

 
 @example
 
 @example

-int yylex   (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);
-int yyparse (int *nastiness, int *randomness);
+int yylex (YYSTYPE *lvalp, int *nastiness);

 @end example
 
 @node Error Reporting
 @end example
 
 @node Error Reporting


@@ -6192,50 +6237,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
 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
+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}.

 
 

-If @samp{%parse-param @{int *nastiness@}} is used, then:
+When @code{%locations %define api.pure full} is used, @code{yyerror} has the
+following signature:

 
 @example
 
 @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
-
-@noindent
-results in the following signatures for all the parser kinds:
-
-@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
 @end example
 
 @noindent


@@ -6597,7 +6608,7 @@ expr:
 term:
   '(' expr ')'
 | term '!'
 term:
   '(' expr ')'
 | term '!'

-| NUMBER
+| "number"

 ;
 @end group
 @end example
 ;
 @end group
 @end example


@@ -6636,20 +6647,20 @@ statements, with a pair of rules like this:
 @example
 @group
 if_stmt:
 @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
 ;
 @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
 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
 rule.
 
 This situation, where either a shift or a reduction would be valid, is


@@ -6658,14 +6669,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.
 
 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
 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
 @end example
 
 But if the parser chose to reduce when possible rather than shift, the


@@ -6673,9 +6684,9 @@ result would be to attach the else-clause to the outermost if-statement,
 making these two inputs equivalent:
 
 @example
 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
 @end example
 
 The conflict exists because the grammar as written is ambiguous: either


@@ -6688,11 +6699,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
 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.
 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
 
 The definition of @code{if_stmt} above is solely to blame for the
 conflict, but the conflict does not actually appear without additional


@@ -6701,7 +6717,6 @@ the conflict:
 
 @example
 @group
 
 @example
 @group

-%token IF THEN ELSE variable

 %%
 @end group
 @group
 %%
 @end group
 @group


@@ -6713,13 +6728,13 @@ stmt:
 
 @group
 if_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:
 ;
 @end group
 
 expr:

-  variable
+  "identifier"

 ;
 @end example
 
 ;
 @end example
 


@@ -6738,6 +6753,7 @@ shift and when to reduce.
 * Using Precedence::  How to specify precedence in Bison grammars.
 * Precedence Examples::  How these features are used in the previous example.
 * How Precedence::    How they work.
 * Using Precedence::  How to specify precedence in Bison grammars.
 * 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
 @end menu
 
 @node Why Precedence


@@ -6825,16 +6841,11 @@ would declare them in groups of equal precedence.  For example, @code{'+'} is
 declared with @code{'-'}:
 
 @example
 declared with @code{'-'}:
 
 @example

-%left '<' '>' '=' NE LE GE
+%left '<' '>' '=' "!=" "<=" ">="

 %left '+' '-'
 %left '*' '/'
 @end example
 
 %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
 
 @node How Precedence
 @subsection How Precedence Works
 


@@ -6857,6 +6868,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.
 
 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
+%nonassoc "then"
+%nonassoc "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,
+support for ``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
 @node Contextual Precedence
 @section Context-Dependent Precedence
 @cindex context-dependent precedence


@@ -7017,30 +7066,38 @@ reduce/reduce conflict must be studied and usually eliminated.  Here is the
 proper way to define @code{sequence}:
 
 @example
 proper way to define @code{sequence}:
 
 @example

+@group

 sequence:
   /* empty */    @{ printf ("empty sequence\n"); @}
 | sequence word  @{ printf ("added word %s\n", $2); @}
 ;
 sequence:
   /* 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
 sequence:
 @end example
 
 Here is another common error that yields a reduce/reduce conflict:
 
 @example
 sequence:

+@group

   /* empty */
 | sequence words
 | sequence redirects
 ;
   /* empty */
 | sequence words
 | sequence redirects
 ;

+@end group

 
 

+@group

 words:
   /* empty */
 | words word
 ;
 words:
   /* empty */
 | words word
 ;

+@end group

 
 

+@group

 redirects:
   /* empty */
 | redirects redirect
 ;
 redirects:
   /* empty */
 | redirects redirect
 ;

+@end group

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -7093,6 +7150,58 @@ redirects:
 @end group
 @end example
 
 @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
+%nonassoc "word"
+%nonassoc "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
 @node Mysterious Conflicts
 @section Mysterious Conflicts
 @cindex Mysterious Conflicts


@@ -7102,8 +7211,6 @@ Here is an example:
 
 @example
 @group
 
 @example
 @group

-%token ID
-

 %%
 def: param_spec return_spec ',';
 param_spec:
 %%
 def: param_spec return_spec ',';
 param_spec:


@@ -7118,10 +7225,10 @@ return_spec:
 ;
 @end group
 @group
 ;
 @end group
 @group

-type: ID;
+type: "id";

 @end group
 @group
 @end group
 @group

-name: ID;
+name: "id";

 name_list:
   name
 | name ',' name_list
 name_list:
   name
 | name ',' name_list


@@ -7129,16 +7236,16 @@ name_list:
 @end group
 @end example
 
 @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.
 
 @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.
 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.


@@ -7169,27 +7276,24 @@ distinct.  In the above example, adding one rule to
 
 @example
 @group
 
 @example
 @group

-%token BOGUS
-@dots{}
-%%

 @dots{}
 return_spec:
   type
 | name ':' type
 @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
 ;
 @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.
 @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:
 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}
 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}


@@ -7202,7 +7306,7 @@ param_spec:
 ;
 return_spec:
   type
 ;
 return_spec:
   type

-| ID ':' type
+| "id" ':' type

 ;
 @end example
 
 ;
 @end example
 


@@ -8095,6 +8199,7 @@ automaton, and how to enable and understand the parser run-time traces.
 @menu
 * Understanding::     Understanding the structure of your parser.
 * Graphviz::          Getting a visual representation of the 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
 
 * Tracing::           Tracing the execution of your parser.
 @end menu
 


@@ -8511,6 +8616,9 @@ precedence of @samp{/} with respect to @samp{+}, @samp{-}, and
 @samp{*}, but also because the
 associativity of @samp{/} is not specified.
 
 @samp{*}, but also because the
 associativity of @samp{/} is not specified.
 

+Note that Bison may also produce an HTML version of this output, via an XML
+file and XSLT processing (@pxref{Xml}).
+

 @c ================================================= Graphical Representation
 
 @node Graphviz
 @c ================================================= Graphical Representation
 
 @node Graphviz


@@ -8525,8 +8633,8 @@ 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.
 
 fail due to memory exhaustion). This option was rather designed for beginners,
 to help them understand LR parsers.
 

-This file is generated when the @option{--graph} option is specified (see
-@pxref{Invocation, , Invoking Bison}).  Its name is made by removing
+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}.
 @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}.


@@ -8618,6 +8726,54 @@ is shown as a blue diamond, labelled "Acc".
 The @samp{go to} jump transitions are represented as dotted lines bearing
 the name of the rule being jumped to.
 
 The @samp{go to} jump transitions are represented as dotted lines bearing
 the name of the rule being jumped to.
 

+Note that a DOT file may also be produced via an XML file and XSLT
+processing (@pxref{Xml}).
+
+@c ================================================= XML
+
+@node Xml
+@section Visualizing your parser in multiple formats
+@cindex xml
+
+Bison supports two major report formats: textual output
+(@pxref{Understanding}) when invoked with option @option{--verbose}, and DOT
+(@pxref{Graphviz}) 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 textual 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 .output file.
+@item xml2xhtml.xsl
+Used to output an xhtml enhancement of the .output file.
+@end table
+
+Sample usage (requires @code{xsltproc}):
+@example
+$ bison -x input.y
+@group
+$ bison --print-datadir
+/usr/local/share/bison
+@end group
+$ xsltproc /usr/local/share/bison/xslt/xml2xhtml.xsl input.xml > input.html
+@end example
+

 @c ================================================= Tracing
 
 @node Tracing
 @c ================================================= Tracing
 
 @node Tracing


@@ -9643,7 +9799,7 @@ 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
 
 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.
+@code{%define api.pure full} directive.  Therefore 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
 
 @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


@@ -10206,7 +10362,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}
 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
+and @code{%define api.pure full} directives does not do anything when used in

 Java.
 
 Push parsers are currently unsupported in Java and @code{%define
 Java.
 
 Push parsers are currently unsupported in Java and @code{%define


@@ -10789,7 +10945,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
 @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
 @end quotation
 
 These problems typically come not from Bison itself, but from


@@ -11994,7 +12150,10 @@ London, Department of Computer Science, TR-00-12 (December 2000).
 @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 LocationType
 @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 LocationType

-@c LocalWords: errorVerbose
+@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"
 
 @c Local Variables:
 @c ispell-dictionary: "american"