[XSL-LIST Mailing List Archive Home] [By Thread] [By Date]

Re: Documenting xsl code.

---

---

David Carlisle wrote:
>The code extraction stylesheet then is parameterised for which options
>you want to extract and it does whatever is needed to make a stylesheet.

Thanks - I get now that the approach that DaveP put forward is specifically
oriented towards extensibility and abstraction, either for creating
sub-stylesheets for different situations or for automatically adding things
to a stylesheet (e.g. debugging messages).

However, the constructs seem so similar to XSLT constructs, that it seems
to me that they should remain in the XSLT namespace, with any extra
constructs (like loops or attributes referenced by the parameters) put in a
different namespace (e.g. http://www.dpawson.co.uk), shouldn't they?

>Of course whether or not such a process fits your needs is another
>matter. Certainly while sketching out initial drafts having the
>"documented source" be directly runnable (as in the extension
>element/fallback technique) has some advantages. 

Speaking personally, given my only stylesheet-authoring activity thus far
only runs to answering questions on this list (more's the pity), I'm not in
the kind of production environment where any of the sophistication of the
'tangle' approach is really necessary.  I just want to be able to include
explanations in the stylesheets that I create without using comments.

>> Another comment: I assume from looking at it that the 'doc' namespace is
>> based on XHTML1.0?
>
>Only to simplify conversion to HTML:-)

As said DaveP.  Fair enough - I only comment on it because I view defining
the XSLT-specific documentation schema as the crux of the matter.

>How much of that is necessary depends in a way on how much syntactic
>analysis the documentation stylesheet does. For example You could
>introduce specific inline elements for describing the mode
>but if the documentaion stylesheet itself was checking the mode of
>each template, adding links to other uses of the same mode, indexing
>such uses etc, then perhaps the need to highlight the fact that it
>is in a special mode in the additional documentation text is reduced.
>
>Similarly if the stylesheet is automatically adding links between 
>calls to a named template or variable references to the documentation at
>the point of definition, the kind of documentation that you need to
>write is somewhat different. 

I agree absolutely.  I would love to see a level of sophistication in the
documentation-producing stylesheet that would mean that the only
documentation that was required within a stylesheet was documentation that
could only be produced by a human.  I'm sure that it's possible to, say,
generate a couple of templates that will break down an XPath and explain it
in a human-readable way, but these generic solutions often miss out on the
individual nuances of a particular problem, mainly involving implicit
knowledge about the scope of the input that's used in constructing the XPath.

So yes, the XSLT-specific documentation schema that I would like to see
would be document-oriented rather than data-oriented, and would
particularly document the implicit knowledge used in creating the
stylesheet, namely the format of the input document.

The area where a data-oriented approach might still be useful is where
there are implicit categories for particular XSLT constructs, e.g., off the
top of my head:
* whether a xsl:key is being used as a grouping mechanism (returning node
sets) or an indexing mechanism (returning single nodes)
* whether a xsl:for-each is being used as an iteration mechanism (cycling
through nodes) or to change the context node

I don't know if these are useful, but if these (or other) categories *are*
important, then they could be identified within the stylesheet and the
documentation-producing stylesheet could use them to create more
human-readable documentation in the same way as it uses the @mode attribute
of the xsl:template to put in something human-readable about the mode of
the template.

In an absolutely ideal world, a schema for documenting XSLT would include
design rationales (why a particular solution was used rather than a
different one - using xsl:for-each rather than xsl:apply-templates, for
example) and documentation of revisions.  However, as these aren't
XSLT-specific, it's probably best to use any generic ones that have/will be
developed.

Time permitting, I'll have a go at putting something more constructive
together.  Inputs welcome.

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

---