Re: [SPAM] Re: [updated PATCH] %language declaration

[Joel E. Denny]

On Mon, 18 Dec 2006, Paul Eggert wrote:

> Thanks. I think it's ready to be put into CVS, even if we need to
> iron out some things before an official release.
> 
> I redid some minor things to fit into Bison usual style, and
> installed the following.  I removed the mention of Java from
> the manual, as I assume that change wasn't intended here.

Thanks.  Unfortunately, this is an older version of his patch, which 
hadn't yet fixed some of those problems.  The latest version I'm aware of 
is here:

  http://lists.gnu.org/archive/html/bison-patches/2006-12/msg00118.html

I think the following patch imports the remaining differences plus some of 
our other suggestions.  Ok to commit?

Index: ChangeLog
===================================================================
RCS file: /sources/bison/bison/ChangeLog,v
retrieving revision 1.1629
diff -p -u -r1.1629 ChangeLog
--- ChangeLog   19 Dec 2006 00:39:07 -0000      1.1629
+++ ChangeLog   19 Dec 2006 02:54:13 -0000
@@ -1,3 +1,25 @@
+2006-12-18  Paolo Bonzini  <address@hidden>
+       and Joel E. Denny  <address@hidden>
+
+       * doc/bison.texinfo (Decl Summary): In the %language entry, mention
+       that the argument is case-insensitive, and there's no `=' here.
+       For the %skeleton entry, mention that %language is better.
+       (Bison Options): Likewise for --language and --skeleton.  Move the
+       --skeleton entry so that the `Tuning the parser' section is sorted
+       alphabetically on long options.
+       (C++ Bison Interface): Don't use the word skeleton.  Don't explain the
+       %language directive in detail here; cross-reference the %language
+       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.
+       * 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
+       appears in the documentation.
+       * examples/calc++/Makefile.am ($(calc_extracted)): Use `$(VERSION)'
+       rather than address@hidden@'.
+
 2006-12-18  Paul Eggert  <address@hidden>
 
        * NEWS: Reword the %language news a bit, and put it earlier.
Index: doc/bison.texinfo
===================================================================
RCS file: /sources/bison/bison/doc/bison.texinfo,v
retrieving revision 1.216
diff -p -u -r1.216 bison.texinfo
--- doc/bison.texinfo   19 Dec 2006 00:34:36 -0000      1.216
+++ doc/bison.texinfo   19 Dec 2006 02:54:16 -0000
@@ -4619,9 +4619,10 @@ Specify a prefix to use for all Bison ou
 chosen as if the input file were named @address@hidden
 @end deffn
 
address@hidden {Directive} %language="@var{language}"
address@hidden {Directive} %language "@var{language}"
 Specify the programming language for the generated parser.  Currently
 supported languages include C and C++.
address@hidden is case-insensitive.
 @end deffn
 
 @deffn {Directive} %locations
@@ -4688,7 +4689,10 @@ Require a Version of Bison}.
 
 @deffn {Directive} %skeleton "@var{file}"
 Specify the skeleton to use.  You probably don't need this option unless
-you are developing Bison.
+you are developing Bison; you should use @code{%language} if you want to
+specify the skeleton for a different language, because it is clearer and
+because it will always choose the correct skeleton for non-deterministic
+or push parsers.
 @end deffn
 
 @deffn {Directive} %token-table
@@ -7270,12 +7274,6 @@ this option is specified.
 Tuning the parser:
 
 @table @option
address@hidden -S @var{file}
address@hidden address@hidden
-Specify the skeleton to use, as if @code{%skeleton} was specified
-(@pxref{Decl Summary, , Bison Declaration Summary}).  You probably
-don't need this option unless you are developing Bison.
-
 @item -t
 @itemx --debug
 In the parser file, define the macro @code{YYDEBUG} to 1 if it is not
@@ -7287,6 +7285,7 @@ already defined, so that the debugging f
 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++.
address@hidden is case-insensitive.
 
 @item --locations
 Pretend that @code{%locations} was specified.  @xref{Decl Summary}.
@@ -7308,6 +7307,16 @@ parser file, treating it as an independe
 @itemx --no-parser
 Pretend that @code{%no-parser} was specified.  @xref{Decl Summary}.
 
