[FYI 2/2] {maint} docs: deprecate JAVA primary

[Stefano Lattarini]

* doc/automake.texi (Java): Deprecate the JAVA primary, stating
that it will become obsolete in automake 1.12 and probably removed
altogether in automake 1.13.  Reflect this in the section title,
by appending the string "(deprecated feature)".
(@menu, @detailmenu): Update.
(Java Support with gcj): The cross-referenced support for bytecode
compilation with the JAVA primary is rudimentary and deprecated.
State that explicitly.
---
 ChangeLog         |   12 ++++++++++++
 doc/automake.texi |   17 +++++++++++------
 2 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 74accb7..aec00f4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,17 @@
 2011-09-19  Stefano Lattarini  <address@hidden>
 
+       docs: deprecate JAVA primary
+       * doc/automake.texi (Java): Deprecate the JAVA primary, stating
+       that it will become obsolete in automake 1.12 and probably removed
+       altogether in automake 1.13.  Reflect this in the section title,
+       by appending the string "(deprecated feature)".
+       (@menu, @detailmenu): Update.
+       (Java Support with gcj): The cross-referenced support for bytecode
+       compilation with the JAVA primary is rudimentary and deprecated.
+       State that explicitly.
+
+2011-09-19  Stefano Lattarini  <address@hidden>
+
        docs: clearer distinction between `.java' with javac and with gcj
        * doc/automake.texi (Java support): Rename this node ...
        (Java support with gcj): ... to this, and change its title from
diff --git a/doc/automake.texi b/doc/automake.texi
index 4c5b9f8..7897391 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -291,7 +291,7 @@ Other GNU Tools
 * Emacs Lisp::                  Emacs Lisp
 * gettext::                     Gettext
 * Libtool::                     Libtool
-* Java::                        Java bytecode compilation
+* Java::                        Java bytecode compilation (deprecated)
 * Python::                      Python
 
 Building documentation
@@ -6698,9 +6698,9 @@ is as follows:
 @cindex Compilation of Java to native code
 
 Automake includes support for natively compiled Java, using @command{gcj},
-the Java front end to the GNU Compiler Collection (preliminary support
+the Java front end to the GNU Compiler Collection (rudimentary support
 for compiling Java to bytecode using the @command{javac} compiler is
-also present; @pxref{Java}).
+also present, @emph{albeit deprecated}; @pxref{Java}).
 
 Any package including Java code to be compiled must define the output
 variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
@@ -7470,7 +7470,7 @@ use in GNU programs, it tries hard to interoperate with 
other GNU tools.
 * Emacs Lisp::                  Emacs Lisp
 * gettext::                     Gettext
 * Libtool::                     Libtool
-* Java::                        Java bytecode compilation
+* Java::                        Java bytecode compilation (deprecated)
 * Python::                      Python
 @end menu
 
@@ -7563,7 +7563,7 @@ libtool, The Libtool Manual}) with the @code{LTLIBRARIES} 
primary.
 
 
 @node Java
address@hidden Java bytecode compilation
address@hidden Java bytecode compilation (deprecated)
 
 @cindex @code{_JAVA} primary, defined
 @cindex @code{JAVA} primary, defined
@@ -7573,7 +7573,12 @@ libtool, The Libtool Manual}) with the 
@code{LTLIBRARIES} primary.
 
 Automake provides some minimal support for Java bytecode compilation with
 the @code{JAVA} primary (in addition to the support for compiling Java to
-native machine code; @pxref{Java Support with gcj}).
+native machine code; @pxref{Java Support with gcj}).  Note however that
address@hidden interface and most features described here are deprecated}; the
+next automake release will strive to provide a better and cleaner
+interface, which however @emph{won't be backward-compatible}; the present
+interface will probably be removed altogether in future automake releases
+(1.13 or later), so don't use it in new code.
 
 Any @file{.java} files listed in a @code{_JAVA} variable will be
 compiled with @code{JAVAC} at build time.  By default, @file{.java}
-- 
1.7.2.3