[PATCH 3/3] doc: introduce api.pure full, rearrange some examples

[Theophile Ranquet]

* NEWS: Add entry.
* doc/bison.texi (%define Summary): Show the old Yacc behaviour.
(Parser Function): Move parse-param examples here.
(Pure Calling): Remove parse-param examples.
(Error Reporting): Don't show the old behavior, stick to 'full'.
---
 NEWS           |  11 +++++
 doc/bison.texi | 125 ++++++++++++++++++++++++++++++---------------------------
 2 files changed, 77 insertions(+), 59 deletions(-)

diff --git a/NEWS b/NEWS
index 3789e92..e7883c6 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,17 @@ GNU Bison NEWS
 
 * Noteworthy changes in release ?.? (????-??-??) [?]
 
+** New value for %define variable: api.pure full
+
+  The %define variable api.pure requests a pure (reentrant) parser. However,
+  for historical reasons, using it in a location-tracking Yacc parser resulted
+  in an yyerror function that did not take a location as a parameter. With this
+  new value, the user may request a better pure parser, where yyerror does take
+  a location as a parameter (in location-tracking parsers).
+
+  The use of "%define api.pure true" should be deprecated in favor of this new
+  "%define api.pure full".
+
 ** Changes in the format of error messages
 
   This used to be the format of many error reports:
diff --git a/doc/bison.texi b/doc/bison.texi
index f2d3dbc..373f738 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -4885,7 +4885,7 @@ declaration @code{%define api.pure} says that you want 
the parser to be
 reentrant.  It looks like this:
 
 @example
-%define api.pure
+%define api.pure full
 @end example
 
 The result is that the communication variables @code{yylval} and
@@ -5008,8 +5008,8 @@ yypull_parse (ps); /* Will call the lexer */
 yypstate_delete (ps);
 @end example
 
-Adding the @code{%define api.pure} declaration does exactly the same thing to
-the generated parser with @code{%define api.push-pull both} as it did for
+Adding the @code{%define api.pure full} declaration does exactly the same thing
+to the generated parser with @code{%define api.push-pull both} as it did for
 @code{%define api.push-pull push}.
 
 @node Decl Summary
@@ -5373,9 +5373,39 @@ Some of the accepted @var{variable}s are:
 @item Purpose: Request a pure (reentrant) parser program.
 @xref{Pure Decl, ,A Pure (Reentrant) Parser}.
 
