This is the mail archive of the
xsl-list@mulberrytech.com
mailing list .
RE: xsl/xslt coding standard
- From: "James Fuller" <james dot fuller at o-idev dot com>
- To: <xsl-list at lists dot mulberrytech dot com>
- Date: Sun, 18 Aug 2002 11:20:11 +0100
- Subject: RE: [xsl] xsl/xslt coding standard
- Reply-to: xsl-list at lists dot mulberrytech dot com
> 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.
I generally agree, though I would like to see something centric around
XHTML, I think its important now to reinforce the usage of XHTML.
> 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.
+1 to that
> 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
but its not xml and not part of our data model....which frankly leaves it
for human consumption
> 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.
reinventing ? I seriousely don't think that <!-- --> serve any good whats so
ever when it comes to automated processing of documents.
cheers, jim fuller
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list