]> git.saurik.com Git - bison.git/blobdiff - doc/bison.texinfo
doc: fix environment issues.
[bison.git] / doc / bison.texinfo
index 8fdac074ae066d11ce0fe3833d178dcd631b3e90..5d87ff50932ef0de84628be09755afa9662402f5 100644 (file)
@@ -33,7 +33,7 @@
 This manual (@value{UPDATED}) is for GNU Bison (version
 @value{VERSION}), the GNU parser generator.
 
-Copyright @copyright{} 1988-1993, 1995, 1998-2011 Free Software
+Copyright @copyright{} 1988-1993, 1995, 1998-2012 Free Software
 Foundation, Inc.
 
 @quotation
@@ -125,7 +125,7 @@ The Concepts of Bison
                            the name of an identifier, etc.).
 * Semantic Actions::     Each rule can have an action containing C code.
 * GLR Parsers::          Writing parsers for general context-free languages.
-* Locations Overview::   Tracking Locations.
+* Locations::            Overview of location tracking.
 * Bison Parser::         What are Bison's input and output,
                            how is the output used?
 * Stages::               Stages in writing and running Bison grammars.
@@ -180,15 +180,15 @@ Multi-Function Calculator: @code{mfcalc}
 
 Bison Grammar Files
 
-* Grammar Outline::   Overall layout of the grammar file.
-* Symbols::           Terminal and nonterminal symbols.
-* Rules::             How to write grammar rules.
-* Recursion::         Writing recursive rules.
-* Semantics::         Semantic values and actions.
-* Locations::         Locations and actions.
-* Named References::  Using named references in actions.
-* Declarations::      All kinds of Bison declarations are described here.
-* Multiple Parsers::  Putting more than one Bison parser in one program.
+* Grammar Outline::    Overall layout of the grammar file.
+* Symbols::            Terminal and nonterminal symbols.
+* Rules::              How to write grammar rules.
+* Recursion::          Writing recursive rules.
+* Semantics::          Semantic values and actions.
+* Tracking Locations:: Locations and actions.
+* Named References::   Using named references in actions.
+* Declarations::       All kinds of Bison declarations are described here.
+* Multiple Parsers::   Putting more than one Bison parser in one program.
 
 Outline of a Bison Grammar
 
@@ -449,7 +449,7 @@ use Bison or Yacc, we suggest you start by reading this chapter carefully.
                            the name of an identifier, etc.).
 * Semantic Actions::     Each rule can have an action containing C code.
 * GLR Parsers::          Writing parsers for general context-free languages.
-* Locations Overview::   Tracking Locations.
+* Locations::            Overview of location tracking.
 * Bison Parser::         What are Bison's input and output,
                            how is the output used?
 * Stages::               Stages in writing and running Bison grammars.
@@ -1205,7 +1205,7 @@ will suffice.  Otherwise, we suggest
 %@}
 @end example
 
-@node Locations Overview
+@node Locations
 @section Locations
 @cindex location
 @cindex textual location
@@ -1217,9 +1217,10 @@ the @dfn{textual location}, or @dfn{location}, of each syntactic construct.
 Bison provides a mechanism for handling these locations.
 
 Each token has a semantic value.  In a similar fashion, each token has an
-associated location, but the type of locations is the same for all tokens and
-groupings.  Moreover, the output parser is equipped with a default data
-structure for storing locations (@pxref{Locations}, for more details).
+associated location, but the type of locations is the same for all tokens
+and groupings.  Moreover, the output parser is equipped with a default data
+structure for storing locations (@pxref{Tracking Locations}, for more
+details).
 
 Like semantic values, locations can be reached in actions using a dedicated
 set of constructs.  In the example above, the location of the whole grouping
@@ -1711,7 +1712,7 @@ yylex (void)
 
   /* Skip white space.  */
   while ((c = getchar ()) == ' ' || c == '\t')
-    ;
+    continue;
 @end group
 @group
   /* Process numbers.  */
@@ -2157,6 +2158,7 @@ yylex (void)
   if (c == EOF)
     return 0;
 
