doc: cleanup.

* NEWS (2.5): Make some minor improvements to wording, and format
entries more consistently.
* doc/bison.texinfo (Language and Grammar): Point out that IELR
and canonical LR are experimental features.
(Decl Summary): In list of %define variables, make wording more
consistent.  Improve discussion of using LALR for GLR.

ChangeLog

@@ -1,3 +1,13 @@
+2010-12-19  Joel E. Denny  <jdenny@clemson.edu>
+
+	doc: cleanup.
+	* NEWS (2.5): Make some minor improvements to wording, and format
+	entries more consistently.
+	* doc/bison.texinfo (Language and Grammar): Point out that IELR
+	and canonical LR are experimental features.
+	(Decl Summary): In list of %define variables, make wording more
+	consistent.  Improve discussion of using LALR for GLR.
+
 2010-12-19  Joel E. Denny  <jdenny@clemson.edu>
 
 	parse.lac: document.

NEWS

@@ -62,7 +62,7 @@ Bison News
 
 * Changes in version 2.5 (????-??-??):
 
-** Named References Support
+** Named references:
 
   Historically, Yacc and Bison have supported positional references
   ($n, $$) to allow access to symbol values from inside of semantic
@@ -87,13 +87,13 @@ Bison News
   These features are experimental in this version.  More user feedback
   will help to stabilize them.
 
-** IELR(1) and Canonical LR(1) Support
+** IELR(1) and canonical LR(1):
 
   IELR(1) is a minimal LR(1) parser table generation algorithm.  That
   is, given any context-free grammar, IELR(1) generates parser tables
   with the full language recognition power of canonical LR(1) but with
-  nearly the same number of parser states as LALR(1).  This reduction in
-  parser states is often an order of magnitude.  More importantly,
+  nearly the same number of parser states as LALR(1).  This reduction
+  in parser states is often an order of magnitude.  More importantly,
   because canonical LR(1)'s extra parser states may contain duplicate
   conflicts in the case of non-LR(1) grammars, the number of conflicts
   for IELR(1) is often an order of magnitude less as well.  This can
@@ -157,15 +157,15 @@ Bison News
   LAC is an experimental feature.  More user feedback will help to
   stabilize it.
 
-** Unrecognized %code qualifiers are now an error not a warning.
+** Unrecognized %code qualifiers are now errors not warnings.
 
-** %define improvements.
+** %define improvements:
 
-*** Unrecognized variables are now an error not a warning.
+*** Unrecognized variables are now errors not warnings.
 
 *** Multiple invocations for any variable is now an error not a warning.
 
-*** Can now be invoked via the command line.
+*** Can now be invoked via the command line:
 
   Each of these command-line options
 
@@ -184,7 +184,7 @@ Bison News
   quietly override %define, but -D and --define do not.  For further
   details, see the section "Bison Options" in the Bison manual.
 
-*** Variables renamed.
+*** Variables renamed:
 
   The following %define variables
 
@@ -199,7 +199,7 @@ Bison News
   The old names are now deprecated but will be maintained indefinitely
   for backward compatibility.
 
-*** Values no longer need to be quoted in grammar file.
+*** Values no longer need to be quoted in grammar file:
 
   If a %define value is an identifier, it no longer needs to be placed
   within quotations marks.  For example,
@@ -210,15 +210,15 @@ Bison News
 
     %define api.push-pull push
 
-** Symbol names.
+** Grammar symbol names can now contain dashes:
 
   Consistently with directives (such as %error-verbose) and variables
-  (e.g. push-pull), symbol names may include dashes in any position,
-  similarly to periods and underscores.  This is GNU extension over
-  POSIX Yacc whose use is reported by -Wyacc, and rejected in Yacc
-  mode (--yacc).
+  (e.g. push-pull), grammar symbol names may include dashes in any
+  position, similarly to periods and underscores.  This is GNU
+  extension over POSIX Yacc whose use is reported by -Wyacc, and
+  rejected in Yacc mode (--yacc).
 
-** YYFAIL now produces warnings and Java parsers no longer implement it.
+** YYFAIL now produces warnings and Java parsers no longer implement it:
 
   YYFAIL has existed for many years as an undocumented feature of
   deterministic parsers in C generated by Bison.  More recently, it was
@@ -229,7 +229,7 @@ Bison News
   discussion of how to suppress C preprocessor warnings about YYFAIL
   being unused, see the Bison 2.4.2 NEWS entry.
 
