DocBook

2003.10.30 - PDF reference handbook for your java source documentation

Now that the initial thank you is out of the way, here is Thank You #2. I think you should be declared "Doclet King" for the way you have embraced doclet-related software (probably Erik Hatcher too). In any case, since you love doclets sooo much (xdoclet, junitdoclet, etc.), let me introduce you to dbdoclet (DocBook Doclet). This doclet creates DocBook output from Java source documentation (javadoc comments). One of the most common uses for this DocBook output is to convert it into PDF. So, instantly (within reason) you can have PDF javadoc documentation.

Here's what you need to add to your build.xml (my build.xml is slightly different from struts-resume/appfuse, but you'll figure it out).

./build.xml
./dbdoclet.properties
./metadata/xsl/fo.xsl

FYI. dbdoclet.dir is set via a property as follows:

<property name="dbdoclet.dir" value="${user.home}/dbdoclet-${dbdoclet.ver}/share/dbdoclet"/>

<!-- ==================== pdfdoc Target ============================= -->

  <target name="pdfdoc" depends="compile"
   description="Create PDF documentation">
    <mkdir          dir="${dist.apidocs}"/>
    <!-- === docbook === -->
    <echo message="Creating docbook"/>
    <javadoc sourcepath="${src.dir};${gen.dir}"
                destdir="${dist.apidocs}"
           packagenames="ca.*">
      <classpath refid="compile.classpath"/>
      <doclet name="org.dbdoclet.doclet.docbook.DocBookDoclet"
            path="${dbdoclet.dir}/jars/dbdoclet.jar">
         <param name="-properties" value="dbdoclet.properties"/>
      </doclet>
      <tag name="jsp.tag"               description="JSP Tag:" />
      <tag name="jsp.attribute"         description="JSP Attribute:" />
      <tag name="struts.action"         description="Mapping:" />
      <tag name="struts.action-forward" description="ActionForward:" />
      <tag name="struts.form"           description="Form Name:" />
      <tag name="struts.validator"      description="Validator:" />
      <tag name="struts.validator-args" description="Validator Args:" />
      <tag name="struts.validator-var"  description="Validator Var:" />
      <tag name="web.listener"          description="Listener:" />
      <tag name="x.generated"           description="Generated:" />
      <tag name="x.copyright"           description="Copyright:" />
    </javadoc>
    <!-- === convert to Full XML with XIncluder === -->
    <echo message="Running XIncluder"/>
    <java classname="com.elharo.xml.xinclude.SAXXIncluder"
            failonerror="yes" dir="${dist.apidocs}"
            output="${dist.apidocs}/reference-full.xml" fork="yes">
        <classpath refid="dbdoclet.xincluder.classpath"/>
        <arg line="reference.xml"/>
    </java>
    <!-- === filter fo.xsl === -->
    <copy tofile="${dist.apidocs}/fo.xsl" file="${metadata.dir}/xsl/fo.xsl">
        <filterset>
            <filter token="DBDOCLET_HOME" value="${dbdoclet.dir}"/>
        </filterset>
    </copy>
    <!-- === convert to pdf === -->
    <echo message="Converting to PDF"/>
    <java classname="org.apache.fop.apps.Fop"
          failonerror="yes" dir="${dist.apidocs}" fork="yes">
      <classpath refid="dbdoclet.fop.classpath"/>
      <arg line="-xml reference-full.xml"/>
      <arg line="-xsl fo.xsl"/>
      <arg line="-pdf reference.pdf"/>
    </java>
  </target>

  <path id="dbdoclet.xincluder.classpath">
    <fileset dir="${dbdoclet.dir}/jars">
      <include name="resolver.jar"/>
      <include name="xincluder.jar"/>
    </fileset>
    <fileset file="${catalina.home}/common/endorsed/xercesImpl.jar"/>
  </path>

