Re: [xsl] xsl/xslt coding standard

Subject: Re: [xsl] xsl/xslt coding standard
From: Francis Norton <francis@xxxxxxxxxxx>
Date: Sun, 18 Aug 2002 08:44:18 +0100
May I suggest John Cowan's IBTWHS ( which is the DTD for an XHTML subset intended for embedded documentation?


Larry Garfield wrote:

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

XSL-List info and archive:

Current Thread