Similar to the recently removed %before-header, add %code-top as the

alternative to the pre-prologue.  Mentioned at
<http://lists.gnu.org/archive/html/bison-patches/2006-10/msg00063.html>.
Also, let the prologue alternatives appear in the grammar section.
* src/parse-gram.y (PERCENT_CODE_TOP): New token.
(prologue_declaration): Move the existing prologue alternatives to...
(grammar_declaration): ... here and add %code-top.
* src/scan-gram.l (PERCENT_CODE_TOP): New token.

Clean up and extend documentation for the prologue alternatives.
* NEWS (2.3a+): Describe prologue alternatives.
* doc/bison.texinfo (Prologue): Move discussion of prologue
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.

NEWS

@@ -6,6 +6,74 @@ Changes in version 2.3a+ (????-??-??):
 * The -g and --graph options now output graphs in Graphviz DOT format,
   not VCG format.
 
+* The Yacc prologue alternatives from Bison 2.3a have been rewritten as the
+  following directives:
+
+    1. %code {CODE}
+
+       Other than semantic actions, this is probably the most common place you
+       should write verbatim code for the parser implementation.  For C/C++, it
+       replaces the traditional Yacc prologue, `%{CODE%}', for most purposes.
+       For Java, it inserts your CODE into the parser class.  Compare with:
+
+         - `%{CODE%}' appearing after the first `%union {CODE}' in a C/C++
+           based grammar file.  While Bison will continue to support `%{CODE%}'
+           for backward compatibility, `%code {CODE}' is cleaner as its
+           functionality does not depend on its position in the grammar file
+           relative to any `%union {CODE}'.  Specifically, `%code {CODE}'
+           always inserts your CODE into the parser code file after the usual
+           contents of the parser header file.
+         - `%after-header {CODE}', which only Bison 2.3a supported.
+
+    2. %requires {CODE}
+
+       This is the right place to write dependency code for externally exposed
+       definitions required by Bison.  For C/C++, such exposed definitions are
+       those usually appearing in the parser header file.  Thus, this is the
+       right place to define types referenced in `%union {CODE}' directives,
+       and it is the right place to override Bison's default YYSTYPE and
+       YYLTYPE definitions.  For Java, this is the right place to write import
+       directives.  Compare with:
+
+         - `%{CODE%}' appearing before the first `%union {CODE}' in a C/C++
+           based grammar file.  Unlike `%{CODE%}', `%requires {CODE}' inserts
+           your CODE both into the parser code file and into the parser header
+           file since Bison's required definitions should depend on it in both
+           places.
+         - `%start-header {CODE}', which only Bison 2.3a supported.
+
+    3. %provides {CODE}
+    
+       This is the right place to write additional definitions you would like
+       Bison to expose externally.  For C/C++, this directive inserts your CODE
+       both into the parser header file and into the parser code file after
+       Bison's required definitions.  For Java, it inserts your CODE into the
+       parser java file after the parser class.  Compare with:
+
+         - `%end-header {CODE}', which only Bison 2.3a supported.
+
+    4. %code-top {CODE}
+
+       Occasionally for C/C++ it is desirable to insert code near the top of
+       the parser code file.  For example:
+
+         %code-top {
+           #define _GNU_SOURCE
+           #include <stdio.h>
+         }
+
+       For Java, `%code-top {CODE}' is currently unused.  Compare with:
+
+         - `%{CODE%}' appearing before the first `%union {CODE}' in a C/C++
+           based grammar file.  `%code-top {CODE}' is cleaner as its
+           functionality does not depend on its position in the grammar file
+           relative to any `%union {CODE}'.
+         - `%before-header {CODE}', which only Bison 2.3a supported.
+
+  If you have multiple occurrences of any one of the above four directives,
+  Bison will concatenate the contents in the order they appear in the grammar
+  file.
+
 Changes in version 2.3a, 2006-09-13:
 
 * Instead of %union, you can define and use your own union type