maint: news: condemn YYPARSE_PARAM and YYLEX_PARAM

[Akim Demaille]

Will install in maint if there is no resistance.

From 188942118aade04d39197afb1fea062d2dd8c773 Mon Sep 17 00:00:00 2001
From: Akim Demaille <address@hidden>
Date: Sun, 17 Jun 2012 10:54:15 +0200
Subject: [PATCH] news: condemn YYPARSE_PARAM and YYLEX_PARAM.

* NEWS: here.
(Bison 1.875): Add %parse-param and %lex-param.
* doc/bison.texinfo: Spello.
---
 NEWS              |   30 +++++++++++++++++++++++++++++-
 doc/bison.texinfo |    2 +-
 2 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/NEWS b/NEWS
index ae8b297..553c6c8 100644
--- a/NEWS
+++ b/NEWS
@@ -6,7 +6,8 @@ GNU Bison NEWS
 
   The next major release will drop support for generating parsers in K&R C,
   and remove the definition of yystype (removal announced since Bison
-  1.875).
+  1.875).  YYPARSE_PARAM and YYLEX_PARAM, which were deprecated in favor of
+  %parse-param (introduced in Bison 1.875 too), will no longer be supported.
 
 ** The generated header is included (yacc.c)
 
@@ -1202,6 +1203,33 @@ GNU Bison NEWS
   - "parsing stack overflow..." -> "parser stack overflow"
     GLR parsers now report "parser stack overflow" as per the Bison manual.
 
+** %parse-param and %lex-param
+  The macros YYPARSE_PARAM and YYLEX_PARAM provide a means to pass
+  additional context to yyparse and yylex.  They suffer from several
+  shortcomings:
+
+  - a single argument only can be added,
+  - their types are weak (void *),
+  - this context is not passed to anciliary functions such as yyerror,
+  - only yacc.c parsers support them.
+
+  The new %parse-param/%lex-param directives provide a more precise control.
+  For instance:
+
+    %parse-param {int *nastiness}
+    %lex-param   {int *nastiness}
+    %parse-param {int *randomness}
+
+  results in the following signatures:
+
+    int yylex   (int *nastiness);
+    int yyparse (int *nastiness, int *randomness);
+
+  or, if both %pure-parser and %locations are used:
+
+    int yylex   (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);
+    int yyparse (int *nastiness, int *randomness);
+
 ** Bison now warns if it detects conflicting outputs to the same file,
   e.g., it generates a warning for "bison -d -o foo.h foo.y" since
   that command outputs both code and header to foo.h.
diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 97b3273..4f2e1c6 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -6011,7 +6011,7 @@ For instance:
 @end example
 
 @noindent
-results in the following signature:
+results in the following signatures:
 
 @example
 int yylex   (int *nastiness);
-- 
1.7.10.4