* ChangeLog: For changes in doc/bison.texinfo, consistently reference

node names: say "Table of Symbols" not "Bison Symbols", and say "Decl
Summary" not "Directives".
* doc/bison.texinfo (Decl Summary, Calc++ Parser): Cross-reference the
%code entry in "Decl Summary" rather than the one in "Table of Symbols"
since the former is now the more complete one.
(Prologue Alternatives): Likewise and do the same for %defines.
(Table of Symbols): Add summary of %code, add summary of %define, and
move full %code documentation to...
(Decl Summary): ... here for consistency with other entries in these
sections.
Move %define entry in order to keep this list alphabetized.
Reword %define entry a little to put less emphasis on the skeleton
concept, which most users shouldn't have to think about.

ChangeLog

@@ -1,3 +1,20 @@
+2007-01-27  Joel E. Denny  <jdenny@ces.clemson.edu>
+
+	* ChangeLog: For changes in doc/bison.texinfo, consistently reference
+	node names: say "Table of Symbols" not "Bison Symbols", and say "Decl
+	Summary" not "Directives".
+	* doc/bison.texinfo (Decl Summary, Calc++ Parser): Cross-reference the
+	%code entry in "Decl Summary" rather than the one in "Table of Symbols"
+	since the former is now the more complete one.
+	(Prologue Alternatives): Likewise and do the same for %defines.
+	(Table of Symbols): Add summary of %code, add summary of %define, and
+	move full %code documentation to...
+	(Decl Summary): ... here for consistency with other entries in these
+	sections.
+	Move %define entry in order to keep this list alphabetized.
+	Reword %define entry a little to put less emphasis on the skeleton
+	concept, which most users shouldn't have to think about.
+
 2007-01-26  Paul Eggert  <eggert@cs.ucla.edu>
 
 	Adjust to recent gnulib changes.
@@ -18,7 +35,7 @@
 	* data/glr.cc: Likewise.
 	* data/location.cc: Use b4_percent_define_flag_if.
 
-	* doc/bison.texinfo (Directives): Document %define.
+	* doc/bison.texinfo (Decl Summary): Document %define.
 
 	* src/parse-gram.y (Unqualified %code): Change muscle name to
 	b4_percent_code().
@@ -200,7 +217,7 @@
 	(C++ Location Values): Update %define uses.
 	(Calc++ Parser Interface): Likewise.
 	(Calc++ Parser): Likewise, and update `%code requires' uses.
-	(Bison Symbols): Update %code documentation.
+	(Table of Symbols): Update %code documentation.
 	* src/parse-gram.y (prologue_declaration): For %define variables, use
 	`variable' instead of `STRING'.
 	(grammar_declaration): For %code qualifiers, use `ID' instead of
@@ -418,7 +435,7 @@
 	* doc/bison.texinfo (Prologue Alternatives): Update.
 	(Decl Summary): Update to %code "requires" and %code "provides".
 	(Calc++ Parser): Update to %code "requires".
-	(Bison Symbols): Remove entries for %requires, %provides, and
+	(Table of Symbols): Remove entries for %requires, %provides, and
 	%code-top.  Rewrite %code entry, and add a %code "QUALIFIER" entry.
 	* data/bison.m4 (b4_user_provides, b4_user_requires): Remove as these
 	are replaced by b4_percent_code_provides and b4_percent_code_requires,
@@ -831,7 +848,7 @@
 	documentation instead.
 	(Calc++ Parser): Use `%require "@value{VERSION}"' rather than
 	`%require "2.3b"' so that the example is always up-to-date.
-	(Bison Symbols): Add entries for %language and %skeleton.
+	(Table of Symbols): Add entries for %language and %skeleton.
 	* examples/extexi (normalize): Instead of replacing every %require
 	argument with the current Bison version, just substitute for
 	`@value{VERSION}'.  This guarantees that we're testing what actually
@@ -866,7 +883,7 @@
 
 	* doc/bison.texinfo (C++ Parser Interface): Prefer %language
 	over %skeleton.
