Subject: RE: [xsl] Re: xsl/xslt coding standard From: "Edward L. Knoll" <ed.knoll@xxxxxxxxxxxxxx> Date: Fri, 16 Aug 2002 09:54:29 -0600 |
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
Current Thread |
---|
|
<- Previous | Index | Next -> |
---|---|---|
[xsl] Any way to intergate for the , Edward L. Knoll | Thread | RE: [xsl] Re: xsl/xslt coding stand, Robert Koberg |
Re: [xsl] variable from file, alex ek | Date | [xsl] msxml and xml:space, Simon Dell |
Month |