Re: [xsl] xsl/xslt coding standard

[Steve Ball <Steve.Ball@xxxxxxxxx>]

Jeni Tennison wrote:
> 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.

For example:

<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>

    </bookinfo>

    <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?

If exclude-result-prefixes works OK, why introduce something new?

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


XSL-List info and archive:  http://www.mulberrytech.com/xsl/xsl-list