<?xml version="1.0" encoding="iso-8859-1"?>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="1.0"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                exclude-result-prefixes="#default"
>

  <xsl:import href="file:@DBDOCLET-HOME@/docbook/xsl/fo/docbook.xsl"/>

  <xsl:param name="body.font.master">10</xsl:param>
  <xsl:param name="insert.xref.page.number">1</xsl:param>
  <xsl:param name="title.margin.left">0pt</xsl:param>
  <xsl:param name="use.extensions">1</xsl:param>
  <xsl:param name="tablecolumns.extension">0</xsl:param>
  <xsl:param name="generate.index">1</xsl:param>
  <xsl:param name="admon.graphics">1</xsl:param>
  <xsl:param name="admon.graphics.path">@DBDOCLET-HOME@/docbook/xsl/images/</xsl:param>
  <xsl:param name="section.autolabel">1</xsl:param>
  <xsl:param name="fop.extensions">1</xsl:param>
  <xsl:param name="draft.watermark.image"></xsl:param>
  <xsl:param name="section.label.includes.component.label">1</xsl:param>
  <xsl:param name="shade.verbatim">1</xsl:param>
  <xsl:param name="make.index.markup">1</xsl:param>

  <xsl:attribute-set name="book.titlepage.recto.style">
    <xsl:attribute name="color">#2f2f2f</xsl:attribute>
  </xsl:attribute-set>

  <xsl:attribute-set name="section.title.properties">
    <xsl:attribute name="font-size">
      <xsl:value-of select="$body.font.master * 1.2"/>
      <xsl:text>pt</xsl:text>
    </xsl:attribute>  
  </xsl:attribute-set>

  <xsl:attribute-set name="section.title.level1.properties">
    <xsl:attribute name="border-after-style">solid</xsl:attribute>
    <xsl:attribute name="border-after-width">.1mm</xsl:attribute>
    <xsl:attribute name="font-size">
      <xsl:value-of select="$body.font.master * 1.6"/>
      <xsl:text>pt</xsl:text>
    </xsl:attribute>  
  </xsl:attribute-set> 

  <xsl:attribute-set name="section.title.level2.properties">
    <xsl:attribute name="border-style">solid</xsl:attribute>
    <xsl:attribute name="border-width">.1mm</xsl:attribute>
    <xsl:attribute name="background-color">#cecfff</xsl:attribute>
    <xsl:attribute name="padding">0.3em</xsl:attribute>
    <xsl:attribute name="start-indent">0pc</xsl:attribute>
    <xsl:attribute name="end-indent">0pc</xsl:attribute>
    <xsl:attribute name="font-style">italic</xsl:attribute>
    <xsl:attribute name="font-weight">normal</xsl:attribute>
    <xsl:attribute name="font-size">
      <xsl:value-of select="$body.font.master * 1.4"/>
      <xsl:text>pt</xsl:text>
    </xsl:attribute>  
  </xsl:attribute-set> 

  <xsl:attribute-set name="section.title.level3.properties">
    <xsl:attribute name="border-after-style">solid</xsl:attribute>
    <xsl:attribute name="border-after-width">.1mm</xsl:attribute>
    <xsl:attribute name="font-weight">normal</xsl:attribute>
    <xsl:attribute name="font-style">italic</xsl:attribute>
    <xsl:attribute name="font-size">
      <xsl:value-of select="$body.font.master * 1.2"/>
      <xsl:text>pt</xsl:text>
    </xsl:attribute>  
  </xsl:attribute-set> 

  <xsl:attribute-set name="formal.title.properties">
    <xsl:attribute name="font-size">
      <xsl:value-of select="$body.font.master * 1.0"/>
      <xsl:text>pt</xsl:text>
    </xsl:attribute>
    <xsl:attribute name="space-after.minimum">0.0em</xsl:attribute>
    <xsl:attribute name="space-after.optimum">0.4em</xsl:attribute>
    <xsl:attribute name="space-after.maximum">0.4em</xsl:attribute>
    <!--
    <xsl:attribute name="border-style">solid</xsl:attribute>
    <xsl:attribute name="border-width">.1mm</xsl:attribute>
    -->
  </xsl:attribute-set> 

  <xsl:attribute-set name="list.block.spacing">
    <xsl:attribute name="space-before.minimum">0em</xsl:attribute>
    <xsl:attribute name="space-before.optimum">0em</xsl:attribute>
    <xsl:attribute name="space-before.maximum">0em</xsl:attribute>

    <xsl:attribute name="space-after.minimum">0.0em</xsl:attribute>
    <xsl:attribute name="space-after.optimum">0.7em</xsl:attribute>
    <xsl:attribute name="space-after.maximum">0.7em</xsl:attribute>
    <!--
    <xsl:attribute name="border-style">solid</xsl:attribute>
    <xsl:attribute name="border-width">.1mm</xsl:attribute>
    -->
  </xsl:attribute-set> 

  <xsl:attribute-set name="list.item.spacing">
    <xsl:attribute name="space-before.minimum">0.0em</xsl:attribute>
    <xsl:attribute name="space-before.optimum">0.3em</xsl:attribute>
    <xsl:attribute name="space-before.maximum">0.3em</xsl:attribute>

    <xsl:attribute name="space-after.minimum">0em</xsl:attribute>
    <xsl:attribute name="space-after.optimum">0.2em</xsl:attribute>
    <xsl:attribute name="space-after.maximum">0.2em</xsl:attribute>
    <!--
    <xsl:attribute name="border-style">solid</xsl:attribute>
    <xsl:attribute name="border-width">.1mm</xsl:attribute>
    -->
  </xsl:attribute-set> 

  <xsl:template match="processing-instruction('line-break')">
    <fo:block/>
  </xsl:template>
