Click here to Skip to main content
13,253,159 members (50,750 online)
Click here to Skip to main content
Add your own
alternative version


25 bookmarked
Posted 18 Jun 2003

Self documenting XSLTs

, 18 Jun 2003
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 19:04
memberJim Crafton19-Jun-03 19:04 
GeneralRe: Have you looked at docbook Pin
Mark Focas19-Jun-03 19:21
memberMark Focas19-Jun-03 19:21 
GeneralRe: Have you looked at docbook Pin
Jim Crafton20-Jun-03 4:50
memberJim Crafton20-Jun-03 4:50 
GeneralRe: Have you looked at docbook Pin
Mark Focas23-Jun-03 22:06
memberMark Focas23-Jun-03 22:06 

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

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

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