[XSL-LIST Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] Re: Documenting xsl code.
> The instant you move away from this, you do not have a XSLT-program > anymore, and you should call it something else, and that it may be rendered > into a XSLT-program and documentation. I think this really is the key point -- with that approach, I can't give somebody the file and say "here, this is standard XSLT, any XSLT processor will now what to do with it." furthermore it'll be a real pain when trying to tell newbie's how they should write XSLT. "well, no, this isn't real XSLT -- this is semi-XSLT that will be processed by XSLT to produce real XSLT that will then process your source document." while that approach is fine for some one who is always using their stylesheets internally, and they can be quite confident that anyone seeing their stylesheets understands what they're doing, I don't think it works for the general case. > The documentation language should not be restricted to any particular set > of DTD. maybe not "restrict" to a DTD, but how about a "suggested" DTD?? what I'm trying to say is, I would really like it if this list could agree on a semi-standard set of tags for documentation. so that if somebody has <param> <paramName>width</paramName> <paramValue>this parameter gets its value from the value of the img elem's @width tag</paramValue> </param> other XSLT developers will understand my documentation. Furthemore, somebody will be able to write a "doc-generating" stylesheet, that should work on any stylesheet, and generate documentation in some way. It will leave everyone free to create the documentation using whatever stylesheet they like (eg. maybe they only want to see the mode of templates). however, having common XML markup means that that your doc-generate.xsl works on my complexTransform.xsl, so you can look at my code and get the comments *you* want. (I'm not really suggesting a syntax like that, just for illustration purpose.) not that we should really restrict others from using a different form of documentation -- it just would be nice to have something semi-standard. Not super official, just commonly understood. but like I said, I'll go with whatever the smarter people decide. Imran XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list
|
PURCHASE STYLUS STUDIO ONLINE TODAY!Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced! Download The World's Best XML IDE!Accelerate XML development with our award-winning XML IDE - Download a free trial today! Subscribe in XML format
|