</xsl:stylesheet>

# The path of the output file. In the directory of the output file a
# subdirectory figures may be created, where the images for the document
# are stored.
destination.file=reference.xml

# One of xml or sgml (case insensitive)
docbook.type=xml

# The version of the produced DocBook. Should be 3.1 or 4.1 for SGML and
# 4.1.2 for XML.
docbook.version=4.2

# If set to true, the file Index.sgml is included. To generate an
# Index.sgml file you can use the script collateindex.pl. The script is
# part of The Modular DocBook Stylesheets.
docbook.has-index=true

# If set to false, the XML/SGML prolog (<?xml..><DOCTYPE...>) is not
# created. This property is necessary, if you want to incorporate the
# output into a DocBook source. e.g a website.
#docbook.has-prolog=true

# A comma separated list of imagedata formats. For every format a
# ImageObject -> ImageData entry will be generated.

# Postscript for printing
# imagedata.formats=eps

# PNG for PDF and HTML
imagedata.formats=png

language=en
title=ROSI SWS
author.firstname=Student
author.surname=Information Systems
[email protected]
copyright.holder=University of Toronto

abstract=Reference Handbook for ROSI SWS Java API

# This properties defines the value for the attribute width of the tag
# ProgramListing. It specifies the width of the longest line in a
# ProgramListing. A formatter can use this value to determine scaling or
# the size of the font used.
code.width=80

# If set to true, the output of warnings is enabled.
parser.warnings=true

# If set to true, an inheritance path is added to the overview section
# for every class. If known, the classes are referenced among each
# other. The default value of this property is true.
show.inheritancePath=true

# If dot from graphviz 1.8.9 is installed on your system, it is used to
# create the class diagrams. This property should contain the path to
# the dot binary.
program.dot.path=/usr/bin/dot

# This property defines the vertical space between the classes in the
# class diagrams. The space is an inch value like 0.3.
# program.dot.ranksep=0.2

# This property enables fully qualified names in the class diagrams
program.dot.qualified-names=true

I am currently trying to modify the sources for dbdoclet to add the capability of handling custom tags. Right now xdoclet-related custom tags just disappear into thin air. I have a working prototype but will wait to hear from the upstream author before making it available.

This has been implemented in the latest dbdoclet version.

Any questions, drop me a line.

Regards,
--
Haroon Rafique [email protected] (reverse the domain to send email)

This looks great, although I don't have time to implement it right now. I am looking for an easy way to generate UML diagrams from my existing class structure though. Know of any tools? ~ MattRaible

For reverse-engineering of your existing .java files ESS-Model seems to work great for me. You give it your source tree and you get UML diagrams as the output. Sorry, Windows binaries only. Source is available in Delphi 6, if anyone cares.

Here's a sample:

p_xmi_232.png		11833 bytes
p_xmi_209.png		5612 bytes