RE: xsl self-documentation - ideas
Gathering up the mail to date: - Further comments requested. Regards, DaveP Problem: Stylesheets are not inherantly self documenting. It is helpful to other users if documentation could be added in a manner which is shared with other users, and hence can be more readily understood. Towards a solution. Purpose: To document a stylesheet with respect to its purpose. Outline: Design goals. To be able to extract stylesheet documentation readily from within a stylesheet. To be able to use the stylesheet without the documentation 'getting in the way'. Ideas: Things One Should Document in a Stylesheet 1. Prime purpose of any simple template 2. Explanations of conditional processing logic. Conditional processing happens (at least) two ways: through template matching (e.g match="p[@show='extralarge']") and through <xsl:if>/<xsl:choose> 3. Use of global variables. To include Stylesheet parameters. The logic of parameters and how/why they get passed. And this folds into 1. when we start talking about fancy recursive templates. 4. Interpretation of any special select patterns. Grouping/sorting logic could fall into this category. 5. Reason for each import/include 6. Use of namespaces, when reason not obvious 7. Purpose of each mode 8. Noteworthy dependence on built-in rules 9. Interpretation of complex when/if tests 10. Purpose of each keyspace 11. Overall purpose of the stylesheet, location (url?)of the DTD. 12. Which source document elements are excluded from output, and why. (empty templates) JT. I'm not sure there's a clear typing evident from these kinds of explanations. There do seem to be levels of explanation -- explanations at the stylesheet level, at the template level, within the template, and perhaps of particular attribute values as well (such as funky select attributes). I do think some clarification of requirements would help direct a design. DP. This does introduce levels of description. Highest to lowest Stylesheet template within template. Another question is how this tag structure should be validated. Clearly a DTD isn't going to get far. Schematron? DP. What would be the purpose of this validation? Coverage of the DTD? Validity as a stylesheet/XML document? =============================================== solution options. DP. Like the idea of using xpointer within the stylesheet! due to lack of implementations it would be nice to avoid (work round) for the time being. JT. These look like a good starting point. As Wendell pointed out, many of these highlight *what* the comments relate to. I'd therefore suggest having an extension 'doc:id' attribute that can be added to any XSLT element so that they can be easily referred to. We could have a general comment element, which has an attribute that points to the element (or attribute) that is being commented on, either using the id or through a full XPointer. Something like: <xsl:comment xlink:href="#template-x"> <xsl:comment xlink:href="#xpointer(//xsl:variable[@name='root'])"> <xsl:comment xlink:href="#xpointer(following-sibling::xsl:apply-templates/@select)"> Comments could refer to the element immediately following by default by having the default value for xlink:href be: #xpointer(following-sibling::*) It also strikes me that in documenting a stylesheet it's useful to be able to point at particular templates (and other elements) within the documentation itself. Maybe there should be nested comments, or maybe there should be a linking element like: passed by the <doc:ref xlink:href="#template-x">x-matching template</doc:ref>... (or maybe both). I have a tendancy to over-abstract these things, though, and it might be simpler to avoid XLink/XPointer. I've also been thinking about what kind of things you want to *say* within the documentation by thinking about the styling conventions that I use in my explanations: 1. literal values e.g. if the @role is <doc:literal>parent</doc:literal>... 2. variables/parameters e.g. this sets <doc:var>foo</doc:var> to... 3. XPaths e.g. selects the ancestor with <doc:xpath>ancestor::*</doc:xpath>... perhaps with internal subelements?!? 4. elements, with a 'role' attribute e.g. the content of <doc:element role="input">list</doc:element>... produces a <doc:element role="output">li</doc:element>... perhaps with a namespace attribute or subelement? 5. attributes, again with a 'role' attribute e.g. the value of <doc:attribute role="input">role</doc:attribute>... sets the <doc:attribute role="output">title</doc:attribute> to... perhaps with a namespace attribute or subelement? 6. keyspaces e.g. indexes into the <doc:key>records</doc:key> with... 7. functions e.g. using <doc:func>lang</doc:func> to test whether... and as David Marston points out 8. modes e.g. processed in <doc:mode>copy</doc:mode> rather than the default... ======================================= Issues: 1. DP. How to access the element of the stylesheet which is active? Is this feasible? 2. How to output the resulting documentation? Solution options: Use of xsl:message? use of saxon:output or equivalent. Issue of append feature? Or output as part of the main processing via a runtime parameter to the stylesheet, or by processing the stylesheet with a seperate stylesheet? 3. ?? 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