RE: [xsl] Re: xsl/xslt coding standard

["Edward L. Knoll" <ed.knoll@xxxxxxxxxxxxxx>]

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