-	(Directives): Document %language and %skeleton.
+	(Decl Summary): Document %language and %skeleton.
 	(Command line): Document -L.
 
 	* examples/extexi: Rewrite %require directive.
@@ -1067,7 +1084,7 @@
 	(2.3a): Annotate this entry to say the old forms of these features were
 	also experimental.
 	* doc/bison.texinfo (Prologue Alternatives, Freeing Discarded Symbols,
-	Bison Symbols): Say they're experimental.  Comment out any mention
+	Table of Symbols): Say they're experimental.  Comment out any mention
 	of Java (we'll want this back eventually).
 
 2006-12-01  Joel E. Denny  <jdenny@ces.clemson.edu>
@@ -1076,7 +1093,7 @@
 	%file-prefix, %name-prefix, and %output.  Discussed at
 	<http://lists.gnu.org/archive/html/help-bison/2006-09/msg00001.html>.
 	* NEWS (2.3a+): Mention.
-	* doc/bison.texinfo (Decl Summary, Bison Symbols): Add entry for new
+	* doc/bison.texinfo (Decl Summary, Table of Symbols): Add entry for new
 	form of %defines, and remove `=' from entries for %file-prefix,
 	%name-prefix, and %output.
 	* src/parse-gram.y (prologue_declaration): Implement.
@@ -1106,7 +1123,7 @@
 	Rename <!> to <>.  Discussed starting at
 	<http://lists.gnu.org/archive/html/bison-patches/2006-11/msg00039.html>.
 	* NEWS (2.3a+): Update.
-	* doc/bison.texinfo (Freeing Discarded Symbols, Bison Symbols):
+	* doc/bison.texinfo (Freeing Discarded Symbols, Table of Symbols):
 	Update.
 	* src/parse-gram.y (TYPE_TAG_NONE, generic_symlist_item): Implement.
 	* src/scan-gram.l (INITIAL): Implement.
@@ -1282,7 +1299,7 @@
 	* NEWS (2.3a+): Mention.
 	* doc/bison.texinfo (Freeing Discarded Symbols): Document this and the
 	previous change today related to mid-rules.
-	(Bison Symbols): Remove %symbol-default and add <*> and <!>.
+	(Table of Symbols): Remove %symbol-default and add <*> and <!>.
 	* src/parse-gram.y (PERCENT_SYMBOL_DEFAULT): Remove.
 	(TYPE_TAG_ANY): Add as <*>.
 	(TYPE_TAG_NONE): Add as <!>.
@@ -1375,8 +1392,8 @@
 	alternatives to...
 	(Prologue Alternatives): ... this new section, and extend it to discuss
 	all 4 directives in detail.
-	(Bison Symbols): Clean up discussion of prologue alternatives and add
+	(Table of Symbols): Clean up discussion of prologue alternatives and
-	%code-top.
+	add %code-top.
 
 2006-10-16  Juan Manuel Guerrero  <juan.guerrero@gmx.de>
 
@@ -1832,7 +1849,7 @@
 	<http://lists.gnu.org/archive/html/bison-patches/2006-09/msg00007.html>.
 	* NEWS (2.3+): Add %symbol-default to example.
 	* bison.texinfo (Freeing Discarded Symbols): Likewise.
-	(Bison Symbols): Add entry for %symbol-default.
+	(Table of Symbols): Add entry for %symbol-default.
 	* src/parse-gram.y (PERCENT_SYMBOL_DEFAULT): New token.
 	(generic_symlist, generic_symlist_item): New nonterminals for creating
 	a list in which each item is a symbol, semantic type, or
@@ -2474,7 +2491,7 @@
 	prologue blocks with %*-header declarations.
 	(Calc++ Parser): Likewise.
 	(Bison Declaration Summary): Update names.
-	(Bison Symbols): Update description.
+	(Table of Symbols): Update description.
 	* src/parse-gram.y (PERCENT_AFTER_DEFINITIONS): Update to...
 	(PERCENT_END_HEADER): ... this.
 	(PERCENT_BEFORE_DEFINITIONS): Update to...
@@ -2555,7 +2572,7 @@
 	file.
 	(Calc++ Parser): Forward declare driver in a %before-definitions rather
 	than in the pre-prologue so that make check succeeds.
-	(Bison Symbols): Add entries for %before-definitions and
+	(Table of Symbols): Add entries for %before-definitions and
 	%after-definitions.
 	* src/parse-gram.y (PERCENT_BEFORE_DEFINITIONS): New token for
 	%before-definitions.
@@ -3645,7 +3662,7 @@
 	in the yychar entry.
 	In the yychar entry, remove mention of the local yychar case (pure
 	parser) since this is irrelevant information when writing semantic
-	actions and since it's already discussed in `Bison Symbols' where
+	actions and since it's already discussed in `Table of Symbols' where
 	yychar is otherwise described as an external variable.
 	In the yychar entry, don't call it the `current' look-ahead since it
 	isn't when semantic actions are deferred.
@@ -3656,7 +3673,7 @@
 	`current' look-ahead, and do mention yylval and yylloc.
 	(Error Recovery): Cross-reference `Action Features' when mentioning
 	yyclearin.
-	(Bison Symbols): In the yychar entry, don't call it the `current'
+	(Table of Symbols): In the yychar entry, don't call it the `current'
 	look-ahead.
 	In the yylloc and yylval entries, mention look-ahead usage.
 

doc/bison.texinfo

@@ -2695,7 +2695,7 @@ field, which identifies the purpose of the code and thus the location(s) where
 Bison should generate it.
 For C/C++, the qualifier can be omitted for the default location, or it can be
 @code{requires}, @code{provides}, or @code{top}.
-@xref{Table of Symbols,,Bison Symbols}.
+@xref{Decl Summary,,%code}.
 
 Look again at the example of the previous section:
 
@@ -2793,8 +2793,8 @@ parser source code file.
 The first line after the warning is required by @code{YYSTYPE} and thus also
 needs to appear in the parser source code file.
 However, if you've instructed Bison to generate a parser header file
-(@pxref{Table of Symbols, ,%defines}), you probably want that line to appear
+(@pxref{Decl Summary, ,%defines}), you probably want that line to appear before
-before the @code{YYSTYPE} definition in that header file as well.
+the @code{YYSTYPE} definition in that header file as well.
 The @code{YYLTYPE} definition should also appear in the parser header file to
 override the default @code{YYLTYPE} definition there.
 
@@ -4569,12 +4569,129 @@ Declare the expected number of shift-reduce conflicts
 In order to change the behavior of @command{bison}, use the following
 directives:
 
+@deffn {Directive} %code @{@var{code}@}
+@findex %code
+This is the unqualified form of the @code{%code} directive.
+It inserts @var{code} verbatim at the default location in the output.
+That default location is determined by the selected target language and/or
+parser skeleton.
+
+@cindex Prologue
+For the current C/C++ skeletons, the default location is the parser source code
+file after the usual contents of the parser header file.
+Thus, @code{%code} replaces the traditional Yacc prologue,
+@code{%@{@var{code}%@}}, for most purposes.
+For a detailed discussion, see @ref{Prologue Alternatives}.
+
+@comment For Java, the default location is inside the parser class.
+
+(Like all the Yacc prologue alternatives, this directive is experimental.
+More user feedback will help to determine whether it should become a permanent
+feature.)
+@end deffn
+
+@deffn {Directive} %code @var{qualifier} @{@var{code}@}
+This is the qualified form of the @code{%code} directive.
+If you need to specify location-sensitive verbatim @var{code} that does not
+belong at the default location selected by the unqualified @code{%code} form,
+use this form instead.
+
+@var{qualifier} identifies the purpose of @var{code} and thus the location(s)
+where Bison should generate it.
+Not all values of @var{qualifier} are available for all target languages:
+
+@itemize @bullet
+@findex %code requires
+@item requires
+
+@itemize @bullet
+@item Language(s): C, C++
+
+@item Purpose: This is the best place to write dependency code required for
+@code{YYSTYPE} and @code{YYLTYPE}.
+In other words, it's the best place to define types referenced in @code{%union}
+directives, and it's the best place to override Bison's default @code{YYSTYPE}
+and @code{YYLTYPE} definitions.
+
+@item Location(s): The parser header file and the parser source code file
+before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE} definitions.
+@end itemize
+
+@item provides
+@findex %code provides
+
+@itemize @bullet
+@item Language(s): C, C++
+
+@item Purpose: This is the best place to write additional definitions and
+declarations that should be provided to other modules.
+
+@item Location(s): The parser header file and the parser source code file after
+the Bison-generated @code{YYSTYPE}, @code{YYLTYPE}, and token definitions.
+@end itemize
+
+@item top
+@findex %code top
+
+@itemize @bullet
+@item Language(s): C, C++
+
+@item Purpose: The unqualified @code{%code} or @code{%code requires} should
+usually be more appropriate than @code{%code top}.
+However, occasionally it is necessary to insert code much nearer the top of the
+parser source code file.
+For example:
+
+@smallexample
+%code top @{
+  #define _GNU_SOURCE
+  #include <stdio.h>
+@}
+@end smallexample
+
+@item Location(s): Near the top of the parser source code file.
+@end itemize
+@ignore
+@item imports
+@findex %code imports
+
+@itemize @bullet
+@item Language(s): Java
+
+@item Purpose: This is the best place to write Java import directives.
+
+@item Location(s): The parser Java file after any Java package directive and
+before any class definitions.
+@end itemize
+@end ignore
+@end itemize
+
+(Like all the Yacc prologue alternatives, this directive is experimental.
+More user feedback will help to determine whether it should become a permanent
+feature.)
+
+@cindex Prologue
+For a detailed discussion of how to use @code{%code} in place of the
+traditional Yacc prologue for C/C++, see @ref{Prologue Alternatives}.
+@end deffn
+
 @deffn {Directive} %debug
 In the parser file, define the macro @code{YYDEBUG} to 1 if it is not
 already defined, so that the debugging facilities are compiled.
 @end deffn
 @xref{Tracing, ,Tracing Your Parser}.
 
