RE: XSLT Documentation (Was: RE: How...interpreted?)

Subject: RE: XSLT Documentation (Was: RE: How...interpreted?)
From: Jeni Tennison <Jeni.Tennison@xxxxxxxxxxxxxxxx>
Date: Fri, 23 Jun 2000 17:11:43 +0100
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.
> 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'])">

Comments could refer to the element immediately following by default by
having the default value for xlink:href be:


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

(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...




Dr Jeni Tennison
Epistemics Ltd, Strelley Hall, Nottingham, NG8 6PE
Telephone 0115 9061301 ? Fax 0115 9061304 ? Email

 XSL-List info and archive:

Current Thread