XSLT Documentation (Was: RE: How is this part of the XSLT specification to be interpreted?)

[Jeni Tennison <Jeni.Tennison@xxxxxxxxxxxxxxxx>]

David Pawson wrote:
>Stylesheet that operates on our Knuthian stylesheet and outputs
>HTML. OK.... I'd missed that one totally.
>Hence the schema for documentation, to permit this to be 
>'standardised'?

I'm missing the Knuth reference, but yes.  The components that we need are:

1. a schema for documenting XSLT (XSLTDocML, for sake of argument)

2. one or more XSLT stylesheets that can take an XSLT stylesheet documented
with XSLTDocML and produce a browsable version of the documentation

3. one or more implementations of the extension elements that can... do
something useful within the XSLTDocML documentation when the XSLT
stylesheet is used

On the final point, you could imagine the documentation giving an extended
version of xsl:message, so that I could have in my XSLT stylesheet
something like:

  <doc:comment><xsl:fallback />
    When <doc:var>$foo</doc:var> is equal to 'bar', ...
  </doc:comment>
  <xsl:if test="$foo = 'bar'">
    ...
  </xsl:if>

During run time, the XSLT processor that understood the documentation
extension elements would recognise the documentation, interpret it, and
give the message:

  When $foo ('baz') is equal to 'bar', ...

You could turn this documentation-interpreting facility on and off
depending on the arguments to the XSLT Processor.  I think that could be
really useful: I could take my debugging messages out, and put
documentation in instead.

There must be code-documenting mark-up languages out there already that we
could adapt if necessary.  Anyone know of any?

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