XSLTdoc - code documentation tool for XSLT

XSLTdoc is a Javadoc-like tool for documenting XSLT.

Home page

The old home for this project was here on SourceForge.

The XSLTdoc tool defines conventions for documenting XSLT source files. The tool extracts these comments and builds documentation as a set of HTML pages. The documentation includes pages that display the XSLT source code with syntax highlighting, among many other features.

Features

  • Supports XSLT include and import
  • Syntax highlighted source code
  • Custom CSS stylesheets
  • Document layout is customizeable
  • Easily extensible with new tags
  • Open source under GPL license
  • Written in XSLT
  • Uses Node.js, npm, and node-java for ease of packaging, installation,
    and running

Requirements

Java Runtime Environment (JRE)

This tool requires a Java Runtime Environment (JRE). To determine whether or not your system has a JRE installed, run the following command at a terminal:

java -version

This library is known to work with Java version 1.8; other versions have not been tested. (If you try it with some other version, and find that it doesn’t work, please open an issue).

If your system does not have a suitable JRE installed, you can download one from here.

Node.js - optional

The easiest way to install and use this tool is with the Node.js package manager npm and the included wrapper scripts. If, however, you prefer not to install Node.js, it is not difficult to set it up to run without them – see Installing and running - manually, below.

To determine whether or not Node.js is installed on your system:

node --version

To install it, download it from the Node.js website, and follow the installation instructions there.

<a name=‘run-with-node’></a>

Installing and running with Node.js

To install the tool, run the following from a terminal:

npm install -g xsltdoc

To set up an XSLT project to use the tool, cd to the project directory, and create a new default configuration file with:

xsltdoc --init

This writes a file named xsltdoc-config.xml that contains the default settings as well as extensive comments describing the various options. Open this file in any editor, and change the settings to suit your needs.

You can try out the tool with a sample XSLT. Create a directory called sample-project, and download this sample XSLT file to that directory. Then:

cd sample-project
xsltdoc --init
xsltdoc

The tool should produce a set of documentation pages in the doc/ subdirectory. To see the results, open the doc/index.html file in your browser.

<a name=‘run-manually’></a>

Installing and running manually (without Node.js)

To use the tool without Node.js, first download one of the latest release bundles from here. Unzip the bundle file to a directory of your choice.

XSLTdoc is written in XSLT 2.0. You need an XSLT 2.0 processor to run it. Download the latest version of Saxon-HE from the Sourceforge download page (for example, SAXONHE9-7-0-3J.zip) and extract that into the lib subdirectory of the XSLTdoc directory.

Set the environment variable XSLTDOC to the path of the directory to which you extracted the bundle.

To set up a project’s configuration file, copy the template from the tool directory:

cp $XSLTDOC/templates/xsltdoc-config.xml .

Then open it in an editor and change the settings as needed.

To generate the documentation:

java -jar $XSLTDOC/lib/saxon9he.jar xsltdoc-config.xml \
  $XSLTDOC/xsl/xsltdoc.xsl

Fonts, colors and layout of the HTML documentation are defined in a few CSS files which can be found in the css directory of the installation. Copy these files to the folder where the documentation was generated. For example:

cp $XSLTDOC/css/* doc

Note: If you need an older version of XSLTdoc, you can find them listed here.

API

You can run it programmatically from a Node.js script with

const xsltdoc = require('xsltdoc');

// The conversion runs asynchronously and then invokes a callback
xsltdoc(opts, targetDir => {
  console.log('Done. Documentation written to ' + targetDir);
});

Documentation format

Documentation elements are written in XML. Because XSLT is expressed in XML too, it is necessary to define a new namespace for XSLTdoc to enable a XSLT processor to distinguish between documentation and source code. The URI for this namespace is http://www.pnp-software.com/XSLTdoc. This namespace must be declared in any stylesheet which uses XSLTdoc for documenting. Example:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:xd="http://www.pnp-software.com/XSLTdoc" version="2.0">
  ...
</xsl:stylesheet>

General documenting rules

The documentation is normally added before the source element that should be documented. Generally this looks like this:

<xd:doc>
  ...
</xd:doc>
<xsl:...>

Any XSLTdoc documentation is enclosed in an xd:doc element. If you just want to write a plain text comment the xd:doc element can contain simple text. Text before the first period is considered as short description, the remaining as detailed description:

<xd:doc>
  This is the short description. And here comes a more detailed
  description that appears in the detailed view of the documentation only.
</xd:doc>
<xsl:...>

If you use this technique, then no HTML elements are allowed in the text. If you want to use HTML tags within short and detailed description the text for the short and detailed description needs to enclosed in special XSLTdoc tags:

<xd:doc>
  <xd:short>This is the short description with
    <code>HTML tags</code>.</xd:short>
  <xd:detail>
    And here comes a <b>more detailed</b>
    description showed only in the detailed view of the documentation.
  </xd:detail>
</xd:doc>
<xsl:...>

Stylesheet documentation

The documentaion of a stylesheet is the only exception where the documentation is written as a subelement of the target element (xsl:stylesheet). To mark a documentation element as a stylesheet documentation the type attribute of the xd:doc element must be set to stylesheet. A stylesheet documentation can have the following subelements (properties): xd:author, xd:copyright, xd:cvsId, xd:svnId. For example:

<xsl:stylesheet ...>
  <xd:doc type="stylesheet">
    ...
    <xd:author>ibirrer</xd:author>
    <xd:copyright>P&P Software, 2007</xd:copyright>
    <xd:cvsId>$Id: XSLTdocConfig.xml 42 2009-01-16 15:02:32Z ibirrer $</xd:cvsId>
  <xd:doc/>
  ...
</xsl:stylesheet>

Properties can be added by writing a property extension. See the properties directory of the XSLTdoc installation for examples.

Stylesheet Parameter

To document a stylesheet parameter you can use the type attribute of the xd:doc element to define its type:

<xsl:stylesheet ...>
...
  <xd:doc type="string">
    A Stylesheet parameter of type string.
  </xd:doc>
  <xsl:param name="outputDir"/>
  ...
</xsl:stylesheet>

Function/Template Documentation

The parameter of a template or a function can be described with a xd:param element. The name attribute is obligatory for templates and functions while the type attribute is optional for template definitions.

<xd:doc>
  A template with a parameter of the type string.
  <xd:param type="string">The string to be processed.</xd:param>
</xd:doc>

Look at the source code of the XSLTdoc tool for more examples. The source code is accessible through this website. Just go to a detailed description of a template or function and click on the source link.

Inline tags

You can use so-called inline tags to tag special parts inside a xs:short or xd:detail element. The xd:xml inline tag can be used to print XML to the output. The whole xml inside the tag is transformed to html by XSLTdoc.

<xd:doc>
  <xd:detail>
    The following XML inside the xd:xml tag is printed exactly as it shows
    here:
    <xd:xml>
<html>
  <head></head>
  <body>
    Bla
  </body>
</html>
    </xd:xml>
  <xd:detail>
</xd:doc>
<xsl:...>

Developing and contributing

You don’t need to build this project in order to use it. If you want to build it anyway, keep reading.

After cloning the repository:

npm install
npm install -g grunt-cli  # allows you to run `grunt` from any terminal
grunt

To get help with grunt, including a list of tasks defined for this project:

grunt --help

Publishing docs to GitHub pages

You’ll need to have commit access to the GitHub pages repo. To publish, first run a build, and then bring up the “doc” pages in a static server to make sure they look okay. Then run

grunt gh-pages

Releasing and publishing

Here’s a checklist for doing a release. Don’t bump the version number – that will be done automatically.

  • Update release-notes.md

  • Wipe out any development side-effects:

    npm uninstall -g xsltdoc
git clean -ndxff    # dry-run "super clean", make sure it's okay, then
git clean -dxff
git checkout -f

  • Do npm install and grunt; make sure tests pass.

  • Check the docs. Start http-server and then go to http://localhost:8080/doc.

  • Try out the instructions for using the tool with a new project. Currently:

    npm install -g .    #=> in the XSLTdoc directory
export XSLTDOC=`pwd`
mkdir -p ~/temp/try-xsltdoc
cd ~/temp/try-xsltdoc
xsltdoc --init
cp $XSLTDOC/test/test.xsl .
xsltdoc
http-server  # Go to http://localhost:8080/doc, and verify

  • Make sure everything is committed and pushed.

  • Tag, publish, and re-generate the gh-pages:

    grunt release

See also

Notes on Node.js implementation

I (Chris Maloney) ported this to Node.js as a proof-of-concept, to see if it would be practical to use Node.js and npm infrastructure, along with node-java, to manage XML/XSLT projects. I think it was a success: as long as the basic prerequisites are met, that the user has Node.js and Java installed, then installing and running this app are very easy and simple – much easier than trying to download, configure and install an XSLT application by hand.

Copyright And Licence

This license information was copied from the XSLTdoc home page on 2016-02-14.

The software and documenation downloadable from this site is made up of the following items:

  • Software and documentation for the XSLTdoc documentation tool. The copyright for these items belongs to P&P Software. These items can be downloaded and used under the terms of the GNU General Public Licence.
  • The The Saxon XSLT and XQuery Processor from Saxonica Limited. This software is used and distributed in accordance with the terms of the Mozilla Public License Version 1.0.
  • The XML to HTML Verbatim Formatter with Syntax Highlighting. This software was downloaded from http://www.informatik.hu-berlin.de/~obecker/XSLT/. There was no license information available on this site at the time of downloading (October 2004).

THE XSLTdoc DELIVERABLES ARE PROVIDED "AS IS’’ AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE PROVIDER OF THE SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.