address@hidden -S @var{file}
address@hidden address@hidden
+Specify the skeleton to use, as if @code{%skeleton} was specified
+(@pxref{Decl Summary, , Bison Declaration Summary}).
+
+You probably don't need this option unless you are developing Bison;
+you should use @option{--language} if you want to specify the skeleton for a
+different language, because it is clearer and because it will always
+choose the correct skeleton for non-deterministic or push parsers.
+
 @item -k
 @itemx --token-table
 Pretend that @code{%token-table} was specified.  @xref{Decl Summary}.
@@ -7454,18 +7463,10 @@ int yyparse (void);
 @c - Always pure
 @c - initial action
 
-The C++ parser @acronym{LALR}(1) skeleton is selected using a
-language directive, @samp{%language "C++"}, or the synonymous
-command-line option @address@hidden both
-the grammar directive and the command-line option, the
-language name is case-insensitive}.  These were introduced
-in Bison 2.3b; for compatibility with earlier versions, you
-may also pass the option @option{--skeleton=lalr1.cc} to Bison
-or include the directive @samp{%skeleton "lalr1.cc"} in the
-grammar preamble.  Specifying the language is however preferred,
-because it is clearer and because it will automatically choose the
-correct skeleton for @acronym{GLR} parsers (the C++ @acronym{GLR}
-skeleton is still under development).
+The C++ @acronym{LALR}(1) parser is selected using the language directive,
address@hidden "C++"}, or the synonymous command-line option
address@hidden
address@hidden Summary}.
 
 When run, @command{bison} will create several
 entities in the @samp{yy} namespace.  Use the @samp{%name-prefix}
@@ -7856,7 +7857,7 @@ the grammar for.
 @comment file: calc++-parser.yy
 @example
 %language "C++"                          /*  -*- C++ -*- */
-%require "2.3b"
+%require "@value{VERSION}"
 %defines
 %define "parser_class_name" "calcxx_parser"
 @end example
@@ -8764,6 +8765,11 @@ Parsers, ,Writing @acronym{GLR} Parsers}
 Run user code before parsing.  @xref{Initial Action Decl, , Performing Actions 
before Parsing}.
 @end deffn
 
address@hidden {Directive} %language
+Specify the programming language for the generated parser.
address@hidden Summary}.
address@hidden deffn
+
 @deffn {Directive} %left
 Bison declaration to assign left associativity to token(s).
 @xref{Precedence Decl, ,Operator Precedence}.
@@ -8882,6 +8888,11 @@ Bison declaration to assign right associ
 @xref{Precedence Decl, ,Operator Precedence}.
 @end deffn
 
address@hidden {Directive} %skeleton
+Specify the skeleton to use; usually for development.
address@hidden Summary}.
address@hidden deffn
+
 @deffn {Directive} %start
 Bison declaration to specify the start symbol.  @xref{Start Decl, ,The
 Start-Symbol}.
Index: examples/extexi
===================================================================
RCS file: /sources/bison/bison/examples/extexi,v
retrieving revision 1.7
diff -p -u -r1.7 extexi
--- examples/extexi     19 Dec 2006 00:34:37 -0000      1.7
+++ examples/extexi     19 Dec 2006 02:54:16 -0000
@@ -111,7 +111,7 @@ function normalize(contents,    i, lines
        else
          line = "";
 
-      gsub (/^%require "[^"]*"$/, "%require \"" VERSION "\"", line);
+      gsub (/"@value\{VERSION\}"/, "\"" VERSION "\"", line)
       gsub (/address@hidden/, "", line);
       gsub (/address@hidden/,  "", line);
       gsub ("@[{]", "{", line);
Index: examples/calc++/Makefile.am
===================================================================
RCS file: /sources/bison/bison/examples/calc++/Makefile.am,v
retrieving revision 1.5
diff -p -u -r1.5 Makefile.am
--- examples/calc++/Makefile.am 19 Dec 2006 00:34:37 -0000      1.5
+++ examples/calc++/Makefile.am 19 Dec 2006 02:54:16 -0000
@@ -35,7 +35,7 @@ extexi = $(top_srcdir)/examples/extexi
 # Extract in src.
 $(calc_extracted): $(doc) $(extexi)
        cd $(srcdir) && \
-          $(AWK) -f ../extexi -v VERSION="@VERSION@" \
+          $(AWK) -f ../extexi -v VERSION="$(VERSION)" \
             ../../doc/bison.texinfo -- calc++-parser.yy \
             calc++-scanner.ll calc++.cc calc++-driver.hh calc++-driver.cc