|
[XSL-LIST Mailing List Archive Home]
[By Thread]
[By Date]
[Recent Entries]
[Reply To This Message]
Re: Should You Comment XSLT And If So, How?
Subject: Re: Should You Comment XSLT And If So, How?
From: Ted Stresen-Reuter <tedmasterweb@xxxxxxx>
Date: Tue, 18 Feb 2003 23:00:26 -0600
|
Very interesting... thanks for the detailed response! This is pretty
much what I was sensing would be the case...
On Tuesday, February 18, 2003, at 10:25 PM, Ryan Gallagher wrote:
I am just getting settled with XSLT myself but the few books i've read
on the
subject, and my fondness of source generated documentation... leads me
to the
approach that follows:
Use XML TAGS in your xsl...
<doc type="variable">
<desc>This variable is for X</desc>
</doc>
<xsl:variable name="foobar" select="Hello World!"/>
<doc type="template">
<desc type="short">This template does foo.</desc>
<desc type="long">I'm the verbose desc...</desc>
</doc>
<xsl:template match="foo">
...
</xsl:template>
This looks a lot like XML schema to me. Could we call it a schema for
XSLT documentation?
Granted normal comments will still have their place. But anything
that you
would specifically like to be able to parse out into "pretty
documentation" to
go alongside your API docs or whatever, could be created from these
tags using
XSLT itself to do the parsing. Gotta love internal solutions!
Yeah, I'm nearly speechless. This is truly a novel approach for
removing code documentation from the code itself. Invisibility by
assimilation ;-)
If you like you can even give your comments a namespace and DTD, but
from what
i've read/understand anything not in the xsl namespace will be safely
ignored
outside of templates. Inside templates i'm not positive, but
namespaces would
certainly resolve the conflicts.
Ok, so the big question is, do we know of an XSLT style sheet a la
javadoc for processing XSLT documents that have been prepared with this
documentation? That would be, well, wonderful!
Aside:
I use normal <!-- --> comments to cause my editor (vim) to fold up
blocks of
code by default. With foldmethod set to marker you can do the
following.
<!-- Template: foo {{{ -->
<xsl: template name="foo" match="example">
...
</xsl:template
<!-- }}} -->
Would result in a collapsed object:
# Template: foo
-->-----------------------------------------------------#
Wish my text editor did that...
This is all probably overkill for small projects (cept maybe the
folding) but if
you undertake a large xslt project, source generated documentation is
very handy.
And in this case, invisible. It integrates with the code, which is a
good thing. Thanks again for the feedback.
Ted
--
Ryan Gallagher (binerman)
binerman@xxxxxxxxxxxxxxxxxxxxx
The Parchive Project
http://parchive.sourceforge.net
http://sourceforge.net/projects/parchive
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list
 |
PURCHASE STYLUS STUDIO ONLINE TODAY!
Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced!
Download The World's Best XML IDE!
Accelerate XML development with our award-winning XML IDE - Download a free trial today!
Subscribe in XML format
| RSS 2.0 |
|
| Atom 0.3 |
|
|
Cart
