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.

diff --git a/ChangeLog b/ChangeLog
index 74accb77072d4c9ad40d4a22ab26ba5ef6504b14..aec00f4370659af6de02931c2d693a1baee34f49 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2011-09-19  Stefano Lattarini  <stefano.lattarini@gmail.com>
+
+       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  <stefano.lattarini@gmail.com>
 
        docs: clearer distinction between `.java' with javac and with gcj

diff --git a/doc/automake.texi b/doc/automake.texi
index 4c5b9f8a7b2c18e81f8a787537f0e41a42109aee..7897391980680f834908759f9e47dac0a120a626 100644 (file)
--- 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
-@section Java bytecode compilation
+@section 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
+@emph{the 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}