jdk/makefiles/docs/Notes.html
changeset 12317 9670c1610c53
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/makefiles/docs/Notes.html	Tue Apr 10 08:22:03 2012 -0700
@@ -0,0 +1,49 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<title>Doc Process Notes</title>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+</head>
+
+<body>
+<h3><a name="REGEXP"></a><br>
+REGEXP</h3>
+<p> REGEXP is a list of wildcard patterns that determines which packages listed 
+  in CORE_PKGS.gmk go into which summary-table on the main API index page. It 
+  was motivated by the need to divide the world into &quot;core packages&quot; 
+  (java.*) and &quot;extension packages&quot; (javax.*). In time, the distinction 
+  went away. The whole table is now called &quot;Platform Packages&quot;--which 
+  eliminated the need for this list of regular expressions. But it lingered on, 
+  accreting all of the packages in the JVM, one by one. I pruned it back to &quot;*&quot;, 
+  so it now covers every package in the Java platform API docs. If some separation 
+  is needed in the future, it can grow back into a colon-separated list, starting 
+  with this, which is in all respects equivalent to &quot;*&quot; at this point 
+  in time:</p>
+<blockquote> 
+  <pre>REGEXP = &quot;java.*:javax.*:org.ietf*:org.omg.</pre>
+</blockquote>
+<h3><a name="releaseTargets"></a><br>
+  Release Targets</h3>
+<p> (Thanks to Kelly O'Hair for this info.)</p>
+<p> The <tt>rel-coredocs</tt> and <tt>rel-docs</tt> targets were added by Eric 
+  Armstrong. <tt>rel-coredocs</tt> assumes the kind of large, 32-bit machine used 
+  in the javapubs group's docs-release process. It specifies memory settings accordingly 
+  to maximize performance.</p>
+<p> The performance settings, like the sanity check, are most important for the 
+  core docs--the platform APIs. Running javadoc on those APIs takes a significant 
+  amount of time and memory. Setting the initial heap size as large as possible 
+  is important to prevent thrashing as the heap grows. Setting the maximum as 
+  large as necessary is also important to keep the job from failing.</p>
+<blockquote>
+  <p> <tt>-J-Xmx512</tt> sets a maximum of 512, which became necessary in 6.0<br>
+    <tt>-J-Xms256</tt> sets starting size to 256 (default is 8)</p>
+</blockquote>
+<p> <tt>rel-coredocs</tt> also includes a sanity check to help ensure that <tt>BUILD_NUMBER</tt> 
+  and <tt>MILESTONE</tt> are specified properly when docs are built outside of 
+  the normal release engineering process, with the intention of releasing them 
+  on the web or in a downloaded docs bundle. (When invoked in release engineering's 
+  control build, the values are always set properly. But when the targets are 
+  run by themselves, they default to b00 and &quot;internal&quot;--which silently 
+  sabotage the result of a build that can take many hours to complete.</p>
+</body>
+</html>