RE: [xsl] Should You Comment XSLT And If So, How?

["Martinez, Brian" <brian.martinez@xxxxxxxx>]

> From: Ted Stresen-Reuter [mailto:tedmasterweb@xxxxxxx]
> Sent: Tuesday, February 18, 2003 7:51 PM
> To: XSL-List@xxxxxxxxxxxxxxxxxxxxxx
> Subject: [xsl] Should You Comment XSLT And If So, How?
> 
> As you can see by the Subject line, I'd like to know if you think you 
> should comment XSTL. And if so, How?
> 
> I'd like to say "here's what I do" but what provoked me to ask this 
> question was a realization that although XML can be 
> commented, I don't 
> really find myself needing it or making much use of it when writing 
> XSLT (which is XML).  The problem is, I've never seen an XML 
> application, just sample code. So, I was wondering, should 
> you comment 
> XSLT and if so, How?

Funny you should ask . . .

I've spent the past few weeks researching documentation systems for XSLT and
writing internal documentation standards for our codebase.

The major problem I have with using basic comment tags (<!-- -->) is that
they aren't structured.  It's a pain to extract the contents of comment
tags, assemble them in a reasonably clean format, and produce documentation
that's accessible to end-users, particularly those not familiar with XSLT.
The only other option would be to give them the source code, which might as
well be written in Kanji as far as they're concerned.  So my mandate was to
come up with a way of documenting our XSLT that was portable and produced
consistent output.

The best way to do this (IMO) is to use a namespace and bind your
documentation elements to it:

<xsl:stylesheet version="1.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
		    xmlns:doc="http://some.funky.uri.com";
                exclude-result-prefixes="doc">

Then just include everything inside doc elements, which you can format any
way you want:

<doc:template type="named">
  <doc:desc>This template transforms foo to bar.</doc:desc>
</doc:template>

You could include the above inside the xsl:template element it refers to,
then run a "doc-processor" stylesheet that grabs all of the doc elements
from your code and transforms them into whatever output you require.  (You
could also display information from the XSLT code, such as template names,
match patterns, the attribute values of xsl:output, etc.)  You could take it
a step further (as I did for our internal standards) and define a
documentation syntax for different XSLT elements such as named and
rules-based templates, global variables and parameters, and even basic
comments (i.e., instead of using <!-- --> at all, you could define
<doc:note> as a replacement).

I didn't come up with any of this on my own, of course:

http://gethelp.devx.com/techtips/xml_pro/10min/10min0201/kc020701/kc020701-1
.asp (my primary source of inspiration)
http://sources.redhat.com/ml/xsl-list/2000-07/msg00315.html (an old message
from Jeni Tennison about commenting stylesheets)
http://www.dpawson.co.uk/xsl/sect2/documentation.html (from the FAQ, some
very interesting posts on self-documenting code)

hth,
b.

| brian martinez                              brian.martinez@xxxxxxxx |
| senior gui programmer                                  303.708.7248 |
| trip network, inc.                                 fax 303.790.9350 |
| 6436 s. racine cir.                             englewood, co 80111 |
| http://www.cheaptickets.com/                   http://www.trip.com/ |

 XSL-List info and archive:  http://www.mulberrytech.com/xsl/xsl-list