cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Matt Sergeant <m...@sergeant.org>
Subject Re: idea for documenting xsp logicsheets
Date Wed, 26 Jul 2000 08:34:02 GMT
On Wed, 26 Jul 2000, Donald Ball wrote:

> while talking with jeremy about the fp logicsheet, an idea occured to
> me. good logicsheets have what amounts to a nice strict API to expose to
> the outer world, but there isn't a nice easy way to document said API,
> which means we have all sorts of confusion about how to use, say, the
> cookie logicsheet, what parameters the sql logicsheet _really_ takes, what
> the fp taglib has to offer, etc. seems like we could fix this pretty
> easily with judicious use of namespaces. suppose i marked up sql
> logicsheet like so:
> 
> <xsl:template match="sql:execute-query">
> <xspdoc:desc>executes a sql query and returns any results</xspdoc:desc>
>         <xsl:variable name="use-connection">
>         <xspdoc:desc>the name of the connection pool to use</xspdoc:desc>
>                 <xsl:call-template name="get-nested-string">
>                         <xsl:with-param
> name="content" select="sql:use-connection"/>
>                 </xsl:call-template>
>         </xsl:variable>
>         <xsl:variable name="driver">
>         <xspdoc:desc>the class name of the database driver</xspdoc:desc>
>                 <xsl:call-template name="get-nested-string">
>                         <xsl:with-param
> name="content" select="sql:driver"/>
>                 </xsl:call-template>
>         </xsl:variable>
>         <xsl:variable name="dburl">
>         <xspdoc:desc>the url of the database source</xspdoc:desc>
>                 <xsl:call-template name="get-nested-string">
>                         <xsl:with-param
> name="content" select="sql:dburl"/>
>                 </xsl:call-template>
>         </xsl:variable>
> 
> assuming we could configure the xsp processor to ignore the xspdoc
> elements (either by stripping them when doing the XSLT transform or adding
> "strip xspdoc elements" rules to the xsp to java stylesheet), all we'd
> need to generate concise docs is a simple stylesheet like this:
> 
> <xsl:template match="/xsl:stylesheet">
> <html>
>  <body>
>   <dl>
>   <xsl:for-each select="xsl:template[xspdoc:desc]">
>    <dt>
>    <xsl:value-of select="@match"/>
>    </dt>
>    <dd>
>    <xsl:apply-templates select="xspdoc:desc"/>
>    <xsl:for-each select="xsl:variable[xspdoc:desc]">
>     <dl>
>      <dt>
>      <xsl:value-of select="@name"/>
>      </dt>
>      <dd>
>      <xsl:apply-templates select="xspdoc:desc"/>
>      </dd>
>     </dl>
>    </xsl:for-each>
>    </dd>
>   </xsl:for-each>
>   </dl>
>  </body>
> </html>
> </xsl:template>
> 
> obviously we could elaborate a bit on the elements and attributes of the
> xspdoc namespace, but that's the gist. any thoughts from other logicsheet
> authors? worthwhile to pursue?

This is pretty much the solution from the XSL-list regarding documenting
stylesheets. Personally I write taglibs either in raw perl for speed, or
in XPathScript, which means I can use POD to document them, but for XSLT
based taglibs this seems like an excellent idea.

-- 
<Matt/>

Fastnet Software Ltd. High Performance Web Specialists
Providing mod_perl, XML, Sybase and Oracle solutions
Email for training and consultancy availability.
http://sergeant.org | AxKit: http://axkit.org


Mime
View raw message