Tag Library Documentation Generator 1.2

Project Info
Tag Library Documentation Generator is a utility for automatically generating javadoc-style documentation for JavaServer PagesTM (JSPTM) Technology Tag Libraries. It accepts a set of tag libraries as input, and generates a set of HTML files as output.

Included in the output is a full description of each defined tag library, the tags contained within those tag libraries, and how to use those tags.

Contents
Tag Library Repository
Screenshot
Download and Installation
Features
Building From Source
Usage Instructions
Support
Revision History

Tag Library Repository
We're attempting to produce a comprehensive collection of tag libraries and their corresponding documentation on the Wiki page for this project. Please consider adding your tag library to the Wiki once you've generated and posted your documentation.

Visit the Tag Library Repository Wiki.

Screenshot

Screenshot

Download and Installation
You can download the latest binary build from the Files Section on java.net.

Features
Tag Library Documentation Generator has the following features:

Build Instructions
To build Tag Library Documentation Generator, follow these steps:
  1. Download and install ant 1.5.1 or greater from http://ant.apache.org/.
  2. Download and install JavaCC 3.2 on your system. You can download JavaCC here: http://javacc.dev.java.net/
  3. Check out the taglibrarydoc source code from java.net. You can do so here: http://taglibrarydoc.dev.java.net/source/browse/taglibrarydoc/
  4. Change your directory to taglibrarydoc and copy the build.properties.sample template to build.properties.
  5. Edit build.properties and set JAVACC_HOME to the directory in which you installed JavaCC.
  6. Run 'ant dist'. A dist directory will be created with tlddoc.jar.
  7. Try a test run with 'ant test'. A out directory will be created with documentation for all the tag libraries in the testcases/ directory.
  8. See the following instructions for how to use the Tag Library Documentation Generator.

Usage Instructions
To use the Tag Library Documentation Generator, first, build the tool using the above instructions or download a precompiled binary, and make sure you can run it. Then, follow the instructions below. The first set of instructions assumes you are using JDK 1.4 or JDK 5.0. Instructions for running with JDK 1.3 are included below.

Generating Tag Library documentation

First, locate the tag libraries you wish to generate documentation for. You can generate documentation for a single TLD file, a set of TLD files, a JAR file, a WAR file, a directory of tag files, or all the tag libraries in a web application. Then, simply invoke as follows: 
	java -jar tlddoc.jar -d <outdir> <tlds>
Where <outdir> is the directory in which to produce the output and <tlds> is the list of files or directories to examine. The -doctitle and -windowtitle options can be used to customize the title for the index and the browser window title, respectively. You can run with -help to list all options.

Customizing the Output

The look and feel of the output can be customized. The generator collects all the information from various tag libraries into a single XML document, annotates it in various ways, and then runs that document through a number of XSLT stylesheets to produce the final output. You can edit or replace the XSLT stylesheets to change how the output looks or the way it is structured.

To do this, first extract the contents of tlddoc.jar to an empty directory. Then, edit the files in com/sun/tlddoc/resources/* to change the output. Finally, run with the -xslt option, pointing to the directory with the modified files. For any file that does not appear in the directory pointed to by -xslt, the default file will be used instead.

Running With JDK 1.3

The Tag Library Documentation Generator uses the JAXP APIs that are included in JDK 1.4 / JDK 5.0. However, it is also possible to run with JDK 1.3. To invoke using JDK 1.3 on Unix, type: 
        java 
          -classpath tlddoc.jar:xml-apis.jar:xercesImpl.jar:xalan.jar
          com.sun.tlddoc.TLDDoc -d <outdir> <tlds>
Or on Windows, use semi-colons (';') instead of colons (':'): 
        java 
          -classpath tlddoc.jar;xml-apis.jar;xercesImpl.jar;xalan.jar
          com.sun.tlddoc.TLDDoc -d <outdir> <tlds>
You can obtain xml-apis.jar, xercesImpl.jar and xalan.jar from the Xalan 2.5.1 release which can be downloaded here.

Thanks to Doug Kenyon from ATG for sending this tip on how to run with JDK 1.3!

Running With Ant

You can run the Tag Library Documentation Generator in ant as part of your build process using the <java> task. Just add the following code to your build.xml.

Using JDK 1.4, JDK 5.0, or greater: 

      <java fork="true" jar="${tlddoc.path}/tlddoc.jar"
            failonerror="true">
        <arg line="-d ${build}/taglibs/doc"/>
        <arg value="${src}/taglibs/tld/my1.tld"/>
        <arg value="${src}/taglibs/tld/my2.tld"/>
        <arg value="${src}/taglibs/tld/my3.tld"/>
      </java>
Or, using JDK 1.3: 
      <java fork="true" classname="com.sun.tlddoc.TLDDoc"
            failonerror="true">
        <arg line="-d ${build}/taglibs/doc"/>
        <arg value="${src}/taglibs/tld/my1.tld"/>
        <arg value="${src}/taglibs/tld/my2.tld"/>
        <arg value="${src}/taglibs/tld/my3.tld"/>
        <classpath>
          <pathelement location="${tools.lib}/tlddoc.jar"/>
          <pathelement location="${tools.lib}/xml-apis.jar"/>
          <pathelement location="${tools.lib}/xercesImpl.jar"/>
          <pathelement location="${tools.lib}/xalan.jar"/>
        </classpath>
      </java>

Support
Tag Library Documentation Generator is a community-supported open-source product. You can find support by subscribing to the various mailing lists offered in this java.net project. Also, see the FAQ.

Revision History
Java and JSP are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-3 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.