xsl-list
[Top] [All Lists]

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

2003-02-19 08:39:10

--- "Martinez, Brian" <brian(_dot_)martinez(_at_)trip(_dot_)com> 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