+@group
   /* Return a single char, and update location.  */
   if (c == '\n')
     @{
@@ -2167,6 +2169,7 @@ yylex (void)
     ++yylloc.last_column;
   return c;
 @}
+@end group
 @end example
 
 Basically, the lexical analyzer performs the same processing as before:
@@ -2466,6 +2469,10 @@ The function @code{getsym} is passed the name of the symbol to look up.  If
 found, a pointer to that symbol is returned; otherwise zero is returned.
 
 @smallexample
+#include <stdlib.h> /* malloc. */
+#include <string.h> /* strlen. */
+
+@group
 symrec *
 putsym (char const *sym_name, int sym_type)
 @{
@@ -2479,7 +2486,9 @@ putsym (char const *sym_name, int sym_type)
   sym_table = ptr;
   return ptr;
 @}
+@end group
 
+@group
 symrec *
 getsym (char const *sym_name)
 @{
@@ -2490,6 +2499,7 @@ getsym (char const *sym_name)
       return ptr;
   return 0;
 @}
+@end group
 @end smallexample
 
 The function @code{yylex} must now recognize variables, numeric values, and
@@ -2519,7 +2529,8 @@ yylex (void)
   int c;
 
   /* Ignore white space, get first nonwhite character.  */
-  while ((c = getchar ()) == ' ' || c == '\t');
+  while ((c = getchar ()) == ' ' || c == '\t')
+    continue;
 
   if (c == EOF)
     return 0;
@@ -2621,15 +2632,15 @@ The Bison grammar file conventionally has a name ending in @samp{.y}.
 @xref{Invocation, ,Invoking Bison}.
 
 @menu
-* Grammar Outline::   Overall layout of the grammar file.
-* Symbols::           Terminal and nonterminal symbols.
-* Rules::             How to write grammar rules.
-* Recursion::         Writing recursive rules.
-* Semantics::         Semantic values and actions.
-* Locations::         Locations and actions.
-* Named References::  Using named references in actions.
-* Declarations::      All kinds of Bison declarations are described here.
-* Multiple Parsers::  Putting more than one Bison parser in one program.
+* Grammar Outline::    Overall layout of the grammar file.
+* Symbols::            Terminal and nonterminal symbols.
+* Rules::              How to write grammar rules.
+* Recursion::          Writing recursive rules.
+* Semantics::          Semantic values and actions.
+* Tracking Locations:: Locations and actions.
+* Named References::   Using named references in actions.
+* Declarations::       All kinds of Bison declarations are described here.
+* Multiple Parsers::   Putting more than one Bison parser in one program.
 @end menu
 
 @node Grammar Outline
@@ -2840,19 +2851,26 @@ definitions.
 Thus, they belong in one or more @code{%code requires}:
 
 @smallexample
+@group
 %code top @{
   #define _GNU_SOURCE
   #include <stdio.h>
 @}
+@end group
 
+@group
 %code requires @{
   #include "ptypes.h"
 @}
+@end group
+@group
 %union @{
   long int n;
   tree t;  /* @r{@code{tree} is defined in @file{ptypes.h}.} */
 @}
+@end group
 
+@group
 %code requires @{
   #define YYLTYPE YYLTYPE
   typedef struct YYLTYPE
@@ -2864,12 +2882,15 @@ Thus, they belong in one or more @code{%code requires}:
     char *filename;
   @} YYLTYPE;
 @}
+@end group
 
+@group
 %code @{
   static void print_token_value (FILE *, int, YYSTYPE);
   #define YYPRINT(F, N, L) print_token_value (F, N, L)
   static void trace_token (enum yytokentype token, YYLTYPE loc);
 @}
+@end group
 
 @dots{}
 @end smallexample
@@ -2907,19 +2928,26 @@ sufficient.  Instead, move its prototype from the unqualified
 @code{%code} to a @code{%code provides}:
 
 @smallexample
+@group
 %code top @{
   #define _GNU_SOURCE
   #include <stdio.h>
 @}
+@end group
 
+@group
 %code requires @{
   #include "ptypes.h"
 @}
+@end group
+@group
 %union @{
   long int n;
   tree t;  /* @r{@code{tree} is defined in @file{ptypes.h}.} */
 @}
