* doc/FAQ: Remove, merged into...

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index eb36845f3499eb5b538c9ccff10c63d4bf5c1fbb..cd5ec423fef01923af4e1a94e31184369c22ada5 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -324,6 +324,13 @@ Frequently Asked Questions
 * How Can I Reset the Parser:: @code{yyparse} Keeps some State
 * Strings are Destroyed::      @code{yylval} Loses Track of Strings
 * Implementing Gotos/Loops::   Control Flow in the Calculator
 * How Can I Reset the Parser:: @code{yyparse} Keeps some State
 * Strings are Destroyed::      @code{yylval} Loses Track of Strings
 * Implementing Gotos/Loops::   Control Flow in the Calculator

+* Secure?  Conform?::          Is Bison @acronym{POSIX} safe?
+* I can't build Bison::        Troubleshooting
+* Where can I find help?::     Troubleshouting
+* Bug Reports::                Troublereporting
+* Other Languages::            Parsers in Java and others
+* Beta Testing::               Experimenting development versions
+* Mailing Lists::              Meeting other Bison users

 
 Copying This Manual
 
 
 Copying This Manual
 


@@ -336,16 +343,16 @@ Copying This Manual
 @unnumbered Introduction
 @cindex introduction
 
 @unnumbered Introduction
 @cindex introduction
 

-@dfn{Bison} is a general-purpose parser generator that converts a
-grammar description for an @acronym{LALR}(1) context-free grammar into a C
-program to parse that grammar.  Once you are proficient with Bison,
-you may use it to develop a wide range of language parsers, from those
+@dfn{Bison} is a general-purpose parser generator that converts a grammar
+description for an @acronym{LALR}(1) or @acronym{GLR} context-free grammar
+into a C or C++ program to parse that grammar.  Once you are proficient with
+Bison, you can use it to develop a wide range of language parsers, from those

 used in simple desk calculators to complex programming languages.
 
 Bison is upward compatible with Yacc: all properly-written Yacc grammars
 ought to work with Bison with no change.  Anyone familiar with Yacc
 should be able to use Bison with little trouble.  You need to be fluent in
 used in simple desk calculators to complex programming languages.
 
 Bison is upward compatible with Yacc: all properly-written Yacc grammars
 ought to work with Bison with no change.  Anyone familiar with Yacc
 should be able to use Bison with little trouble.  You need to be fluent in

-C programming in order to use Bison or to understand this manual.
+C or C++ programming in order to use Bison or to understand this manual.

 
 We begin with tutorial chapters that explain the basic concepts of using
 Bison and show three explained examples, each building on the last.  If you
 
 We begin with tutorial chapters that explain the basic concepts of using
 Bison and show three explained examples, each building on the last.  If you


@@ -1135,13 +1142,16 @@ memory referenced by @code{yylval}.
 @findex YYERROR
 @cindex @acronym{GLR} parsers and @code{YYERROR}
 Another Bison feature requiring special consideration is @code{YYERROR}
 @findex YYERROR
 @cindex @acronym{GLR} parsers and @code{YYERROR}
 Another Bison feature requiring special consideration is @code{YYERROR}

-(@pxref{Action Features}), which you can invoke in any semantic action to
+(@pxref{Action Features}), which you can invoke in a semantic action to

 initiate error recovery.
 During deterministic @acronym{GLR} operation, the effect of @code{YYERROR} is
 the same as its effect in an @acronym{LALR}(1) parser.
 In a deferred semantic action, its effect is undefined.
 @c The effect is probably a syntax error at the split point.
 
 initiate error recovery.
 During deterministic @acronym{GLR} operation, the effect of @code{YYERROR} is
 the same as its effect in an @acronym{LALR}(1) parser.
 In a deferred semantic action, its effect is undefined.
 @c The effect is probably a syntax error at the split point.
 

+Also, see @ref{Location Default Action, ,Default Action for Locations}, which
+describes a special usage of @code{YYLLOC_DEFAULT} in @acronym{GLR} parsers.
+

 @node Compiler Requirements
 @subsection Considerations when Compiling @acronym{GLR} Parsers
 @cindex @code{inline}
 @node Compiler Requirements
 @subsection Considerations when Compiling @acronym{GLR} Parsers
 @cindex @code{inline}


@@ -3571,6 +3581,7 @@ This location is stored in @code{yylloc}.
 @node Location Default Action
 @subsection Default Action for Locations
 @vindex YYLLOC_DEFAULT
 @node Location Default Action
 @subsection Default Action for Locations
 @vindex YYLLOC_DEFAULT

+@cindex @acronym{GLR} parsers and @code{YYLLOC_DEFAULT}

 
 Actually, actions are not the best place to compute locations.  Since
 locations are much more general than semantic values, there is room in
 
 Actually, actions are not the best place to compute locations.  Since
 locations are much more general than semantic values, there is room in


