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

> From: Dimitre Novatchev [mailto:dnovatchev@xxxxxxxxx]
> Sent: Wednesday, February 19, 2003 8:39 AM
> Subject: RE:  Should You Comment XSLT And If So, How? 
> 
> --- "Martinez, Brian" <brian.martinez@xxxxxxxx> wrote:
> > Funny you should ask . . .
> 
> > 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).
> 
> The problem with this approach, as other people already noted, is that
> if you put a doc:something element inside a template, it will be
> treated as a literal result element and will be output as part of the
> instantiation of this template.
> 
> 
> This was discussed extensively in a more recent thread:
> 
> http://sources.redhat.com/ml/xsl-list/2002-08/msg00602.html

You're right, of course, which is why you'd need to apply a stylesheet to
the source tree to strip out the extension elements prior to deployment, or
at least use xsl:fallback and add extension-element-prefixes to the
stylesheet element.  As Jeni mentions, it's not elegant, but it's simple
enough to implement in our deployment process to make the tradeoff
acceptable.

We still have the issue of Xalan throwing TransformerExceptions in the logs
during dev-testing (because the namespace URI references a non-existent
resource), but this is merely annoying in my view, since the stylesheet
still renders properly.  I think the benefits of being able to build
structured documentation offset the minor annoyances, but as always YMMV.

cheers,
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