Subject: RE: [xsl] xsl/xslt coding standard From: "James Fuller" <james.fuller@xxxxxxxxxx> Date: Sun, 18 Aug 2002 11:20:11 +0100 |
> 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
Current Thread |
---|
|
<- Previous | Index | Next -> |
---|---|---|
RE: [xsl] xsl/xslt coding standard, James Fuller | Thread | Re: [xsl] xsl/xslt coding standard, Larry Garfield |
Re: [xsl] XSL support detection, Antonio Fiol Bonnín | Date | RE: [xsl] xsl/xslt coding standard, James Fuller |
Month |