* 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
`@value{VERSION}'.  This guarantees that we're testing what actually
appears in the documentation.
* examples/calc++/Makefile.am ($(calc_extracted)): Use `$(VERSION)'
rather than `@VERSION@'.

ChangeLog

@@ -1,3 +1,25 @@
+2006-12-19  Paolo Bonzini  <bonzini@gnu.org>
+	and Joel E. Denny  <jdenny@ces.clemson.edu>
+
+	* 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
+	`@value{VERSION}'.  This guarantees that we're testing what actually
+	appears in the documentation.
+	* examples/calc++/Makefile.am ($(calc_extracted)): Use `$(VERSION)'
+	rather than `@VERSION@'.
+
 2006-12-18  Paul Eggert  <eggert@cs.ucla.edu>
 
 	* NEWS: Reword the %language news a bit, and put it earlier.

doc/bison.texinfo

@@ -4619,9 +4619,10 @@ Specify a prefix to use for all Bison output file names.  The names are
 chosen as if the input file were named @file{@var{prefix}.y}.
 @end deffn
 
-@deffn {Directive} %language="@var{language}"
+@deffn {Directive} %language "@var{language}"
 Specify the programming language for the generated parser.  Currently
 supported languages include C and C++.
+@var{language} 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
-@item -S @var{file}
-@itemx --skeleton=@var{file}
-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 facilities are compiled.
 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++.
+@var{language} is case-insensitive.
 
 @item --locations
 Pretend that @code{%locations} was specified.  @xref{Decl Summary}.
@@ -7308,6 +7307,16 @@ parser file, treating it as an independent source file in its own right.
 @itemx --no-parser
 Pretend that @code{%no-parser} was specified.  @xref{Decl Summary}.
 
+@item -S @var{file}
+@itemx --skeleton=@var{file}
+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
+The C++ @acronym{LALR}(1) parser is selected using the language directive,
-language directive, @samp{%language "C++"}, or the synonymous
+@samp{%language "C++"}, or the synonymous command-line option
-command-line option @option{--language=c++}@footnote{For both
+@option{--language=c++}.
-the grammar directive and the command-line option, the
+@xref{Decl Summary}.
-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).
 
 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
 
+@deffn {Directive} %language
+Specify the programming language for the generated parser.
+@xref{Decl Summary}.
+@end 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 associativity to token(s).
 @xref{Precedence Decl, ,Operator Precedence}.
 @end deffn
 
+@deffn {Directive} %skeleton
+Specify the skeleton to use; usually for development.
+@xref{Decl Summary}.
+@end deffn
+
 @deffn {Directive} %start
 Bison declaration to specify the start symbol.  @xref{Start Decl, ,The
 Start-Symbol}.

examples/calc++/Makefile.am

@@ -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
 

examples/extexi

@@ -111,7 +111,7 @@ function normalize(contents,    i, lines, n, line, res) {
 	else
 	  line = "";
 
-      gsub (/^%require "[^"]*"$/, "%require \"" VERSION "\"", line);
+      gsub (/"@value\{VERSION\}"/, "\"" VERSION "\"", line)
       gsub (/^@result\{\}/, "", line);
       gsub (/^@error\{\}/,  "", line);
       gsub ("@[{]", "{", line);