doc: document carets

* NEWS: Announce it.
* doc/bison.texi (Bison Options):  Here.

NEWS

@@ -7,6 +7,19 @@ GNU Bison NEWS
   The introduction of this feature, in 2.4, was four years ago. The --language
   option and the %language directive are no longer experimental.
 
+** New format for error reports: carets
+
+  Caret errors have been added to Bison, for example (taken from the
+  documentation):
+
+    input.y:3.20-23: error: ambiguous reference: '$exp'
+     exp: exp '+' exp { $exp = $1 + $2; };
+                        ^^^^
+
+  The default behaviour for now is still not to display these unless explictly
+  asked with -fall of -fcaret. However, in a later release, it will be made the
+  default behavior (but may still be deactivated with -fno-caret).
+
 ** New value for %define variable: api.pure full
 
   The %define variable api.pure requests a pure (reentrant) parser. However,

doc/bison.texi

@@ -9239,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