RE: Re: xsl/xslt coding standard
The main theme of this thread appears to be inline documentation. This is something that I have been thinking about regularly with regards to XSL stylesheets. Currently I'm using "<!-- ... -->" comments (and a "standard" preamble which I have been using for several years across several technologies); at one point I played with using <xsl:comment> elements, but comments elements can't have sub-elements. I'm now thinking that inline documentation should be done using XML elements; this leaves the window open for post-processing: design documentation, help text, html documentation, .... I'm not (entirely) convienced that it makes since to automatically embed HTML for formatting: browsers are not the only mechanism by which documentation is consumed (yet). Besides XML (IMHO) is intended to represent/identify content; XSL supplies the formatting. XSL inline documentation is content; other XSL stylesheets would be applied to extract/format it. On the other hand, one of the things which I think is one of the most potentially useful/powerful elements of Java is Javadoc. Although, it doesn't seem to be used to the extent I believe it should. Code, especially complicated and/or large systems, will not be reused if future/ignorant developers/maintainers can not understand easily what it does and how to use it. Additionally, people/engineers being people, it is extremely unlikely that documentation for large/complex system will be maintained or even "travel" with the code. I have long been convinced that, in the long run, the most useful documentation is co-resident (and probably inline) with the components it's associated with. That said, it is difficult for me to ignore the potential upside of a Javadoc type mechanism when I think about inline XSL stylesheet documentation. There is also much to be said for "standardization". A set of Java classes with decent Javadoc is such treat to (re)use. An XML approach to inline XSL stylesheet documentation would seem a very natural and consistent approach. Unfortunately, it's unlikely to yield a very consistent approach except at very high/abstract level. Maybe there's some way to achieve both? Regards, Ed Knoll -- Edward L. Knoll Phone (work) : (719)484-2717 e-mail (work) : ed.knoll@xxxxxxxxxxxxxx e-mail (business): eknoll@xxxxxxxxxx e-mail (personal): edward@xxxxxxxxxxx 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