[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: Steve Ball <Steve.Ball@xxxxxxxxx>
Date: Thu, 20 Feb 2003 09:39:05 +1100
xslt comment
Ted Stresen-Reuter wrote:
As you can see by the Subject line, I'd like to know if you think you should comment XSTL. And if so, How?

Of course you should! All software should be documented if it is to be usable and maintainable in the long-term.

Take a look at the XSLT Standard Library [*], which includes
standards for stylesheet engineering.  The method of
documentation used is modelled on that used by the DocBook
stylesheets [at some stage I have to take a look at
Norm Walsh's XWEB for literate programming in XSLT].

XSLTSL documentation takes the form of namespaced elements
at the toplevel of the stylesheet.  Every (public) template
is documented, with information such as the purpose of the
template, how it is to be used, parameters and expected
results.

One deficiency of this approach is that the documentation cannot
be included inside a template itself.  This was discussed
last year (check the list archives).  There was a suggestion
to include an annotation mechanism in XSLT 2.0, whereas
I suggested extending the whitespace stripping mechanism
to also allow stripping of any elements.

[*] http://xsltsl.sourceforge.net/

HTHs,
Steve Ball

--
Steve Ball            |   XSLT Standard Library   | Training & Seminars
Zveno Pty Ltd         |     Web Tcl Complete      |   XML XSL Schemas
http://www.zveno.com/ |      TclXML TclDOM        | Tcl, Web Development
Steve.Ball@xxxxxxxxx  +---------------------------+---------------------
Ph. +61 2 6242 4099   |   Mobile (0413) 594 462   | Fax +61 2 6242 4099


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



Current Thread

PURCHASE STYLUS STUDIO ONLINE TODAY!

Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced!

Buy Stylus Studio Now

Download The World's Best XML IDE!

Accelerate XML development with our award-winning XML IDE - Download a free trial today!

Don't miss another message! Subscribe to this list today.
Email
First Name
Last Name
Company
Subscribe in XML format
RSS 2.0
Atom 0.3
Site Map | Privacy Policy | Terms of Use | Trademarks
Free Stylus Studio XML Training:
W3C Member
Stylus Studio® and DataDirect XQuery ™are products from DataDirect Technologies, is a registered trademark of Progress Software Corporation, in the U.S. and other countries. © 2004-2013 All Rights Reserved.