Subject: Re: [xsl] xsl/xslt coding standard From: Larry Garfield <lgarfiel@xxxxxxxxxxxxxxxxxxx> Date: Sun, 18 Aug 2002 06:27:42 -0500 |
James Fuller wrote: > I generally agree, though I would like to see something centric around > XHTML, I think its important now to reinforce the usage of XHTML. Perhaps there is some level of XHTML philosophy that I'm not getting. As far as I know, XHTML is HTML turned XML, modularized so that it can be supported piecemeal by systems that can't afford to support the full spec or wouldn't know what to do with it anyway, like cell phones. Is there a broader philosophical attitude that I'm not aware of? > > 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 And an author-specific XML-structured system is really no better in that respect. > > 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. It serves just as much and as little use as /* and */ did for JavaDoc. You could build a JavaDoc-esque documentation system that uses text-structured information inside <!-- --> tags, and it could be quite useful. I'd rather see an XML-based one, too, though. My point is that not having a standard vocabulary for it, such as just adding a documentation-prefix="doc" attribute to the root element and leaving the internals of such elements to the author's preference as was suggested, doesn't buy you all that much, because then to make sense of it you would need a different extraction script for each author's tastes. OK, there would probably be a few big ones (XHTML, DocBook, RDF), but it's still only slightly more universal than /* */ and <!-- -->. Which still leaves my initial question, what exactly is it that we want to document? Honest question, I've not been documenting my XSLT that much because I'm not sure what I want to say. :-) -- Larry Garfield AIM: LOLG42 lgarfiel@xxxxxxxxxxxxxxxxxxx ICQ: 6817012 -- "If at first you don't succeed, skydiving isn't for you." :-) 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, James Fuller |
RE: [xsl] XSL support detection, James Fuller | Date | RE: [xsl] xsl/xslt coding standard, James Fuller |
Month |