XSLTdoc
XSLTdoc is a Javadoc-like tool for all versions of XSLT (1.0, 1.1, 2.0). It defines conventions to document "code elements" directly in the source code. These "documentation elements" are then extracted by the XSLTdoc tool to build a documentation consisting of several linked HTML pages which provide easy browsing through the documentation. The XSLT source code is available with syntax highlighting.
XSLTdoc was developed in a project funded by the European Space Agency under contract 18664/04/NL/LvH.XSLTdoc is written in XSLT 2.0 and is documented with XSLTdoc (This page). It is freely available on a GPL licence.
Project Page on sourceforge.
Please report bugs by using the bug tracking tool (Choose 'XSLTdoc' project in the upper right corner).
Any comments on XSLTdoc are welcome. Email us.
Table of Contents
- News
- Features
- Installing XSLTdoc
- Running XSLTdoc
- Documenting the code
- Download
- Copyright And License
News
- January 5, 2005: Release 1.1 is available for download
- December 20, 2004: Released Version 1.0.1
Features
- Documentation is embedded in the XSL program
- Documenting of XSLT 2.0 functions
- Syntax highlighted source code browsing
- Generates documentation a whole set of stylesheets
- Generates documentation for included and imported stylesheets
- Layout is customizeable with CSS stylesheets
- Site layout is based on a customizeable/interchangeable html template
- Easely extensible with new tags
- Open source under GPL license
- Written in XSLT
Installing XSLTdoc
Installation of XSLTdoc is simply done by unzipping the XSLTdoc distribution file in a dedicated target directory (usually called XSLTdoc).
Running XSLTdoc
XSLTdoc is written in XSLT 2.0. You need an XSLT 2.0 processor to run it. The downloadable package of XSLTdoc includes the free version of the Saxon XSLT and XQuery Processor from Saxonica Limited, which needs an installation of a java virtual machine to be run.
To generate a documentation for one or more XSLT programs you need to write a configuration file which inlcudes all the information needed for the generation process. The configuration file is a simple XML file. Use the template below as a starting point for your own configuration file. Not mandatory elements are marked.
<?xml version="1.0" encoding="UTF-8"?> <XSLTdocConfig> <Title>The title used on the main page</Title> <Introduction> This section is copied to the main documentation page. It can include any HTML tags. </Introduction> <!-- The absolute or relative path to the target directory where the HTML files are created. If a relative path is used it is always relative to the config file. --> <TargetDirectory path="../doc"/> <!-- The absolute or relative path to the source directory. This is where the XSLT source files can be found. If a relative path is used it is always relative to the config file. --> <SourceDirectory path="./"/> <!-- A list of source code files which shall be documented. Only stylesheets which are not included by another have to be listed here. The included stylesheets are found automatically by following the include or the import statements in the including stylesheet. Relative references are relative to the SourceDirectory defined above. --> <RootStylesheets> <File href="xsltdoc.xsl"/> <File href="test.xsl"/> </RootStylesheets> <!-- A list of CSS Stylesheet files which should be added to the standard CSS file included (XSLTdoc.css) - Not mandatory - media attribute optional. --> <AdditionalCSS> <File href="print.css" media="print"/> </AdditionalCSS>
To start the generation process use the configuration file as the input for the xsltdoc.xsl program. The command using Saxon 8 XSLT processor looks like this (while being in the XSLTdoc installation folder):
java -jar lib/saxon8.jar <configuration file> xsl/xsltdoc.xsl
Fonts, colors and layout of the HTML documentation are defined in two CSS files which can be found in the CSS folder of the installation. Copy both files to the folder where the documentation was generated. With ant this step can easily be automated. See the build.xml ant-file that is used to generate the documentation for XSLTdoc as an example:
<?xml version="1.0" standalone="yes" ?> <project name="XSLTdoc" default="xsltdoc" basedir="."> <description>Ant Build file for the XSLTdoc program</description> <path id="classpath"> <pathelement location="lib/saxon8.jar" /> <pathelement path="${java.class.path}" /> </path> <target name="xsltdoc"> <delete dir="doc" /> <copy todir="doc"> <fileset dir="css"> <filename name="*.css" /> </fileset> </copy> <xslt force="true" style="xsl/xsltdoc.xsl" in="xsl/XSLTdocConfig.xml" out="doc/log.txt"> <!-- The target directory must be given relative to stylesheet --> <classpath refid="classpath" /> </xslt> <delete dir="doc/log.txt"/> </target> </project>
If you simply want to create a documentation without writing a config
file you can use the stylesheetsMultiple.xsl
program. The input
is a stylesheet file and a targetDir parameter for the XSLT processor.
With Saxon 8 the command to create the XSLTdoc documentation looks like
this (while being in the XSLTdoc installation folder):
java -jar lib/saxon8.jar <XSLT file> xsl\stylesheetMultiple.xsl targetDir=<Destination direcory>
Documenting the code
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: xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xdoc="http://www.pnp-software.com/XSLTdoc" version="2.0"> ... <xsl:stylesheet>
The documentation is normally added before the source element that should
be documented. Generally this looks like this (with the XSLTdoc namespace
mapped to xd
):
<xd:doc> ... </xd:doc> <xsl:...>
The only exception to this is documentation for the stylesheet itself. It
must be a child element of the stylesheet element and be declared as is
with the type attribute of the xd:doc
element.
<xsl: xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xdoc="http://www.pnp-software.com/XSLTdoc" version="2.0"> <xd:doc type="stylesheet"> ... <xd:doc/> ... <xsl:stylesheet>
Any XSLTdoc documentation is enclosed in a xd:doc
element.
The possible sub elements depend on the XSLT element which should be
described. If you just want to write a plain comment for a XSLT element
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 showed only in the detailed view of the documentation. </xd:doc> <xsl:...>
No HTML elements are allowed in the text. If you want to use HTML tags within short and detailed description the text 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:...>
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 only possible for
template definitions.
<xdoc:doc> A template with a parameter of the type string. <xdoc:param type="string">The string to be processed.</xdoc:param> </xdoc:doc>
To document a stylesheet parameter you can use the type attribute of the xd:doc element to define its type:
<xsl:stylesheet ...> ... <xdoc:doc type="string"> A Stylesheet parameter of type string. </xdoc:doc> <xsl:param name="outputDir"/> ... </xsl:stylesheet>
The elements listed below can only be used in a stylesheet documentation (type=stylesheet) element.
-
xd:author
-
xd:copyright
-
xd:cvsId
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 to print print an 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:...>
Download
Downloads are available through the sourceforge project page.
By downloading any of these files you are accepting the licence condition stated below.
Copyright And Licence
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.