YYFAIL: deprecate.

* NEWS (2.4.2): Document deprecation and the phase-out plan.
* data/lalr1.java (parser::YYStack::YYFAIL): Add comment about
deprecation.
* data/yacc.c (YYFAIL): Likewise, and suppress warnings about
YYFAIL from GCC cpp's -Wunused-macros.
* doc/bison.texinfo (Java Action Features): Remove YYFAIL
documentation.
(LocalWords): Remove YYFAIL.

data/lalr1.java

@@ -352,7 +352,8 @@ b4_lexer_if([[
 
   /**
    * Returned by a Bison action in order to print an error message and start
-   * error recovery.  */
+   * error recovery.  Formally deprecated in Bison 2.4.2's NEWS entry, where
+   * a plan to phase it out is discussed.  */
   public static final int YYFAIL = 3;
 
   private static final int YYNEWSTATE = 4;

data/yacc.c

@@ -609,9 +609,18 @@ static const ]b4_int_type_for([b4_toknum])[ yytoknum[] =
 
 /* Like YYERROR except do call yyerror.  This remains here temporarily
    to ease the transition to the new meaning of YYERROR, for GCC.
-   Once GCC version 2 has supplanted version 1, this can go.  */
+   Once GCC version 2 has supplanted version 1, this can go.  However,
+   YYFAIL appears to be in use.  Nevertheless, it is formally deprecated
+   in Bison 2.4.2's NEWS entry, where a plan to phase it out is
+   discussed.  */
 
 #define YYFAIL		goto yyerrlab
+#if defined YYFAIL
+  /* This is here to suppress warnings from the GCC cpp's
+     -Wunused-macros.  Normally we don't worry about that warning, but
+     some users do, and we want to make it easy for users to remove
+     YYFAIL uses, which will produce warnings from Bison 2.5.  */
+#endif
 
 #define YYRECOVERING()  (!!yyerrstatus)