diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml
index d28e75e935..071a56c5a8 100644
--- a/en_US.ISO8859-1/books/porters-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml
@@ -1536,7 +1536,11 @@ PORTEPOCH=      1</programlisting>
 	      <row>
 		<entry><filename>java</filename></entry>
 		<entry>Software related to the Java language.</entry>
-		<entry></entry>
+		<entry>The <filename>java</filename> category shall not be
+		  the only one for a port. Save for ports directly related to
+		  the Java language, porters are also encouraged not to
+		  use <filename>java</filename> as the main category of a
+		  port.</entry>
 	      </row>
 
 	      <row>
@@ -4297,7 +4301,10 @@ LDCONFIG_DIRS=  %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
 		<command>jikes</command> (by setting <literal>'no'</literal>
 		or <literal>'yes'</literal>). In the later case, <filename
 		role="package">devel/jikes</filename> will be added to build
-		dependencies of the port.</entry>
+		dependencies of the port. In any case that <command>jikes</command>
+		is actually used in place of <command>javac</command>, then the
+		<makevar>HAVE_JIKES</makevar> variable is defined by
+		<filename>bsd.java.mk</filename>.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
@@ -4435,6 +4442,11 @@ LDCONFIG_DIRS=  %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
 		JDKs used
 		<filename>${JAVA_HOME}/lib/classes.zip</filename>.</entry>
 	    </row>
+	    <row>
+	      <entry><makevar>HAVE_JIKES</makevar></entry>
+	      <entry>Defined whenever <command>jikes</command> is used by
+	        the port (see <makevar>USE_JIKES</makevar> above).</entry>
+	    </row>
 	  </tbody>
 	</tgroup>
       </table>
@@ -4469,10 +4481,40 @@ LDCONFIG_DIRS=  %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
 		Default:
 		<filename>${JAVASHAREDIR}/classes</filename>.</entry>
 	    </row>
+	    <row>
+	      <entry><makevar>JAVALIBDIR</makevar></entry>
+	      <entry>The directory where JAR files installed by other
+	        ports are located. Default:
+		<filename>${LOCALBASE}/share/java/classes</filename>.</entry>
+	    </row>
 	  </tbody>
 	</tgroup>
       </table>
 
+      <para>The related entries are defined in both
+	<makevar>PLIST_SUB</makevar> (documented in
+	<xref linkend="porting-plist">) and
+	<makevar>SUB_LIST</makevar>.</para>
+
+      </sect2>
+
+      <sect2 id="java-building-with-ant">
+	<title>Building with Ant</title>
+
+	<para>When the port is to be built using Apache Ant, it has to
+	  define <makevar>USE_ANT</makevar>. Ant is thus considered to be
+	  the sub-make command. When no <literal>do-build</literal> target
+	  is defined by the port, a default one will be set that simply
+	  runs Ant according to <makevar>MAKE_ENV</makevar>,
+	  <makevar>MAKE_ARGS</makevar> and <makevar>ALL_TARGETS</makevar>.
+	  This is similar to the <makevar>USE_GMAKE</makevar> mechanism,
+	  which is documented in <xref linkend="makefile-build">.</para>
+
+	<para>If <command>jikes</command> is used in place of
+	  <command>javac</command> (see <makevar>USE_JIKES</makevar> in
+	  <xref linkend="java-variables">), then Ant will automatically
+	  use it to build the port.</para>
+
       </sect2>
 
       <sect2 id="java-best-practices">
@@ -4487,7 +4529,7 @@ LDCONFIG_DIRS=  %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
 	  statement (where <filename>myport.jar</filename> is the name
 	  of the JAR file installed as part of the port):</para>
 
-	<programlisting>PLIST_FILES+= ${JAVAJARDIR:S,^${PREFIX}/,,}/myport.jar</programlisting>
+	<programlisting>PLIST_FILES+= %%JAVAJARDIR%%/myport.jar</programlisting>
 
 	<para>When porting a Java application, the port usually installs
 	  everything under a single directory (including its JAR
@@ -4518,8 +4560,8 @@ LDCONFIG_DIRS=  %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
 	  idea to override <makevar>DATADIR</makevar> to
 	  <filename>${JAVASHAREDIR}/${PORTNAME}</filename> for Java ports.
 	  Indeed, <makevar>DATADIR</makevar> is automatically addded to
-	  <makevar>PLIST_SUB</makevar> (documented <link
-	  linkend="porting-plist">here</link>) so you may use
+	  <makevar>PLIST_SUB</makevar> (documented in <xref
+	  linkend="porting-plist">) so you may use
 	  <literal>%%DATADIR%%</literal> directly in
 	  <filename>pkg-plist</filename>.</para>
 
@@ -4548,6 +4590,10 @@ LDCONFIG_DIRS=  %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
 	  the issue you are trying to resolve is related to either a JDK
 	  implementation or <filename>bsd.java.mk</filename>.</para>
 
+	<para>Similarly, there is a defined policy regarding the
+	  <makevar>CATEGORIES</makevar> of a Java port, which is detailed
+	  in <xref linkend="makefile-categories">.</para>
+
       </sect2>
 
     </sect1>