doc: clearly deprecate YYPRINT

* doc/bison.texi (Prologue): Stop using YYPRINT as an example.
(The YYPRINT Macro): Clearly show this macro is deprecated.

NEWS

@@ -2,6 +2,12 @@ GNU Bison NEWS
 
 * Noteworthy changes in release ?.? (????-??-??) [?]
 
+** Deprecated features
+
+  The YYPRINT macro, which works only with yacc.c and only for tokens, was
+  obsoleted long ago by %printer, introduced in Bison 1.50 (November 2002).
+  It is deprecated and its support will be removed eventually.
+
 ** New Features
 
 *** A skeleton for the D programming language

TODO

@@ -1,7 +1,4 @@
 * Bison 3.5
-** Deprecate YYPRINT
-The doc shows it too much.
-
 ** doc
 I feel its ugly to use the GNU style to declare functions in the doc.  It
 generates tons of white space in the page, and may contribute to bad page

doc/bison.texi

@@ -2935,8 +2935,7 @@ declaration.
 
 @group
 %@{
-  static void print_token_value (FILE *, int, YYSTYPE);
+  static void print_token (enum yytokentype token, YYSTYPE val);
-  #define YYPRINT(F, N, L) print_token_value (F, N, L)
 %@}
 @end group
 
@@ -2985,8 +2984,7 @@ Look again at the example of the previous section:
 
 @group
 %@{
-  static void print_token_value (FILE *, int, YYSTYPE);
+  static void print_token (enum yytokentype token, YYSTYPE val);
-  #define YYPRINT(F, N, L) print_token_value (F, N, L)
 %@}
 @end group
 
@@ -3048,8 +3046,7 @@ the same time:
 
 @group
 %code @{
-  static void print_token_value (FILE *, int, YYSTYPE);
+  static void print_token (enum yytokentype token, YYSTYPE val);
-  #define YYPRINT(F, N, L) print_token_value (F, N, L)
   static void trace_token (enum yytokentype token, YYLTYPE loc);
 @}
 @end group
@@ -3114,8 +3111,7 @@ Thus, they belong in one or more @code{%code requires}:
 
 @group
 %code @{
-  static void print_token_value (FILE *, int, YYSTYPE);
+  static void print_token (enum yytokentype token, YYSTYPE val);
-  #define YYPRINT(F, N, L) print_token_value (F, N, L)
   static void trace_token (enum yytokentype token, YYLTYPE loc);
 @}
 @end group
@@ -3194,8 +3190,7 @@ unqualified @code{%code} to a @code{%code provides}:
 
 @group
 %code @{
-  static void print_token_value (FILE *, int, YYSTYPE);
+  static void print_token (FILE *file, int token, YYSTYPE val);
-  #define YYPRINT(F, N, L) print_token_value (F, N, L)
 @}
 @end group
 
@@ -10069,9 +10064,7 @@ of variables show where in the grammar it is working.
 The debugging information normally gives the token type of each token read,
 but not its semantic value.  The @code{%printer} directive allows specify
 how semantic values are reported, see @ref{Printer Decl, , Printing
-Semantic Values}.  For backward compatibility, Yacc like C parsers may also
+Semantic Values}.
-use the @code{YYPRINT} (@pxref{The YYPRINT Macro, , The @code{YYPRINT}
-Macro}), but its use is discouraged.
 
 As a demonstration of @code{%printer}, consider the multi-function
 calculator, @code{mfcalc} (@pxref{Multi-function Calc}).  To enable run-time
@@ -10234,14 +10227,16 @@ Cleanup: popping nterm input ()
 
 @node The YYPRINT Macro
 @subsection The @code{YYPRINT} Macro
-
 @findex YYPRINT
-Before @code{%printer} support, semantic values could be displayed using the
+
-@code{YYPRINT} macro, which works only for terminal symbols and only with
+The @code{%printer} directive was introduced in Bison 1.50 (Novembre 2002).
-the @file{yacc.c} skeleton.
+Before then, @code{YYPRINT} provided a similar feature, but only for
+terminal symbols and only with the @file{yacc.c} skeleton.
 
 @deffn {Macro} YYPRINT (@var{stream}, @var{token}, @var{value});
 @findex YYPRINT
+Deprecated, will be removed eventually.
+
 If you define @code{YYPRINT}, it should take three arguments.  The parser
 will pass a standard I/O stream, the numeric code for the token type, and
 the token value (from @code{yylval}).
@@ -10254,7 +10249,7 @@ calculator (@pxref{Mfcalc Declarations, ,Declarations for @code{mfcalc}}):
 
 @example
 %@{
-  static void print_token_value (FILE *, int, YYSTYPE);
+  static void print_token_value (FILE *file, int type, YYSTYPE value);
   #define YYPRINT(File, Type, Value)            \
     print_token_value (File, Type, Value)
 %@}
@@ -10271,6 +10266,9 @@ print_token_value (FILE *file, int type, YYSTYPE value)
 @}
 @end example
 
+@xref{Mfcalc Traces, ,Enabling Debug Traces for @code{mfcalc}}, for the
+proper use of @code{%printer}.
+
 @c ================================================= Invoking Bison
 
 @node Invocation
@@ -14232,7 +14230,8 @@ parsing.  @xref{Parser Function, ,The Parser Function @code{yyparse}}.
 
 @deffn {Macro} YYPRINT
 Macro used to output token semantic values.  For @file{yacc.c} only.
-Obsoleted by @code{%printer}.
+Deprecated, use @code{%printer} instead (@pxref{Printer Decl, , Printing
+Semantic Values}).
 @xref{The YYPRINT Macro, , The @code{YYPRINT} Macro}.
 @end deffn