+@deffn {Directive} %define @var{define-variable}
+@deffnx {Directive} %define @var{define-variable} @var{value}
+Define a variable to adjust Bison's behavior.
+The list of available variables and their meanings depends on the selected
+target language and/or the parser skeleton (@pxref{Decl Summary,,%language}).
+The @var{value} can be omitted for boolean variables; for
+boolean variables, the skeletons will treat a @var{value} of @samp{0}
+or @samp{false} as the boolean variable being false, and anything else
+as true.
+@end deffn
+
 @deffn {Directive} %defines
 Write a header file containing macro definitions for the token type
 names defined in the grammar as well as a few other declarations.
@@ -4612,16 +4729,7 @@ Tokens}.
 @findex %code provides
 If you have declared @code{%code requires} or @code{%code provides}, the output
 header also contains their code.
-@xref{Table of Symbols, ,%code}.
+@xref{Decl Summary, ,%code}.
-@end deffn
-
-@deffn {Directive} %define @var{define-variable}
-@deffnx {Directive} %define @var{define-variable} @var{value}
-Define a variable to be used by the skeleton in order to adjust its
-behavior.  The @var{value} can be omitted for boolean variables; for
-boolean variables, the skeletons will treat a @var{value} of @samp{0}
-or @samp{false} as the boolean variable being false, and anything else
-as true.
 @end deffn
 
 @deffn {Directive} %defines @var{defines-file}
