Re: preparing for 2.3b

[Joel E. Denny]

On Wed, 20 Feb 2008, Akim Demaille wrote:

> I would mention it in NEWS and in --help.  Make it "experimental" in
> the NEWS file, and with a bit of luck someone will provide help on
> it.  But I agree with Wojciech it should be advertised, even though
> not finished.

Thanks.  I committed the patch below.

Also, I just noticed a couple of problems in the manual that I don't have 
time to fix right now:

1. The "Bison Options" section omits the --warnings option.

2. The "Option Cross Key" section says -g and -x take an optional FILE 
argument, but they don't.  It indicates that the -o argument is optional, 
but it's not.  There may be other instances of each case that I didn't 
notice.

Index: ChangeLog
===================================================================
RCS file: /sources/bison/bison/ChangeLog,v
retrieving revision 1.1774
diff -p -u -r1.1774 ChangeLog
--- ChangeLog   21 Feb 2008 17:08:18 -0000      1.1774
+++ ChangeLog   23 Feb 2008 04:22:47 -0000
@@ -1,3 +1,30 @@
+2008-02-22  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.
+
+       * NEWS (2.3a+): Mention XML support, and say the schema is
+       experimental.
+       * doc/bison.texinfo (Bison Options): Mention -x and --xml.
+       * src/getargs.c (usage): Say the XML schema is experimental.
+
+       * NEWS (2.3a+): Say option instead of flag.
+
 2008-02-21  Wojciech Polak  <address@hidden>
 
        * data/xslt/xml2xhtml.xsl (xsl:template match="/"): Change footer
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        23 Feb 2008 04:22:47 -0000
@@ -28,13 +28,35 @@ 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".
+
+* XML Automaton Report
+
+  Bison can now generate an XML report of the LALR(1) automaton using the new
+  `--xml' option.  The current XML schema is experimental and may evolve.  More
+  user feedback will help to stabilize it.
 
 * The grammar file may now specify the name of the parser header file using
   %defines.  For example:
@@ -79,7 +101,8 @@ Changes in version 2.3a+ (????-??-??):
   bug affected only the `.output' file and not the generated parser source
   code.
 
-* --report-file=FILE is a new flag to override the default `.output' file name.
+* --report-file=FILE is a new option to override the default `.output' file
+  name.
 
 * The `=' that used to be required in the following directives is now
   deprecated:
@@ -126,7 +149,7 @@ Changes in version 2.3a+ (????-??-??):
   sometimes prove to be false alarms in existing grammars employing the Yacc
   constructs $0 or $-N (where N is some positive integer).
 
-  To enable these warnings, specify the flag `--warnings=midrule-values' or
+  To enable these warnings, specify the option `--warnings=midrule-values' or
   `-W', which is a synonym for `--warnings=all'.
 
 * Default %destructor or %printer with `<*>' or `<>'
Index: doc/bison.texinfo
===================================================================
RCS file: /sources/bison/bison/doc/bison.texinfo,v
retrieving revision 1.251
diff -p -u -r1.251 bison.texinfo
--- doc/bison.texinfo   20 Feb 2008 18:23:21 -0000      1.251
+++ doc/bison.texinfo   23 Feb 2008 04:22:51 -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.
@@ -5348,6 +5362,9 @@ allocated.
 @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.
@@ -7775,7 +7792,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
@@ -7876,9 +7893,18 @@ If the grammar file is @file{foo.y}, the
 be @file{foo.dot}.
 
 @item address@hidden
-The behavior of @var{--graph} is the same than @samp{-g}.  The only
+The behavior of @var{--graph} is the same as @samp{-g}.  The only
 difference is that it has an optional argument which is the name of
 the output graph file.
+
address@hidden -x
address@hidden address@hidden
+Output an XML report of the @acronym{LALR}(1) automaton computed by Bison.
address@hidden@var{file}} is optional.
+If omitted and the grammar file is @file{foo.y}, the output file will be
address@hidden
+(The current XML schema is experimental and may evolve.
+More user feedback will help to stabilize it.)
 @end table
 
 @node Option Cross Key
@@ -8669,6 +8695,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}.
@@ -9781,6 +9810,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
@@ -9788,6 +9819,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
@@ -9795,12 +9828,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       23 Feb 2008 04:22:51 -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\
@@ -288,6 +289,7 @@ Output:\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\
+                             (the XML schema is experimental)\n\
 \n\
 "), stdout);