From 3b1977eab5b3ad1dd97c225518d694b3ec43a151 Mon Sep 17 00:00:00 2001 From: "Joel E. Denny" Date: Sun, 19 Dec 2010 22:14:08 -0500 Subject: [PATCH] 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. (cherry picked from commit f1b238df182101b9c9d3808bf2d5e2333e27c50f) Conflicts: doc/bison.texinfo --- ChangeLog | 10 ++++++++++ NEWS | 44 ++++++++++++++++++++++---------------------- doc/bison.texinfo | 18 +++++++++++------- 3 files changed, 43 insertions(+), 29 deletions(-) diff --git a/ChangeLog b/ChangeLog index 2fa9b5d5..d87b6e53 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +2010-12-19 Joel E. Denny + + 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 parse.lac: document. diff --git a/NEWS b/NEWS index e3510938..a2c0b029 100644 --- a/NEWS +++ b/NEWS @@ -3,7 +3,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 @@ -28,13 +28,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 @@ -98,15 +98,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 @@ -125,7 +125,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 @@ -140,7 +140,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, @@ -151,15 +151,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 @@ -170,7 +170,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 @@ -191,7 +191,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 @@ -202,7 +202,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: @@ -242,14 +242,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 @@ -284,7 +284,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 diff --git a/doc/bison.texinfo b/doc/bison.texinfo index 8a1031ef..0c09e35e 100644 --- a/doc/bison.texinfo +++ b/doc/bison.texinfo @@ -475,8 +475,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 @@ -5011,7 +5011,7 @@ Some of the accepted @var{variable}s are: @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.) @@ -5100,8 +5100,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 @@ -5148,7 +5148,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.) @@ -5175,6 +5175,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 @@ -5229,7 +5233,7 @@ sacrificing @code{%nonassoc} or default reductions. @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 -- 2.45.2