Re: Bison H file generation

[Paul Eggert]

I installed the following patch to the Bison documentation to help
explain this issue better.  Thanks again for your bug report.

2004-05-25  Paul Eggert  <address@hidden>

        * doc/bison.texinfo (Decl Summary, Bison Options): Clarify what's
        put into the -d output file, and mention what to do if YYSTYPE is
        defined as a macro.

Index: doc/bison.texinfo
===================================================================
RCS file: /cvsroot/bison/bison/doc/bison.texinfo,v
retrieving revision 1.122
diff -p -u -r1.122 bison.texinfo
--- doc/bison.texinfo   31 Mar 2004 00:37:20 -0000      1.122
+++ doc/bison.texinfo   25 May 2004 19:04:59 -0000
@@ -3739,17 +3739,33 @@ already defined, so that the debugging f
 @xref{Tracing, ,Tracing Your Parser}.
 
 @deffn {Directive} %defines
-Write an extra output file containing macro definitions for the token
-type names defined in the grammar and the semantic value type
address@hidden, as well as a few @code{extern} variable declarations.
-
+Write a header file containing macro definitions for the token type
+names defined in the grammar as well as a few other declarations.
 If the parser output file is named @address@hidden then this file
 is named @address@hidden
 
-This output file is essential if you wish to put the definition of
address@hidden in a separate source file, because @code{yylex} needs to
-be able to refer to token type codes and the variable
address@hidden  @xref{Token Values, ,Semantic Values of Tokens}.
+Unless @code{YYSTYPE} is already defined as a macro, the output header
+declares @code{YYSTYPE}.  Therefore, if you have defined a
address@hidden macro (@pxref{Value Type, ,Data Types of Semantic
+Values}) you need to arrange for this definition to be propagated to
+all modules, e.g., by putting the macro definition in another,
+prerequisite header that is included both by your parser and by any
+other module that needs @code{YYSTYPE}.
+
+Unless your parser is pure, the output header declares @code{yylval}
+as an external variable.  @xref{Pure Decl, ,A Pure (Reentrant)
+Parser}.
+
+If you have also used locations, the output header declares
address@hidden and @code{yylloc} using a protocol similar to that of
address@hidden and @code{yylval}.  @xref{Locations, ,Tracking
+Locations}.
+
+This output file is normally essential if you wish to put the
+definition of @code{yylex} in a separate source file, because
address@hidden typically needs to be able to refer to the
+above-mentioned declarations and to the token type codes.
address@hidden Values, ,Semantic Values of Tokens}.
 @end deffn
 
 @deffn {Directive} %destructor
@@ -6281,8 +6297,7 @@ Adjust the output:
 @itemx --defines
 Pretend that @code{%defines} was specified, i.e., write an extra output
 file containing macro definitions for the token type names defined in
-the grammar and the semantic value type @code{YYSTYPE}, as well as a few
address@hidden variable declarations.  @xref{Decl Summary}.
+the grammar, as well as a few other declarations.  @xref{Decl Summary}.
 
 @item address@hidden
 Same as above, but save in the file @var{defines-file}.