[XSL-LIST Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] RE: XSLT Documentation (Was: RE: How...interpreted?)
David_Marston@xxxxxxxxx wrote: >DaveP starts off the list of > >Things One Should Document in a Stylesheet >>1. Prime purpose of a simple template >>2. Exception processing >>3. Use of global variables. >>4. Interpretation of any special select patterns. > >...to which I add >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 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[1]/@select)"> Comments could refer to the element immediately following by default by having the default value for xlink:href be: #xpointer(following-sibling::*[1]) 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... Thoughts? 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
|