doc: improve html and pdf rendering

[bison.git] / doc / bison.texi

diff --git a/doc/bison.texi b/doc/bison.texi
index 6e46c78d666a2f5c0bfddd20a855f1168f222276..737a119cc9ceb05d2378a4b7921fae44c488dc25 100644 (file)
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -35,7 +35,7 @@
 This manual (@value{UPDATED}) is for GNU Bison (version
 @value{VERSION}), the GNU parser generator.
 
 This manual (@value{UPDATED}) is for GNU Bison (version
 @value{VERSION}), the GNU parser generator.
 

-Copyright @copyright{} 1988-1993, 1995, 1998-2014 Free Software
+Copyright @copyright{} 1988-1993, 1995, 1998-2015 Free Software

 Foundation, Inc.
 
 @quotation
 Foundation, Inc.
 
 @quotation


@@ -3851,7 +3851,7 @@ example:
 @noindent
 specifies the union tag @code{value}, so the corresponding C type is
 @code{union value}.  If you do not specify a tag, it defaults to
 @noindent
 specifies the union tag @code{value}, so the corresponding C type is
 @code{union value}.  If you do not specify a tag, it defaults to

-@code{YYSTYPE}.
+@code{YYSTYPE} (@pxref{%define Summary,,api.value.union.name}).

 
 As another extension to POSIX, you may specify multiple @code{%union}
 declarations; their contents are concatenated.  However, only the first
 
 As another extension to POSIX, you may specify multiple @code{%union}
 declarations; their contents are concatenated.  However, only the first


@@ -5145,7 +5145,9 @@ value by default.  However, when the parser displays a @code{STRING1} or a
 @code{string1}, it formats it as a string in double quotes.  It performs
 only the second @code{%printer} in this case, so it prints only once.
 Finally, the parser print @samp{<>} for any symbol, such as @code{TAGLESS},
 @code{string1}, it formats it as a string in double quotes.  It performs
 only the second @code{%printer} in this case, so it prints only once.
 Finally, the parser print @samp{<>} for any symbol, such as @code{TAGLESS},

-that has no semantic type tag.  See also
+that has no semantic type tag.  @xref{Mfcalc Traces, ,Enabling Debug Traces
+for @code{mfcalc}}, for a complete example.
+

 
 
 @node Expect Decl
 
 
 @node Expect Decl


@@ -6012,12 +6014,12 @@ Use this @var{type} as semantic value.
 @item Default Value:
 @itemize @minus
 @item
 @item Default Value:
 @itemize @minus
 @item

-@code{%union} if @code{%union} is used, otherwise @dots{}
+@code{union-directive} if @code{%union} is used, otherwise @dots{}

 @item
 @code{int} if type tags are used (i.e., @samp{%token <@var{type}>@dots{}} or
 @item
 @code{int} if type tags are used (i.e., @samp{%token <@var{type}>@dots{}} or

-@samp{%token <@var{type}>@dots{}} is used), otherwise @dots{}
+@samp{%type <@var{type}>@dots{}} is used), otherwise @dots{}

 @item
 @item

-@code{""}
+undefined.

 @end itemize
 
 @item History:
 @end itemize
 
 @item History:


@@ -6028,6 +6030,30 @@ introduced in Bison 3.0.  Was introduced for Java only in 2.3b as
 @c api.value.type
 
 
 @c api.value.type
 
 

+@c ================================================== api.value.union.name
+@deffn Directive {%define api.value.union.name} @var{name}
+@itemize @bullet
+@item Language(s):
+C
+
+@item Purpose:
+The tag of the generated @code{union} (@emph{not} the name of the
+@code{typedef}).  This variable is set to @code{@var{id}} when @samp{%union
+@var{id}} is used.  There is no clear reason to give this union a name.
+
+@item Accepted Values:
+Any valid identifier.
+
+@item Default Value:
+@code{YYSTYPE}.
+
+@item History:
+Introduced in Bison 3.0.3.
+@end itemize
+@end deffn
+@c api.value.type
+
+

 @c ================================================== location_type
 @deffn Directive {%define location_type}
 Obsoleted by @code{api.location.type} since Bison 2.7.
 @c ================================================== location_type
 @deffn Directive {%define location_type}
 Obsoleted by @code{api.location.type} since Bison 2.7.


@@ -7524,7 +7550,7 @@ in an associativity related conflict, which can be specified as follows.
 
 The unary-minus is another typical example where associativity is
 usually over-specified, see @ref{Infix Calc, , Infix Notation
 
 The unary-minus is another typical example where associativity is
 usually over-specified, see @ref{Infix Calc, , Infix Notation

-Calculator: @code{calc}}.  The @code{%left} directive is traditionally
+Calculator - @code{calc}}.  The @code{%left} directive is traditionally

 used to declare the precedence of @code{NEG}, which is more than needed
 since it also defines its associativity.  While this is harmless in the
 traditional example, who knows how @code{NEG} might be used in future
 used to declare the precedence of @code{NEG}, which is more than needed
 since it also defines its associativity.  While this is harmless in the
 traditional example, who knows how @code{NEG} might be used in future


