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.

src/parse-gram.h

@@ -56,46 +56,47 @@
      PERCENT_DPREC = 270,
      PERCENT_MERGE = 271,
      PERCENT_CODE = 272,
-     PERCENT_DEBUG = 273,
-     PERCENT_DEFAULT_PREC = 274,
-     PERCENT_DEFINE = 275,
-     PERCENT_DEFINES = 276,
-     PERCENT_ERROR_VERBOSE = 277,
-     PERCENT_EXPECT = 278,
-     PERCENT_EXPECT_RR = 279,
-     PERCENT_FILE_PREFIX = 280,
-     PERCENT_GLR_PARSER = 281,
-     PERCENT_INITIAL_ACTION = 282,
-     PERCENT_LEX_PARAM = 283,
-     PERCENT_LOCATIONS = 284,
-     PERCENT_NAME_PREFIX = 285,
-     PERCENT_NO_DEFAULT_PREC = 286,
-     PERCENT_NO_LINES = 287,
-     PERCENT_NONDETERMINISTIC_PARSER = 288,
-     PERCENT_OUTPUT = 289,
-     PERCENT_PARSE_PARAM = 290,
-     PERCENT_PROVIDES = 291,
-     PERCENT_PURE_PARSER = 292,
-     PERCENT_PUSH_PARSER = 293,
-     PERCENT_REQUIRE = 294,
-     PERCENT_REQUIRES = 295,
-     PERCENT_SKELETON = 296,
-     PERCENT_START = 297,
-     PERCENT_TOKEN_TABLE = 298,
-     PERCENT_VERBOSE = 299,
-     PERCENT_YACC = 300,
-     BRACED_CODE = 301,
-     CHAR = 302,
-     EPILOGUE = 303,
-     EQUAL = 304,
-     ID = 305,
-     ID_COLON = 306,
-     PERCENT_PERCENT = 307,
-     PIPE = 308,
-     PROLOGUE = 309,
-     SEMICOLON = 310,
-     TYPE = 311,
-     PERCENT_UNION = 312
+     PERCENT_CODE_TOP = 273,
+     PERCENT_DEBUG = 274,
+     PERCENT_DEFAULT_PREC = 275,
+     PERCENT_DEFINE = 276,
+     PERCENT_DEFINES = 277,
+     PERCENT_ERROR_VERBOSE = 278,
+     PERCENT_EXPECT = 279,
+     PERCENT_EXPECT_RR = 280,
+     PERCENT_FILE_PREFIX = 281,
+     PERCENT_GLR_PARSER = 282,
+     PERCENT_INITIAL_ACTION = 283,
+     PERCENT_LEX_PARAM = 284,
+     PERCENT_LOCATIONS = 285,
+     PERCENT_NAME_PREFIX = 286,
+     PERCENT_NO_DEFAULT_PREC = 287,
+     PERCENT_NO_LINES = 288,
+     PERCENT_NONDETERMINISTIC_PARSER = 289,
+     PERCENT_OUTPUT = 290,
+     PERCENT_PARSE_PARAM = 291,
+     PERCENT_PROVIDES = 292,
+     PERCENT_PURE_PARSER = 293,
+     PERCENT_PUSH_PARSER = 294,
+     PERCENT_REQUIRE = 295,
+     PERCENT_REQUIRES = 296,
+     PERCENT_SKELETON = 297,
+     PERCENT_START = 298,
+     PERCENT_TOKEN_TABLE = 299,
+     PERCENT_VERBOSE = 300,
+     PERCENT_YACC = 301,
+     BRACED_CODE = 302,
+     CHAR = 303,
+     EPILOGUE = 304,
+     EQUAL = 305,
+     ID = 306,
+     ID_COLON = 307,
+     PERCENT_PERCENT = 308,
+     PIPE = 309,
+     PROLOGUE = 310,
+     SEMICOLON = 311,
+     TYPE = 312,
+     PERCENT_UNION = 313
    };
 #endif
 /* Tokens.  */
@@ -115,46 +116,47 @@
 #define PERCENT_DPREC 270
 #define PERCENT_MERGE 271
 #define PERCENT_CODE 272
