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

--- "Martinez, Brian" <brian.martinez@xxxxxxxx> wrote:
> Funny you should ask . . .

[snip]

> 
> 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).

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




=====
Cheers,

Dimitre Novatchev.
http://fxsl.sourceforge.net/ -- the home of FXSL

__________________________________________________
Do you Yahoo!?
Yahoo! Shopping - Send Flowers for Valentine's Day
http://shopping.yahoo.com

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