Leo Simons wrote:
>
> > > >Other than that, Excalibur really needs
> > > >documentation badly.
> > >
> > > Would it be better that instead of describing each component
> > individually
> > > we point them to package.html for each package??? We could then
> > just have a
> > > short highlevel description in xdocs which points to package.html for
> > > further data???
> >
> > I would like to see implementation details in the package.html files--but
> > have the package.html files generated by XSLT. (In other words we use our
> > document DTD to write those docs).
>
> That's what I've been thinking about. I wonder, is it possible
> with the current setup to not have "dtd" dirs all across your
> xdocs project (seems like a bad design choice, and all but
> impossible to use when you want to do doc generation inside
> the java source tree).
Sure it's possible, but I just have to flesh out how I am going to accomplish
it. BTW, if you never declare the <!DOCTYPE !> line, you never have to worry
about the DTD (but you never get the benefit of the declared entities either).
What I was thinking of doing is creating a directory where the package xdocs
lived like this:
xdocs/packages/
org-apache-avalon-excalibur-datasources.xml
...
And after they are transformed (simple XSLT, Javadocs don't need the same
menu as regular docs), they get moved into the appropriate packages. It
may require creating our own Ant Task to do, but I think it would be worth
it.
> > The high-level description should be more "what is it" and "what
> > does it do",
> > while the package.html describes "how do I use it".
>
> Why?
> Looking at the java setup, it seems to be more the reverse: the
> API is academic in tone, while the tutorial series document how
> to use the API.
Take a look at the SimpleDateFormatter and the Calendar objects. I
am refering to the JavaDocs in Excalibur taking after that format.
IOW, describing the different options available, and the different
Components that can be instantiated.
Each of the Excalibur components do need the general overview, and
the more detailed hand walking tutorial (i.e. for the beginners).
> I think I like that one better: good programmers are interested
> in high-level overviews and have no prob reading api docs; new
> programmers need a tutorial and more down-to-earth docs.
I like this approach. Keeping the high level docs in the javadocs
is good--just be sure to include the configuration info. The
site can have a general overview ("what is it") and a more detailed
tutorial ("what does it do?" and "walk me through it").
> cheers,
>
> LSD, who is working on a "Getting Started with the
> Avalon Framework" tutorial.
I am working on my paper for the Avalon presentation I am preparing
for at ApacheCon. That will be my basis for the "Getting Started"
tutorial.
> PS: anyone know a good paper about COP to refer to?
:) I'm writing it. Really though, I am writing a three part paper
that I am going to donate to the Avalon project--I just need a word
processor to write it at the beginning.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