@@ -7903,7 +8011,7 @@ 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.
-@xref{Table of Symbols, ,%code}.
+@xref{Decl Summary, ,%code}.
 
 @comment file: calc++-parser.yy
 @example
@@ -8669,109 +8777,9 @@ Start-Symbol}.  It cannot be used in the grammar.
 @end deffn
 
 @deffn {Directive} %code @{@var{code}@}
-@findex %code
+@deffnx {Directive} %code @var{qualifier} @{@var{code}@}
-This is the unqualified form of the @code{%code} directive.
+Insert @var{code} verbatim into output parser source.
-It inserts @var{code} verbatim at the default location in the output.
+@xref{Decl Summary,,%code}.
-That default location is determined by the selected target language and/or
-parser skeleton.
-
-@cindex Prologue
-For the current C/C++ skeletons, the default location is the parser source code
-file after the usual contents of the parser header file.
-Thus, @code{%code} replaces the traditional Yacc prologue,
-@code{%@{@var{code}%@}}, for most purposes.
-For a detailed discussion, see @ref{Prologue Alternatives}.
-
-@comment For Java, the default location is inside the parser class.
-
-(Like all the Yacc prologue alternatives, this directive is experimental.
-More user feedback will help to determine whether it should become a permanent
-feature.)
-@end deffn
-
-@deffn {Directive} %code @var{qualifier} @{@var{code}@}
-This is the qualified form of the @code{%code} directive.
-If you need to specify location-sensitive verbatim @var{code} that does not
-belong at the default location selected by the unqualified @code{%code} form,
-use this form instead.
-
-@var{qualifier} identifies the purpose of @var{code} and thus the location(s)
-where Bison should generate it.
-Not all values of @var{qualifier} are available for all target languages:
-
-@itemize @bullet
-@findex %code requires
-@item requires
-
-@itemize @bullet
-@item Language(s): C, C++
-
-@item Purpose: This is the best place to write dependency code required for
-@code{YYSTYPE} and @code{YYLTYPE}.
-In other words, it's the best place to define types referenced in @code{%union}
-directives, and it's the best place to override Bison's default @code{YYSTYPE}
-and @code{YYLTYPE} definitions.
-
-@item Location(s): The parser header file and the parser source code file
-before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE} definitions.
-@end itemize
-
-@item provides
-@findex %code provides
-
-@itemize @bullet
-@item Language(s): C, C++
-
-@item Purpose: This is the best place to write additional definitions and
-declarations that should be provided to other modules.
-
-@item Location(s): The parser header file and the parser source code file after
-the Bison-generated @code{YYSTYPE}, @code{YYLTYPE}, and token definitions.
-@end itemize
-
-@item top
-@findex %code top
-
-@itemize @bullet
-@item Language(s): C, C++
-
-@item Purpose: The unqualified @code{%code} or @code{%code requires} should
-usually be more appropriate than @code{%code top}.
-However, occasionally it is necessary to insert code much nearer the top of the
-parser source code file.
-For example:
-
-@smallexample
-%code top @{
-  #define _GNU_SOURCE
-  #include <stdio.h>
-@}
-@end smallexample
-
-@item Location(s): Near the top of the parser source code file.
-@end itemize
-@ignore
-@item imports
-@findex %code imports
-
-@itemize @bullet
-@item Language(s): Java
-
-@item Purpose: This is the best place to write Java import directives.
-
-@item Location(s): The parser Java file after any Java package directive and
-before any class definitions.
-@end itemize
-@end ignore
-@end itemize
-
-(Like all the Yacc prologue alternatives, this directive is experimental.
-More user feedback will help to determine whether it should become a permanent
-feature.)
-
-@cindex Prologue
-For a detailed discussion of how to use @code{%code} in place of the
-traditional Yacc prologue for C/C++, see @ref{Prologue Alternatives}.
 @end deffn
 
 @deffn {Directive} %debug
@@ -8790,6 +8798,12 @@ Precedence}.
 @end deffn
 @end ifset
 
+@deffn {Directive} %define @var{define-variable}
+@deffnx {Directive} %define @var{define-variable} @var{value}
+Define a variable to adjust Bison's behavior.
+@xref{Decl Summary,,%define}.
+@end deffn
+
 @deffn {Directive} %defines
 Bison declaration to create a header file meant for the scanner.
 @xref{Decl Summary}.