1. XSLStyle™ documentation environment for XSLT stylesheets

1.1. Introduction

At XML'2004 and XTech'2005 I demonstrated to attendees my technique for embedding an arbitrary formatting vocabulary into an XSLT stylesheet in such a way that by dragging the stylesheet into an XSLT-aware web browser, the stylesheet is formatted into a fully-documented report of all the documentation found therein, plus a report of any inconsistencies detected.

The benefits of this would not be immediately obvious to writers of monolithic stylesheets. However, for large stylesheet libraries with multiple stylesheet fragments being referenced in an import tree, one can easily lose track of where things can be found and how things are related in the stylesheet fragments. This fully documented report keys off of the import tree for a stylesheet and summarizes all of the top level elements from all of the stylesheet fragments into a single hyperlinked alphabetized index indicating in which modules each named top-level construct can be found. Two of my customers have stylesheet libraries with dozens of stylesheet fragments in the import tree from a single XSLT stylesheet.

Performing a view/source on the reported document in the browser reveals the actual stylesheet, though typically this would be examined in a text editor.

1.2. History

This stylesheet came about from my own need to check for completeness, because not only does the stylesheet format the embedded documentation, it checks that the embedded documentation is "complete" with respect to its own rules for what constitutes completeness. I experimented with the need to force the stylesheet writer to document all of the top-level constructs in an XSLT stylesheet, and for constructs like xsl:template check for the presence of xsl:param and associated documentation.

Thus, from a programmer's perspective of documentation completeness, a "clean" report of the stylesheet would give the stylesheet writer the assurance that not only every top-level element in the stylesheet was formally documented, but that all of the parameters of templates were also documented. All this and all of the top-level elements are indexed from all modules in the import tree. All this would, hopefully, promote easier maintenance downstream.

I then deployed this embedding the DocBook vocabulary in a customer's set of stylesheets in a stylesheet library, followed by embedding the Intelligence Community's vocabulary in another customer's set of stylesheets in a different library. Interestingly, the IC vocabulary documents the stylesheets that present the IC vocabulary in HTML, so it is recursive in that the stylesheets are formatting their own documentation in Internet Explorer.

In both cases, I deployed very large XSLT stylesheet libraries following my practice of extensively using namespaces (I'm a big fan of XML namespaces) to qualify the names of top-level constructs. The level of consistency checking implemented in each case is less than what is done in the current stock XSLStyle™, primarily because the stylesheet writers had not yet embraced the consistency checking, but also because more consistency checks have come to mind after working with both of these stylesheet libraries. Getting stylesheet writers to embrace the documentation and business-rule enforcement has not been easy.

I made XSLStyle™ publicly available in November 2005 and announced it at XML'2005. In March 2006 I revamped it to be more easily adaptable to new embedded vocabularies other than DocBook. This required turning the import tree inside out, so users updating to the March 2006 environment from the November 2005 environment need to know that the top of the import tree has changed to how it is documented below.

Over the years since, this package has been updated to enforce a number of stylesheet-writing rules for XSLT 2.0 such as declaring types for parameters, functions, and top-level variables, as well as reporting the arity of functions in declarations and the index.

1.3. Download

The current download package supports DocBook, DITA or XHTML as the documentation vocabulary embedded within the XSLStyle™ scaffolding and is found at the main resources index entry. It includes a complete snapshot of the DocBook HTML stylesheets, and a subset snapshot of the DITA HTML stylesheets. Of course you can use your own stylesheet installation by changing the relevant xsl:import statements in xslstyle-{vocabulary}.xsl and deleting the delivered subdirectory.

You can create your own XSLStyle™ environment for a different vocabulary for the embedded documentation by writing xslstyle-{vocabulary}.xsl and importing the xslstyle-core.xsl as is done in xslstyle-docbook.xsl.

Using CSS stylesheets you can decorate your formatted results with quite stunning appearances. Contributed appearances are included in the package, as well as a debug appearance exposing CSS style names to help you develop your own appearance.

1.4. Use

To see the XSLStyle™ stylesheets in operation, they are themselves documented using XSLStyle™ conventions, so you have three options to view the documentation and completeness report (though they are complete so you won't see any errors; I will add tests in the future to illustrate incomplete reports):

(1) - open up Internet Explorer and drag xslstyle-docbook.xsl from an open folder onto the browser canvas which automatically uses the embedded stylesheet association for the location of the formatting stylesheet

Note that Internet Explorer does not recognize hyperlinks when browsing a file with extension ".xsl" so none of the links actually work, but you can check the presence of the inconsistency report and jump to the bottom of the file if it exists. Note the next option.

(2) - browse the test harness xslstyle-docbook.xml that is a skeleton XSLT stylesheet with a .xml extension; this adds a redundant layer to the import tree, but Internet Explorer deigns to allow hyperlinks to work for this XML file even though it doesn't for the XSLT XML file.

(3) - run a standalone XSLT transformation engine to produce an HTML result that can be browsed in any browser, as in the following Saxon invocation that specifies the use of stylesheet association for the location of the formatting stylesheet (note this has already been done and is viewable in the xslstyle.html in the package):

java -jar %saxon%saxon.jar -o xslstyle-docbook.html -a xslstyle-docbook.xsl

Note that XSLStyle™ does not yet work by dragging a stylesheet or a stylesheet harness into Firefox because a required extension function (the conversion of a result-tree fragment into a node-set) is not available in its embedded XSLT processor.

1.5. Documentation

The documentation is embedded in the stylesheet using the stylesheet's own documentation framework. To review the documentation, just drag the xslstyle-docbook.xml test harness, or the xslstyle-docbook.xsl stylesheet from a folder into Internet Explorer or any other web browser that supports XSLT 1.0 with an extension for the conversion of a result tree fragment into a node set.

Alternatively, one can just browse xslstyle-docbook.html which was created using xslstyle-docbook.xsl to format itself.

1.6. Summary

This environment is a good example of the power of namespaces in that a complete suite of stylesheets using namespace-qualified top-level elements can incorporate an off-the-shelf XSLT library (first in the two independent cases I've used of DocBook and the IC vocabulary, and now a third case of yet another custom vocabulary but now with a commonly imported sub-tree) without interfering with the library, and produce a formatted HTML result suitable for a browser.

We are pleased to make available this resource free for public use, provided on an "AS IS" basis without formal support or warranty of any kind. Please see the licensing information in the stylesheets for details.

We would appreciate any feedback you have, or suggestions for changes and improvements; please forward your comments to info@CraneSoftwrights.com.

1.7. Testimonials

We are starting to find some testimonials on the use of XSLStyle™, such as from Florent Georges.

If you have a testimonial to share, please let us know.