[XSL-LIST Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message]

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
doc mode xslt
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


Current Thread

PURCHASE STYLUS STUDIO ONLINE TODAY!

Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced!

Buy Stylus Studio Now

Download The World's Best XML IDE!

Accelerate XML development with our award-winning XML IDE - Download a free trial today!

Don't miss another message! Subscribe to this list today.
Email
First Name
Last Name
Company
Subscribe in XML format
RSS 2.0
Atom 0.3
Site Map | Privacy Policy | Terms of Use | Trademarks
Free Stylus Studio XML Training:
W3C Member
Stylus Studio® and DataDirect XQuery ™are products from DataDirect Technologies, is a registered trademark of Progress Software Corporation, in the U.S. and other countries. © 2004-2013 All Rights Reserved.