+@end group
 
+@group
 %code requires @{
   #define YYLTYPE YYLTYPE
   typedef struct YYLTYPE
@@ -2931,15 +2959,20 @@ sufficient.  Instead, move its prototype from the unqualified
     char *filename;
   @} YYLTYPE;
 @}
+@end group
 
+@group
 %code provides @{
   void trace_token (enum yytokentype token, YYLTYPE loc);
 @}
+@end group
 
+@group
 %code @{
   static void print_token_value (FILE *, int, YYSTYPE);
   #define YYPRINT(F, N, L) print_token_value (F, N, L)
 @}
+@end group
 
 @dots{}
 @end smallexample
@@ -2969,15 +3002,19 @@ For example, you may organize semantic-type-related directives by semantic
 type:
 
 @smallexample
+@group
 %code requires @{ #include "type1.h" @}
 %union @{ type1 field1; @}
 %destructor @{ type1_free ($$); @} <field1>
 %printer @{ type1_print ($$); @} <field1>
+@end group
 
+@group
 %code requires @{ #include "type2.h" @}
 %union @{ type2 field2; @}
 %destructor @{ type2_free ($$); @} <field2>
 %printer @{ type2_print ($$); @} <field2>
+@end group
 @end smallexample
 
 @noindent
@@ -3509,8 +3546,8 @@ the addition-expression just recognized by the rule.  If there were a
 useful semantic value associated with the @samp{+} token, it could be
 referred to as @code{$2}.
 
-@xref{Named References,,Using Named References}, for more information
-about using the named references construct.
+@xref{Named References}, for more information about using the named
+references construct.
 
 Note that the vertical-bar character @samp{|} is really a rule
 separator, and actions are attached to a single rule.  This is a
@@ -3806,7 +3843,7 @@ compound: subroutine
 Now Bison can execute the action in the rule for @code{subroutine} without
 deciding which rule for @code{compound} it will eventually use.
 
-@node Locations
+@node Tracking Locations
 @section Tracking Locations
 @cindex location
 @cindex textual location
@@ -3876,8 +3913,8 @@ The location of the @var{n}th component of the right hand side is
 
 In addition, the named references construct @code{@@@var{name}} and
 @code{@@[@var{name}]} may also be used to address the symbol locations.
-@xref{Named References,,Using Named References}, for more information
-about using the named references construct.
+@xref{Named References}, for more information about using the named
+references construct.
 
 Here is a basic example using the default data type for locations:
 
@@ -4015,13 +4052,19 @@ statement when it is followed by a semicolon.
 @end itemize
 
 @node Named References
-@section Using Named References
+@section Named References
 @cindex named references
 
-While every semantic value can be accessed with positional references
-@code{$@var{n}} and @code{$$}, it's often much more convenient to refer to
-them by name.  First of all, original symbol names may be used as named
-references.  For example:
+As described in the preceding sections, the traditional way to refer to any
+semantic value or location is a @dfn{positional reference}, which takes the
+form @code{$@var{n}}, @code{$$}, @code{@@@var{n}}, and @code{@@$}.  However,
+such a reference is not very descriptive.  Moreover, if you later decide to
+insert or remove symbols in the right-hand side of a grammar rule, the need
+to renumber such references can be tedious and error-prone.
+
+To avoid these issues, you can also refer to a semantic value or location
+using a @dfn{named reference}.  First of all, original symbol names may be
+used as named references.  For example:
 
 @example
 @group
@@ -4031,8 +4074,7 @@ invocation: op '(' args ')'
 @end example
 
 @noindent
-The positional @code{$$}, @code{@@$}, @code{$n}, and @code{@@n} can be
-mixed with @code{$name} and @code{@@name} arbitrarily.  For example:
+Positional and named references can be mixed arbitrarily.  For example:
 
 @example
 @group
@@ -4070,10 +4112,9 @@ exp[result]: exp[left] '/' exp[right]
 @end example
 
 @noindent
-Explicit names may be declared for RHS and for LHS symbols as well.  In order
-to access a semantic value generated by a mid-rule action, an explicit name
-may also be declared by putting a bracketed name after the closing brace of
-the mid-rule action code:
+In order to access a semantic value generated by a mid-rule action, an
+explicit name may also be declared by putting a bracketed name after the
+closing brace of the mid-rule action code:
 @example
 @group
 exp[res]: exp[x] '+' @{$left = $x;@}[left] exp[right]
@@ -4087,18 +4128,21 @@ In references, in order to specify names containing dots and dashes, an explicit
 bracketed syntax @code{$[name]} and @code{@@[name]} must be used:
 @example
 @group
-if-stmt: IF '(' expr ')' THEN then.stmt ';'
+if-stmt: "if" '(' expr ')' "then" then.stmt ';'
   @{ $[if-stmt] = new_if_stmt ($expr, $[then.stmt]); @}
 @end group
 @end example
 
 It often happens that named references are followed by a dot, dash or other
 C punctuation marks and operators.  By default, Bison will read
-@code{$name.suffix} as a reference to symbol value @code{$name} followed by
-@samp{.suffix}, i.e., an access to the @samp{suffix} field of the semantic
-value.  In order to force Bison to recognize @code{name.suffix} in its entirety
-as the name of a semantic value, bracketed syntax @code{$[name.suffix]}
-must be used.
+@samp{$name.suffix} as a reference to symbol value @code{$name} followed by
+@samp{.suffix}, i.e., an access to the @code{suffix} field of the semantic
+value.  In order to force Bison to recognize @samp{name.suffix} in its
+entirety as the name of a semantic value, the bracketed syntax
+@samp{$[name.suffix]} must be used.
+
+The named references feature is experimental.  More user feedback will help
+to stabilize it.
 
 @node Declarations
 @section Bison Declarations
@@ -4540,12 +4584,12 @@ redefine it from @code{$end} to, for example, @code{END}:
 @cindex mid-rule actions
 Finally, Bison will never invoke a @code{%destructor} for an unreferenced
 mid-rule semantic value (@pxref{Mid-Rule Actions,,Actions in Mid-Rule}).
-That is, Bison does not consider a mid-rule to have a semantic value if you do
-not reference @code{$$} in the mid-rule's action or @code{$@var{n}} (where
-@var{n} is the RHS symbol position of the mid-rule) in any later action in that
-rule.
-However, if you do reference either, the Bison-generated parser will invoke the
-@code{<>} @code{%destructor} whenever it discards the mid-rule symbol.
+That is, Bison does not consider a mid-rule to have a semantic value if you
+do not reference @code{$$} in the mid-rule's action or @code{$@var{n}}
+(where @var{n} is the right-hand side symbol position of the mid-rule) in
+any later action in that rule.  However, if you do reference either, the
+Bison-generated parser will invoke the @code{<>} @code{%destructor} whenever
+it discards the mid-rule symbol.
 
 @ignore
 @noindent
@@ -4911,9 +4955,8 @@ Unless your parser is pure, the parser header file declares
 (Reentrant) Parser}.
 
 If you have also used locations, the parser header file declares
