You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Donald Ball <ba...@webslingerZ.com> on 2000/10/17 19:00:22 UTC
RE: New ESQL changes...
On Tue, 17 Oct 2000, Per Kreipke wrote:
> Speaking of schemas, the xspdoc namespace you've added to the taglib is
> handy. I've written a script to document your esql.xsl taglib without using
> stylebook (a limitation you mentioned earlier). Similar to the stylesheet
> you mention, but executable using Cocoon itself.
sweet.
> However, what is the full set of tags for that namespace? I can't find a way
> to search the archives to look for the past posts on "xspdoc" and "xsp doc"
> you mentioned in another email.
er, um... i wonder what the subject line was... in any case, the schema
was never really carved out, everyone just agreed that it was a pretty
good idea and that you wouldn't run into trouble as long as the xspdoc
elements appeared as children of xsl:stylesheet.
if you have suggestions for expanding (or explicitly defining!) the xspdoc
schema, i'm all ears.
> For myself, I've annotated an earlier version of esql.xsl as below and I'd
> be glad to annotate the current esql (or other) taglibs with more detail:
>
> <xspdoc:desc>
> returns the value of the given column as a date. if a format attribute
> exists, its value is taken to be a date format string as defined in
> java.text.SimpleDateFormat, and the result is formatted accordingly.
> </xspdoc:desc>
> <xspdoc:args>
> <xspdoc:arg name="format">
> optional formatting value passed directly to 'SimpleDataFormat'
> </xspdoc:arg>
> </xspdoc:args>
> <xsl:template match="esql:results//esql:get-date">
> ...
> </xsl:template>
good idea with the args element. thought though - how do you distinguish
between arguments passed as attributes and arguments passed as elements?
i'd love it if you sent me the annotated esql logicsheet and the script to
generate the docs. wonder if anyone would be interested in annotating the
other logicsheets?
- donald
RE: New ESQL changes...
Posted by Donald Ball <ba...@webslingerZ.com>.
On Thu, 26 Oct 2000, Jeremy Quinn wrote:
> At 13:00 -0400 17/10/00, Donald Ball wrote:
> >On Tue, 17 Oct 2000, Per Kreipke wrote:
> >
> >> Speaking of schemas, the xspdoc namespace you've added to the taglib is
> >> handy. I've written a script to document your esql.xsl taglib without using
> >> stylebook (a limitation you mentioned earlier). Similar to the stylesheet
> >> you mention, but executable using Cocoon itself.
>
> >if you have suggestions for expanding (or explicitly defining!) the xspdoc
> >schema, i'm all ears.
>
> I added these:
>
> Namespace
> <xspdoc:ns>http://www.apache.org/cocoon/XSP/Mailer/1.0</xspdoc:ns>
>
> External package requirements
> <xspdoc:requires>
> <xspdoc:desc>Sun's JavaMail Package</xspdoc:desc>
> <xspdoc:file>mail.jar</xspdoc:file>
> <xspdoc:uri>http://blah.blah/blah</xspdoc:uri>
> </xspdoc:requires>
>
> I would also suggest adding something like the following.
>
> <xspdoc:children>
> <xspdoc:child multiple="true">splish</xspdoc:child>
> <xspdoc:child>splosh</xspdoc:child>
> <xspdoc:children>
>
> To simply document the legal child elements of any tag.
interesting, but do you worry that this is getting too close to being an
actual xml schema? should we look into integrating xspdoc into
that?
- donald
RE: New ESQL changes...
Posted by Jeremy Quinn <je...@media.demon.co.uk>.
At 13:00 -0400 17/10/00, Donald Ball wrote:
>On Tue, 17 Oct 2000, Per Kreipke wrote:
>
>> Speaking of schemas, the xspdoc namespace you've added to the taglib is
>> handy. I've written a script to document your esql.xsl taglib without using
>> stylebook (a limitation you mentioned earlier). Similar to the stylesheet
>> you mention, but executable using Cocoon itself.
>if you have suggestions for expanding (or explicitly defining!) the xspdoc
>schema, i'm all ears.
I added these:
Namespace
<xspdoc:ns>http://www.apache.org/cocoon/XSP/Mailer/1.0</xspdoc:ns>
External package requirements
<xspdoc:requires>
<xspdoc:desc>Sun's JavaMail Package</xspdoc:desc>
<xspdoc:file>mail.jar</xspdoc:file>
<xspdoc:uri>http://blah.blah/blah</xspdoc:uri>
</xspdoc:requires>
I would also suggest adding something like the following.
<xspdoc:children>
<xspdoc:child multiple="true">splish</xspdoc:child>
<xspdoc:child>splosh</xspdoc:child>
<xspdoc:children>
To simply document the legal child elements of any tag.
>good idea with the args element. thought though - how do you distinguish
>between arguments passed as attributes and arguments passed as elements?
There appears to be a general rule whereby the "config" elements of a Tag
can be either Attributes or child elements.
ie.
<blob:thing shape="amorphous"/>
or
<blob:thing>
<blob:shape>amorphous</blob:shape>
</blob:thing>
So what is the difference between a "child element" and a "config element"?
I think a distinction could be made between an element that merely adds
(dynamic) configuration to a Tag, but could otherwise be an Attribute; and
Tags that are Tags in their own right and are allowed to be nested inside
their "brothers". The "multiple" attribute would signify that it made sense
to have multiple nested elements of that name.
regards Jeremy
--
___________________________________________________________________
Jeremy Quinn Karma Divers
webSpace Design
HyperMedia Research Centre
<ma...@mac.com> <http://www.media.demon.co.uk>
<phone:+44.[0].20.7737.6831> <pa...@sms.genie.co.uk>
RE: New ESQL changes...
Posted by Per Kreipke <pe...@onclave.com>.
> > Speaking of schemas, the xspdoc namespace you've added to the taglib is
> > handy. I've written a script to document your esql.xsl taglib
> without using
> > stylebook (a limitation you mentioned earlier). Similar to the
> stylesheet
> > you mention, but executable using Cocoon itself.
>
> sweet.
>
> > However, what is the full set of tags for that namespace? I
> can't find a way
> > to search the archives to look for the past posts on "xspdoc"
> and "xsp doc"
> > you mentioned in another email.
>
> er, um... i wonder what the subject line was... in any case, the schema
> was never really carved out, everyone just agreed that it was a pretty
> good idea and that you wouldn't run into trouble as long as the xspdoc
> elements appeared as children of xsl:stylesheet.
>
> if you have suggestions for expanding (or explicitly defining!) the xspdoc
> schema, i'm all ears.
Ok. Did that as described below.
> > For myself, I've annotated an earlier version of esql.xsl as
> below and I'd
> > be glad to annotate the current esql (or other) taglibs with
> more detail:
> >
> > <xspdoc:desc>
> > returns the value of the given column as a date. if a
> format attribute
> > exists, its value is taken to be a date format string as defined in
> > java.text.SimpleDateFormat, and the result is formatted accordingly.
> > </xspdoc:desc>
> > <xspdoc:args>
> > <xspdoc:arg name="format">
> > optional formatting value passed directly to 'SimpleDataFormat'
> > </xspdoc:arg>
> > </xspdoc:args>
> > <xsl:template match="esql:results//esql:get-date">
> > ...
> > </xsl:template>
>
> good idea with the args element. thought though - how do you distinguish
> between arguments passed as attributes and arguments passed as elements?
Hmmm. Thought that it was a Cocoon design pattern to always allow either
(can't remember who said this, Ricardo maybe?) so I assumed that an arg was
just an arg. How about
<xspdoc:arg name="xxx" type="attribute|element|both">blah blah</xspdoc:arg>
You'll see in my code that I actually tried to capture a lot of the
different ways that the pattern was expressed when run against the old
taglibs. You found a new way to express that pattern in esql.xsl, so they no
longer work. Of course, they're not necessary either. So, if not declared
explicitly as above, could auto-discover them.
> i'd love it if you sent me the annotated esql logicsheet and the script to
> generate the docs. wonder if anyone would be interested in annotating the
> other logicsheets?
Will do. Was just futzing with it to fix the business described above and
broke it. Give me 5 to fix it again.
Per.
RE: New ESQL changes...
Posted by Per Kreipke <pe...@onclave.com>.
> > 4. I think there's an error in the (old) esql.xsl I've
> attached. According
> > to the XSLT spec, you can't have a <xsl:template> element have both a
> > 'match' and 'name' element. I could be wrong. It's the following match:
> >
> > <xsl:template match="esql:results//esql:get-string" name="get-string">
>
> erm, i think you're wrong. from the xslt spec:
>
> If an xsl:template element has a name attribute, it may, but need not,
> also have a match attribute. (http://www.w3.org/TR/xslt#named-templates)
Corrected, it's pretty explicit :-). Hmm, wonder where I got that from.
Sigh, too much info.
> i'll mull over your xspdoc suggestions and get back with my thoughts
> later. looks pretty good tho.
Ok.
I'm wondering about using nesting:
<xspdoc:func>
<xspdoc:desc>
blah blah
</xspdoc:desc>
<xspdoc:args>
<xspdoc:arg name="arg1" optional="true"
type="attribute|element|either">
optional arg1 blah blah
</xspdoc:arg>
</xspdoc:args>
</xspdoc:func>
Using nesting does removes the dependency on relative position but maybe
it's not as simple or elegant as simply <xspdoc:desc>.
Alternative:
<xspdoc:desc>
blah blah description
<xspdoc:args>
<xspdoc:arg name="arg1" optional="true"
type="attribute|element|either">
optional arg1 blah blah
</xspdoc:arg>
</xspdoc:args>
</xspdoc:desc>
Is there value in simply using <xspdoc:desc> to comment any XML (not just
taglibs) in a way that makes the comments extractable?
I could see using it to comment my actual XML or XSP source files without
necessarily defining functions (e.g. <xspdoc:func>). Maybe one could
define<xspdoc:comment> instead.
Or, how about <xspdoc:buggy>? And <xspdoc:revisit> and <xspdoc:slow>? :-)
Per
RE: New ESQL changes...
Posted by Donald Ball <ba...@webslingerZ.com>.
On Tue, 17 Oct 2000, Per Kreipke wrote:
> 4. I think there's an error in the (old) esql.xsl I've attached. According
> to the XSLT spec, you can't have a <xsl:template> element have both a
> 'match' and 'name' element. I could be wrong. It's the following match:
>
> <xsl:template match="esql:results//esql:get-string" name="get-string">
erm, i think you're wrong. from the xslt spec:
If an xsl:template element has a name attribute, it may, but need not,
also have a match attribute. (http://www.w3.org/TR/xslt#named-templates)
i'll mull over your xspdoc suggestions and get back with my thoughts
later. looks pretty good tho.
- donald
RE: New ESQL changes...
Posted by Donald Ball <ba...@webslingerZ.com>.
On Thu, 19 Oct 2000, Per Kreipke wrote:
> Donald,
>
> Further thoughts about xspdoc?
naw, been busy getting ready for apachecon. i think you pretty much nailed
it though - i'm just trying to figure out if there's a (sane) logicsheet
design methodology which would not be amenable to documentation this
way...
- donald
RE: New ESQL changes...
Posted by Per Kreipke <pe...@onclave.com>.
Donald,
Further thoughts about xspdoc?
Per
> -----Original Message-----
> From: Per Kreipke [mailto:per@onclave.com]
> Sent: Tuesday, October 17, 2000 4:42 PM
> To: cocoon-dev@xml.apache.org
> Subject: RE: New ESQL changes...
>
>
> Donald,
>
> This comment of mine earlier was vague, thought I'd be more specific.
>
> > In tagdocs.xsl you'll see I had to tweak your version from
> > skins/../xsp2document.xsl (sp?), it associated xspdoc:desc's to
> the wrong
> > xsl:template items).
>
> In xspdoc2document.xsl, you have:
>
> <xsl:template match="xspdoc:desc">
> <dt><xsl:value-of select="following-sibling::xsl:template/@match"/></dt>
> <dd><xsl:apply-templates select="text()"/></dd>
> </xsl:template>
>
> but <xsl:value-of select="following-sibling::xsl:template/@match"/> will
> match the next xsl:template in the file, not necessarily only the
> one which
> follows immediately after. The following will:
>
> <xsl:apply-templates
> select="following-sibling::xsl:template[position() = 1]/@match"/>
>
>
> Per.
>
>
RE: New ESQL changes...
Posted by Per Kreipke <pe...@onclave.com>.
Donald,
This comment of mine earlier was vague, thought I'd be more specific.
> In tagdocs.xsl you'll see I had to tweak your version from
> skins/../xsp2document.xsl (sp?), it associated xspdoc:desc's to the wrong
> xsl:template items).
In xspdoc2document.xsl, you have:
<xsl:template match="xspdoc:desc">
<dt><xsl:value-of select="following-sibling::xsl:template/@match"/></dt>
<dd><xsl:apply-templates select="text()"/></dd>
</xsl:template>
but <xsl:value-of select="following-sibling::xsl:template/@match"/> will
match the next xsl:template in the file, not necessarily only the one which
follows immediately after. The following will:
<xsl:apply-templates
select="following-sibling::xsl:template[position() = 1]/@match"/>
Per.
RE: New ESQL changes...
Posted by Per Kreipke <pe...@onclave.com>.
Donald,
1. Attached is an old esql.xsl (renamed to avoid conflicts) annotated as I
described in the earlier email.
2. Also attached are tagdocs.xml and tagdocs.xsl. Instructions are at the
top of tagdocs.xml. You'll need to massage the internal 'baseDir' variable.
3. Perhaps it would be better to set up the xspdoc namespace to be more like
I've shown below. I had trouble getting the XSLT expression right to get the
prev and next sibling.
In tagdocs.xsl you'll see I had to tweak your version from
skins/../xsp2document.xsl (sp?), it associated xspdoc:desc's to the wrong
xsl:template items).
<xspdoc:func>
<xspdoc:desc>
<xspdoc:args>
<xspdoc:arg>
</xspdoc:arg>
</xspdoc:args>
</xspdoc:func>
4. I think there's an error in the (old) esql.xsl I've attached. According
to the XSLT spec, you can't have a <xsl:template> element have both a
'match' and 'name' element. I could be wrong. It's the following match:
<xsl:template match="esql:results//esql:get-string" name="get-string">
Per.
> -----Original Message-----
> From: Donald Ball [mailto:balld@webslingerZ.com]
> Sent: Tuesday, October 17, 2000 1:00 PM
> To: cocoon-users@xml.apache.org
> Cc: cocoon-dev@xml.apache.org
> Subject: RE: New ESQL changes...
>
>
> On Tue, 17 Oct 2000, Per Kreipke wrote:
>
> > Speaking of schemas, the xspdoc namespace you've added to the taglib is
> > handy. I've written a script to document your esql.xsl taglib
> without using
> > stylebook (a limitation you mentioned earlier). Similar to the
> stylesheet
> > you mention, but executable using Cocoon itself.
>
> sweet.
>
> > However, what is the full set of tags for that namespace? I
> can't find a way
> > to search the archives to look for the past posts on "xspdoc"
> and "xsp doc"
> > you mentioned in another email.
>
> er, um... i wonder what the subject line was... in any case, the schema
> was never really carved out, everyone just agreed that it was a pretty
> good idea and that you wouldn't run into trouble as long as the xspdoc
> elements appeared as children of xsl:stylesheet.
>
> if you have suggestions for expanding (or explicitly defining!) the xspdoc
> schema, i'm all ears.
>
> > For myself, I've annotated an earlier version of esql.xsl as
> below and I'd
> > be glad to annotate the current esql (or other) taglibs with
> more detail:
> >
> > <xspdoc:desc>
> > returns the value of the given column as a date. if a
> format attribute
> > exists, its value is taken to be a date format string as defined in
> > java.text.SimpleDateFormat, and the result is formatted accordingly.
> > </xspdoc:desc>
> > <xspdoc:args>
> > <xspdoc:arg name="format">
> > optional formatting value passed directly to 'SimpleDataFormat'
> > </xspdoc:arg>
> > </xspdoc:args>
> > <xsl:template match="esql:results//esql:get-date">
> > ...
> > </xsl:template>
>
> good idea with the args element. thought though - how do you distinguish
> between arguments passed as attributes and arguments passed as elements?
>
> i'd love it if you sent me the annotated esql logicsheet and the script to
> generate the docs. wonder if anyone would be interested in annotating the
> other logicsheets?
>
> - donald
>
>