On Fri, 2003-08-15 at 06:32, robert burrell donkin wrote:
> committed. many thanks.
>
> it all looks fine. i've managed to resist the temptation to tinker too
> much (just yet ;) but i have renamed the directory from example1 to
> addressbook since i prefer descriptive names where possible. (i think that
> it makes it easier for users.)
Tweak away :-) Any improvements to the examples are welcome; I would be
keen to see better ways of implementing the "addressbook" example.
I should have explained why I picked the name "example1"; it was chosen
so that we could also have example2, example3, etc.
Example 1 is the "start here" point, showing the simplest features of
Digester.
I had intended to add an Example 2 with more complex things like:
* passing Digester as a SAXContentHandler to an existing SAXParser
instead of calling parse(File), as done in example 1
* demonstrating ObjectFactoryRule
* wildcards in patterns
And maybe example 3 getting on to really tricky stuff like:
* extended rules matching
* NodeCreateRule (if I can figure it out myself :-)
* subclassing the Digester
* handling namespaces
If you want to name the examples by the example filetype they happen to
process, then I suggest the readme file be modified to indicate which
order a newbie to Digester should read the examples in.
> don't worry too much about the build script, it not a priority. maybe it'd
> be a good idea to have a separate build.xml script in the examples
> directory.
I just want to make sure that changes in Digester itself don't break the
examples. It would be rather embarrassing to ship a digester release
where the examples don't compile. To avoid this, I suggest that the
examples be *compiled* as part of the "dist" target, though of course
the resulting class files shouldn't be included in the distribution jar!
That way, any time someone runs "ant dist", they immediately see if the
examples are broken or not. Agreed, they don't know if the examples
still *work*; that would require them to be written as "unit tests",
which unfortunately then makes them less useful as tutorials (too much
unit-test-related clutter).
Or we could build them whenever the unit tests are built? I don't think
that the Digester unit tests are in a very good state though (I was
going to look into this soon, as I also need to build unit tests for the
Plugins module).
>
> i've been toying with the idea of using maven to create some kind of
> documentation based on the source plus html contained in the files but i
> don't have the time to do this right now.
>
> - robert
>
> On Saturday, August 2, 2003, at 07:15 AM, Simon Kitching wrote:
>
> > Hi,
> >
> > Recently there was a suggestion on the users email group that some
> > digester examples would be helpful.
> >
> > I felt this myself when starting to use digester.
> >
> > So attached is a tar file containing a (proposed) initial example.
> >
> > The tar file contains the tree:
> >
> > examples
> > api
> > example1
> > **files here
> > xmlrules
> >
> > I suggest that this could all go under "src", so that there would be
> > "src/java", "src/test" and "src/examples".
> >
> > This would be consistent with the "httpclient" projects' directory
> > structure.
> >
> > I think that additional examples could usefully be added in future,
> > hence the name "example1" for the dir containing the provided code.
> >
> > Stuff that could be covered in later examples include:
> > * FactoryCreateRule
> > * NodeCreateRule
> > * mapping of attribute names to bean properties
> > (eg some-attr --> someAttr) when using setProperties et al.
> >
> > This contribution is not entirely selfless :-). The existence of this
> > examples directory also gives me somewhere to put "plugins" module
> > examples if the "plugins" module is accepted [patch coming soon....]
> >
> >
> > NOTE: I haven't made any changes to the existing digester "build.xml" to
> > either build or not build these new files. This would have to be done
> > sometime I think.
> >
> > Regards,
> >
> > Simon
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: [EMAIL PROTECTED]
> > For additional commands, e-mail: [EMAIL PROTECTED]
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
