Self documenting XSLTs

• Download files - 9.9 Kb

Introduction

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

Background

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">
    ...
</xsl:template>

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:documentation>
  <focas:system>CD Output Master XSLT</focas:system>
  <focas:description>Imports all necessary sheets, and Project 
    specific variables are set here</focas:description>
  <focas:fileName>$Source: 
    o:\\cvs_tol_repository/publishing/cdspecific/cd.xsl,v 
  $</focas:fileName>
  <focas:author>Mark Focas</focas:author>
  <focas:version>$Revision: 1.2 $</focas:version>
  <focas:date>6 June 2003</focas:date>
  <focas:lastModified>
    $Date: 2003/06/13 05:50:07 $</focas:lastModified>
  <focas:revisionHistory>
    <focas:revision>
      <focas:date>10 June 2003</focas:date>
      <focas:revisionAuthor>Mark Focas</focas:revisionAuthor>
      <focas:comment>Added menu variables</focas:comment>
    </focas:revision>
    <focas:revision>
      <focas:date>12 June 2003</focas:date>
      <focas:revisionAuthor>Mark Focas</focas:revisionAuthor>
      <focas:comment>Another lang attribute</focas:comment>
    </focas:revision>
  </focas:revisionHistory>
  <focas:notes>
    <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
    </focas:note>
  </focas:notes>
</focas:documentation>

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

History

• 10 June 2003 - Added HTML support for notes