Re: [xsl] xsl/xslt coding standard

[Larry Garfield <lgarfiel at students dot depaul dot edu>]

James Fuller wrote:

> - XHTML is a native format one can use for documentation, so there is a
> standard native option that is close enough to the HTML we all know and love
> ( instead of XSLT or XML schema specific, niether of who's core requirement
> is to be a language for documentation or meta data )

XHTML is not a language whose core requirement is to be a language for
documentation, either.  In that sense, DocBook is more "naturally
targeted" at documentation than XHTML is.  If we're going to say that
XSLT and XML Schema are not designed for documenting code so we
shouldn't use it for documenting code, then by extension we need to
find/develop some system that is specifically designed and optimized for
commenting code.

Personally, I'd be in favor of going as far as a W3C-standardized
XML-documentation format beyond normal <!-- comment --> tags.  That way,
just as with JavaDoc, you could easily parse it into a separate document
to serve as documentation.  The SVG folks are using RDF as a
documentation format, which has its ups and downs.  

Of course, before we do that, I have to ask, exactly what are we
commenting?  We already have a system for unstructured comments, <!--
-->.  If we're talking about structured, parsable documentation, the
first question to ask is what exactly we're documenting.  With JavaDoc,
it was fairly easy.  Methods and classes had been around long enough
that figuring out what to document about them was fairly
straight-forward.  With XSLT or other XML technologies, what exactly are
we commenting?  That's a question we have to ask before we figure out
how to comment it.  Otherwise, we're just reinventing <!-- -->, which
has already been done.

-- 
Larry Garfield			AIM: LOLG42
lgarfiel@students.depaul.edu	ICQ: 6817012

-- "If at first you don't succeed, skydiving isn't for you." :-)

 XSL-List info and archive:  http://www.mulberrytech.com/xsl/xsl-list