@@ -3578,6 +3589,9 @@ the output parser to redefine the default action to take for each
 rule.  The @code{YYLLOC_DEFAULT} macro is invoked each time a rule is
 matched, before the associated action is run.  It is also invoked
 while processing a syntax error, to compute the error's location.
 rule.  The @code{YYLLOC_DEFAULT} macro is invoked each time a rule is
 matched, before the associated action is run.  It is also invoked
 while processing a syntax error, to compute the error's location.

+Before reporting an unresolvable syntactic ambiguity, a @acronym{GLR}
+parser invokes @code{YYLLOC_DEFAULT} recursively to compute the location
+of that ambiguity.

 
 Most of the time, this macro is general enough to suppress location
 dedicated code from semantic actions.
 
 Most of the time, this macro is general enough to suppress location
 dedicated code from semantic actions.


@@ -3586,9 +3600,11 @@ The @code{YYLLOC_DEFAULT} macro takes three parameters.  The first one is
 the location of the grouping (the result of the computation).  When a
 rule is matched, the second parameter identifies locations of
 all right hand side elements of the rule being matched, and the third
 the location of the grouping (the result of the computation).  When a
 rule is matched, the second parameter identifies locations of
 all right hand side elements of the rule being matched, and the third

-parameter is the size of the rule's right hand side.  When processing
-a syntax error, the second parameter identifies locations of
-the symbols that were discarded during error processing, and the third
+parameter is the size of the rule's right hand side.
+When a @acronym{GLR} parser reports an ambiguity, which of multiple candidate
+right hand sides it passes to @code{YYLLOC_DEFAULT} is undefined.
+When processing a syntax error, the second parameter identifies locations
+of the symbols that were discarded during error processing, and the third

 parameter is the number of discarded symbols.
 
 By default, @code{YYLLOC_DEFAULT} is defined this way:
 parameter is the number of discarded symbols.
 
 By default, @code{YYLLOC_DEFAULT} is defined this way:


@@ -7317,10 +7333,11 @@ factor both as follows.
 @comment file: calc++-driver.hh
 @example
 // Announce to Flex the prototype we want for lexing function, ...
 @comment file: calc++-driver.hh
 @example
 // Announce to Flex the prototype we want for lexing function, ...

-# define YY_DECL                                                \
-  int yylex (yy::calcxx_parser::semantic_type* yylval,           \
-             yy::calcxx_parser::location_type* yylloc,           \
-             calcxx_driver& driver)
+# define YY_DECL                                       \
+  yy::calcxx_parser::token_type                         \
+  yylex (yy::calcxx_parser::semantic_type* yylval,      \
+         yy::calcxx_parser::location_type* yylloc,      \
+         calcxx_driver& driver)

 // ... and declare it for the parser's sake.
 YY_DECL;
 @end example
 // ... and declare it for the parser's sake.
 YY_DECL;
 @end example


@@ -7612,6 +7629,10 @@ parser's to get the set of defined tokens.
   <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=333231>.  */
 # undef yywrap
 # define yywrap() 1
   <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=333231>.  */
 # undef yywrap
 # define yywrap() 1

+/* By default yylex returns int, we use token_type.
+   Unfortunately yyterminate by default returns 0, which is
+   not of token_type.  */
+#define yyterminate() return token::END 

 %@}
 @end example
 
 %@}
 @end example
 


@@ -7669,8 +7690,8 @@ It is convenient to use a typedef to shorten
 %@{
   typedef yy::calcxx_parser::token token;
 %@}
 %@{
   typedef yy::calcxx_parser::token token;
 %@}

