1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/common/makefiles/javadoc/Notes.html Tue Sep 18 11:29:16 2012 -0700 1.3 @@ -0,0 +1,49 @@ 1.4 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 1.5 +<html> 1.6 +<head> 1.7 +<title>Doc Process Notes</title> 1.8 +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 1.9 +</head> 1.10 + 1.11 +<body> 1.12 +<h3><a name="REGEXP"></a><br> 1.13 +REGEXP</h3> 1.14 +<p> REGEXP is a list of wildcard patterns that determines which packages listed 1.15 + in CORE_PKGS.gmk go into which summary-table on the main API index page. It 1.16 + was motivated by the need to divide the world into "core packages" 1.17 + (java.*) and "extension packages" (javax.*). In time, the distinction 1.18 + went away. The whole table is now called "Platform Packages"--which 1.19 + eliminated the need for this list of regular expressions. But it lingered on, 1.20 + accreting all of the packages in the JVM, one by one. I pruned it back to "*", 1.21 + so it now covers every package in the Java platform API docs. If some separation 1.22 + is needed in the future, it can grow back into a colon-separated list, starting 1.23 + with this, which is in all respects equivalent to "*" at this point 1.24 + in time:</p> 1.25 +<blockquote> 1.26 + <pre>REGEXP = "java.*:javax.*:org.ietf*:org.omg.</pre> 1.27 +</blockquote> 1.28 +<h3><a name="releaseTargets"></a><br> 1.29 + Release Targets</h3> 1.30 +<p> (Thanks to Kelly O'Hair for this info.)</p> 1.31 +<p> The <tt>rel-coredocs</tt> and <tt>rel-docs</tt> targets were added by Eric 1.32 + Armstrong. <tt>rel-coredocs</tt> assumes the kind of large, 32-bit machine used 1.33 + in the javapubs group's docs-release process. It specifies memory settings accordingly 1.34 + to maximize performance.</p> 1.35 +<p> The performance settings, like the sanity check, are most important for the 1.36 + core docs--the platform APIs. Running javadoc on those APIs takes a significant 1.37 + amount of time and memory. Setting the initial heap size as large as possible 1.38 + is important to prevent thrashing as the heap grows. Setting the maximum as 1.39 + large as necessary is also important to keep the job from failing.</p> 1.40 +<blockquote> 1.41 + <p> <tt>-J-Xmx512</tt> sets a maximum of 512, which became necessary in 6.0<br> 1.42 + <tt>-J-Xms256</tt> sets starting size to 256 (default is 8)</p> 1.43 +</blockquote> 1.44 +<p> <tt>rel-coredocs</tt> also includes a sanity check to help ensure that <tt>BUILD_NUMBER</tt> 1.45 + and <tt>MILESTONE</tt> are specified properly when docs are built outside of 1.46 + the normal release engineering process, with the intention of releasing them 1.47 + on the web or in a downloaded docs bundle. (When invoked in release engineering's 1.48 + control build, the values are always set properly. But when the targets are 1.49 + run by themselves, they default to b00 and "internal"--which silently 1.50 + sabotage the result of a build that can take many hours to complete.</p> 1.51 +</body> 1.52 +</html>