gnulib: update

[bison.git] / doc / bison.texi

diff --git a/doc/bison.texi b/doc/bison.texi
index 21ce3929f2c2f0d6f2bb7eaadf0fdce680963662..06af0884350e6b775cdb87fc19fd8502d25dc3af 100644 (file)
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -2452,7 +2452,7 @@ function that initializes the symbol table.  Here it is, and
 void
 yyerror (char const *s)
 @{
 void
 yyerror (char const *s)
 @{

-  printf ("%s\n", s);
+  fprintf (stderr, "%s\n", s);

 @}
 @end group
 
 @}
 @end group
 


@@ -5170,8 +5170,6 @@ Specify the programming language for the generated parser.  Currently
 supported languages include C, C++, and Java.
 @var{language} is case-insensitive.
 
 supported languages include C, C++, and Java.
 @var{language} is case-insensitive.
 

-This directive is experimental and its effect may be modified in future
-releases.

 @end deffn
 
 @deffn {Directive} %locations
 @end deffn
 
 @deffn {Directive} %locations


@@ -5379,8 +5377,9 @@ The value may be omitted: this is equivalent to specifying @code{true}, as is
 the case for Boolean values.
 
 When @code{%define api.pure full} is used, the parser is made reentrant. This
 the case for Boolean values.
 
 When @code{%define api.pure full} is used, the parser is made reentrant. This

-changes the signature for yylex (@pxref{Pure Calling}), and also that of
-yyerror when the tracking of locations has been activated, as shown below.
+changes the signature for @code{yylex} (@pxref{Pure Calling}), and also that of
+@code{yyerror} when the tracking of locations has been activated, as shown
+below.

 
 The @code{true} value is very similar to the @code{full} value, the only
 difference is in the signature of @code{yyerror} on Yacc parsers without
 
 The @code{true} value is very similar to the @code{full} value, the only
 difference is in the signature of @code{yyerror} on Yacc parsers without


@@ -7363,9 +7362,9 @@ mysterious behavior altogether.  You simply need to activate a more powerful
 parser table construction algorithm by using the @code{%define lr.type}
 directive.
 
 parser table construction algorithm by using the @code{%define lr.type}
 directive.
 

-@deffn {Directive} {%define lr.type} @var{TYPE}
+@deffn {Directive} {%define lr.type} @var{type}

 Specify the type of parser tables within the LR(1) family.  The accepted
 Specify the type of parser tables within the LR(1) family.  The accepted

-values for @var{TYPE} are:
+values for @var{type} are:

 
 @itemize
 @item @code{lalr} (default)
 
 @itemize
 @item @code{lalr} (default)


@@ -7552,9 +7551,9 @@ split the parse instead.
 To adjust which states have default reductions enabled, use the
 @code{%define lr.default-reductions} directive.
 
 To adjust which states have default reductions enabled, use the
 @code{%define lr.default-reductions} directive.
 

-@deffn {Directive} {%define lr.default-reductions} @var{WHERE}
+@deffn {Directive} {%define lr.default-reductions} @var{where}

 Specify the kind of states that are permitted to contain default reductions.
 Specify the kind of states that are permitted to contain default reductions.

-The accepted values of @var{WHERE} are:
+The accepted values of @var{where} are:

 @itemize
 @item @code{most} (default for LALR and IELR)
 @item @code{consistent}
 @itemize
 @item @code{most} (default for LALR and IELR)
 @item @code{consistent}


@@ -7592,7 +7591,7 @@ that solves these problems for canonical LR, IELR, and LALR without
 sacrificing @code{%nonassoc}, default reductions, or state merging.  You can
 enable LAC with the @code{%define parse.lac} directive.
 
 sacrificing @code{%nonassoc}, default reductions, or state merging.  You can
 enable LAC with the @code{%define parse.lac} directive.
 

-@deffn {Directive} {%define parse.lac} @var{VALUE}
+@deffn {Directive} {%define parse.lac} @var{value}

 Enable LAC to improve syntax error handling.
 @itemize
 @item @code{none} (default)
 Enable LAC to improve syntax error handling.
 @itemize
 @item @code{none} (default)


@@ -7688,9 +7687,9 @@ resolution because they are useless in the generated parser.  However,
 keeping unreachable states is sometimes useful when trying to understand the
 relationship between the parser and the grammar.
 
 keeping unreachable states is sometimes useful when trying to understand the
 relationship between the parser and the grammar.
 

-@deffn {Directive} {%define lr.keep-unreachable-states} @var{VALUE}
+@deffn {Directive} {%define lr.keep-unreachable-states} @var{value}

 Request that Bison allow unreachable states to remain in the parser tables.
 Request that Bison allow unreachable states to remain in the parser tables.

-@var{VALUE} must be a Boolean.  The default is @code{false}.
+@var{value} must be a Boolean.  The default is @code{false}.

 @end deffn
 
 There are a few caveats to consider:
 @end deffn
 
 There are a few caveats to consider:


@@ -9240,6 +9239,56 @@ Treat warnings as errors.
 A category can be turned off by prefixing its name with @samp{no-}.  For
 instance, @option{-Wno-yacc} will hide the warnings about
 POSIX Yacc incompatibilities.
 A category can be turned off by prefixing its name with @samp{no-}.  For
 instance, @option{-Wno-yacc} will hide the warnings about
 POSIX Yacc incompatibilities.

+
+@item -f [@var{feature}]
+@itemx --feature[=@var{feature}]
+Activate miscellaneous @var{feature}. @var{feature} can be one of:
+@table @code
+@item caret
+@itemx diagnostics-show-caret
+Show caret errors, in a manner similar to GCC's
+@option{-fdiagnostics-show-caret}, or Clang's @option{-fcaret-diagnotics}. The
+location provided with the message is used to quote the corresponding line of
+the source file, underlining the important part of it with carets (^). Here is
+an example, using the following file @file{input.y}:
+
+@example
+%type <ival> exp
+%%
+exp: exp '+' exp @{ $exp = $1 + $2; @};
+@end example
+
+When invoked with @option{-fcaret}, Bison will report:
+
+@example
+@group
+input.y:3.20-23: error: ambiguous reference: '$exp'
+ exp: exp '+' exp @{ $exp = $1 + $2; @};
+                    ^^^^
+@end group
+@group
+input.y:3.1-3:       refers to: $exp at $$
+ exp: exp '+' exp @{ $exp = $1 + $2; @};
+ ^^^
+@end group
+@group
+input.y:3.6-8:       refers to: $exp at $1
+ exp: exp '+' exp @{ $exp = $1 + $2; @};
+      ^^^
+@end group
+@group
+input.y:3.14-16:     refers to: $exp at $3
+ exp: exp '+' exp @{ $exp = $1 + $2; @};
+              ^^^
+@end group
+@group
+input.y:3.32-33: error: $2 of 'exp' has no declared type
+ exp: exp '+' exp @{ $exp = $1 + $2; @};
+                                ^^
+@end group
+@end example
+
+@end table

 @end table
 
 @noindent
 @end table
 
 @noindent


@@ -9288,9 +9337,6 @@ Specify the programming language for the generated parser, as if
 Summary}).  Currently supported languages include C, C++, and Java.
 @var{language} is case-insensitive.
 
 Summary}).  Currently supported languages include C, C++, and Java.
 @var{language} is case-insensitive.
 

-This option is experimental and its effect may be modified in future
-releases.
-

 @item --locations
 Pretend that @code{%locations} was specified.  @xref{Decl Summary}.
 
 @item --locations
 Pretend that @code{%locations} was specified.  @xref{Decl Summary}.