Javadoc example

This demonstrates xmlroff processing the XML created from Javadoc comments and creating PDF.

Javadoc currently supports a "MIF doclet" that extracts Javadoc comments from Java programs and creates a MIF file that can be imported into Adobe's FrameMaker desktop publishing program. The pages made in FrameMaker are typically exported as PDF and used as the printed or online API documentation for a Java program.

The Javadoc developers also have a prototype "XML doclet" that extracts Javadoc comments from Java programs and creates XML files. This demonstration shows xmlroff using that XML and an XSL stylesheet and creating PDF output. The XSL styles were created by translating the FrameMaker styles into XSL properties.

The sample XML file documents the com.package1.SubClass class, which is one of the classes used by the Javadoc developers to test the Javadoc system.

The complete example is included with the xmlroff distribution.

Javadoc formatted by xmlroff

Javadoc formatted by FrameMaker

Further Details

This demonstration shows xmlroff processing an XML file with an XSLT stylesheet to produce a result tree comprising elements and attributes in the XSL formatting object vocabulary. xmlroff then formats that tree to produce PDF output.

The original XML document provided by the XML doclet developer does not contain all of the information present in the formatted output.

The Javadoc formatted in FrameMaker contains information about both the class being documented and the superclasses of that class. For example, the formatted output shows the "class tree" of superclasses back up to java.lang.Object. The formatted output also contains a table of fields and members inherited from superclasses and from interfaces implemented by those superclasses.

It is good technique to generate a Javadoc XML file for a single .java file that contains only information derived from that file.

It is also good to show the extra information about inherited members, etc. in the formatted output.

This demonstration is based on the single XML file provided by the XML doclet developer. We do not have the other files that would be necessary for a full Javadoc implementation.

The purpose of this demonstration is to show xmlroff formatting XML that is not in the XSL Formatting Object vocabulary. It is not the purpose of this demonstration to show neat XSLT tricks for extracting information from multiple XML files.

Even if the files were available, it would be the job of an XSLT transformation, not an XSL formatter, to traverse the object hierarchy and transform information from multiple files into a single result tree.

The XML formatted by xmlroff, therefore, has been augmented with the extra class, field, interface, and method information as if such a transformation had been done.

Note that the XML file uses Javadoc-style markup for this extra information. It does not try to short-circuit the transformation from Javadoc to FOs by including FO markup for the inherited fields, etc.

Properties extracted from FrameMaker MIF styles

Only the XSL property names are listed here, since it is unlikely that anyone knows the MIF style keywords well enough to recognise them.


DocBookLibxslt SourceForge