After experimenting with a few different options, I've decided that
DocBook is a good way to go for writing the user and developer
documentation for DrJava. It's a very simple XML format, and is widely
used for project documentation. If you want more information on it,
follow some of the links at the DocBook Wiki (http://docbook.org/wiki/).
Anyway, the initial framework has now been committed. The docs
directory is within edu/rice/cs/drjava, which isn't ideal, but works
well enough. (Ideally it would be parallel to the src directory, but we
can't easily change the CVS root, which currently starts at the src
directory.)
There is now a "docs" target to call from ant, which will generate
the HTML files for the documentation if you have "docbook2html" on your
path. I know this is installed on at least the Linux CS machines (eg.
nunavut), though I haven't found it on the Solaris ones. The HTML files
will be written to a "docs" directory next to your "built" directory.
There is also a "commit-docs" ant target, so that changes to the
documentation can be committed without having to run all the tests.
At the moment, only the user documentation has been started (not any
of the developer docs). It has chapters on getting started and editing
programs, as well as an appendix on how to configure DrJava. As soon as
I get simple chapters written for the Interactions, Compiler, and JUnit
integration, I'll start posting it on the main web site for users. (It
should be a useful companion to the upcoming stable release.) I can
post a private copy on my own page if people are interested in seeing
what's there so far (without compiling it themselves). Anyway, there
will be lots of changes to it over the next few days, but feel free to
send me any feedback.
Charlie
|
