[XSL-LIST Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message]

RE: Re: xsl/xslt coding standard

Subject: RE: Re: xsl/xslt coding standard
From: "Edward L. Knoll" <ed.knoll@xxxxxxxxxxxxxx>
Date: Fri, 16 Aug 2002 09:54:29 -0600
robert knoll studio
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

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.