RE: xsl self-documentation - ideas

Subject: RE: xsl self-documentation - ideas
From: "Pawson, David" <DPawson@xxxxxxxxxxx>
Date: Mon, 26 Jun 2000 16:24:00 +0100
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[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...

=======================================

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


Current Thread