This is the mail archive of the xsl-list@mulberrytech.com mailing list .


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

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


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

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]