Re: xsl/xslt coding standard

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

Hi Jeni,

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?

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?




=====
Cheers,

Dimitre Novatchev.
http://fxsl.sourceforge.net/ -- the home of FXSL

__________________________________________________
Do You Yahoo!?
HotJobs - Search Thousands of New Jobs
http://www.hotjobs.com

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