preparing for 2.3b

[Joel E. Denny]

In my opinion, the following patch (not yet committed) is the last thing 
that really needs to happen before the next Bison release, but we need to 
discuss a few things beforehand.

1. It's been a long time since 2.3 or even 2.3a was released, and there 
have been many changes that I feel could use more beta testing before we 
claim stability.  Among those changes are at least two major ones that 
could impact existing functionality:

a. mv push.c yacc.c

b. Unreachable state removal.  See the NEWS file for details.

While I feel that the code in both cases is solid, it's hard to predict 
how some users may be affected.  A test release would be a good 
opportunity to find out, for example, if unreachable state removal should 
be disabled by default.

Even without these two major changes, I think the next release should be 
2.3b.  2.4 might follow soon afterwards.  Also, I hope 2.4 will include 
translation of user messages generated by the skeletons.

2. There's the question of what features are experimental in this release:

a. The following patch removes the "experimental" label from %language.  
It's a fairly straight-forward interface, and I don't foresee much 
changing about it.  On the other hand, I don't recall much user feedback.  
What do others think about this?

b. The push parsing and Java interfaces are complex and I've not seen much 
user feedback.  The following patch labels their interfaces as 
experimental.  In other words, these features are not going away, but we 
reserve the freedom to change them in a backward incompatible manner based 
on user feedback.

c. Finally, the XML output is completely undocumented in Bison except in 
the command-line usage notes, and I've seen little user feedback.  The 
following patch removes mention of it from the command-line usage notes 
for now.  Those who follow the mailing lists know about it already.  
Let's wait to tell more casual users until we've written at least a little 
more documentation.

Index: ChangeLog
===================================================================
RCS file: /sources/bison/bison/ChangeLog,v
retrieving revision 1.1771
diff -p -u -r1.1771 ChangeLog
--- ChangeLog   17 Feb 2008 19:55:48 -0000      1.1771
+++ ChangeLog   17 Feb 2008 22:21:25 -0000
@@ -1,5 +1,27 @@
 2008-02-17  Joel E. Denny  <address@hidden>
 
+       * NEWS (2.3a+): Don't say %language is experimental.  Mention Java and
+       say its interface is experimental.
+       * doc/bison.texinfo (Decl Summary): In the %language entry, mention
+       Java.
+       (Bison Options): In the -L and --language entry, mention Java.
+       (Java Bison Interface): Say the interface is experimental.
+       * src/getargs.c (usage): Mention -L and --language.
+
+       * NEWS (2.3a+): Say the push parsing interface is experimental.
+       * doc/bison.texinfo (Push Decl): Likewise.
+       (Decl Summary): Likewise in the "%define api.push_pull" entry.
+       (Push Parser Function): Likewise.
+       (Pull Parser Function): Likewise.
+       (Parser Create Function): Likewise.
+       (Parser Delete Function): Likewise.
+       (Table of Symbols): Likewise in the yypstate_delete, yypstate_new,
+       yypull_parse, and yypush_parse entries.
+
+       * src/getargs.c (usage): Don't mention --xml yet.
+
+2008-02-17  Joel E. Denny  <address@hidden>
+
        * data/Makefile.am (dist_pkgdata_DATA): Remove push.c.
        * data/push.c: Rename to...
        * data/yacc.c: ... this, overwriting it.
