Fix impure push parser compile error reported by Bob Rossi at

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 583f48dbef3bc534a0ad16ede33672170fca702b..d513b5558826ccca1a797bcd44ab5651cf101db9 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -34,7 +34,8 @@ This manual is for @acronym{GNU} Bison (version @value{VERSION},
 @value{UPDATED}), the @acronym{GNU} parser generator.
 
 Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998,
-1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software
+Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -45,10 +46,10 @@ being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in
 (a) below.  A copy of the license is included in the section entitled
 ``@acronym{GNU} Free Documentation License.''
 
-(a) The @acronym{FSF}'s Back-Cover Text is: ``You have freedom to copy
-and modify this @acronym{GNU} Manual, like @acronym{GNU} software.
-Copies published by the Free Software Foundation raise funds for
-@acronym{GNU} development.''
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this @acronym{GNU} manual.  Buying copies from the @acronym{FSF}
+supports it in developing @acronym{GNU} and promoting software
+freedom.''
 @end quotation
 @end copying
 
@@ -4022,7 +4023,7 @@ associativity and precedence.  @xref{Precedence Decl, ,Operator
 Precedence}.
 
 You can explicitly specify the numeric code for a token type by appending
-a decimal or hexadecimal integer value in the field immediately
+a nonnegative decimal or hexadecimal integer value in the field immediately
 following the token name:
 
 @example
@@ -4075,6 +4076,16 @@ Once you equate the literal string and the token name, you can use them
 interchangeably in further declarations or the grammar rules.  The
 @code{yylex} function can use the token name or the literal string to
 obtain the token type code number (@pxref{Calling Convention}).
+Syntax error messages passed to @code{yyerror} from the parser will reference
+the literal string instead of the token name.
+
+The token numbered as 0 corresponds to end of file; the following line
+allows for nicer error messages referring to ``end of file'' instead
+of ``$end'':
+
+@example
+%token END 0 "end of file"
+@end example
 
 @node Precedence Decl
 @subsection Operator Precedence
@@ -4088,7 +4099,7 @@ once.  These are called @dfn{precedence declarations}.
 @xref{Precedence, ,Operator Precedence}, for general information on
 operator precedence.
 
-The syntax of a precedence declaration is the same as that of
+The syntax of a precedence declaration is nearly the same as that of
 @code{%token}: either
 
 @example
@@ -4126,6 +4137,18 @@ When two tokens declared in different precedence declarations associate,
 the one declared later has the higher precedence and is grouped first.
 @end itemize
 
+For backward compatibility, there is a confusing difference between the
+argument lists of @code{%token} and precedence declarations.
+Only a @code{%token} can associate a literal string with a token type name.
+A precedence declaration always interprets a literal string as a reference to a
+separate token.
+For example:
+
+@example
+%left  OR "<="         // Does not declare an alias.
+%left  OR 134 "<=" 135 // Declares 134 for OR and 135 for "<=".
+@end example
+
 @node Union Decl
 @subsection The Collection of Value Types
 @cindex declaring value types
@@ -4887,8 +4910,9 @@ are useless in the generated parser.
 @item Caveats:
 
 @itemize @bullet
-@item Unreachable states may contain conflicts and may reduce rules not
-reduced in any other state.
+
+@item Unreachable states may contain conflicts and may use rules not used in
+any other state.
 Thus, keeping unreachable states may induce warnings that are irrelevant to
 your parser's behavior, and it may eliminate warnings that are relevant.
 Of course, the change in warnings may actually be relevant to a parser table
@@ -5315,7 +5339,9 @@ This function is available if either the @code{%define api.push_pull "push"} or
 
 @deftypefun yypstate *yypstate_new (void)
 The fuction will return a valid parser instance if there was memory available
-or NULL if no memory was available.
+or 0 if no memory was available.
+In impure mode, it will also return 0 if a parser instance is currently
+allocated.
 @end deftypefun
 
 @node Parser Delete Function
@@ -7155,9 +7181,9 @@ useless: STR;
 @command{bison} reports:
 
 @example
-calc.y: warning: 1 useless nonterminal and 1 useless rule
-calc.y:11.1-7: warning: useless nonterminal: useless
-calc.y:11.10-12: warning: useless rule: useless: STR
+calc.y: warning: 1 nonterminal and 1 rule useless in grammar
+calc.y:11.1-7: warning: nonterminal useless in grammar: useless
+calc.y:11.10-12: warning: rule useless in grammar: useless: STR
 calc.y: conflicts: 7 shift/reduce
 @end example
 
@@ -7196,17 +7222,17 @@ State 11 conflicts: 4 shift/reduce
 The next section reports useless tokens, nonterminal and rules.  Useless
 nonterminals and rules are removed in order to produce a smaller parser,
 but useless tokens are preserved, since they might be used by the
-scanner (note the difference between ``useless'' and ``not used''
+scanner (note the difference between ``useless'' and ``unused''
 below):
 
 @example
-Useless nonterminals:
+Nonterminals useless in grammar:
    useless
 
-Terminals which are not used:
+Terminals unused in grammar:
    STR
 
-Useless rules:
+Rules useless in grammar:
 #6     useless: STR;
 @end example
 
@@ -7826,6 +7852,9 @@ Implies @code{state} and augments the description of the automaton with
 the full set of items for each state, instead of its core only.
 @end table
 
+@item --report-file=@var{file}
+Specify the @var{file} for the verbose description.
+
 @item -v
 @itemx --verbose
 Pretend that @code{%verbose} was specified, i.e., write an extra output