Raible's Wiki

Raible Designs
Wiki Home
News
Recent Changes

AppFuse

Homepage
  - Korean
  - Chinese
  - Italian
  - Japanese

QuickStart Guide
  - Chinese
  - French
  - German
  - Italian
  - Korean
  - Portuguese
  - Spanish
  - Japanese

User Guide
  - Korean
  - Chinese

Tutorials
  - Chinese
  - German
  - Italian
  - Korean
  - Portuguese
  - Spanish

FAQ
  - Korean

Latest Downloads

Other Applications

Struts Resume
Security Example
Struts Menu

Set your name in
UserPreferences

Edit this page


Referenced by
StrutsResumeSupport




JSPWiki v2.2.33

[RSS]


Hide Menu

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).


These are the files required:
./build.xml
./dbdoclet.properties
./metadata/xsl/fo.xsl

A portion of my build.xml watch out for packagenames="ca.*" (adjust accordingly)

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>

Here's how to set dbdoclet.xincluder.classpath
  <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>

This portion of build.xml is dependent on the following metadata/xsl/fo.xsl file
<?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>

and finally dbdoclet.properties
# 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
author.email=haroon.rafique@utoronto.ca
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
Another yummy feature is class diagrams (which show inheritence path and all implemented interfaces) in PNG (or other) format. That's why you need the graphviz package from AT&T. A sample class diagram follows:
StrutsResume/ClassDiagram.png

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 haroon.rafique@ca.utoronto (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_209.png


Attachments:
p_xmi_232.png Info on p_xmi_232.png 11833 bytes
p_xmi_209.png Info on p_xmi_209.png 5612 bytes


Go to top   Edit this page   More info...   Attach file...
This page last changed on 06-Nov-2006 13:52:58 MST by HaroonRafique.