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