Re: xsl/xslt coding standard

Mike Brown wrote:

I add frequent comments to explain why I'm doing whatever I'm doing.

At an XSLT Q&A in Oxford recently, someone asked about adding comments
to stylesheets, and it made me think of the discussions we had ages
ago about the different ways of embedding *structured* comments in
a stylesheet. We talked then about using extension elements, but it's
a real pain because you have to have xsl:fallback in each of them to
stop processors getting worried.

For the XSLT Standard Library, which is all about establishing
engineering standards for XSLT stylesheets, I adapted Norm Walsh's
DocBook-in-XSLT approach.  It seems to work just fine, and I
haven't observed any problems requiring xsl:fallback.

<xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:doc="http://xsltsl.org/xsl/documentation/1.0"
  exclude-result-prefixes="doc"
  version="1.0">

  <doc:book xmlns="">
    <bookinfo>
      <title>XSLT Standard Library</title>

    <para>Everything in here is DocBook doco</para>
  </doc:book>
</xsl:stylesheet>

There is specific support for documenting templates
(parameters, return results, etc).

The library comes with stylesheets to extract the documentation
and turn that into HTML.

One possibility that came to mind, though, was being able to specify
one or more documentation-element namespaces for adding documentation
to the stylesheet. So something like:

<xsl:stylesheet version="2.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:html="http://www.w3.org/1999/xhtml"
                documentation-element-prefixes="html">

<html:p>Here's some documentation of my stylesheet</html:p>

<xsl:template match="/">
  <html:p>And I can use it within templates too!</html:p>
  ...
</xsl:template>
                </xsl:stylesheet>

What do y'all think?

Cheers,
Steve Ball

--
Steve Ball            |   XSLT Standard Library   | Training & Seminars
Zveno Pty Ltd         |     Web Tcl Complete      |   XML XSL Schemas
http://www.zveno.com/ |      TclXML TclDOM        | Tcl, Web Development
Steve.Ball@xxxxxxxxx  +---------------------------+---------------------
Ph. +61 2 6242 4099   |   Mobile (0413) 594 462   | Fax +61 2 6242 4099