You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@xalan.apache.org by Gary L Peskin <ga...@firstech.com> on 2000/12/19 17:44:02 UTC
XalanJ2 Beta Documentation task
I'm a little concerned because I haven't seen any discussion or received
any feedback on the rather extensive changes that I made to the
extension documentation (extensions.html). It has not been out on the
web site since the changes were made after the last alpha was released.
However, the changes are in CVS.
I never claimed to be a great tech writer and I made so many changes
that my goal was mostly just to get the information on the page rather
than worry extensively about placement, etc. I do hope to get more
feedback as people start asking questions once the beta is released and
the documentation is on the web site.
However, if anybody is interested in reviewing the page in CVS at
java/xdocs/sources/xalan/extensions.xml, I'd be happy to incorporate any
comments of a substantive or editorial nature into the page. I'm
particularly looking for places where things are unclear, confusing, or
incomplete.
Gary
Re: XalanJ2 Beta Documentation task
Posted by John Gentilin <jo...@eyecatching.com>.
Gary L Peskin wrote:
> The two mechanisms just allow you to specify the java classname in
> different places in the case of extension functions. For example, I
> could write:
>
> <xsl:stylesheet version="1.0"
> xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
> xmlns:java="http://xml.apache.org/xslt/java">
>
> <xsl:variable name="myHash" select="java:java.util.Hashtable.new()">
>
> </xsl:stylesheet>
>
> -or-
>
> <xsl:stylesheet version="1.0"
> xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
> xmlns:hash="xalan://java.util.Hashtable">
>
> <xsl:variable name="myHash" select="hash:new()">
>
> </xsl:stylesheet>
>
>
> They both do the same thing. Either way will also work for the SQL
> extensions. Try it!
>
> You can actually make this even more complicated with lxslt:component
> and lxslt:script which are other ways of also doing the same thing.
>
> Gary
I think part of my confusion is that in Section 6, your example of HashTable is
inside a script. Probably my issue was not reading the document more completely
further down.
John G
Re: XalanJ2 Beta Documentation task
Posted by Gary L Peskin <ga...@firstech.com>.
John Gentilin wrote:
> Gary L Peskin wrote:
> > Do you thing that we should include pointers to the spec on the
> > Extensions page itself? I was thinking of just including a short
> > paragraph that said
> I think a pointer would help. Some of my frustration may be because
> I am coming from the perspective of implementing an extension and
> not using one.
I'll add this into the documentation. CVS is down right now but I'll
take a look when it returns.
> I read Kay's book, I think it needs a re-read. I do remember reading
> about extending Saxon but not XSLT as a standard.
See pages 121 through 127 ("Extensibility"). Also see section 14 of the
actual Recommendation (http://www.w3.org/TR/xslt.html#extension).
> Is there a stylesheet that will produce a printable copy of the XSLT
> Standard out there ??
I just load it into my browser and print from there.
> > > Another example is the use of Java Extensions. There is no clear path
> > > between a Java function written specifically for Xalan and using a non
> > > Xalan specific java class in the http://xml.apache.org/xslt namespace.
> > > If I am not mistaken, they are treated differently.
> > No, they're treated the same. Either type of java function can be
> > treated in any of the ways described in the Extensions document.
> Why are there two distinct mechinsms then. The SQL Extensions
> are written specifically for Xalan where Hashtable uses the
> http://xml.apache.org/xml namespace.
The two mechanisms just allow you to specify the java classname in
different places in the case of extension functions. For example, I
could write:
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:java="http://xml.apache.org/xslt/java">
<xsl:variable name="myHash" select="java:java.util.Hashtable.new()">
</xsl:stylesheet>
-or-
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:hash="xalan://java.util.Hashtable">
<xsl:variable name="myHash" select="hash:new()">
</xsl:stylesheet>
They both do the same thing. Either way will also work for the SQL
extensions. Try it!
You can actually make this even more complicated with lxslt:component
and lxslt:script which are other ways of also doing the same thing.
Gary
Re: XalanJ2 Beta Documentation task
Posted by John Gentilin <jo...@eyecatching.com>.
Gary L Peskin wrote:
>
> Do you thing that we should include pointers to the spec on the
> Extensions page itself? I was thinking of just including a short
> paragraph that said
>
I think a pointer would help. Some of my frustration may be because
I am coming from the perspective of implementing an extension and
not using one.
I read Kay's book, I think it needs a re-read. I do remember reading
about extending Saxon but not XSLT as a standard.
Is there a stylesheet that will produce a printable copy of the XSLT
Standard out there ??
> > Another example is the use of Java Extensions. There is no clear path
> > between a Java function written specifically for Xalan and using a non
> > Xalan specific java class in the http://xml.apache.org/xslt namespace.
> > If I am not mistaken, they are treated differently.
>
> No, they're treated the same. Either type of java function can be
> treated in any of the ways described in the Extensions document.
>
Why are there two distinct mechinsms then. The SQL Extensions
are written specifically for Xalan where Hashtable uses the
http://xml.apache.org/xml namespace.
> As for the Stylebook, how difficult would it be to make printable docs.
> Printer friendly HTML would be good, PDF even better. For me going
> over new material is much easier in printed form, e-copy is good for
> reference and quick lookup but it bugs my eyes after a long period of time.
>
> Find a way to create the Apache series books, Xalan in softcover, and
> I will buy them.
>
> I think that this is an Apache issue and not limited to Xalan.
>
True, although the coocon projects produces printable docs.
What is the history of Stylebook ?? It doesn't seem like a
separate project.
>
> Gary
Re: XalanJ2 Beta Documentation task
Posted by Gary L Peskin <ga...@firstech.com>.
John Gentilin wrote:
>
> Gary,
>
> Let's me start by saying I know how hard it is to create documentation
> that is understandable and clear to all. On first pass of the
> documentation,
> it was difficult as a new user to Xalan to understand the detail level
> concepts discussed in the Extension document. In trying to work on
> the SQL Extensions, I had to go over the document several times and
> it really did not sink in until I sat down and read the code. While your
> documentation is accurate, I think some additional basic Xalan
> discussions would make is easier for the novice to engage the process.
>
> As an example, in the discussion about Extension Elements and Extension
> functions it is not real clear when you would use one over the other. Maybe
> a pseudo example depicting each separately right there in the primary
> discussion instead of a combine example later in the document.
John --
I think the philosophy of the Extensions page was to explain the
implementation of extension functions and extension elements in Xalan.
These are XSLT concepts which are laid out in the XSLT Recommendation
and discussed at length in books like Mike Kay's excellent book. They
are also discussed in Dave Pawson's FAQ. These resources and others are
all referenced in the "Getting Up To Speed With XSLT" section of the
"Overview" page and no attempt was made to duplicate those discussions.
Do you thing that we should include pointers to the spec on the
Extensions page itself? I was thinking of just including a short
paragraph that said
Extension elements and extension functions are XSLT features discussed
in the <link>XSLT Recommendation</link>. For further information on
when and how to use extension elements or extension functions in
general, please consult the Recommendation or the resources listed in
<link>Getting Up To Speed With XSLT"</link>
> Another example is the use of Java Extensions. There is no clear path
> between a Java function written specifically for Xalan and using a non
> Xalan specific java class in the http://xml.apache.org/xslt namespace.
> If I am not mistaken, they are treated differently.
No, they're treated the same. Either type of java function can be
treated in any of the ways described in the Extensions document.
> If there is a section that covers basic Xalan theory, please point me there
> and I will read it. The closest I was able to find was the basic patterns
> page.
Yes. That's the best place. Also, the samples supplied with the
release are good and getting better.
> As for the Stylebook, how difficult would it be to make printable docs.
> Printer friendly HTML would be good, PDF even better. For me going
> over new material is much easier in printed form, e-copy is good for
> reference and quick lookup but it bugs my eyes after a long period of time.
>
> Find a way to create the Apache series books, Xalan in softcover, and
> I will buy them.
I think that this is an Apache issue and not limited to Xalan.
Gary
Re: XalanJ2 Beta Documentation task
Posted by Gary L Peskin <ga...@firstech.com>.
John Gentilin wrote:
>
> Gary,
>
> Let's me start by saying I know how hard it is to create documentation
> that is understandable and clear to all.
John --
I also want to thank you very much for taking the time to read and
critique the documentation. I know that this is no fun either and I do
appreciate it. My goal is to make the clearest possible documentation
focused on the Xalan extension implementation. I'm definitely not a
writer so I hope that those that are will take the time to contribute to
Xalan. I'm happy to make all reasonable changes so that the
documentation serves its intended audience.
Gary
Re: XalanJ2 Beta Documentation task
Posted by John Gentilin <jo...@eyecatching.com>.
Gary,
Let's me start by saying I know how hard it is to create documentation
that is understandable and clear to all. On first pass of the
documentation,
it was difficult as a new user to Xalan to understand the detail level
concepts discussed in the Extension document. In trying to work on
the SQL Extensions, I had to go over the document several times and
it really did not sink in until I sat down and read the code. While your
documentation is accurate, I think some additional basic Xalan
discussions would make is easier for the novice to engage the process.
As an example, in the discussion about Extension Elements and Extension
functions it is not real clear when you would use one over the other. Maybe
a pseudo example depicting each separately right there in the primary
discussion instead of a combine example later in the document.
Another example is the use of Java Extensions. There is no clear path
between a Java function written specifically for Xalan and using a non
Xalan specific java class in the http://xml.apache.org/xslt namespace.
If I am not mistaken, they are treated differently.
If there is a section that covers basic Xalan theory, please point me there
and I will read it. The closest I was able to find was the basic patterns
page.
As for the Stylebook, how difficult would it be to make printable docs.
Printer friendly HTML would be good, PDF even better. For me going
over new material is much easier in printed form, e-copy is good for
reference and quick lookup but it bugs my eyes after a long period of time.
Find a way to create the Apache series books, Xalan in softcover, and
I will buy them.
Regards
John Gentilin
Gary L Peskin wrote:
> I'm a little concerned because I haven't seen any discussion or received
> any feedback on the rather extensive changes that I made to the
> extension documentation (extensions.html). It has not been out on the
> web site since the changes were made after the last alpha was released.
> However, the changes are in CVS.
>
> I never claimed to be a great tech writer and I made so many changes
> that my goal was mostly just to get the information on the page rather
> than worry extensively about placement, etc. I do hope to get more
> feedback as people start asking questions once the beta is released and
> the documentation is on the web site.
>
> However, if anybody is interested in reviewing the page in CVS at
> java/xdocs/sources/xalan/extensions.xml, I'd be happy to incorporate any
> comments of a substantive or editorial nature into the page. I'm
> particularly looking for places where things are unclear, confusing, or
> incomplete.
>
> Gary