From 7a0f681cb8ec40bccace0e9c8b9ed903798a5901 Mon Sep 17 00:00:00 2001
From: Akim Demaille <akim.demaille@gmail.com>
Date: Thu, 17 Jan 2019 09:10:23 +0100
Subject: [PATCH] NEWS: update for fixits and --update

---
 NEWS | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/NEWS b/NEWS
index 773dad7a..5aad16fd 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,59 @@ GNU Bison NEWS
 
 * Noteworthy changes in release ?.? (????-??-??) [?]
 
+** New features
+
+*** Generation of fix-its for IDEs/Editors
+
+  When given the new option -ffixit (aka -fdiagnostics-parseable-fixits),
+  bison now generates machine readable editing instructions to fix some
+  issues.  Currently, this is mostly limited to updating deprecated
+  directives and removing duplicates.  For instance:
+
+    $ cat foo.y
+    %error-verbose
+    %define parser_class_name "Parser"
+    %define api.parser.class "Parser"
+    %%
+    exp:;
+
+  See the "fix-it:" lines below:
+
+    $ bison -ffixit foo.y
+    foo.y:1.1-14: warning: deprecated directive, use '%define parse.error verbose' [-Wdeprecated]
+     %error-verbose
+     ^~~~~~~~~~~~~~
+    fix-it:"foo.y":{1:1-1:15}:"%define parse.error verbose"
+    foo.y:2.1-34: warning: deprecated directive, use '%define api.parser.class {Parser}' [-Wdeprecated]
+     %define parser_class_name "Parser"
+     ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    fix-it:"foo.y":{2:1-2:35}:"%define api.parser.class {Parser}"
+    foo.y:3.1-33: error: %define variable 'api.parser.class' redefined
+     %define api.parser.class "Parser"
+     ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    foo.y:2.1-34:     previous definition
+     %define parser_class_name "Parser"
+     ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    fix-it:"foo.y":{3:1-3:34}:""
+    foo.y: warning: fix-its can be applied.  Rerun with option '--update'. [-Wother]
+
+  This uses the same output format as GCC and Clang.
+
+*** Updating grammar files
+
+  Fixes can be applied on the fly.  The previous example ends with the
+  suggestion to re-run bison with the option -u/--update, which results in a
+  cleaner grammar file.
+
+    $ bison --update foo.y
+    [...]
+    bison: file 'foo.y' was updated (backup: 'foo.y~')
+
+    $ cat foo.y
+    %define parse.error verbose
+    %define api.parser.class {Parser}
+    %%
+    exp:;
 
 * Noteworthy changes in release 3.2.90 (2019-01-12) [beta]
 
@@ -12,6 +65,8 @@ GNU Bison NEWS
 
 ** Deprecated features
 
+*** Deprecated directives
+
   The %error-verbose directive is deprecated in favor of '%define
   parse.error verbose' since Bison 3.0, but no warning was issued.
 
@@ -23,6 +78,17 @@ GNU Bison NEWS
   @code{YYTOKENTYPE}, @code{yytokentype}, @code{YYSTYPE}, @code{YYLTYPE},
   etc.
 
+  Users of Flex that move from '%name-prefix "xx"' to '%define api.prefix
+  {xx}' will typically have to update YY_DECL from
+
+    #define YY_DECL int xxlex (YYSTYPE *yylval, YYLTYPE *yylloc)
+
+  to
+
+    #define YY_DECL int xxlex (XXSTYPE *yylval, XXLTYPE *yylloc)
+
+*** Deprecated %define variable names
+
   The following variables, mostly related to parsers in Java, have been
   renamed for consistency.  Backward compatibility is ensured, but upgrading
   is recommended.