RE: xsl/xslt coding standard

> 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