How the Quick Reference Is Generated (Java in a Nutshell)

0.8. How the Quick Reference Is Generated

For the nerdy or merely inquisitive reader, this section explains a bit about how the quick-reference material in Java in a Nutshell and related books is created.

As Java has evolved, so has my system for generating Java quick-reference material. The current system is part of a larger commercial documentation browser system I'm developing (visit http://www.davidflanagan.com/Jude/ for more information about it). The program works in two passes: the first pass collects and organizes the API information, and the second pass outputs that information in the form of quick-reference chapters.

The first pass begins by reading the class files for all of the classes and interfaces to be documented. Almost all of the API information in the quick reference is available in these class files. The notable exception is the names of method arguments, which are not stored in class files. These argument names are obtained by parsing the Java source file for each class and interface. Where source files are not available, I obtain method argument names by parsing the API documentation generated by javadoc. The parsers I use to extract API information from the source files and javadoc files are created using the Antlr parser generator developed by Terrence Parr of the Magelang Institute. (See http://www.antlr.org/ for details on this very powerful programming tool.)

Once the API information has been obtained by reading class files, source files, and javadoc files, the program spends some time sorting and cross-referencing everything. Then it stores all the API information into a single large data file.

The second pass reads API information from that data file and outputs quick-reference chapters using a custom SGML format. The SGML markup is fairly complex, but the code that generates it is quite mundane. Once I've generated the SGML output, I hand it off to the production team at O'Reilly & Associates. They process it and convert it to troff source code. The troff source is processed with the GNU groff program (ftp://ftp.gnu.org/gnu/groff/ ) and a custom set of troff macros to produce PostScript output that is shipped directly to the printer.