doc: document -ffixit and --update

[Akim Demaille]

commit 4a690d3d19acea8792300834ad453d69a1d76a74
Author: Akim Demaille <address@hidden>
Date:   Thu Jan 17 19:53:14 2019 +0100

    doc: document -ffixit and --update
    
    * doc/bison.texi (Bison Options): here.

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.
 
address@hidden -u
address@hidden --update
+Update the grammar file (remove duplicates, update deprecated directives,
+etc.).  Leaves a backup of the original file with a @code{~} appended.  For
+instance:
+
address@hidden
address@hidden
+$ @kbd{cat foo.y}
+%error-verbose
+%define parse.error verbose
+%%
+exp:;
address@hidden group
address@hidden
+$ @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~')
address@hidden group
address@hidden
+$ @kbd{cat foo.y}
+%define parse.error verbose
+%%
+exp:;
address@hidden group
address@hidden 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.
 
address@hidden fixit
address@hidden diagnostics-parseable-fixits
+Show machine-readable fixes, in a manner similar to GCC's and Clang's
address@hidden
+
+Fix-its are generated for duplicate directives:
+
address@hidden
address@hidden
+$ @kbd{cat foo.y}
+%define api.prefix @address@hidden
+%define api.prefix @address@hidden
+%%
+exp:;
address@hidden group
+
address@hidden
+$ @kbd{bison -ffixit foo.y}
+foo.y:2.1-24: error: %define variable 'api.prefix' redefined
+ %define api.prefix @address@hidden
+ ^~~~~~~~~~~~~~~~~~~~~~~~
+foo.y:1.1-24:     previous definition
+ %define api.prefix @address@hidden
+ ^~~~~~~~~~~~~~~~~~~~~~~~
+fix-it:"foo.y":@{2:1-2:address@hidden:""
+foo.y: warning: fix-its can be applied.  Rerun with option '--update'. 
[-Wother]
address@hidden group
address@hidden example
+
+They are also generated to update deprecated directives, unless
address@hidden was given:
+
address@hidden
address@hidden
+$ @kbd{cat /tmp/foo.yy}
+%error-verbose
+%name-prefix "foo"
+%%
+exp:;
address@hidden group
address@hidden
+$ @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 
@address@hidden' [-Wdeprecated]
+ %name-prefix "foo"
+ ^~~~~~~~~~~~~~~~~~
+foo.y: warning: fix-its can be applied.  Rerun with option '--update'. 
[-Wother]
address@hidden group
address@hidden example
+
+The fix-its are applied by @command{bison} itself when given the option
address@hidden/@option{--update}.  See its documentation above.
+
 @end table
 @end table