Click here to Skip to main content
11,795,848 members (73,270 online)
Click here to Skip to main content

Self documenting XSLTs

, 18 Jun 2003 49.8K 598 24
Rate this:
Please Sign up or sign in to vote.
Make your XSLTs self documenting


XSLTs are so prevalent in all forms of coding, that we should take advantage of the fact that they are XML files, and make them self documenting, by adding documentation elements and attributes in an additional namespace. This makes the code easier to understand, enabling a separation of code and documentation, which allows an XSL to be run across the file to create a report of both.

xsltdocumentor.xsl will

  • Create a summary of all templates in an XSL, including
    • What xpath expression they are matching
    • What parameters they accept
    • What variables are declared inside, and what templates are called to set them
    • Any comments attached to the template
  • All imported XSLs
  • All included XSLs
  • All global variables, their values, how they are set, and any comments included
  • All global parameters, and any comments
  • A revision history (if supplied)
  • Supplementary notes


Documentation is always the tedious part of any system. But as C# and Java programmers know, the ability to place comments in code and later extract them in a standard format makes life much easier. This system will enable standard documentation format for any XSL files you have, that adhere to these documentation guidelines. Even a standard XSL will still create reasonable documentation, because the documentation is not just based on the additional focas namespace, it also reads the XSL elements and reports on what it finds.

Using the code

In this example I implement a namespace prefix of "focas". Elements and attributes can be added from this namespace. A comment can be added to any XSL element, but at present the only comment attributes that will be reported are those on <xsl:template> elements. For example:

<xsl:template match="//content[1]"
    focas:comment="Creates the HTML shell for the page, and calls the
    pageContainer template in the utilities stylesheet to populate the
    page The headElement template in the head stylesheet is called, 
    and populates the ead with CD Rom output specific support files">

In addition, there are standard tags to document the file and its revision history. These are self explanatory, and will be picked up by xsltdocumentor.xsl. An example is shown below:

  <focas:system>CD Output Master XSLT</focas:system>
  <focas:description>Imports all necessary sheets, and Project 
    specific variables are set here</focas:description>
  <focas:author>Mark Focas</focas:author>
  <focas:version>$Revision: 1.2 $</focas:version>
  <focas:date>6 June 2003</focas:date>
    $Date: 2003/06/13 05:50:07 $</focas:lastModified>
      <focas:date>10 June 2003</focas:date>
      <focas:revisionAuthor>Mark Focas</focas:revisionAuthor>
      <focas:comment>Added menu variables</focas:comment>
      <focas:date>12 June 2003</focas:date>
      <focas:revisionAuthor>Mark Focas</focas:revisionAuthor>
      <focas:comment>Another lang attribute</focas:comment>
    <focas:note date="13 June 2003">
      This XSLT is part of a suite of XSLT's to transform the XML files 
      based on a mapping file<br />
      <strong>Output format: </strong>CD Rom

To view an HTML report, take any XSL file, and transform it using the supplied xsldocumentor.xsl. I use Nant to recursively run thru my XSL directories, creating a report for every XSL that it finds.

Points of interest

One great side benefit of this, is that we can run xsltdocumentor.xsl on itself, to document itself, so the documenter creates its own documentation. The serpent eats its own tail

Still to do

  • At present, dates are only handled as strings, it may be good to treat them differently in the future.
  • The styles could be cleaned
  • List all namespaces used in the XSL


  • 10 June 2003 - Added HTML support for notes


This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


About the Author

Mark Focas
Web Developer
Australia Australia
Working in the educational arena, automating publishing processes, developing a single XML source, multiple output format publishing solution for a distributed environment

You may also be interested in...

Comments and Discussions

GeneralHave you looked at docbook Pin
Jim Crafton19-Jun-03 18:04
memberJim Crafton19-Jun-03 18:04 
GeneralRe: Have you looked at docbook Pin
Mark Focas19-Jun-03 18:21
memberMark Focas19-Jun-03 18:21 
Yes, I have looked at docbook, However, Docbook is oriented towards print. It is fairly easy to get HTML output from Docbook, but in the end all you really end up with is a book online. In our solution we are looking at such things as activities. In Web output they will be output as javascript (possibly using SCORM - educational web standards). In print they will be printed, with feedback at the end. Video, and audio need to be treated similarly with transcripts. Unfortunately Docbook doesn't cater for all of these things.

Being in a minority of one, doesn't make you insane
(George Orwell , I think)
GeneralRe: Have you looked at docbook Pin
Jim Crafton20-Jun-03 3:50
memberJim Crafton20-Jun-03 3:50 
GeneralRe: Have you looked at docbook Pin
Mark Focas23-Jun-03 21:06
memberMark Focas23-Jun-03 21:06 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Terms of Use | Mobile
Web02 | 2.8.151002.1 | Last Updated 19 Jun 2003
Article Copyright 2003 by Mark Focas
Everything else Copyright © CodeProject, 1999-2015
Layout: fixed | fluid