A nice XSLT documentation tool

Taking "self-documentation" to a new level.

I just learned from Uche and Chimezie's del.icio.us bookmarks page about a very nice tool on the Web Kanzaki for generating XSLT stylesheet documentation. When you go to the tool's web page, you're looking at the output of the tool run on itself. It looks great, due to two simple tricks, the first being quite clever:

[web kanzaki]
  • It's easy enough to add a processing instruction to an XML file to tell a browser that, upon retrieving that file, it should run a particular XSLT stylesheet on it. That stylesheet typically creates HTML output, and the browser displays that HTML, while still showing the original XML when you do a "View Source". (I've enjoyed doing this to prototype new link architectures.) Kanzaki Masahide has done this recursively, pointing the XSLT documentation stylesheet at itself, so that when you go to the URL http://www.kanzaki.com/parts/xsltdoc.xsl you see an xsltdoc.xsl report about the xsltdoc.xsl stylesheet.

  • To make it look even nicer, the result also points at CSS stylesheet.

If you have a lot of XSLT that isn't well-documented, running it all through xsltdoc.xsl is an easy first step.

While I'm getting to appreciate XQuery more and more lately, this is the kind of area where XSLT really outshines XQuery—the idea of using XQuery scripts to read or write other XQuery scripts is pretty far-fetched, while using XSLT stylesheets to read or write other XSLT stylesheets is simple and productive. (Well, not too simple if you don't have a good handle on how to manipulate namespaces in XSLT, but it's not too difficult.) This kind of automation isn't just an XML geek party trick, but something that becomes increasingly useful as processing-intensive XML manipulation scales up. That's the manipulation itself that I'm talking about scaling up; when you scale up the size of the XML content, XQuery—or, more specifically, XQuery engines—start to demonstrate their advantage over the XSLT processors that need all of their input to be in memory at once.

Mr. Kanzaki's webpage shows that in addition to interesting XSLT work, he's done some cool RDF projects and also plays the upright bass. I'd love to meet him someday; we'd have a lot to talk about.