--- doc/bison.texinfo	2005-09-29 07:49:05.000000000 +0200
+++ /tmp/bison.texinfo	2005-09-26 21:59:12.000000000 +0200
@@ -1197,13 +1197,11 @@
 This also includes numerous identifiers used for internal purposes.
 Therefore, you should avoid using C identifiers starting with @samp{yy}
 or @samp{YY} in the Bison grammar file except for the ones defined in
-this manual.  Also, you should avoid using the C identifiers
-@samp{malloc} and @samp{free} for anything other than their usual
-meanings.
+this manual.
 
 In some cases the Bison parser file includes system headers, and in
 those cases your code should respect the identifiers reserved by those
-headers.  On some non-@acronym{GNU} hosts, @code{<alloca.h>}, @code{<malloc.h>},
+headers.  On some non-@acronym{GNU} hosts, @code{<alloca.h>},
 @code{<stddef.h>}, and @code{<stdlib.h>} are included as needed to
 declare memory allocators and related types.  @code{<libintl.h>} is
 included if message translation is in use
@@ -6933,12 +6931,13 @@
 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 (variants) might be implemented to alleviate
-these issues.}, which have a few specific features in C++.
+within pseudo-unions (similar to Boost variants) might be implemented to
+alleviate these issues.}, which have a few specific features in C++.
 @itemize @minus
 @item
-The name @code{YYSTYPE} also denotes @samp{union YYSTYPE}.  You may
-forward declare it just with @samp{union YYSTYPE;}.
+The type @code{YYSTYPE} is defined but its use is discouraged: rather
+you should refer to the parser's encapsulated type
+@code{yy::parser::semantic_type}.
 @item
 Non POD (Plain Old Data) types cannot be used.  C++ forbids any
 instance of classes with constructors in unions: only @emph{pointers}
@@ -7139,7 +7138,8 @@
 
 The declaration of this driver class, @file{calc++-driver.hh}, is as
 follows.  The first part includes the CPP guard and imports the
-required standard library components.
+required standard library components, and the declaration of the parser
+class.
 
 @comment file: calc++-driver.hh
 @example
@@ -7147,26 +7147,9 @@
 # define CALCXX_DRIVER_HH
 # include <string>
 # include <map>
+# include "calc++-parser.hh"
 @end example
 
-@noindent
-Then come forward declarations.  Because the parser uses the parsing
-driver and reciprocally, simple inclusions of header files will not
-do.  Because the driver's declaration is the one that will be imported
-by the rest of the project, it is saner to forward declare the
-parser's information here.
-
-@comment file: calc++-driver.hh
-@example
-// Forward declarations.
-union YYSTYPE;
-namespace yy
-@{
-  class location;
-  class calcxx_parser;
-@}
-class calcxx_driver;
-@end example
 
 @noindent
 Then comes the declaration of the scanning function.  Flex expects
@@ -7178,7 +7161,9 @@
 @example
 // Announce to Flex the prototype we want for lexing function, ...
 # define YY_DECL						 \
-  int yylex (YYSTYPE* yylval, yy::location* yylloc, calcxx_driver& driver)
+  int yylex (yy::calcxx_parser::semantic_type* yylval,           \
+             yy::calcxx_parser::location_type* yylloc,           \
+             calcxx_driver& driver)
 // ... and declare it for the parser's sake.
 YY_DECL;
 @end example
@@ -7289,18 +7274,29 @@
 @subsection Calc++ Parser
 
 The parser definition file @file{calc++-parser.yy} starts by asking
-for the C++ skeleton, the creation of the parser header file, and
-specifies the name of the parser class.  It then includes the required
-headers.
+for the C++ LALR(1) skeleton, the creation of the parser header file, and
+specifies the name of the parser class.
 
 @comment file: calc++-parser.yy
 @example
 %skeleton "lalr1.cc"                          /*  -*- C++ -*- */
-%define "parser_class_name" "calcxx_parser"
 %defines
+%define "parser_class_name" "calcxx_parser"
+@end example
+
+@noindent
+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
+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.
+
+@comment file: calc++-parser.yy
+@example
 %@{
 # include <string>
-# include "calc++-driver.hh"
+class calcxx_driver;
 %@}
 @end example
 
@@ -7357,6 +7353,19 @@
 @end example
 
 @noindent
+The code between @samp{%@{} and @samp{%@}} after the introduction of the
+@samp{%union} is output in the @file{*.cc} file; it needs detailed
+knowledge about the driver.
+
+@comment file: calc++-parser.yy
+@example
+%@{
+# include "calc++-driver.hh"
+%@}
+@end example
+
+
+@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
@@ -7372,6 +7381,7 @@
 %type  <ival> exp              "expression"
 @end example
 
+
 @noindent
 To enable memory deallocation during error recovery, use
 @code{%destructor}.
@@ -8129,7 +8139,10 @@
 reserved for future Bison extensions.  If not defined,
 @code{YYSTACK_USE_ALLOCA} defaults to 0.
 
-In the all-too-common case where your code may run on a host with a
+If you define @code{YYSTACK_USE_ALLOCA} to 1, it is your
+responsibility to make sure that @code{alloca} is visible, e.g., by
+using @acronym{GCC} or by including @code{<stdlib.h>}.  Furthermore,
+in the all-too-common case where your code may run on a host with a
 limited stack and with unreliable stack-overflow checking, you should
 set @code{YYMAXDEPTH} to a value that cannot possibly result in
 unchecked stack overflow on any of your target hosts when