[xsl] Embedding stylesheet documentation using other vocabularies (e.g. DocBook)

Subject: [xsl] Embedding stylesheet documentation using other vocabularies (e.g. DocBook)
From: "G. Ken Holman" <gkholman@xxxxxxxxxxxxxxxxxxxx>
Date: Thu, 20 Oct 2005 22:17:40 -0400
Here's a different twist on an old topic: documenting XSLT stylesheets. But I haven't seen my technique being mentioned as done by others and I've been encouraged to put it in a condition to be shared.

I privately showed peers at XML'2004 and XTech'2005 my technique for embedding arbitrary documentation vocabularies in an XSLT stylesheet. I've done this twice since for customers, embedding the DocBook vocabulary in XSLT for one customer, and the Intelligence Community Metadata Standards for Publication (IC-MSP) vocabulary in XSLT for another customer.

What I think is interesting about this embedding (and the reason I pursued it in the first place) is the ability to simply drag an XSLT stylesheet into Internet Explorer and have the embedded information displayed as formatted documentation in HTML. If you do a View/Source you see the raw XSLT stylesheet. Because of the recognition of a stylesheet association processing instruction, I document my stylesheets by adding an association with a stylesheet for stylesheets, so it is automatically recognized. Using the node-set extension in XSLT 1.0 processors, I feed the transformed documentation in the arbitrary vocabulary back through imported template rules for the documentation vocabulary to produce the HTML that is seen on the screen.

I used it for my small environments and stylesheet libraries and didn't think much of exploiting it until, in both my customer situations, I was working with very large import trees: a single apex of an import tree linking together dozens of stylesheet fragments.

Two things came to light when dealing with very large import trees: (1) - how the heck does one find out where a particular top-level construct is declared in a set of 37 stylesheet fragments (the report produces an alphabetized index of all top level elements and the modules in which they are declared), and (2) - how to ensure there isn't namespace collision (I'm a big fan and user of namespace-qualified top-level construct names and modes in XSLT stylesheets).

A bonus is, with arbitrary logic available using XSLT, the ability to enforce "business rules" about XSLT stylesheets, for example: "thou shalt document each and every top-level construct and each and every <xsl:param> in an <xsl:template>" and "every name and mode declared in this fragment must be namespace qualified with one of the following prefixes". This is accomplished in the report by way of an "inconsistency section" published at the end of the report: if the section doesn't exist, there are no business rule inconsistencies. Thus, the manager of a staff of XSLT stylesheet writers could express and enforce organizational business rules on the writing of XSLT stylesheets and refuse to accept a staff member's stylesheet as complete until the inconsistency report is empty.

I did this for myself to ensure I would have no inconsistencies in my own stuff (reduces some of the early bugs from typos), but I'm learning from managers with whom I speak about this that this may, indeed, address a big problem they have enforcing the documentation of XSLT stylesheets in their shops.

Two big browser hassles:

(1) Internet Explorer deigns ".xsl" files not to be hyperlinked, thus all of the generated hyperlinks cannot be browsed after dragging the ".xsl" file in and seeing the printed report.

(2) Firefox does not implement any node-set extension, so it just plain doesn't work.

I get around both by using saxon with the "-a" option and producing an HTML file that can then be browsed by either.

Also, a browsing harness, or test harness, can be used to get around (1) ... what I do is create a 10-line XSL stylesheet that imports the stylesheet I want documented, but I name this short stylesheet ".xml", and when I drag that into Internet Explorer, lo and behold, the hyperlinks happen to work.

I've finally cleaned up my internal stuff to create a downloadable working example of this technique, and, guess what: to read the documentation you have to drag the stylesheet into a browser or run it through an XSLT processor.

I've named it XSLStyle and the code is available for free unfettered use with a flavour of the BSD license asking you to keep my copyright and not use the XSLStyle name to represent any other set of stylesheets.

It is just a method for encapsulating documentation using any vocabulary, and the stylesheet processes the stripped out vocabulary using imported stylesheets. It is "plug and play" with any vocabulary, and the downloaded package is documented using DocBook and includes the DocBook HTML stylesheets. If you have your own installation of the DocBook stylesheets, then just modify a single import statement to point to it, then you can delete the subdirectory. To support a different vocabulary, only change the template rules in that same single module and everything works.

These stylesheets are, themselves, examples of stylesheets rigourously using namespace-qualified top-level construct names and modes. I think that is the "magic" bit: by using namespace-qualified modes and template rules I can safely import DocBook, IC-MSP, or probably most other documentation vocabularies without ever risking an importation collision, as none of my constructs are in the null-URI namespace or unnamed mode.

I've made this available through my web site linked below. From the home page there are links on the right hand page. Go to the "Free resources" link, to the "XSLT Resources" section to the "XSLStyle" subsection. I won't publish the direct link in this post as I don't want the direct location archived in case it has to change.

I look forward to any comments and I hope that people find this useful. I plan to beef up the documentation based on feedback I receive.

. . . . . . . . . Ken

p.s. if anyone at Microsoft is reading this, please have your IE team review the decision to inhibit XSLT-transformed HTML hyperlinks when the file extension is other than ".xml" ... I would think that any file with any extension that happens to be XML on the inside, transformed with XSLT into HTML, should have the resulting HTML hyperlinks functional in the browser. It was a real surprise that this wasn't the case.

cc: XSL List, Yahoo XSL-FO, XML-Dev

--
World-wide on-site corporate, govt. & user group XML/XSL training.
G. Ken Holman                 mailto:gkholman@xxxxxxxxxxxxxxxxxxxx
Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/s/
Box 266, Kars, Ontario CANADA K0A-2E0    +1(613)489-0999 (F:-0995)
Male Cancer Awareness Aug'05  http://www.CraneSoftwrights.com/s/bc
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal

Current Thread