Subject: RE: [xsl] Should You Comment XSLT And If So, How? From: "Martinez, Brian" <brian.martinez@xxxxxxxx> Date: Wed, 19 Feb 2003 07:37:30 -0700 |
> 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
Current Thread |
---|
|
<- Previous | Index | Next -> |
---|---|---|
Re: [xsl] Should You Comment XSLT A, Simon Kelly | Thread | RE: [xsl] Should You Comment XSLT A, Dimitre Novatchev |
[xsl] String comparison (>), jfi | Date | Re: [xsl] The Perils of Sudden Type, Charles White |
Month |