-@code{YYLTYPE} and @code{yylloc} using a protocol similar to that of
-the @code{YYSTYPE} macro and @code{yylval}.  @xref{Locations,
-,Tracking Locations}.
+@code{YYLTYPE} and @code{yylloc} using a protocol similar to that of the
+@code{YYSTYPE} macro and @code{yylval}.  @xref{Tracking Locations}.
 
 This parser header file is normally essential if you wish to put the
 definition of @code{yylex} in a separate source file, because
@@ -5752,12 +5795,12 @@ then the code in @code{yylex} might look like this:
 @subsection Textual Locations of Tokens
 
 @vindex yylloc
-If you are using the @samp{@@@var{n}}-feature (@pxref{Locations, ,
-Tracking Locations}) in actions to keep track of the textual locations
-of tokens and groupings, then you must provide this information in
-@code{yylex}.  The function @code{yyparse} expects to find the textual
-location of a token just parsed in the global variable @code{yylloc}.
-So @code{yylex} must store the proper data in that variable.
+If you are using the @samp{@@@var{n}}-feature (@pxref{Tracking Locations})
+in actions to keep track of the textual locations of tokens and groupings,
+then you must provide this information in @code{yylex}.  The function
+@code{yyparse} expects to find the textual location of a token just parsed
+in the global variable @code{yylloc}.  So @code{yylex} must store the proper
+data in that variable.
 
 By default, the value of @code{yylloc} is a structure and you need only
 initialize the members that are going to be used by the actions.  The
@@ -6083,9 +6126,9 @@ Actions}).
 
 @deffn {Value} @@$
 @findex @@$
-Acts like a structure variable containing information on the textual location
-of the grouping made by the current rule.  @xref{Locations, ,
-Tracking Locations}.
+Acts like a structure variable containing information on the textual
+location of the grouping made by the current rule.  @xref{Tracking
+Locations}.
 
 @c Check if those paragraphs are still useful or not.
 
@@ -6109,9 +6152,9 @@ Tracking Locations}.
 
 @deffn {Value} @@@var{n}
 @findex @@@var{n}
-Acts like a structure variable containing information on the textual location
-of the @var{n}th component of the current rule.  @xref{Locations, ,
-Tracking Locations}.
+Acts like a structure variable containing information on the textual
+location of the @var{n}th component of the current rule.  @xref{Tracking
+Locations}.
 @end deffn
 
 @node Internationalization
@@ -6676,18 +6719,22 @@ For example, here is an erroneous attempt to define a sequence
 of zero or more @code{word} groupings.
 
 @example
+@group
 sequence: /* empty */
                 @{ printf ("empty sequence\n"); @}
         | maybeword
         | sequence word
                 @{ printf ("added word %s\n", $2); @}
         ;
+@end group
 
+@group
 maybeword: /* empty */
                 @{ printf ("empty maybeword\n"); @}
         | word
                 @{ printf ("single word %s\n", $1); @}
         ;
+@end group
 @end example
 
 @noindent
@@ -6764,18 +6811,24 @@ Second, to prevent either a @code{words} or a @code{redirects}
 from being empty:
 
 @example
+@group
 sequence: /* empty */
         | sequence words
         | sequence redirects
         ;
+@end group
 
+@group
 words:    word
         | words word
         ;
+@end group
 
+@group
 redirects:redirect
         | redirects redirect
         ;
+@end group
 @end example
 
 @node Mysterious Conflicts
@@ -7615,11 +7668,13 @@ earlier:
 @example
 typedef int foo, bar;
 int baz (void)
+@group
 @{
   static bar (bar);      /* @r{redeclare @code{bar} as static variable} */
   extern foo foo (foo);  /* @r{redeclare @code{foo} as function} */
   return foo (bar);
 @}
+@end group
 @end example
 
 Unfortunately, the name being declared is separated from the declaration
@@ -7632,17 +7687,21 @@ declaration in which that can't be done.  Here is a part of the
 duplication, with actions omitted for brevity:
 
 @example
+@group
 initdcl:
           declarator maybeasm '='
           init
         | declarator maybeasm
         ;
+@end group
 
+@group
 notype_initdcl:
           notype_declarator maybeasm '='
           init
         | notype_declarator maybeasm
         ;
+@end group
 @end example
 
 @noindent
@@ -7897,6 +7956,7 @@ Grammar
 and reports the uses of the symbols:
 
 @example
+@group
 Terminals, with rules where they appear
 
 $end (0) 0
@@ -7906,13 +7966,16 @@ $end (0) 0
 '/' (47) 4
 error (256)
 NUM (258) 5
+@end group
 
+@group
 Nonterminals, with rules where they appear
 
 $accept (8)
     on left: 0
 exp (9)
     on left: 1 2 3 4 5, on right: 0 1 2 3 4
+@end group
 @end example
 
 @noindent
@@ -8129,6 +8192,7 @@ state 8
 The remaining states are similar:
 
 @example
+@group
 state 9
 
     exp  ->  exp . '+' exp   (rule 1)
@@ -8142,7 +8206,9 @@ state 9
 
     '/'         [reduce using rule 2 (exp)]
     $default    reduce using rule 2 (exp)
