Doc Process Notes

###
REGEXP

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 "core packages" (java.*) and "extension packages" (javax.*). In time, the distinction went away. The whole table is now called "Platform Packages"--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 "*", 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 "*" at this point in time:

>     REGEXP = "java.*:javax.*:org.ietf*:org.omg.

###
Release Targets

(Thanks to Kelly O'Hair for this info.)

The `rel-coredocs` and `rel-docs` targets were added by Eric Armstrong. `rel-coredocs` 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.

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.

> `-J-Xmx512` sets a maximum of 512, which became necessary in 6.0
> `-J-Xms256` sets starting size to 256 (default is 8)

`rel-coredocs` also includes a sanity check to help ensure that `BUILD_NUMBER` and `MILESTONE` 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 "internal"--which silently sabotage the result of a build that can take many hours to complete.