-#define PERCENT_DEBUG 273
-#define PERCENT_DEFAULT_PREC 274
-#define PERCENT_DEFINE 275
-#define PERCENT_DEFINES 276
-#define PERCENT_ERROR_VERBOSE 277
-#define PERCENT_EXPECT 278
-#define PERCENT_EXPECT_RR 279
-#define PERCENT_FILE_PREFIX 280
-#define PERCENT_GLR_PARSER 281
-#define PERCENT_INITIAL_ACTION 282
-#define PERCENT_LEX_PARAM 283
-#define PERCENT_LOCATIONS 284
-#define PERCENT_NAME_PREFIX 285
-#define PERCENT_NO_DEFAULT_PREC 286
-#define PERCENT_NO_LINES 287
-#define PERCENT_NONDETERMINISTIC_PARSER 288
-#define PERCENT_OUTPUT 289
-#define PERCENT_PARSE_PARAM 290
-#define PERCENT_PROVIDES 291
-#define PERCENT_PURE_PARSER 292
-#define PERCENT_PUSH_PARSER 293
-#define PERCENT_REQUIRE 294
-#define PERCENT_REQUIRES 295
-#define PERCENT_SKELETON 296
-#define PERCENT_START 297
-#define PERCENT_TOKEN_TABLE 298
-#define PERCENT_VERBOSE 299
-#define PERCENT_YACC 300
-#define BRACED_CODE 301
-#define CHAR 302
-#define EPILOGUE 303
-#define EQUAL 304
-#define ID 305
-#define ID_COLON 306
-#define PERCENT_PERCENT 307
-#define PIPE 308
-#define PROLOGUE 309
-#define SEMICOLON 310
-#define TYPE 311
-#define PERCENT_UNION 312
+#define PERCENT_CODE_TOP 273
+#define PERCENT_DEBUG 274
+#define PERCENT_DEFAULT_PREC 275
+#define PERCENT_DEFINE 276
+#define PERCENT_DEFINES 277
+#define PERCENT_ERROR_VERBOSE 278
+#define PERCENT_EXPECT 279
+#define PERCENT_EXPECT_RR 280
+#define PERCENT_FILE_PREFIX 281
+#define PERCENT_GLR_PARSER 282
+#define PERCENT_INITIAL_ACTION 283
+#define PERCENT_LEX_PARAM 284
+#define PERCENT_LOCATIONS 285
+#define PERCENT_NAME_PREFIX 286
+#define PERCENT_NO_DEFAULT_PREC 287
+#define PERCENT_NO_LINES 288
+#define PERCENT_NONDETERMINISTIC_PARSER 289
+#define PERCENT_OUTPUT 290
+#define PERCENT_PARSE_PARAM 291
+#define PERCENT_PROVIDES 292
+#define PERCENT_PURE_PARSER 293
+#define PERCENT_PUSH_PARSER 294
+#define PERCENT_REQUIRE 295
+#define PERCENT_REQUIRES 296
+#define PERCENT_SKELETON 297
+#define PERCENT_START 298
+#define PERCENT_TOKEN_TABLE 299
+#define PERCENT_VERBOSE 300
+#define PERCENT_YACC 301
+#define BRACED_CODE 302
+#define CHAR 303
+#define EPILOGUE 304
+#define EQUAL 305
+#define ID 306
+#define ID_COLON 307
+#define PERCENT_PERCENT 308
+#define PIPE 309
+#define PROLOGUE 310
+#define SEMICOLON 311
+#define TYPE 312
+#define PERCENT_UNION 313
 
 
 
@@ -163,7 +165,7 @@
 typedef union YYSTYPE
 {
 /* Line 1535 of yacc.c  */
-#line 98 "../../src/parse-gram.y"
+#line 98 "parse-gram.y"
 
   symbol *symbol;
   symbol_list *list;
@@ -175,7 +177,7 @@ typedef union YYSTYPE
 }
 
 /* Line 1535 of yacc.c  */
-#line 179 "../../src/parse-gram.h"
+#line 181 "parse-gram.h"
 	YYSTYPE;
 # define YYSTYPE_IS_TRIVIAL 1
 # define yystype YYSTYPE /* obsolescent; will be withdrawn */

src/parse-gram.y

@@ -134,6 +134,7 @@ static int current_prec = 0;
 
 %token
   PERCENT_CODE            "%code"
+  PERCENT_CODE_TOP        "%code-top"
   PERCENT_DEBUG           "%debug"
   PERCENT_DEFAULT_PREC    "%default-prec"
   PERCENT_DEFINE          "%define"
@@ -221,7 +222,6 @@ prologue_declarations:
 prologue_declaration:
   grammar_declaration
 | "%{...%}"     { prologue_augment (translate_code ($1, @1), @1, union_seen); }
-| "%code" braceless                { prologue_augment ($2, @2, true); }
 | "%debug"                         { debug_flag = true; }
 | "%define" STRING content.opt     { muscle_insert ($2, $3); }
 | "%defines"                       { defines_flag = true; }
@@ -245,11 +245,9 @@ prologue_declaration:
 | "%nondeterministic-parser"	{ nondeterministic_parser = true; }
 | "%output" "=" STRING          { spec_outfile = $3; }
 | "%parse-param" "{...}"	{ add_param ("parse_param", $2, @2); }
-| "%provides" braceless         { muscle_code_grow ("provides", $2, @2); }
 | "%pure-parser"                { pure_parser = true; }
 | "%push-parser"                { push_parser = true; }
 | "%require" STRING             { version_check (&@2, $2); }
-| "%requires" braceless         { muscle_code_grow ("requires", $2, @2); }
 | "%skeleton" STRING            { skeleton = $2; }
 | "%token-table"                { token_table_flag = true; }
 | "%verbose"                    { report_flag = report_states; }
@@ -288,6 +286,10 @@ grammar_declaration:
     {
       default_prec = false;
     }
+| "%code" braceless      { prologue_augment ($2, @2, true); }
+| "%code-top" braceless  { prologue_augment ($2, @2, false); }
+| "%provides" braceless  { muscle_code_grow ("provides", $2, @2); }
+| "%requires" braceless  { muscle_code_grow ("requires", $2, @2); }
 ;
 
 

src/reader.c

@@ -72,7 +72,7 @@ grammar_start_symbol_set (symbol *sym, location loc)
 
 /*---------------------------------------------------------------------.
 | There are two prologues: one before the first %union and one after.  |
-|  Augment the one specified by POST.                                  |
+| Augment the one specified by POST.                                   |
 `---------------------------------------------------------------------*/
 
 void

src/scan-gram.l

@@ -158,6 +158,7 @@ splice	 (\\[ \f\t\v]*\n)*
 {
   "%binary"               	    return PERCENT_NONASSOC;
   "%code"                           return PERCENT_CODE;
+  "%code-top"                       return PERCENT_CODE_TOP;
   "%debug"                	    return PERCENT_DEBUG;
   "%default"[-_]"prec"    	    return PERCENT_DEFAULT_PREC;
   "%define"               	    return PERCENT_DEFINE;