Xalan-C++ Documentation

[Rachael Ludwick-Sandefer <rs...@mgbltd.com>]

Hey everyone!

When David posted about the 1.5 version freeze, he mentioned the need for more documentation (and updated documentation). I volunteered as a good way to get involved with Xalan development. 

Although David said that he and Berin will be finishing the doc updates for this release, he did point out that there are plenty of other doc stuff that could be done: a user's guide, updating/expanding the FAQ, adding stuff to the usage, etc. But he also suggested that I ask the mailing lists for what people think is lacking in the documentation or could use improvement.

I was thinking about starting with the FAQ by expanding it (to start) with common questions asked about programming Xalan, since the list tends to get a lot of programming questions (by going through the list archives). I know I ended up asking a few questions when I first started using Xalan. :) But what other documentation would people like to see?

I can also be privately emailed at r343l@vzavenue.net (home address) with suggestions, but I do try to read most of the posts on the mailing lists.

Rachael

Re: Xalan-C++ Documentation

[Rachael Ludwick <r3...@vzavenue.net>]

----- Original Message -----
From: Berin Lautenbach <be...@ozemail.com.au>
<snip>
> Firstly - great stuff that you are picking up the dox!

Thanks :)

> One of the things I have noticed is that there is a lot on the basics
> (e.g. how to create a transformer), but not a lot on the more intricate
> stuff.  E.g. I found when I was playing with XPath that I had to do a
> lot of reading of code to determine how to install an external function.
>
> I wonder if it might be worth going through the example programs and
> providing some details around them?  What does a FormatterListener do?
> Why is it there, how does it work?

Right now I'm going through the xalan-c-users archives looking for things
people ask a lot to get some more faqs -- there just didn't seem to be as
many as for xerces, especially programming faqs. If there are faqs anyone
thinks belong in there, just email them! I've also got an outline started on
a users' guide, but I hadn't thought to add usage of the FormatterListener.

And then I could probably go through the examples -- people seem somewhat
disinclined to go through the source even of examples (and to be fair, it
doesn't always help), so it might be a good idea for a few of the examples
to do a line-by-line explanation (well, at least the important parts.) Give
people an idea of the why as well as the what. After a gude maybe.. :)

> Don't know if that helps?
<snip>

Thanks for the suggestions, Berin!!

Rachael

Re: Xalan-C++ Documentation

[Berin Lautenbach <be...@ozemail.com.au>]

Rachel,

Firstly - great stuff that you are picking up the dox!

One of the things I have noticed is that there is a lot on the basics 
(e.g. how to create a transformer), but not a lot on the more intricate 
stuff.  E.g. I found when I was playing with XPath that I had to do a 
lot of reading of code to determine how to install an external function.

I wonder if it might be worth going through the example programs and 
providing some details around them?  What does a FormatterListener do? 
Why is it there, how does it work?

Don't know if that helps?

Cheers,
	Berin


Rachael Ludwick-Sandefer wrote:
> Hey everyone!
> 
> When David posted about the 1.5 version freeze, he mentioned the need for more documentation (and updated documentation). I volunteered as a good way to get involved with Xalan development. 
> 
> Although David said that he and Berin will be finishing the doc updates for this release, he did point out that there are plenty of other doc stuff that could be done: a user's guide, updating/expanding the FAQ, adding stuff to the usage, etc. But he also suggested that I ask the mailing lists for what people think is lacking in the documentation or could use improvement.
> 
> I was thinking about starting with the FAQ by expanding it (to start) with common questions asked about programming Xalan, since the list tends to get a lot of programming questions (by going through the list archives). I know I ended up asking a few questions when I first started using Xalan. :) But what other documentation would people like to see?
> 
> I can also be privately emailed at r343l@vzavenue.net (home address) with suggestions, but I do try to read most of the posts on the mailing lists.
> 
> Rachael
>