Re: xsl/xslt coding standard

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.

--
"Never mind manoeuvre, go straight at 'em." - Admiral Horatio Nelson