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)
 @{
-  printf ("%s\n", s);
+  fprintf (stderr, "%s\n", s);
 @}
 @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.
 
-This directive is experimental and its effect may be modified in future
-releases.
 @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
-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
@@ -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.
 
-@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
-values for @var{TYPE} are:
+values for @var{type} are:
 
 @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.
 
-@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.
-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}
@@ -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.
 
-@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)
@@ -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.
 
-@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.
-@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:
@@ -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.
+
+@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
@@ -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.
 
-This option is experimental and its effect may be modified in future
-releases.
-
 @item --locations
 Pretend that @code{%locations} was specified.  @xref{Decl Summary}.