XDC is an application which allows the generation of documentation pages in HTML format from special comments ("XDC" comments) within XML files of various dialects.
XDC strongly resembles the Javadoc tool included in the JDK of the Sun Java Platform Standard Edition (JavaSE). This resemblance is reflected
- - in the format of the comments:
Like Javadoc comments, which differ from standard multi-line comments in Java source files by a additional asterisk ("*") marking the starting delimiter of the comment, XDC comments differ from standard XML comments by an additional dash ("-") character opening the comment:
<!-- This is a standard XML comment -->
<!--- This is an XDC comment -->- - in the way the tool is invoked:
Like the Javadoc tool, XDC can be invoked on the command line with an almost identical format. Moreover, most options that XDC recognizes are identical to those of Javadoc.
The XDC tool can also be invoked in a build process controlled by an Apache Ant build file. For this, a
xdctask is included in the XDC distribution. This task has again a similar set of attributes and recognized subelements as thejavadoctask.- - in the format of the generated HTML pages
The look and feel of the HTML pages generated by the XDC has been designed to also resemble the files produced by the Javadoc tool.
The DJDoc API is licensed under the Apache Software License 2.0.
The application uses the following APIs which are included in the distribution:
Archive(s) Description Version Use License Remarks/Resource URL log4j.jar Logging library 1.2.13 compile,runtime Apache Software License 2.0 http://logging.apache.org/log4j/ commons-cli-1.0.jar Commons CLI (Command line interface) 1.0 compile,runtime Apache Software License 2.0 http://jakarta.apache.org/commons/cli/ xalan.jar Xalan XSLT transformer 2.7.0 compile,runtime Apache Software License 2.0 http://xml.apache.org/xalan-j/ xercesImpl.jar, xml-apis.jar, serializer.jar Xerces XML parser 2.6.2 runtime Apache Software License 2.0 http://xerces.apache.org/xerces2-j/ ant.jar Apache Ant build framework 1.6.5 compile,runtime Apache Software License 2.0 http://ant.apache.org/ nalax.jar Xalan extension package 0.9.4 runtime Apache Software License 2.0 http://nalax.sourceforge.net junit.jar Java unit testing framework 3.8.1 compiling (just unit tests), testing Common Public License 1.0 http://junit.sourceforge.net/ alster.jar XSLT unit testing framework 0.5.1 testing Apache Software License 2.0 http://alster.sourceforge.net
Installation from Source
If you have downloaded the XDC sources, follow these steps to install the software:
Extract the source archive into a new directory and open a shell in that directory.
Run the
build.shresp.build.batscript. This will invoke the Ant build utility and execute a number of build steps such as cleaning the directories, compiling the XDC and the unit test sources, running the tests, generating the documentation and packaging the generated classes into a JAR file.Binary Installation
If you have just downloaded the binaries of the XDC application, install XDC by following these steps:
Extract the XDC binary archive into a new directory.
The XDC tool can now be run by executing the
xdc.shresp.xdc.batscripts. If you run these in a directory other than the XDC root directory, make sure that thexdc.jararchive and all JAR files in the/libdirectory are in the classpath.
Command Line
The XDC application can be invoked from the command line using the class
net.sf.xdc.Mainas the entry point. The processing of the command line arguments is handled by the Commons CLI (command line interface) library of the Apache Jakarta project (somewhat extended to meet special needs).For easier invocation of the tool, two shell scripts (
xdc.batresp.xdc.sh) have been provided which take care of correctly setting the classpath, the Java VM options and the actual invocation of the Java runtime.HTML File Generation
Almost all of the files produced by the XDC tools are generated using XSLT transformations. The heart of the XDC application consists of a hierarchy of XSLT stylesheets responsible for converting XDC documentation as well as some information about the structure of the documented XML files into various parts of the generated documentation.
CSS Stylesheet Files
The default CSS stylesheet file is not produced from an XML source but is simply copied to the correct location in the output directory hierarchy.
Other Support Files
The remaining support files are generated from various XML sources:
The help file is generated from a source in docbook format (
net/sf/xdc/resources/help-doc.xml)) using a proprietary docbook stylesheet (net/sf/xdc/xsl/docbook.xsl).Depending on the number of packages involved in the XDC invocation, the correct frameset is generated from an empty XML document (plus some global stylesheet variables) using one of the
net/sf/xdc/xsl/index?.xslstylesheets.The lists of documented packages and/or files are produced from XML files containing the corresponding lists (generated by the Java class
net.sf.xdc.processing.XdcSourceCollector) using one of thenet/sf/xdc/xsl/*-frame.xslstylesheets.Summary Files
The XDC tool produces one package summary file which contains a table with summary data for each file documented within that package, along with HTML code contained in a file named
xdc-package.html. Similarly, if XDC documents more than one package, an overview file is generated with a summary table for each documented package as well as HTML code read from a file specified by the-overviewoption.Source Element Pages
The XDC tool produces one file for every documented XML file. The XSLT stylesheet used for the transformation of the source XML file is determined by the XML dialect of the source file. XDC includes three built in dialect-specific XSLT files named
ant.xsl,xsl.xslandgeneric.xslused for Ant build files, XSLT stylesheet files and generic XML files, respectively.XML source view
If the
-linksourceoption is used, the XDC tool produces an additional HTML presentation of each XML source file in a separate folder. This file is produced using an instance of thenet.sf.xdc.processing.SourceProcessorclass by parsing the content of the source files line by line and streaming it into the output file along with line numbers and anchors (and with the special XML characters appropriately escaped).Standard Compliance
In the design phase of the XDC tool, it appeared quite natural to use XSLT stylesheets for the "engine" of the application because XSLT is the prime choice when it comes to converting XML to HTML.
The goal of the implementation was to use pure XSLT 1.0 in the stylesheets. This had the big advantage that the transformation of the source XML file to HTML (which really made up the heart of the application) could be done not only by the XSLT transformer used by the Java runtime used but also by any XSLT 1.0 compliant transformer. In particular, the XSLT transformers used by the common web browsers Micorsoft Internet Explorer (MSXML) and Mozilla Firefox (Transformiix) could be used for "previewing" the XML source files (e.g. by including a processing instruction like
<?xml-stylesheet type="text/xsl" href="generic.xsl"?>in the XML file). This functionality has proved very valuable especially for "debugging".The only exception to the compliance to the XSLT 1.0 standard are the use of the
java:org.apache.xalan.lib.NodeInfo.lineNumber()function in two places: One place this is used is for writing an<xsl:message>with the line number of an XML subelement which fails to provide XDC documentation (in case the-reportmissingoption has been selected). The other place is in the hyperlink from the detail view of an XML subelement to the corresponding anchor in the XML source view page (for which there was really no alternative). As a consequence of this deviation from the standard compliance, the preview functionality fails to provide a correct hyperlink to the XML source view page.During the development phase, a few drawbacks of the "pure XSLT 1.0" approach became apparent:
XSLT does not work well with "syntactically unstructured" text such as comments which is structured in a non-XML way. It required a lot of ugly low-level parsing to correctly process all constituents of the XDC comments.
This problem could have been much more nicely solved by using a custom XSLT extension, but it would have been very tedious (if at all possible) to implement equivalent functionality for all targeted XSLT transformers.
Another solution would have been to place the XDC information in XML elements from a separate
xdcnamespace rather than in XML comments (and in fact, this may become part of an XDC 2.0 release), but it is not in all cases desirable to introduce new subelements as they may break XSLT stylesheet logic (even with a separate namespace), so the comments were prefered over elements in the implementation.XSLT is rather limited in the possible data types of template parameters. In particular, any node set-valued parameters must be immediate subnode sets of the processed documents or documents read in with the
document()function. There is no support for the using result tree fragments as template parameters for further XSLT processing.This problem was solved by structuring "record" typed parameters artificially by passing them as a delimited string to a template which recursively tokenizes that string and passes the individual elements to yet another template.
Of course, this solution is not very satisfactory; a perhaps better approach could have been the use of the exslt XSLT extension library which has a
node-set()function converting a result tree fragment into a node set. This library supports a number of XSLT processors, but not the ones included in the IE or Mozilla browsers (even though MSXML does have anode-set()function), so this solution would break (or at least reduce) the "preview" functionality.XSLT has no support for file I/O (not even the "I" of "I/O"); this is not even part of the exslt extension library. It would have been unbelievably cool to have one XSLT stylesheet scan the contents of a directory and produce e.g. the package frame page, but due to the lack of necessary functionality in XSLT, this was completely out of reach.
Of course, such functionality could have been provided by a custom XSLT extension (and in fact, something similar is possible with the Nalax XSLT extension package which is part of the Alster XSLT unit testing framework included in the XDC distribution), but since the list of selected packages and/or source files depends on so many command line settings anyway and since the command line processing could not be implemented inside the stylesheets either, this approach seemed rather inpractical.
Future enhancements
There are a number of features that a followup version of XDC may include.
- Integration with external API dcumentation
Support for the Javadoc
-linkand-linkofflineoptions should also be added in the future. An integration with Javadoc generated API documentation should also be possible.- Enhanced extendability
Another feature probably implemented in a future version of XDC will be the equivalent of the Javadoc Doclets and Taglets which will give the user more flexibility in the presentation of the generated documentation as well as control over how certain (dialect-specific) tags are handled.
- Alternative XDC comment format
As mentioned above, a followup version of XDC might allow XDC information to be placed in XML subelements from a custom namespace besides the option to use XDC comments.
- Support for "inclusions"
Each of the two main target XML dialects of the XDC application, Apache Ant scripts and XSLT stylesheets, has ways to include other XML files (Ant does so with the <import> element; XSLT with the <xsl:import> and <xsl:include> elements). Moreover, any XML file has the possibility to include another file as an external entity.
A future version of XDC is likely to have some sort of support for all these types of inclusions (and some of its consequenses such as Ant target overriding or XSLT template precedence) as Javadoc has for Java inheritance related features.
- Partial rearchitecture
The more awkward the development in "pure XSLT 1.0" mode becomes, the greater the urge will be to open up this concept and solve particular problems with custom XSLT extensions - even if that means that XDC would be restricted to the Xalan XSLT processor and would thus lose the preview functionality.
Also, the XDC architecture may move away from the concept which identifies one source file with one documented page and one source directory with one package. Depending on the complexity of the documented sources, it might instead be desirable to split up one source XML file into several pages in the generated documentation (somewhat similar to what Javadoc does with inner classes) or combine several source XML files to one page in the documentation (comparable perhaps to the way TLDDoc/taglibrarydoc does).
- Tool integration
Finally, it would be nice to have support for different aspects of the XDC product in IDEs or other tools. This could include custom syntax highlighting of XDC comments, automatic comment skeleton generation in XML files, code inspections (issuing warnings in cases of missing or incomplete XDC comments) and XDC comment previewing.