Say %language is experimental.

We're thinking of extending it's effect on output file naming.  See the
thread at
<http://lists.gnu.org/archive/html/bison-patches/2008-10/msg00003.html>.
* NEWS: Say it's experimental.
* doc/bison.texinfo (Decl Summary): Say it's experimental, and so don't
recommend it over %skeleton for now.
(Bison Options): Likewise.
(C++ Bison Interface): Use %skeleton not %language.
(Calc++ Parser): Use %skeleton not %language.
* src/getargs.c (usage): Say it's experimental.

4 files changed, 42 insertions, 15 deletions

diff --git a/ChangeLog b/ChangeLog
index 870083a9..4899cf2a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2008-11-02  Joel E. Denny  <jdenny@ces.clemson.edu>
+
+	Say %language is experimental.
+	We're thinking of extending it's effect on output file naming.  See the
+	thread at
+	<http://lists.gnu.org/archive/html/bison-patches/2008-10/msg00003.html>.
+	* NEWS: Say it's experimental.
+	* doc/bison.texinfo (Decl Summary): Say it's experimental, and so don't
+	recommend it over %skeleton for now.
+	(Bison Options): Likewise.
+	(C++ Bison Interface): Use %skeleton not %language.
+	(Calc++ Parser): Use %skeleton not %language.
+	* src/getargs.c (usage): Say it's experimental.
+
 2008-11-01  Di-an Jan  <dianj@freeshell.org>
 	    Paolo Bonzini  <bonzini@gnu.org>
 
diff --git a/NEWS b/NEWS
index 53334d6e..b11333a0 100644
--- a/NEWS
+++ b/NEWS
@@ -3,7 +3,13 @@ Bison News
 
 Changes in version ?.? (????-??-??):
 
-*
+* %language is an experimental feature.
+
+  We first introduced this feature in test release 2.3b as a cleaner
+  alternative to %skeleton.  Since then, we have discussed the possibility of
+  modifying its effect on Bison's output file names.  Thus, in this release,
+  we consider %language to be an experimental feature that will likely evolve
+  in future releases.
 
 Changes in version 2.3b (2008-05-27):
 
diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index c6fc0a5f..71e9a16a 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -4838,7 +4838,7 @@ already defined, so that the debugging facilities are compiled.
 Define a variable to adjust Bison's behavior.
 The possible choices for @var{variable}, as well as their meanings, depend on
 the selected target language and/or the parser skeleton (@pxref{Decl
-Summary,,%language}).
+Summary,,%language}, @pxref{Decl Summary,,%skeleton}).
 
 Bison will warn if a @var{variable} is defined multiple times.
 
@@ -5051,6 +5051,9 @@ chosen as if the input file were named @file{@var{prefix}.y}.
 Specify the programming language for the generated parser.  Currently
 supported languages include C, C++, and Java.
 @var{language} is case-insensitive.
+
+This directive is experimental and its effect may be modified in future
+releases.
 @end deffn
 
 @deffn {Directive} %locations
@@ -5111,10 +5114,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 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.
+@c You probably don't need this option unless you are developing Bison.
+@c You should use @code{%language} if you want to specify the skeleton for a
+@c different language, because it is clearer and because it will always choose the
+@c correct skeleton for non-deterministic or push parsers.
 
 If @var{file} does not contain a @code{/}, @var{file} is the name of a skeleton
 file in the Bison installation directory.
@@ -7837,6 +7840,9 @@ Specify the programming language for the generated parser, as if
 Summary}).  Currently supported languages include C, C++, and Java.
 @var{language} is case-insensitive.
 
+This option is experimental and its effect may be modified in future
+releases.
+
 @item --locations
 Pretend that @code{%locations} was specified.  @xref{Decl Summary}.
 
@@ -7858,10 +7864,10 @@ parser file, treating it as an independent source file in its own right.
 Specify the skeleton to use, similar to @code{%skeleton}
 (@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.
+@c You probably don't need this option unless you are developing Bison.
+@c You should use @option{--language} if you want to specify the skeleton for a
+@c different language, because it is clearer and because it will always
+@c choose the correct skeleton for non-deterministic or push parsers.
 
 If @var{file} does not contain a @code{/}, @var{file} is the name of a skeleton
 file in the Bison installation directory.
@@ -8009,13 +8015,13 @@ int yyparse (void);
 
 @node C++ Bison Interface
 @subsection C++ Bison Interface
-@c - %language "C++"
+@c - %skeleton "lalr1.cc"
 @c - Always pure
 @c - initial action
 
-The C++ @acronym{LALR}(1) parser is selected using the language directive,
-@samp{%language "C++"}, or the synonymous command-line option
-@option{--language=c++}.
+The C++ @acronym{LALR}(1) parser is selected using the skeleton directive,
+@samp{%skeleton "lalr1.c"}, or the synonymous command-line option
+@option{--skeleton=lalr1.c}.
 @xref{Decl Summary}.
 
 When run, @command{bison} will create several entities in the @samp{yy}
@@ -8409,7 +8415,7 @@ the grammar for.
 
 @comment file: calc++-parser.yy
 @example
-%language "C++"                          /*  -*- C++ -*- */
+%skeleton "lalr1.cc"                          /*  -*- C++ -*- */
 %require "@value{VERSION}"
 %defines
 %define parser_class_name "calcxx_parser"
diff --git a/src/getargs.c b/src/getargs.c
index 8eecb5f2..c9fc9bfc 100644
--- a/src/getargs.c
+++ b/src/getargs.c
@@ -272,6 +272,7 @@ Operation modes:\n\
       fputs (_("\
 Parser:\n\
   -L, --language=LANGUAGE    specify the output programming language\n\
+                             (this is an experimental feature)\n\
   -S, --skeleton=FILE        specify the skeleton to use\n\
   -t, --debug                instrument the parser for debugging\n\
       --locations            enable locations computation\n\