[XSL-LIST Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] Re: Documenting xsl code.
David Carlisle wrote: >The code extraction stylesheet then is parameterised for which options >you want to extract and it does whatever is needed to make a stylesheet. Thanks - I get now that the approach that DaveP put forward is specifically oriented towards extensibility and abstraction, either for creating sub-stylesheets for different situations or for automatically adding things to a stylesheet (e.g. debugging messages). However, the constructs seem so similar to XSLT constructs, that it seems to me that they should remain in the XSLT namespace, with any extra constructs (like loops or attributes referenced by the parameters) put in a different namespace (e.g. http://www.dpawson.co.uk), shouldn't they? >Of course whether or not such a process fits your needs is another >matter. Certainly while sketching out initial drafts having the >"documented source" be directly runnable (as in the extension >element/fallback technique) has some advantages. Speaking personally, given my only stylesheet-authoring activity thus far only runs to answering questions on this list (more's the pity), I'm not in the kind of production environment where any of the sophistication of the 'tangle' approach is really necessary. I just want to be able to include explanations in the stylesheets that I create without using comments. >> Another comment: I assume from looking at it that the 'doc' namespace is >> based on XHTML1.0? > >Only to simplify conversion to HTML:-) As said DaveP. Fair enough - I only comment on it because I view defining the XSLT-specific documentation schema as the crux of the matter. >How much of that is necessary depends in a way on how much syntactic >analysis the documentation stylesheet does. For example You could >introduce specific inline elements for describing the mode >but if the documentaion stylesheet itself was checking the mode of >each template, adding links to other uses of the same mode, indexing >such uses etc, then perhaps the need to highlight the fact that it >is in a special mode in the additional documentation text is reduced. > >Similarly if the stylesheet is automatically adding links between >calls to a named template or variable references to the documentation at >the point of definition, the kind of documentation that you need to >write is somewhat different. I agree absolutely. I would love to see a level of sophistication in the documentation-producing stylesheet that would mean that the only documentation that was required within a stylesheet was documentation that could only be produced by a human. I'm sure that it's possible to, say, generate a couple of templates that will break down an XPath and explain it in a human-readable way, but these generic solutions often miss out on the individual nuances of a particular problem, mainly involving implicit knowledge about the scope of the input that's used in constructing the XPath. So yes, the XSLT-specific documentation schema that I would like to see would be document-oriented rather than data-oriented, and would particularly document the implicit knowledge used in creating the stylesheet, namely the format of the input document. The area where a data-oriented approach might still be useful is where there are implicit categories for particular XSLT constructs, e.g., off the top of my head: * whether a xsl:key is being used as a grouping mechanism (returning node sets) or an indexing mechanism (returning single nodes) * whether a xsl:for-each is being used as an iteration mechanism (cycling through nodes) or to change the context node I don't know if these are useful, but if these (or other) categories *are* important, then they could be identified within the stylesheet and the documentation-producing stylesheet could use them to create more human-readable documentation in the same way as it uses the @mode attribute of the xsl:template to put in something human-readable about the mode of the template. In an absolutely ideal world, a schema for documenting XSLT would include design rationales (why a particular solution was used rather than a different one - using xsl:for-each rather than xsl:apply-templates, for example) and documentation of revisions. However, as these aren't XSLT-specific, it's probably best to use any generic ones that have/will be developed. Time permitting, I'll have a go at putting something more constructive together. Inputs welcome. Cheers, Jeni Dr Jeni Tennison Epistemics Ltd, Strelley Hall, Nottingham, NG8 6PE Telephone 0115 9061301 ? Fax 0115 9061304 ? Email jeni.tennison@xxxxxxxxxxxxxxxx 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
|