commons-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Simon Kitching <>
Subject Re: [Digester 1.5] Pattern matching screwed me up
Date Sun, 29 Feb 2004 09:08:32 GMT
On Sun, 2004-02-29 at 21:16, Martin Kersten wrote:
> > And when you're done, feel free to write a user manual and submit it for
> > inclusion into the project...
> My english isn't that good. But I can provide some concepts and if someone
> would like to play an English teacher and correct my bumpy english, I am
> sure
> we can improve the situation about the first contact on digester.
> Here is what I would like to do:
> 1. Write a getting-started.html put into the docs directory telling people
> where
> to look for the 'orginal' documentation (link to the package description).
> 2. Write a tutorial teaching the pattern matching and xml-parts mapping.
> I guess it would take me additional 4 hours. But I would likely to
> contribute that
> peaces. But again, I need a person who's playing the English teacher.
> Bye the way,
> Thanks for the help, it seams to work now and I am going to alter my test
> cases
> to avoid top-level attributes containing itself and adding an interface for
> adding
> (cause this function is called within two tags).

I'm glad your code is now working.

And I think it's great that you are really willing to help with
documentation. I didn't mean to imply that Digester's documentation was
perfect - we all know it's not. But there's a line between helpfully
pointing out an issue and complaining/criticising. Of course those who
are willing to actually *do* something get forgiven a lot :-)

First thing to check is whether .html form is the correct format for new
docs. I know that at least some docs at Apache are in something called
"xdoc". I'm not sure exactly what xdoc is, though.

Then there's the issues of deciding where to put the docs, and how to
link to them from the project site. That probably involves some Maven
configuration. If you can find a commons project which has documentation
along the lines you are suggesting, and can investigate how they write &
deploy it, that would be good too.

If you can do that, and produce some intros/tutorials, I would be
willing to do some proof-reading if you wish.

I'm currently (and concurrently) learning Websphere, Debian, Linux
network security, nagios, LVM, LDAP and subversion, so my poor brain
isn't up to learning xdoc or Maven at the moment. 

I think a few people are in this same situation, which is why writing a
package.html file (which is standard html/javadoc) is so much easier
than writing external documentation like you are proposing.

You'll find quite a lot of documentation written as package javadoc, so
it's a good habit to check for it when learning a new library.

Oh - and if you want to see a really badly documented library, I suggest
looking at IBM WebsphereMQ Cluster Workload Exits. And they get *paid*
to write that stuff :-(



To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message