cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Arno Illmann <illm...@onlinemedia.de>
Subject Standard Taglib Documentation
Date Mon, 22 Jan 2001 14:10:18 GMT
> from cocoon-users:
>Re: XSD / From "Robin Green" <greenrd@hotmail.com>
>2001-01-19 16:43:09

>Arno Illmann <illmann@onlinemedia.de> wrote:
>>In my sleepless nights when testing and trying with cocoon 1x (i believe
in
>>it) i had a vision in triple stereo about docs like esql.xsd.
>>I dreamed to assist generating something similar for the context.xsl,
>>cookie.xsl, global.xsl, request.xsl, response.xsl, session.xsl, util.xsl
>>in\src\org\apache\cocoon\processor\xsp\library\java, but my skills are  
>>at that moment not that. 
>>I need a little bit of doc about it. 
>>Perhaps something like esql.xsd.
>
>Yes, yes, great idea man!!
>
>It's really quite simple. Firstly the docs will be primarily used as a
human 
>reference, so if they exist at all that's a big improvement - it doesn't 
>matter if there are syntax errors.
>
>So you can base them on esql.xsd. Then you can crib^H^H^H^H base your docs 
>on the Servlet API documentation, because the standard taglibs mirror the 
>servlet API quite closely.
>
>But please check that the tags really do what you think they do first!
>
>Actually it would be really useful to have a little demo of every little 
>tag. This would help in so many ways:
>
>(1) Testing that the docs are correct.
>(2) When we do a new release we can click on these demos and see if any of 
>them breaks - unit testing!
>(3) Samples for newbies.
>
>So yes, please go right ahead and post them to the list when you're done!
>
>And if you think of any taglib improvements, again, yes please!!
>
>
>>"The ultimate reference to my knotted brain is of course the source code,
>>which is an XSLT logicsheet."
>
>LOL. :)

... uh er well but i AM a newbie. I really want to help creating a standard
taglib documentation but I assume I need a litttltle bit of more
documentation :-). For first: at http://de.signandco.de/doctaglib/ you can
get a small zip-file with a very first v0.1 version of a rough copy, then
I'll demonstrate you the probs:

Case a)

Have a look at
\cocoon\src\org\apache\cocoon\processor\xsp\library\java\response.xsl, line
363:

  <xsl:template match="response:send-redirect">
    <xsl:variable name="location">
      <xsl:choose>
        <xsl:when test="@location">"<xsl:value-of
select="@location"/>"</xsl:when>
        <xsl:when test="location">
          <xsl:call-template name="get-nested-content">
            <xsl:with-param name="content" select="location"/>
          </xsl:call-template>
        </xsl:when>
      </xsl:choose>
    </xsl:variable>

Testing <response:send-redirect location='test.htm'/>. Works. Probably
that's all. Ok, next one:

Case b) 

Looking at
\cocoon\src\org\apache\cocoon\processor\xsp\library\java\util.xsl, line 186:

  <!-- Include expression as DOM -->
  <xsl:template match="util:include-expr">
    <xsl:variable name="expr">
      <xsl:choose>
        <xsl:when test="@expr">"<xsl:value-of select="@expr"/>"</xsl:when>
        <xsl:when test="util:expr">
          <xsl:apply-templates select="util:expr/*|util:expr/text()"/>
        </xsl:when>
      </xsl:choose>
    </xsl:variable>

    <xsp:expr>
      this.xspParser.parse(
        new InputSource(
          new StringReader(
	    String.valueOf(<xsl:copy-of select="$expr"/>)
          )
        )
      ).getDocumentElement()
    </xsp:expr>
  </xsl:template>

Testing <util:include-expr expr=''/>.

 Error found handling the request.
 org.xml.sax.SAXException: The root element is required in a well-formed
document. [FATAL ERROR] [File: "null" Line: 
 1 Column: 1] (nested exception: org.xml.sax.SAXParseException: The root
element is required in a well-formed document. )

-Looking at Javadocs Sevlet API Class XSPUtil for "IncludeExpression". None.

-Looking at packages org.apache.cocoon at Util. Nought.
-Searching "exp" in Hierarchy For All Packages. Nnn.
-Searching directory docs\api for "IncludeExpression".
-Searching directory docs\api for "exp". 
-Getting for instance docs\api\org\apache\cocoon\processor\xsp\XSPPage.html
.
At Method Summary: protected  org.w3c.dom.Text xspExpr(boolean v,
org.w3c.dom.Document factory).

Ehrm. Yes.

Testing <util:include-expr expr='&lt;?xml version="1.0"?&gt;'/>.

 Error found handling the request.
 java.lang.Exception: XSP Java Compiler: Compilation failed for
_taglibstest.java 
 2753: ')' expected.
 String.valueOf("<?xml version="1.0"?>")
                                ^
[...]

Testing <util:include-expr expr='<xsp:expr>(xspExpr(new
Date())</xsp:expr>'/>.

 Error found handling the request.
 java.lang.Exception: XSP Java Compiler: Compilation failed for
_taglibstest.java
 2761: ')' expected.
 xspExpr((xspExpr(new Date()), document)
                             ^
OK. Let's get a cup of coffee.

<------------>

I think a undocumented taglib is no help to xml authors, because you have to
be at least a java programmer to understand most tags and if this is so, you
can abandon a taglib.

I hereby call by heart all standard taglib authors

         *******************************
         *        Jeremy Quinn         *
         *      Donald A. Ball Jr.     *
         *           Ugo Cei           *
         *     and (oh!) especially    *
         *        Ricardo Rocha        *
         *******************************

to fuel your work with purpose and syntax/sample, for you it will be the
easiest task!

A very detailed and profound example is for instance the auth-docs.xml from
Ulrich Mayrings Auth-Taglib (http://xml.apache.org/cocoon/3rdparty.html).

<------------>

With respect, I think that a <xspdoc:desc> in the esql.xsl or like esql.xsd
without any 

<xspdoc:syntax>
 <lib:action attrib1='string' attrib2='int'>example</lib:action>
</xspdoc:syntax>
                     (DTD: <!ELEMENT xspdoc:syntax (#CDATA)>)

aims not to the users of taglibs.

In future it should be possible to generate taglib-docs with examples of
syntax at a time on the fly with something like xspdoc2document.xsl. This
means, Authors of taglibs should use e.g <xsp:syntax>.

<------------>

Again: I really want to help creating a standard taglib documentation,
because I believe in the power of cocoon "allowing different presentations
of the same data depending on the requesting client" and allowing document
content, style and logic to be independently designed, created and managed.

Next will be to complete the list of tags at
http://de.signandco.de/doctaglib/, to get information about syntax and to
post it in a version 0.5. Then I could imagine to help updating the taglibs
(e.g <xsp:syntax>) with guidance of the authors.

OK and I will post only this mail to the DEV-list. =:)

Regards, Arno Illmann

Arno Illmann 
Online Media Riedlbauer GmbH 
Bischofstra├če 89 
47809 Krefeld 
Telefon: 0049/2151/554217 

Mime
View raw message