address@hidden Accepted Values: Boolean
address@hidden Accepted Values: @code{true}, @code{false}, @code{full}
+
+The value may be omitted: this is equivalent to specifying @code{true}, as is
+the case for Boolean values.
+
+Note: the @code{full} value is very similar to the @code{true} value, the only
+difference is in the signature of @code{yyerror} on Yacc parsers without
address@hidden, for historical reasons.
+
+I.e., if @samp{%locations %define api.pure} is passed then the prototypes for
address@hidden are:
+
address@hidden
+void yyerror (char const *msg);                 /* Yacc parsers.  */
+void yyerror (YYLTYPE *locp, char const *msg);  /* GLR parsers.  */
address@hidden example
+
+But if @samp{%locations %define api.pure %parse-param @{int address@hidden is
+used, then both parsers have the same signature:
+
address@hidden
+void yyerror (YYLTYPE *llocp, int *nastiness, char const *msg);
address@hidden example
+
+However, this is a deprecated work-around, prefer using @code{%define api.pure
+full}.
+
+(@pxref{Error Reporting, ,The Error
+Reporting Function @code{yyerror}})
 
 @item Default Value: @code{false}
+
address@hidden History: the @code{full} value was introduced in Bison 2.7
 @end itemize
 
 @c ================================================== api.push-pull
@@ -5820,6 +5850,27 @@ In the grammar actions, use expressions like this to 
refer to the data:
 exp: @dots{}    @{ @dots{}; *randomness += 1; @dots{} @}
 @end example
 
address@hidden
+Using the following:
address@hidden
+%parse-param @{int address@hidden
address@hidden example
+
+Results in these signatures:
address@hidden
+void yyerror (int *randomness, const char *msg);
+int  yyparse (int *randomness);
address@hidden example
+
address@hidden
+Or, if both @code{%define api.pure full} (or just @code{%define api.pure})
+and @code{%locations} are used:
+
address@hidden
+void yyerror (YYLTYPE *llocp, int *randomness, const char *msg);
+int  yyparse (int *randomness);
address@hidden example
+
 @node Push Parser Function
 @section The Push Parser Function @code{yypush_parse}
 @findex yypush_parse
@@ -6106,35 +6157,25 @@ Declare that the braced-code @var{argument-declaration} 
is an
 additional @code{yylex} argument declaration.
 @end deffn
 
address@hidden
 For instance:
 
 @example
-%parse-param @{int address@hidden
 %lex-param   @{int address@hidden
-%parse-param @{int address@hidden
 @end example
 
 @noindent
-results in the following signatures:
+results in the following signature:
 
 @example
 int yylex   (int *nastiness);
-int yyparse (int *nastiness, int *randomness);
address@hidden example
-
-If @code{%define api.pure} is added:
-
address@hidden
-int yylex   (YYSTYPE *lvalp, int *nastiness);
-int yyparse (int *nastiness, int *randomness);
 @end example
 
 @noindent
-and finally, if both @code{%define api.pure} and @code{%locations} are used:
+If @code{%define api.pure} (or @code{%define api.pure full}) is added:
 
 @example
-int yylex   (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);
-int yyparse (int *nastiness, int *randomness);
+int yylex   (YYSTYPE *lvalp, int *nastiness);
 @end example
 
 @node Error Reporting
@@ -6194,50 +6235,16 @@ error recovery if you have written suitable error 
recovery grammar rules
 immediately return 1.
 
 Obviously, in location tracking pure parsers, @code{yyerror} should have
-an access to the current location.
-This is indeed the case for the GLR
-parsers, but not for the Yacc parser, for historical reasons.  I.e., if
address@hidden %define api.pure} is passed then the prototypes for
address@hidden are:
-
address@hidden
-void yyerror (char const *msg);                 /* Yacc parsers.  */
-void yyerror (YYLTYPE *locp, char const *msg);  /* GLR parsers.   */
address@hidden example
+an access to the current location. With @code{%define api.pure}, this is
+indeed the case for the GLR parsers, but not for the Yacc parser, for
+historical reasons, and this is the why @code{%define api.pure full} should be
+prefered over @code{%define api.pure}.
 
-If @samp{%parse-param @{int address@hidden is used, then:
-
address@hidden
-void yyerror (int *nastiness, char const *msg);  /* Yacc parsers.  */
-void yyerror (int *nastiness, char const *msg);  /* GLR parsers.   */
address@hidden example
-
-Finally, GLR and Yacc parsers share the same @code{yyerror} calling
-convention for absolutely pure parsers, i.e., when the calling
-convention of @code{yylex} @emph{and} the calling convention of
address@hidden api.pure} are pure.
-I.e.:
-
address@hidden
-/* Location tracking.  */
-%locations
-/* Pure yylex.  */
-%define api.pure
-%lex-param   @{int address@hidden
-/* Pure yyparse.  */
-%parse-param @{int address@hidden
-%parse-param @{int address@hidden
address@hidden example
-
address@hidden
-results in the following signatures for all the parser kinds:
+When @code{%locations %define api.pure full} is used, @code{yyerror} has the
+following signature:
 
 @example
-int yylex (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);
-int yyparse (int *nastiness, int *randomness);
-void yyerror (YYLTYPE *locp,
-              int *nastiness, int *randomness,
-              char const *msg);
+void yyerror (YYLTYPE *locp, char const *msg);
 @end example
 
 @noindent
-- 
1.8.0