Click here to Skip to main content
Click here to Skip to main content
Go to top

Self documenting XSLTs

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

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

License

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

Share

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
http://blog.focas.net.au

Comments and Discussions

 
GeneralHave you looked at docbook PinmemberJim Crafton19-Jun-03 18:04 
GeneralRe: Have you looked at docbook PinmemberMark Focas19-Jun-03 18:21 
GeneralRe: Have you looked at docbook PinmemberJim Crafton20-Jun-03 3:50 
GeneralRe: Have you looked at docbook PinmemberMark 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 | Mobile
Web02 | 2.8.140922.1 | Last Updated 19 Jun 2003
Article Copyright 2003 by Mark Focas
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid