This is the mail archive of the
xsl-list@mulberrytech.com
mailing list .
RE: XSLT Documentation (Was: RE: How...interpreted?)
- To: xsl-list at mulberrytech dot com
- Subject: RE: XSLT Documentation (Was: RE: How...interpreted?)
- From: Jeni Tennison <Jeni dot Tennison at epistemics dot co dot uk>
- Date: Fri, 23 Jun 2000 17:11:43 +0100
- Reply-To: xsl-list at mulberrytech dot com
David_Marston@lotus.com 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@epistemics.co.uk
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list