Index: NEWS
===================================================================
RCS file: /sources/bison/bison/NEWS,v
retrieving revision 1.186
diff -p -u -r1.186 NEWS
--- NEWS        17 Feb 2008 02:47:53 -0000      1.186
+++ NEWS        17 Feb 2008 22:21:25 -0000
@@ -28,13 +28,29 @@ Changes in version 2.3a+ (????-??-??):
 
   See the new section `A Push Parser' in the Bison manual for details.
 
+  The current push parsing interface is experimental and may evolve.  More user
+  feedback will help to stabilize it.
+
 * The -g and --graph options now output graphs in Graphviz DOT format,
   not VCG format.
 
-* An experimental directive %language specifies the language of the
-  generated parser, which can be C (the default) or C++.  This
-  directive affects the skeleton used, and the names of the generated
-  files if the grammar file's name ends in ".y".
+* Java
+
+  Bison can now generate an LALR(1) parser in Java.  The skeleton is
+  `data/lalr1.java'.  Consider using the new %language directive instead of
+  %skeleton to select it.
+
+  See the new section `Java Parsers' in the Bison manual for details.
+
+  The current Java interface is experimental and may evolve.  More user
+  feedback will help to stabilize it.
+
+* %language
+
+  This new directive specifies the programming language of the generated
+  parser, which can be C (the default), C++, or Java.  This directive affects
+  the skeleton used and the names of the generated files if the grammar file's
+  name ends in ".y".
 
 * The grammar file may now specify the name of the parser header file using
   %defines.  For example:
Index: doc/bison.texinfo
===================================================================
RCS file: /sources/bison/bison/doc/bison.texinfo,v
retrieving revision 1.250
diff -p -u -r1.250 bison.texinfo
--- doc/bison.texinfo   17 Feb 2008 02:47:53 -0000      1.250
+++ doc/bison.texinfo   17 Feb 2008 22:21:29 -0000
@@ -4553,6 +4553,9 @@ valid grammar.
 @cindex push parser
 @findex %define api.push_pull
 
+(The current push parsing interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
+
 A pull parser is called once and it takes control until all its input
 is completely parsed.  A push parser, on the other hand, is called
 each time a new token is made available.
@@ -4882,6 +4885,8 @@ Some of the accepted @var{variable}s are
 
 @item Purpose: Requests a pull parser, a push parser, or both.
 @xref{Push Decl, ,A Push Parser}.
+(The current push parsing interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
 
 @item Accepted Values: @code{"pull"}, @code{"push"}, @code{"both"}
 
@@ -5042,7 +5047,7 @@ chosen as if the input file were named @
 
 @deffn {Directive} %language "@var{language}"
 Specify the programming language for the generated parser.  Currently
-supported languages include C and C++.
+supported languages include C, C++, and Java.
 @var{language} is case-insensitive.
 @end deffn
 
@@ -5304,6 +5309,9 @@ exp: @dots{}    @{ @dots{}; *randomness 
 @section The Push Parser Function @code{yypush_parse}
 @findex yypush_parse
 
+(The current push parsing interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
+
 You call the function @code{yypush_parse} to parse a single token.  This
 function is available if either the @code{%define api.push_pull "push"} or
 @code{%define api.push_pull "both"} declaration is used.
@@ -5319,6 +5327,9 @@ is required to finish parsing the gramma
 @section The Pull Parser Function @code{yypull_parse}
 @findex yypull_parse
 
+(The current push parsing interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
+
 You call the function @code{yypull_parse} to parse the rest of the input
 stream.  This function is available if the @code{%define api.push_pull "both"}
 declaration is used.
@@ -5332,6 +5343,9 @@ The value returned by @code{yypull_parse
 @section The Parser Create Function @code{yystate_new}
 @findex yypstate_new
 
+(The current push parsing interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
+
 You call the function @code{yypstate_new} to create a new parser instance.
 This function is available if either the @code{%define api.push_pull "push"} or
 @code{%define api.push_pull "both"} declaration is used.
@@ -5346,6 +5360,9 @@ or NULL if no memory was available.
 @section The Parser Delete Function @code{yystate_delete}
 @findex yypstate_delete
 
+(The current push parsing interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
+
 You call the function @code{yypstate_delete} to delete a parser instance.
 function is available if either the @code{%define api.push_pull "push"} or
 @code{%define api.push_pull "both"} declaration is used.
@@ -7773,7 +7790,7 @@ already defined, so that the debugging f
 @itemx address@hidden
 Specify the programming language for the generated parser, as if
 @code{%language} was specified (@pxref{Decl Summary, , Bison Declaration
-Summary}).  Currently supported languages include C and C++.
+Summary}).  Currently supported languages include C, C++, and Java.
 @var{language} is case-insensitive.
 
 @item --locations
@@ -8667,6 +8684,9 @@ main (int argc, char *argv[])
 @c - %language "Java"
 @c - initial action
 
+(The current Java interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
+
 The Java parser skeletons are selected using a language directive,
 @samp{%language "Java"}, or the synonymous command-line option
 @option{--language=java}.
@@ -9779,6 +9799,8 @@ The function to delete a parser instance
 call this function to delete the memory associated with a parser.
 @xref{Parser Delete Function, ,The Parser Delete Function
 @code{yypstate_delete}}.
+(The current push parsing interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
 @end deffn
 
 @deffn {Function} yypstate_new
@@ -9786,6 +9808,8 @@ The function to create a parser instance
 call this function to create a new parser.
 @xref{Parser Create Function, ,The Parser Create Function
 @code{yypstate_new}}.
+(The current push parsing interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
 @end deffn
 
 @deffn {Function} yypull_parse
@@ -9793,12 +9817,16 @@ The parser function produced by Bison in
 parse the rest of the input stream.
 @xref{Pull Parser Function, ,The Pull Parser Function
 @code{yypull_parse}}.
+(The current push parsing interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
 @end deffn
 
 @deffn {Function} yypush_parse
 The parser function produced by Bison in push mode; call this function to
 parse a single token.  @xref{Push Parser Function, ,The Push Parser Function
 @code{yypush_parse}}.
+(The current push parsing interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
 @end deffn
 
 @deffn {Macro} YYPARSE_PARAM
Index: src/getargs.c
===================================================================
RCS file: /sources/bison/bison/src/getargs.c,v
retrieving revision 1.103
diff -p -u -r1.103 getargs.c
--- src/getargs.c       18 Nov 2007 06:40:41 -0000      1.103
+++ src/getargs.c       17 Feb 2008 22:21:32 -0000
@@ -1,7 +1,7 @@
 /* Parse command line arguments for Bison.
 
    Copyright (C) 1984, 1986, 1989, 1992, 2000, 2001, 2002, 2003, 2004,
-   2005, 2006, 2007 Free Software Foundation, Inc.
+   2005, 2006, 2007, 2008 Free Software Foundation, Inc.
 
    This file is part of Bison, the GNU Compiler Compiler.
 
@@ -269,6 +269,7 @@ Operation modes:\n\
 
       fputs (_("\
 Parser:\n\
+  -L, --language=LANGUAGE    specify the output programming language\n\
   -S, --skeleton=FILE        specify the skeleton to use\n\
   -t, --debug                instrument the parser for debugging\n\
       --locations            enable locations computation\n\
@@ -287,9 +288,11 @@ Output:\n\
   -b, --file-prefix=PREFIX   specify a PREFIX for output files\n\
   -o, --output=FILE          leave output to FILE\n\
   -g, --graph[=FILE]         also output a graph of the automaton\n\
-  -x, --xml[=FILE]           also output an XML report of the automaton\n\
 \n\
 "), stdout);
+/*
+  -x, --xml[=FILE]           also output an XML report of the automaton\n\
+*/
 
       fputs (_("\
 Warning categories include:\n\