@@ -10356,9 +10382,23 @@ declare @code{yyerror} as follows:
 int yyerror (char const *);
 @end example
 
 int yyerror (char const *);
 @end example
 

-Bison ignores the @code{int} value returned by this @code{yyerror}.
-If you use the Yacc library's @code{main} function, your
-@code{yyparse} function should have the following type signature:
+@noindent
+The @code{int} value returned by this @code{yyerror} is ignored.
+
+The implementation of Yacc library's @code{main} function is:
+
+@example
+int main (void)
+@{
+  setlocale (LC_ALL, "");
+  return yyparse ();
+@}
+@end example
+
+@noindent
+so if you use it, the internationalization support is enabled (e.g., error
+messages are translated), and your @code{yyparse} function should have the
+following type signature:

 
 @example
 int yyparse (void);
 
 @example
 int yyparse (void);


@@ -10660,12 +10700,17 @@ The first, inclusive, position of the range, and the first beyond.
 Forwarded to the @code{end} position.
 @end deftypemethod
 
 Forwarded to the @code{end} position.
 @end deftypemethod
 

-@deftypemethod {location} {location} operator+ (const location& @var{end})
-@deftypemethodx {location} {location} operator+ (int @var{width})
+@deftypemethod  {location} {location} operator+  (int @var{width})

 @deftypemethodx {location} {location} operator+= (int @var{width})
 @deftypemethodx {location} {location} operator+= (int @var{width})

-@deftypemethodx {location} {location} operator- (int @var{width})
+@deftypemethodx {location} {location} operator-  (int @var{width})

 @deftypemethodx {location} {location} operator-= (int @var{width})
 @deftypemethodx {location} {location} operator-= (int @var{width})

-Various forms of syntactic sugar.
+Various forms of syntactic sugar for @code{columns}.
+@end deftypemethod
+
+@deftypemethod {location} {location} operator+ (const location& @var{end})
+@deftypemethodx {location} {location} operator+= (const location& @var{end})
+Join two locations: starts at the position of the first one, and ends at the
+position of the second.

 @end deftypemethod
 
 @deftypemethod {location} {void} step ()
 @end deftypemethod
 
 @deftypemethod {location} {void} step ()


@@ -10703,8 +10748,8 @@ it must be copyable;
 in order to compute the (default) value of @code{@@$} in a reduction, the
 parser basically runs
 @example
 in order to compute the (default) value of @code{@@$} in a reduction, the
 parser basically runs
 @example

-@@$.begin = @@$1.begin;
-@@$.end   = @@$@var{N}.end; // The location of last right-hand side symbol.
+@@$.begin = @@1.begin;
+@@$.end   = @@@var{N}.end; // The location of last right-hand side symbol.

 @end example
 @noindent
 so there must be copyable @code{begin} and @code{end} members;
 @end example
 @noindent
 so there must be copyable @code{begin} and @code{end} members;


@@ -10856,12 +10901,12 @@ Regular union-based code in Lex scanner typically look like:
 
 @example
 [0-9]+   @{
 
 @example
 [0-9]+   @{

-           yylval.ival = text_to_int (yytext);
-           return yy::parser::INTEGER;
+           yylval->ival = text_to_int (yytext);
+           return yy::parser::token::INTEGER;

          @}
 [a-z]+   @{
          @}
 [a-z]+   @{

-           yylval.sval = new std::string (yytext);
-           return yy::parser::IDENTIFIER;
+           yylval->sval = new std::string (yytext);
+           return yy::parser::token::IDENTIFIER;

          @}
 @end example
 
          @}
 @end example
 


@@ -10870,12 +10915,12 @@ initialized.  So the code would look like:
 
 @example
 [0-9]+   @{
 
 @example
 [0-9]+   @{

-           yylval.build<int>() = text_to_int (yytext);
-           return yy::parser::INTEGER;
+           yylval->build<int> () = text_to_int (yytext);
+           return yy::parser::token::INTEGER;

          @}
 [a-z]+   @{
          @}
 [a-z]+   @{

-           yylval.build<std::string> = yytext;
-           return yy::parser::IDENTIFIER;
+           yylval->build<std::string> () = yytext;
+           return yy::parser::token::IDENTIFIER;

          @}
 @end example
 
          @}
 @end example
 


@@ -10884,12 +10929,12 @@ or
 
 @example
 [0-9]+   @{
 
 @example
 [0-9]+   @{

-           yylval.build(text_to_int (yytext));
-           return yy::parser::INTEGER;
+           yylval->build (text_to_int (yytext));
+           return yy::parser::token::INTEGER;

          @}
 [a-z]+   @{
          @}
 [a-z]+   @{

-           yylval.build(yytext);
-           return yy::parser::IDENTIFIER;
+           yylval->build (yytext);
+           return yy::parser::token::IDENTIFIER;

          @}
 @end example
 
          @}
 @end example
 


@@ -10917,8 +10962,8 @@ it is still possible to give an integer as semantic value for a string.
 
 So for each token type, Bison generates named constructors as follows.
 
 
 So for each token type, Bison generates named constructors as follows.
 

