This is the mail archive of the
xsl-list@mulberrytech.com
mailing list .
RE: Re: xsl/xslt coding standard
- From: "Edward L. Knoll" <ed dot knoll at cosd dot fedex dot com>
- To: XSL-List at lists dot mulberrytech dot com
- Date: Fri, 16 Aug 2002 09:54:29 -0600
- Subject: RE: [xsl] Re: xsl/xslt coding standard
- Organization: WSCR
- References: <3D4AF861.54A15060@cosd.fedex.com> <3D4B0543.E650E1C4@cosd.fedex.com>
- Reply-to: xsl-list at lists dot mulberrytech dot com
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@cosd.fedex.com
e-mail (business): eknoll@sf-inc.com
e-mail (personal): edward@elknoll.com
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list