-
-[-+*/]     return yytext[0];
+           /* Convert ints to the actual type of tokens. */
+[-+*/]     return yy::calcxx_parser::token_type (yytext[0]);

 ":="       return token::ASSIGN;
 @{int@}      @{
   errno = 0;
 ":="       return token::ASSIGN;
 @{int@}      @{
   errno = 0;


@@ -7744,10 +7765,17 @@ Several questions about Bison come up occasionally.  Here some of them
 are addressed.
 
 @menu
 are addressed.
 
 @menu

-* Memory Exhausted::           Breaking the Stack Limits
-* How Can I Reset the Parser:: @code{yyparse} Keeps some State
-* Strings are Destroyed::      @code{yylval} Loses Track of Strings
-* Implementing Gotos/Loops::   Control Flow in the Calculator
+* Memory Exhausted::            Breaking the Stack Limits
+* How Can I Reset the Parser::  @code{yyparse} Keeps some State
+* Strings are Destroyed::       @code{yylval} Loses Track of Strings
+* Implementing Gotos/Loops::    Control Flow in the Calculator
+* Secure?  Conform?::           Is Bison @acronym{POSIX} safe?
+* I can't build Bison::         Troubleshooting
+* Where can I find help?::      Troubleshouting
+* Bug Reports::                 Troublereporting
+* Other Languages::             Parsers in Java and others
+* Beta Testing::                Experimenting development versions
+* Mailing Lists::               Meeting other Bison users

 @end menu
 
 @node Memory Exhausted
 @end menu
 
 @node Memory Exhausted


@@ -7941,6 +7969,122 @@ This topic is way beyond the scope of this manual, and the reader is
 invited to consult the dedicated literature.
 
 
 invited to consult the dedicated literature.
 
 

+@node Secure?  Conform?
+@section Secure?  Conform?
+
+@display
+Is Bison secure?  Does it conform to POSIX?
+@end display
+
+If you're looking for a guarantee or certification, we don't provide it.
+However, Bison is intended to be a reliable program that conforms to the
+@acronym{POSIX} specification for Yacc.  If you run into problems,
+please send us a bug report.
+
+@node I can't build Bison
+@section I can't build Bison
+
+@display
+I can't build Bison because "make" complains that "msgfmt" is not found.
+What should I do?
+@end display
+
+Like most GNU packages with internationalization support, that feature
+is turned on by default.  If you have problems building in the @file{po}
+subdirectory, it indicates that your system's internationalization
+support is lacking.  You can re-configure Bison with
+@option{--disable-nls} to turn off this support, or you can install GNU
+gettext from @url{ftp://ftp.gnu.org/gnu/gettext/} and re-configure
+Bison.  See the file @file{ABOUT-NLS} for more information.
+
+
+@node Where can I find help?
+@section Where can I find help?
+
+@display
+I'm having trouble using Bison.  Where can I find help?
+@end display
+
+First, read this fine manual.  Beyond that, you can send mail to
+@email{help-bison@@gnu.org}.  This mailing list is intended to be
+populated with people who are willing to answer questions about using
+and installing Bison.  Please keep in mind that (most of) the people on
+the list have aspects of their lives which are not related to Bison (!),
+so you may not receive an answer to your question right away.  This can
+be frustrating, but please try not to honk them off; remember that any
+help they provide is purely voluntary and out of the kindness of their
+hearts.
+
+@node Bug Reports
+@section Bug Reports
+
+@display
+I found a bug.  What should I include in the bug report?
+@end display
+
+Before you send a bug report, make sure you are using the latest
+version.  Check @url{ftp://ftp.gnu.org/pub/gnu/bison/} or one of its
+mirrors.  Be sure to include the version number in your bug report.  If
+the bug is present in the latest version but not in a previous version,
+try to determine the most recent version which did not contain the bug.
+
+If the bug is parser-related, you should include the smallest grammar
+you can which demonstrates the bug.  The grammar file should also be
+complete (i.e., I should be able to run it through Bison without having
+to edit or add anything).  The smaller and simpler the grammar, the
+easier it will be to fix the bug.
+
+Include information about your compilation environment, including your
+operating system's name and version and your compiler's name and
+version.  If you have trouble compiling, you should also include a
+transcript of the build session, starting with the invocation of
+`configure'.  Depending on the nature of the bug, you may be asked to
+send additional files as well (such as `config.h' or `config.cache').
+
+Patches are most welcome, but not required.  That is, do not hesitate to
+send a bug report just because you can not provide a fix.
+
+Send bug reports to @email{bug-bison@@gnu.org}.
+
+@node Other Languages
+@section Other Languages
+
+@display
+Will Bison ever have C++ support?  How about Java or @var{insert your
+favorite language here}?
+@end display
+
+C++ support is there now, and is documented.  We'd love to add other
+languages; contributions are welcome.
+
+@node Beta Testing
+@section Beta Testing
+
+@display
+What is involved in being a beta tester?
+@end display
+
+It's not terribly involved.  Basically, you would download a test
+release, compile it, and use it to build and run a parser or two.  After
+that, you would submit either a bug report or a message saying that
+everything is okay.  It is important to report successes as well as
+failures because test releases eventually become mainstream releases,
+but only if they are adequately tested.  If no one tests, development is
+essentially halted.
+
+Beta testers are particularly needed for operating systems to which the
+developers do not have easy access.  They currently have easy access to
+recent GNU/Linux and Solaris versions.  Reports about other operating
+systems are especially welcome.
+
+@node Mailing Lists
+@section Mailing Lists
+
+@display
+How do I join the help-bison and bug-bison mailing lists?
+@end display
+
+See @url{http://lists.gnu.org/}.

 
 @c ================================================= Table of Symbols
 
 
 @c ================================================= Table of Symbols