[PATCH 4/4] doc: document carets

[Theophile Ranquet]

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

diff --git a/NEWS b/NEWS
index 2cd57c2..10dc93a 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,19 @@ GNU Bison NEWS
 
 * Noteworthy changes in release ?.? (????-??-??) [?]
 
+** New option for invoking Bison: -fcaret
+
+  Caret errors have been added to Bison, for example (taken from the
+  documentation):
+
+    err.y:4.5-8: error: invalid reference: '$foo'
+     C: {$foo{bar} };
+         ^^^^
+
+  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 5952225..ffc8ac8 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -9239,6 +9239,50 @@ 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.
+
address@hidden -f address@hidden
address@hidden address@hidden
+Activate miscellaneous @var{feature}, which can be one of:
address@hidden @code
address@hidden caret
address@hidden diagnostics-show-caret
+Show caret errors, in a manner similar to GCC's
address@hidden, 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}:
+
address@hidden
+%%
+exp : A BBBBB CC;
+B: 'char';
+C: @address@hidden@} @};
address@hidden example
+
+When invoked with @option{-fcaret}, Bison will output:
+
address@hidden
+err.y:3.4-9: warning: extra characters in character literal
+ B: 'char';
+    ^^^^^^
+err.y:2.7: error: symbol A is used, but is not defined as a token and has no 
rules
+ exp : A BBBBB CC;
+       ^
+err.y:2.9-13: error: symbol BBBBB is used, but is not defined as a token and 
has no rules
+ exp : A BBBBB CC;
+         ^^^^^
+err.y:2.15-16: error: symbol CC is used, but is not defined as a token and has 
no rules
+ exp : A BBBBB CC;
+               ^^
+err.y:4.5-8: error: invalid reference: '$foo'
+ C: @address@hidden@} @};
+     ^^^^
+err.y:4.4-15:    symbol not found in production: foo
+ C: @address@hidden@} @};
+    ^^^^^^^^^^^^
address@hidden example
+
address@hidden table
 @end table
 
 @noindent
-- 
1.8.0