From 7bada5355e10f560269825cbd658caaa473573f7 Mon Sep 17 00:00:00 2001
From: Theophile Ranquet <ranquet@lrde.epita.fr>
Date: Tue, 4 Dec 2012 13:12:12 +0100
Subject: [PATCH] doc: document carets

* NEWS: Announce it.
* doc/bison.texi (Bison Options):  Here.
---
 NEWS           | 13 +++++++++++++
 doc/bison.texi | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+)

diff --git a/NEWS b/NEWS
index 93a1ef54..0c3d025e 100644
--- a/NEWS
+++ b/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,
diff --git a/doc/bison.texi b/doc/bison.texi
index 5952225c..06af0884 100644
--- a/doc/bison.texi
+++ b/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
-- 
2.47.2