-@deftypemethod {symbol_type} {} make_@var{token} (const @var{value_type}& @var{value}, const location_type& @var{location})
-@deftypemethodx {symbol_type} {} make_@var{token} (const location_type& @var{location})
+@deftypemethod {symbol_type} {} {make_@var{token}} (const @var{value_type}& @var{value}, const location_type& @var{location})
+@deftypemethodx {symbol_type} {} {make_@var{token}} (const location_type& @var{location})

 Build a complete terminal symbol for the token type @var{token} (not
 including the @code{api.token.prefix}) whose possible semantic value is
 @var{value} of adequate @var{value_type}.  If location tracking is enabled,
 Build a complete terminal symbol for the token type @var{token} (not
 including the @code{api.token.prefix}) whose possible semantic value is
 @var{value} of adequate @var{value_type}.  If location tracking is enabled,


@@ -10938,20 +10983,18 @@ For instance, given the following declarations:
 Bison generates the following functions:
 
 @example
 Bison generates the following functions:
 
 @example

-symbol_type make_IDENTIFIER(const std::string& v,
-                            const location_type& l);
-symbol_type make_INTEGER(const int& v,
-                         const location_type& loc);
-symbol_type make_COLON(const location_type& loc);
+symbol_type make_IDENTIFIER (const std::string&, const location_type&);
+symbol_type make_INTEGER (const int&, const location_type&);
+symbol_type make_COLON (const location_type&);

 @end example
 
 @noindent
 which should be used in a Lex-scanner as follows.
 
 @example
 @end example
 
 @noindent
 which should be used in a Lex-scanner as follows.
 
 @example

-[0-9]+   return yy::parser::make_INTEGER(text_to_int (yytext), loc);
-[a-z]+   return yy::parser::make_IDENTIFIER(yytext, loc);
-":"      return yy::parser::make_COLON(loc);
+[0-9]+   return yy::parser::make_INTEGER (text_to_int (yytext), loc);
+[a-z]+   return yy::parser::make_IDENTIFIER (yytext, loc);
+":"      return yy::parser::make_COLON (loc);

 @end example
 
 Tokens that do not have an identifier are not accessible: you cannot simply
 @end example
 
 Tokens that do not have an identifier are not accessible: you cannot simply


@@ -11292,7 +11335,7 @@ regular destructors.  All the values are printed using their
 
 @noindent
 The grammar itself is straightforward (@pxref{Location Tracking Calc, ,
 
 @noindent
 The grammar itself is straightforward (@pxref{Location Tracking Calc, ,

-Location Tracking Calculator: @code{ltcalc}}).
+Location Tracking Calculator - @code{ltcalc}}).

 
 @comment file: calc++-parser.yy
 @example
 
 @comment file: calc++-parser.yy
 @example


@@ -11416,13 +11459,13 @@ The rules are simple.  The driver is used to report errors.
 
 @comment file: calc++-scanner.ll
 @example
 
 @comment file: calc++-scanner.ll
 @example

-"-"      return yy::calcxx_parser::make_MINUS(loc);
-"+"      return yy::calcxx_parser::make_PLUS(loc);
-"*"      return yy::calcxx_parser::make_STAR(loc);
-"/"      return yy::calcxx_parser::make_SLASH(loc);
-"("      return yy::calcxx_parser::make_LPAREN(loc);
-")"      return yy::calcxx_parser::make_RPAREN(loc);
-":="     return yy::calcxx_parser::make_ASSIGN(loc);
+"-"      return yy::calcxx_parser::make_MINUS  (loc);
+"+"      return yy::calcxx_parser::make_PLUS   (loc);
+"*"      return yy::calcxx_parser::make_STAR   (loc);
+"/"      return yy::calcxx_parser::make_SLASH  (loc);
+"("      return yy::calcxx_parser::make_LPAREN (loc);
+")"      return yy::calcxx_parser::make_RPAREN (loc);
+":="     return yy::calcxx_parser::make_ASSIGN (loc);

 
 @group
 @{int@}      @{
 
 @group
 @{int@}      @{


@@ -11430,12 +11473,12 @@ The rules are simple.  The driver is used to report errors.
   long n = strtol (yytext, NULL, 10);
   if (! (INT_MIN <= n && n <= INT_MAX && errno != ERANGE))
     driver.error (loc, "integer is out of range");
   long n = strtol (yytext, NULL, 10);
   if (! (INT_MIN <= n && n <= INT_MAX && errno != ERANGE))
     driver.error (loc, "integer is out of range");

-  return yy::calcxx_parser::make_NUMBER(n, loc);
+  return yy::calcxx_parser::make_NUMBER (n, loc);

 @}
 @end group
 @}
 @end group

-@{id@}       return yy::calcxx_parser::make_IDENTIFIER(yytext, loc);
+@{id@}       return yy::calcxx_parser::make_IDENTIFIER (yytext, loc);

 .          driver.error (loc, "invalid character");
 .          driver.error (loc, "invalid character");

-<<EOF>>    return yy::calcxx_parser::make_END(loc);
+<<EOF>>    return yy::calcxx_parser::make_END (loc);

 %%
 @end example
 
 %%
 @end example