minor documentation cleanup

[Joel E. Denny]

I committed this.

Index: ChangeLog
===================================================================
RCS file: /sources/bison/bison/ChangeLog,v
retrieving revision 1.1672
diff -p -u -r1.1672 ChangeLog
--- ChangeLog   26 Jan 2007 23:11:59 -0000      1.1672
+++ ChangeLog   27 Jan 2007 23:30:56 -0000
@@ -1,3 +1,20 @@
+2007-01-27  Joel E. Denny  <address@hidden>
+
+       * 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  <address@hidden>
 
        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
        address@hidden'.  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  <address@hidden>
@@ -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
-       %code-top.
+       (Table of Symbols): Clean up discussion of prologue alternatives and
+       add %code-top.
 
 2006-10-16  Juan Manuel Guerrero  <address@hidden>
 
@@ -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.
 
Index: doc/bison.texinfo
===================================================================
RCS file: /sources/bison/bison/doc/bison.texinfo,v
retrieving revision 1.223
diff -p -u -r1.223 bison.texinfo
--- doc/bison.texinfo   23 Jan 2007 12:24:27 -0000      1.223
+++ doc/bison.texinfo   27 Jan 2007 23:31:00 -0000
@@ -2695,7 +2695,7 @@ field, which identifies the purpose of t
 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}.
address@hidden of Symbols,,Bison Symbols}.
address@hidden 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
-before the @code{YYSTYPE} definition in that header file as well.
+(@pxref{Decl Summary, ,%defines}), you probably want that line to appear before
+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-red
 In order to change the behavior of @command{bison}, use the following
 directives:
 
address@hidden {Directive} %code @address@hidden@}
address@hidden %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.
+
address@hidden 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,
address@hidden@address@hidden@}}, for most purposes.
+For a detailed discussion, see @ref{Prologue Alternatives}.
+
address@hidden 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.)
address@hidden deffn
+
address@hidden {Directive} %code @var{qualifier} @address@hidden@}
+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.
+
address@hidden 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:
+
address@hidden @bullet
address@hidden %code requires
address@hidden requires
+
address@hidden @bullet
address@hidden Language(s): C, C++
+
address@hidden Purpose: This is the best place to write dependency code 
required for
address@hidden 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.
+
address@hidden Location(s): The parser header file and the parser source code 
file
+before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE} definitions.
address@hidden itemize
+
address@hidden provides
address@hidden %code provides
+
address@hidden @bullet
address@hidden Language(s): C, C++
+
address@hidden Purpose: This is the best place to write additional definitions 
and
+declarations that should be provided to other modules.
+
address@hidden Location(s): The parser header file and the parser source code 
file after
+the Bison-generated @code{YYSTYPE}, @code{YYLTYPE}, and token definitions.
address@hidden itemize
+
address@hidden top
address@hidden %code top
+
address@hidden @bullet
address@hidden Language(s): C, C++
+
address@hidden 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:
+
address@hidden
+%code top @{
+  #define _GNU_SOURCE
+  #include <stdio.h>
address@hidden
address@hidden smallexample
+
address@hidden Location(s): Near the top of the parser source code file.
address@hidden itemize
address@hidden
address@hidden imports
address@hidden %code imports
+
address@hidden @bullet
address@hidden Language(s): Java
+
address@hidden Purpose: This is the best place to write Java import directives.
+
address@hidden Location(s): The parser Java file after any Java package 
directive and
+before any class definitions.
address@hidden itemize
address@hidden ignore
address@hidden 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.)
+
address@hidden 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}.
address@hidden 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}.
 
address@hidden {Directive} %define @var{define-variable}
address@hidden {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.
address@hidden 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.
address@hidden of Symbols, ,%code}.
address@hidden deffn
-
address@hidden {Directive} %define @var{define-variable}
address@hidden {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.
address@hidden Summary, ,%code}.
 @end deffn
 
 @deffn {Directive} %defines @var{defines-file}
@@ -7903,7 +8011,7 @@ reciprocally, both cannot include the he
 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.
address@hidden of Symbols, ,%code}.
address@hidden Summary, ,%code}.
 
 @comment file: calc++-parser.yy
 @example
@@ -8669,109 +8777,9 @@ Start-Symbol}.  It cannot be used in the
 @end deffn
 
 @deffn {Directive} %code @address@hidden@}
address@hidden %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.
-
address@hidden 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,
address@hidden@address@hidden@}}, for most purposes.
-For a detailed discussion, see @ref{Prologue Alternatives}.
-
address@hidden 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.)
address@hidden deffn
-
address@hidden {Directive} %code @var{qualifier} @address@hidden@}
-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.
-
address@hidden 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:
-
address@hidden @bullet
address@hidden %code requires
address@hidden requires
-
address@hidden @bullet
address@hidden Language(s): C, C++
-
address@hidden Purpose: This is the best place to write dependency code 
required for
address@hidden 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.
-
address@hidden Location(s): The parser header file and the parser source code 
file
-before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE} definitions.
address@hidden itemize
-
address@hidden provides
address@hidden %code provides
-
address@hidden @bullet
address@hidden Language(s): C, C++
-
address@hidden Purpose: This is the best place to write additional definitions 
and
-declarations that should be provided to other modules.
-
address@hidden Location(s): The parser header file and the parser source code 
file after
-the Bison-generated @code{YYSTYPE}, @code{YYLTYPE}, and token definitions.
address@hidden itemize
-
address@hidden top
address@hidden %code top
-
address@hidden @bullet
address@hidden Language(s): C, C++
-
address@hidden 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:
-
address@hidden
-%code top @{
-  #define _GNU_SOURCE
-  #include <stdio.h>
address@hidden
address@hidden smallexample
-
address@hidden Location(s): Near the top of the parser source code file.
address@hidden itemize
address@hidden
address@hidden imports
address@hidden %code imports
-
address@hidden @bullet
address@hidden Language(s): Java
-
address@hidden Purpose: This is the best place to write Java import directives.
-
address@hidden Location(s): The parser Java file after any Java package 
directive and
-before any class definitions.
address@hidden itemize
address@hidden ignore
address@hidden 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.)
-
address@hidden 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}.
address@hidden {Directive} %code @var{qualifier} @address@hidden@}
+Insert @var{code} verbatim into output parser source.
address@hidden Summary,,%code}.
 @end deffn
 
 @deffn {Directive} %debug
@@ -8790,6 +8798,12 @@ Precedence}.
 @end deffn
 @end ifset
 
address@hidden {Directive} %define @var{define-variable}
address@hidden {Directive} %define @var{define-variable} @var{value}
+Define a variable to adjust Bison's behavior.
address@hidden Summary,,%define}.
address@hidden deffn
+
 @deffn {Directive} %defines
 Bison declaration to create a header file meant for the scanner.
 @xref{Decl Summary}.