+@end group
 
+@group
 state 10
 
     exp  ->  exp . '+' exp   (rule 1)
@@ -8155,7 +8221,9 @@ state 10
 
     '/'         [reduce using rule 3 (exp)]
     $default    reduce using rule 3 (exp)
+@end group
 
+@group
 state 11
 
     exp  ->  exp . '+' exp   (rule 1)
@@ -8174,6 +8242,7 @@ state 11
     '*'         [reduce using rule 4 (exp)]
     '/'         [reduce using rule 4 (exp)]
     $default    reduce using rule 4 (exp)
+@end group
 @end example
 
 @noindent
@@ -8753,10 +8822,10 @@ Symbols}.
 @c - %define filename_type "const symbol::Symbol"
 
 When the directive @code{%locations} is used, the C++ parser supports
-location tracking, see @ref{Locations, , Locations Overview}.  Two
-auxiliary classes define a @code{position}, a single point in a file,
-and a @code{location}, a range composed of a pair of
-@code{position}s (possibly spanning several files).
+location tracking, see @ref{Tracking Locations}.  Two auxiliary classes
+define a @code{position}, a single point in a file, and a @code{location}, a
+range composed of a pair of @code{position}s (possibly spanning several
+files).
 
 @deftypemethod {position} {std::string*} file
 The name of the file.  It will always be handled as a pointer, the
@@ -9307,9 +9376,11 @@ preceding tokens.  Comments would be treated equally.
 
 @comment file: calc++-scanner.ll
 @example
+@group
 %@{
 # define YY_USER_ACTION  yylloc->columns (yyleng);
 %@}
