[XSL-LIST Mailing List Archive Home]
[By Thread]
[By Date]
RE: [xsl] xsl/xslt coding standard
Subject: RE: [xsl] xsl/xslt coding standard From: "James Fuller" <james.fuller@xxxxxxxxxx> Date: Sun, 18 Aug 2002 13:07:50 +0100 |
Larry Garfield wrote > 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? no, u get it .....i would like to have a nice little 'piecemeal' bit that is general enough for documentation, similar to John Cowan's IBTWHS ( from Francis ) but able to deal with a slightly expanded scope...I had suggested reusing the meta data module...but I can see something that is a mixture of a reduced IBTWHS and meta module. I feel quite confident that XHTML is the place for this, as it imparts the native ability to document ( though as u pointed out is not necc core for this type of thing ) instead of asking XSLT or XML Schema to go outside of their problem domain and specify ( as done with xs:documentation or some sort of proposed xsl:doc does ) specific elements that would be strange to use across all markup. As stated it would be strange to be using an xsl:doc in the middle of a VOICEML document. I am quite amazed at the slow burn that XHTML is, with respect to taking over HTML especially...as I mentioned before I think that we need to promote its usage, and reduce the many headed hydra that XML is today...to something that was 'pre browser war HTML useful'. > 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 I agree, but if we are talking about a XML wide, instead of just XSL, requirement for documentation then we should probably use markup for this, I think that all I am reaching for is part 'Lingua Franca' pattern, nothing so overarching..... The difference between using <!-- --> or /* */ is trivial in implementation be it this syntax or another xml specific one. And if purely constrained to the world of markup, then I don't have an issue doing this, I can see where having snippets of xml within C code would be interesting...but possibly counterintuitive; though I do it all the time. Javadoc is useful, but would it not more useful for Javadoc to directly publish in xml form. Various transforms could produce the human documentation we love, the WSDL-like file for describing methods, possibly the UML diagrams in SVG, and a variety of fun things....which of course is the Java Doclet technology from SUN. > 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 <!-- -->. I see what where you are getting at. > 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. :-) naughty, naughty...but honestly I don't want to get into that line of reasoning, its not rare that I will perform the following when dealing with any markup in my daily life; - general documentation - code level annotation - meta data along the lines of versioning and author - the ability to specify a generic container, by just using meta:doc or doc:doc; ...in other words I may want to pop in a bit of Docbook, Dublin Core or whatever else might come done the pipe we had a similar discussion, when doing the EXSLT effort....and to a certain degree we went a little overblown....so I think that I will knock up something that is simple and fulfills the requirements of the lowly programmer just wanting to document their code. will look forward to your comments. 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, Larry Garfield | Thread | Re: [xsl] xsl/xslt coding standard, Steve Ball |
Re: [xsl] xsl/xslt coding standard, Larry Garfield | Date | Re: [xsl] XSL support detection, Wesley W. Terpstra |
Month |