Re: Re: xsl/xslt coding standard

Hi Dimitre,

> If I read you well, the documentation-element-prefixes will be
> needed to instruct the XSLT processor not to treat documentation
> inside templates as literal result elements. Is this correct?

Yes, that's right; similar to extension-element-prefixes except that
you don't need to use xsl:fallback inside to stop the processor from
panicking.

> One *can* have embedded structured documentation even without the
> above requirement, e.g.:
>
> <xsl:stylesheet version="1.0"
>                 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
>                 xmlns:doc="doc:documentation"
>                 exclude-result-prefixes="doc">
>
> <doc:module>Here's some documentation of my stylesheet</doc:module>
>
> <xsl:template match="/">
>   <xsl:if test="0">
>     <doc:template name="templateName" match="whatever">
>        <doc:descr>And I can use it within templates too!</doc:descr>
>        <doc:result type="tNode-set">result description</doc:result>
>        <doc:param name="someName">Param description</doc:param> 
>        <doc:param name="someOtherName">Param description</doc:param>
>        ............... 
>     </doc:template>
>   </xsl:if>
>   ...
> </xsl:template>
>
> </xsl:stylesheet>
>
> Does this make sense?

Sure. You can also do it with:

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

<doc:module>Here's some documentation of my stylesheet</doc:module>

<xsl:template match="/">
  <doc:template name="templateName" match="whatever">
     <doc:descr>And I can use it within templates too!</doc:descr>
     <doc:result type="tNode-set">result description</doc:result>
     <doc:param name="someName">Param description</doc:param>
     <doc:param name="someOtherName">Param description</doc:param>
     ...............
     <xsl:fallback />
  </doc:template>
  ...
</xsl:template>

</xsl:stylesheet>

I don't think that either of these methods (wrapping the documentation
in an xsl:if that never gets processed or using xsl:fallback inside
the documentation element) is particularly elegant. I also don't like
the extra step that's involved if you embed documentation naturally
and then use a stylesheet to remove it to give you the proper
stylesheet.

I don't think it's a massive thing, but since we're getting a new
version of XSLT anyway, we might as well fix this to make it simpler.

Cheers,

Jeni

---
Jeni Tennison
http://www.jenitennison.com/


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