+@end group
 %%
 %@{
   yylloc->step ();
@@ -9351,6 +9422,7 @@ on the scanner's data, it is simpler to implement them in this file.
 
 @comment file: calc++-scanner.ll
 @example
+@group
 void
 calcxx_driver::scan_begin ()
 @{
@@ -9359,16 +9431,19 @@ calcxx_driver::scan_begin ()
     yyin = stdin;
   else if (!(yyin = fopen (file.c_str (), "r")))
     @{
-      error (std::string ("cannot open ") + file);
-      exit (1);
+      error (std::string ("cannot open ") + file + ": " + strerror(errno));
+      exit (EXIT_FAILURE);
     @}
 @}
+@end group
 
+@group
 void
 calcxx_driver::scan_end ()
 @{
   fclose (yyin);
 @}
+@end group
 @end example
 
 @node Calc++ Top Level
@@ -9381,6 +9456,7 @@ The top level file, @file{calc++.cc}, poses no problem.
 #include <iostream>
 #include "calc++-driver.hh"
 
+@group
 int
 main (int argc, char *argv[])
 @{
@@ -9393,6 +9469,7 @@ main (int argc, char *argv[])
     else if (!driver.parse (*argv))
       std::cout << driver.result << std::endl;
 @}
+@end group
 @end example
 
 @node Java Parsers
@@ -9508,14 +9585,13 @@ can be used to print the semantic values.  This however may change
 @c - class Position
 @c - class Location
 
-When the directive @code{%locations} is used, the Java parser
-supports location tracking, see @ref{Locations, , Locations Overview}.
-An auxiliary user-defined class defines a @dfn{position}, a single point
-in a file; Bison itself defines a class representing a @dfn{location},
-a range composed of a pair of positions (possibly spanning several
-files).  The location class is an inner class of the parser; the name
-is @code{Location} by default, and may also be renamed using
-@code{%define location_type "@var{class-name}"}.
+When the directive @code{%locations} is used, the Java parser supports
+location tracking, see @ref{Tracking Locations}.  An auxiliary user-defined
+class defines a @dfn{position}, a single point in a file; Bison itself
+defines a class representing a @dfn{location}, a range composed of a pair of
+positions (possibly spanning several files).  The location class is an inner
+class of the parser; the name is @code{Location} by default, and may also be
+renamed using @code{%define location_type "@var{class-name}"}.
 
 The location class treats the position as a completely opaque value.
 By default, the class name is @code{Position}, but this can be changed
@@ -9991,10 +10067,10 @@ are addressed.
 @node Memory Exhausted
 @section Memory Exhausted
 
-@display
+@quotation
 My parser returns with error with a @samp{memory exhausted}
 message.  What can I do?
-@end display
+@end quotation
 
 This question is already addressed elsewhere, @xref{Recursion,
 ,Recursive Rules}.
@@ -10005,20 +10081,20 @@ This question is already addressed elsewhere, @xref{Recursion,
 The following phenomenon has several symptoms, resulting in the
 following typical questions:
 
-@display
+@quotation
 I invoke @code{yyparse} several times, and on correct input it works
 properly; but when a parse error is found, all the other calls fail
 too.  How can I reset the error flag of @code{yyparse}?
-@end display
+@end quotation
 
 @noindent
 or
 
-@display
+@quotation
 My parser includes support for an @samp{#include}-like feature, in
 which case I run @code{yyparse} from @code{yyparse}.  This fails
-although I did specify @code{%define api.pure}.
-@end display
+although I did specify @samp{%define api.pure}.
+@end quotation
 
 These problems typically come not from Bison itself, but from
 Lex-generated scanners.  Because these scanners use large buffers for
@@ -10026,43 +10102,57 @@ speed, they might not notice a change of input file.  As a
 demonstration, consider the following source file,
 @file{first-line.l}:
 
-@verbatim
-%{
+@example
+@group
+%@{
 #include <stdio.h>
 #include <stdlib.h>
-%}
+%@}
+@end group
 %%
 .*\n    ECHO; return 1;
 %%
+@group
 int
 yyparse (char const *file)
-{
+@{
   yyin = fopen (file, "r");
   if (!yyin)
-    exit (2);
+    @{
+      perror ("fopen");
+      exit (EXIT_FAILURE);
+    @}
+@end group
+@group
   /* One token only.  */
   yylex ();
   if (fclose (yyin) != 0)
-    exit (3);
+    @{
+      perror ("fclose");
+      exit (EXIT_FAILURE);
+    @}
   return 0;
-}
+@}
+@end group
 
+@group
 int
 main (void)
-{
+@{
   yyparse ("input");
   yyparse ("input");
   return 0;
-}
-@end verbatim
+@}
+@end group
+@end example
 
 @noindent
 If the file @file{input} contains
 
-@verbatim
+@example
 input:1: Hello,
 input:2: World!
-@end verbatim
+@end example
 
 @noindent
 then instead of getting the first line twice, you get:
@@ -10093,35 +10183,41 @@ start condition, through a call to @samp{BEGIN (0)}.
 @node Strings are Destroyed
 @section Strings are Destroyed
 
-@display
+@quotation
 My parser seems to destroy old strings, or maybe it loses track of
 them.  Instead of reporting @samp{"foo", "bar"}, it reports
 @samp{"bar", "bar"}, or even @samp{"foo\nbar", "bar"}.
-@end display
+@end quotation
 
 This error is probably the single most frequent ``bug report'' sent to
 Bison lists, but is only concerned with a misunderstanding of the role
 of the scanner.  Consider the following Lex code:
 
-@verbatim
-%{
+@example
+@group
+%@{
 #include <stdio.h>
 char *yylval = NULL;
-%}
+%@}
+@end group
+@group
 %%
 .*    yylval = yytext; return 1;
 \n    /* IGNORE */
 %%
+@end group
+@group
 int
 main ()
-{
+@{
   /* Similar to using $1, $2 in a Bison action.  */
   char *fst = (yylex (), yylval);
   char *snd = (yylex (), yylval);
   printf ("\"%s\", \"%s\"\n", fst, snd);
   return 0;
-}
-@end verbatim
+@}
+@end group
+@end example
 
 If you compile and run this code, you get:
 
@@ -10152,10 +10248,10 @@ $ @kbd{printf 'one\ntwo\n' | ./split-lines}
 @node Implementing Gotos/Loops
 @section Implementing Gotos/Loops
 
-@display
+@quotation
 My simple calculator supports variables, assignments, and functions,
 but how can I implement gotos, or loops?
-@end display
+@end quotation
 
 Although very pedagogical, the examples included in the document blur
 the distinction to make between the parser---whose job is to recover
@@ -10182,11 +10278,11 @@ invited to consult the dedicated literature.
 @node Multiple start-symbols
 @section Multiple start-symbols
 
-@display
+@quotation
 I have several closely related grammars, and I would like to share their
 implementations.  In fact, I could use a single grammar but with
 multiple entry points.
-@end display
+@end quotation
 
 Bison does not support multiple start-symbols, but there is a very
 simple means to simulate them.  If @code{foo} and @code{bar} are the two
@@ -10231,9 +10327,9 @@ available in the scanner (e.g., a global variable or using
 @node Secure?  Conform?
 @section Secure?  Conform?
 
-@display
+@quotation
 Is Bison secure?  Does it conform to POSIX?
-@end display
+@end quotation
 
 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
@@ -10243,11 +10339,11 @@ please send us a bug report.
 @node I can't build Bison
 @section I can't build Bison
 
-@display
+@quotation
 I can't build Bison because @command{make} complains that
 @code{msgfmt} is not found.
 What should I do?
-@end display
+@end quotation
 
 Like most GNU packages with internationalization support, that feature
 is turned on by default.  If you have problems building in the @file{po}
@@ -10261,9 +10357,9 @@ Bison.  See the file @file{ABOUT-NLS} for more information.
 @node Where can I find help?
 @section Where can I find help?
 
-@display
+@quotation
 I'm having trouble using Bison.  Where can I find help?
-@end display
+@end quotation
 
 First, read this fine manual.  Beyond that, you can send mail to
 @email{help-bison@@gnu.org}.  This mailing list is intended to be
@@ -10278,9 +10374,9 @@ hearts.
 @node Bug Reports
 @section Bug Reports
 
-@display
+@quotation
 I found a bug.  What should I include in the bug report?
-@end display
+@end quotation
 
 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
@@ -10302,17 +10398,17 @@ transcript of the build session, starting with the invocation of
 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 a bug report just because you cannot provide a fix.
 
 Send bug reports to @email{bug-bison@@gnu.org}.
 
 @node More Languages
 @section More Languages
 
-@display
+@quotation
 Will Bison ever have C++ and Java support?  How about @var{insert your
 favorite language here}?
-@end display
+@end quotation
 
 C++ and Java support is there now, and is documented.  We'd love to add other
 languages; contributions are welcome.
@@ -10320,9 +10416,9 @@ languages; contributions are welcome.
 @node Beta Testing
 @section Beta Testing
 
-@display
+@quotation
 What is involved in being a beta tester?
-@end display
+@end quotation
 
 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
@@ -10340,9 +10436,9 @@ systems are especially welcome.
 @node Mailing Lists
 @section Mailing Lists
 
-@display
+@quotation
 How do I join the help-bison and bug-bison mailing lists?
-@end display
+@end quotation
 
 See @url{http://lists.gnu.org/}.
 
@@ -10355,22 +10451,22 @@ See @url{http://lists.gnu.org/}.
 
 @deffn {Variable} @@$
 In an action, the location of the left-hand side of the rule.
-@xref{Locations, , Locations Overview}.
+@xref{Tracking Locations}.
 @end deffn
 
 @deffn {Variable} @@@var{n}
-In an action, the location of the @var{n}-th symbol of the right-hand
-side of the rule.  @xref{Locations, , Locations Overview}.
+In an action, the location of the @var{n}-th symbol of the right-hand side
+of the rule.  @xref{Tracking Locations}.
 @end deffn
 
 @deffn {Variable} @@@var{name}
-In an action, the location of a symbol addressed by name.
-@xref{Locations, , Locations Overview}.
+In an action, the location of a symbol addressed by name.  @xref{Tracking
+Locations}.
 @end deffn
 
 @deffn {Variable} @@[@var{name}]
-In an action, the location of a symbol addressed by name.
-@xref{Locations, , Locations Overview}.
+In an action, the location of a symbol addressed by name.  @xref{Tracking
+Locations}.
 @end deffn
 
 @deffn {Variable} $$