Overview

Java has javadoc; .NET has NDoc or Sandcastle. Even Perl has pod. Most programming languages have a mechanism for generating code documentation from embedded comments in the code.

XSLT is a powerful modern day programming language that allows developers to transform XML content into a wide variety of formats. It is extremely flexible and extensible and supports the ability to override "built-in" behavior with custom behavior.

There is one drawback to all this power and flexibility: debugging and diagnosing XSLT is a real headache. Templates can be scattered through dozens of physical files linked together through a maze of imports and includes, and knowing exactly which template is firing for a particular context can be enigmatic.

This is really frustrating for developers who want to extend an XSLT stylesheet application or modify the output behavior for a few elements. Which templates, parameters, attribute-sets, or other core components do I override? What is the logical flow? Which file is this named template located in? To answer these kinds of questions, developers can waste hours digging into the code trying to understand the logic. Even with a good set of tools to search the countless number of stylesheets for a specific text string (e.g., a template named 'foo'), there is no guarantee that there will only be a single instance given XSLT's import precedence behavior. Developers have to trace through the import and include stack to determine which template will be fired.

Code Commenting

We all know the benefit of good code comments. If you aren't the original developer, good commenting will save you precious time having to read and understand the logic and intent of the original developer. Even if you are the original developer, good code comments provide a point-in-time log of what you were trying to do.

In XSLT, you can comment code with standard XML comment markup () but this of little help to developers who want to see this in context of the entire application. With languages like Java or C#, developers can embed comments that ultimately can be extracted into a single set of documentation that provide other developers the ability to understand each component's interaction within the context of the entire system. XSLT doesn't provide this capability.

Introducing Doxsl

I started Doxsl in large part because I was so frustrated trying to understand someone else's poorly commented (even the very few comments were extremely cryptic), complex XSLT code for an XSL-FO application. I spent hours tracing through the code trying to find the code that changed the header and footer content. In my frustration, I whipped up some proto code in XSLT 2.0 that allowed me to see all of the templates, parameters and attribute-sets used in this application and to find out how they were called, who called them and which files they were located in. This proved very useful and I was able to quickly and intelligently override the appropriate components for my customization.

In the process of developing and using this proto code, I thought it might be useful to be able to generate code documentation not only in standard HTML, but for other markups as well. Often in my work on large system integration projects, the XSLT apps are only a small portion of the entire functionality. The entire system has to be documented, and often the XSLT code is given little attention. Doxsl enables you to integrate into larger documentation sets by allowing developers to output the XSLT reference docs into several formats including DITA, DocBook, or HTML. However, the Doxsl framework is highly extensible and can be designed to produce other formats such as ODF or WordML.