-** Temporary hack for adding a semicolon to the user action.
+** Temporary hack for adding a semicolon to the user action:
 
   Previously, Bison appended a semicolon to every user action for
   reductions when the output language defaulted to C (specifically, when
@@ -250,7 +250,7 @@ Bison News
   about a missing semicolon where it did not before.  Future releases of
   Bison will cease to append semicolons entirely.
 
-** Character literals not of length one.
+** Character literals not of length one:
 
   Previously, Bison quietly converted all character literals to length
   one.  For example, without warning, Bison interpreted the operators in
@@ -261,7 +261,7 @@ Bison News
        ;
 
   Bison now warns when a character literal is not of length one.  In
-  some future release, Bison will report an error instead.
+  some future release, Bison will start reporting an error instead.
 
 ** Verbose syntax error message fixes:
 
@@ -301,14 +301,14 @@ Bison News
     canonical LR.  However, LAC is still experimental and is disabled
     by default.
 
-** Destructor calls fixed for lookaheads altered in semantic actions.
+** Destructor calls fixed for lookaheads altered in semantic actions:
 
   Previously for deterministic parsers in C, if a user semantic action
   altered yychar, the parser in some cases used the old yychar value to
   determine which destructor to call for the lookahead upon a syntax
   error or upon parser return.  This bug has been fixed.
 
-** C++ parsers use YYRHSLOC
+** C++ parsers use YYRHSLOC:
 
   Similarly to the C parsers, the C++ parsers now define the YYRHSLOC
   macro and use it in the default YYLLOC_DEFAULT.  You are encouraged
@@ -343,7 +343,7 @@ Bison News
             }                                                              \
         while (false)
 
-** YYLLOC_DEFAULT in C++
+** YYLLOC_DEFAULT in C++:
 
   The default implementation of YYLLOC_DEFAULT used to be issued in
   the header file.  It is now output in the implementation file, after

doc/bison.texinfo

@@ -477,8 +477,8 @@ For historical reasons, Bison by default is limited by the additional
 restrictions of @acronym{LALR}(1), which is hard to explain simply.
 @xref{Mystery Conflicts, ,Mysterious Reduce/Reduce Conflicts}, for
 more information on this.
-To escape these additional restrictions, you can request
-@acronym{IELR}(1) or canonical @acronym{LR}(1) parser tables.
+As an experimental feature, you can escape these additional restrictions by
+requesting @acronym{IELR}(1) or canonical @acronym{LR}(1) parser tables.
 @xref{Decl Summary,,lr.type}, to learn how.
 
 @cindex @acronym{GLR} parsing
@@ -5077,7 +5077,7 @@ Some of the accepted @var{variable}s are:
 @itemize
 @item Languages(s): C++
 
-@item Purpose: Specifies the namespace for the parser class.
+@item Purpose: Specify the namespace for the parser class.
 For example, if you specify:
 
 @smallexample
@@ -5150,7 +5150,7 @@ The parser namespace is @code{foo} and @code{yylex} is referenced as
 @itemize @bullet
 @item Language(s): C (deterministic parsers only)
 
-@item Purpose: Requests a pull parser, a push parser, or both.
+@item Purpose: Request 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.)
@@ -5302,8 +5302,8 @@ That is, it does not perform any extra reductions.
 @itemize @bullet
 @item Language(s): all
 
-@item Purpose: Requests that Bison allow unreachable parser states to remain in
-the parser tables.
+@item Purpose: Request that Bison allow unreachable parser states to
+remain in the parser tables.
 Bison considers a state to be unreachable if there exists no sequence of
 transitions from the start state to that state.
 A state can become unreachable during conflict resolution if Bison disables a
@@ -5351,7 +5351,7 @@ However, Bison does not compute which goto actions are useless.
 @itemize @bullet
 @item Language(s): all
 
-@item Purpose: Specifies the type of parser tables within the
+@item Purpose: Specify the type of parser tables within the
 @acronym{LR}(1) family.
 (This feature is experimental.
 More user feedback will help to stabilize it.)
@@ -5378,6 +5378,10 @@ In this case, the use of @acronym{LALR} parser tables is guaranteed not
 to alter the language accepted by the parser.
 @acronym{LALR} parser tables are the smallest parser tables Bison can
 currently generate, so they may be preferable.
+Nevertheless, once you begin to resolve conflicts statically,
+@acronym{GLR} begins to behave more like a deterministic parser, and so
+@acronym{IELR} and canonical @acronym{LR} can be helpful to avoid
+@acronym{LALR}'s mysterious behavior.
 
 @item Occasionally during development, an especially malformed grammar
 with a major recurring flaw may severely impede the @acronym{IELR} or
@@ -5590,7 +5594,7 @@ is not already defined, so that the debugging facilities are compiled.
 C++
 
 @item Purpose:
-Requests variant-based semantic values.
+Request variant-based semantic values.
 @xref{C++ Variants}.
 
 @item Accepted Values: