From 4a690d3d19acea8792300834ad453d69a1d76a74 Mon Sep 17 00:00:00 2001
From: Akim Demaille <akim.demaille@gmail.com>
Date: Thu, 17 Jan 2019 19:53:14 +0100
Subject: [PATCH] doc: document -ffixit and --update

* doc/bison.texi (Bison Options): here.
---
 doc/bison.texi | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)

diff --git a/doc/bison.texi b/doc/bison.texi
index 775a99a6..c31e851b 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -10269,6 +10269,43 @@ Print the name of the directory containing locale-dependent data.
 @item --print-datadir
 Print the name of the directory containing skeletons and XSLT.
 
+@item -u
+@item --update
+Update the grammar file (remove duplicates, update deprecated directives,
+etc.).  Leaves a backup of the original file with a @code{~} appended.  For
+instance:
+
+@example
+@group
+$ @kbd{cat foo.y}
+%error-verbose
+%define parse.error verbose
+%%
+exp:;
+@end group
+@group
+$ @kbd{bison -u foo.y}
+foo.y:1.1-14: warning: deprecated directive, use '%define parse.error verbose' [-Wdeprecated]
+ %error-verbose
+ ^~~~~~~~~~~~~~
+foo.y:2.1-27: error: %define variable 'parse.error' redefined
+ %define parse.error verbose
+ ^~~~~~~~~~~~~~~~~~~~~~~~~~~
+foo.y:1.1-14:     previous definition
+ %error-verbose
+ ^~~~~~~~~~~~~~
+bison: file 'foo.y' was updated (backup: 'foo.y~')
+@end group
+@group
+$ @kbd{cat foo.y}
+%define parse.error verbose
+%%
+exp:;
+@end group
+@end example
+
+See the documentation of @option{--feature=fixit} below for more details.
+
 @item -y
 @itemx --yacc
 Act more like the traditional Yacc command.  This can cause different
@@ -10509,6 +10546,61 @@ in.y:3.32-33: error: $2 of ‘exp’ has no declared type
 
 This option is activated by default.
 
+@item fixit
+@itemx diagnostics-parseable-fixits
+Show machine-readable fixes, in a manner similar to GCC's and Clang's
+@option{-fdiagnostics-parseable-fixits}.
+
+Fix-its are generated for duplicate directives:
+
+@example
+@group
+$ @kbd{cat foo.y}
+%define api.prefix @{foo@}
+%define api.prefix @{bar@}
+%%
+exp:;
+@end group
+
+@group
+$ @kbd{bison -ffixit foo.y}
+foo.y:2.1-24: error: %define variable 'api.prefix' redefined
+ %define api.prefix @{bar@}
+ ^~~~~~~~~~~~~~~~~~~~~~~~
+foo.y:1.1-24:     previous definition
+ %define api.prefix @{foo@}
+ ^~~~~~~~~~~~~~~~~~~~~~~~
+fix-it:"foo.y":@{2:1-2:25@}:""
+foo.y: warning: fix-its can be applied.  Rerun with option '--update'. [-Wother]
+@end group
+@end example
+
+They are also generated to update deprecated directives, unless
+@option{-Wno-deprecated} was given:
+
+@example
+@group
+$ @kbd{cat /tmp/foo.yy}
+%error-verbose
+%name-prefix "foo"
+%%
+exp:;
+@end group
+@group
+$ @kbd{bison foo.y}
+foo.y:1.1-14: warning: deprecated directive, use '%define parse.error verbose' [-Wdeprecated]
+ %error-verbose
+ ^~~~~~~~~~~~~~
+foo.y:2.1-18: warning: deprecated directive, use '%define api.prefix @{foo@}' [-Wdeprecated]
+ %name-prefix "foo"
+ ^~~~~~~~~~~~~~~~~~
+foo.y: warning: fix-its can be applied.  Rerun with option '--update'. [-Wother]
+@end group
+@end example
+
+The fix-its are applied by @command{bison} itself when given the option
+@option{-u}/@option{--update}.  See its documentation above.
+
 @end table
 @end table