Re: [xsl] commenting and documenting XSLT (small survey)

["cking" <cking@xxxxxxxxxx>]

Hi y'all

this thread caught my attention last week,
first off: I want to say that I *do* see the advantages of Chris'
approach, in terms of readability while coding (more about that later)
but, also in my opinion, this is outweighed by the advantages of
using XML. Isn't that what XML is about in the first place:
extensibility, exchangeability, validatability (is that english? :) etc

I went looking in the XSL FAQ, there's a section about code
documentation there, and decided to give it a try myself, 
made a "stylesheet documentation stylesheet". Yet another 
maybe, but I'm fairly impressed with the possibilities of this.

FWIW: http://users.telenet.be/cking/webstuff/xdoc/xdoc.xsl

Advantages:
- use all the formatting and other capabilities of xhtml+css, including
pictures, tables, and hyperlinks across the stylesheet, and to/from
external uri's.
- even without adding documentation, you can apply this stylesheet
to get a display with headings on every template, and a clear distinction
between xsl- and html-elements.
- use the documentation nodes for explanations, and use plain <!--
comments for TODO's, disabling problematic code, etc.

The main disadvantage, I must admit, is the readablity inside the
code editor, with all these <xdoc:doc> and <xsl:fallback/> elems
cluttered around. But you can display it in your browser for reading
and tracking down problems, and then jump to the code editor
for editing. While I was working on the template, I already found
it very helpful. I already imagine an IDE that does this on-the-fly!

A question: in the FAQ section mentioned above, somebody
suggests a "documentation-element-prefixes" attribute (instead
of "extension-element-prefixes") does something like that exist
already? Or is there another way to do it without these xsl:fallbacks?


Greetings
Anton Triest