[responding to [EMAIL PROTECTED]
Alessio Marchetti wrote:
Martin Sebor wrote:
As far as the presentation I will easily be able to use a pretty
standard stylesheet at first, then I could customize it to match the
Apache look&feel.
Excellent!
Martin
Now I'm thinking about the process that the documentation creation
should follow.
I have in mind two different processes for the reference guide and for
the other docs (User Guide, FAQ, Technical notes, Help for people
wanting to contribute to the project, etc.).
There are a couple of projects in use at Apache: Forrest and Maven.
I haven't used either but I believe a lot of the Web pages around
here are generated by Forrest.
While the other docs are best single-sourced from XML content (DocBook,
as most open -- and closed --- source projects are converting to it
right now), the reference guide (until the days of literate programming
will come...) is better implemented with a Doxygen-like process, that
is: put the documentation in the source code.
I'm sure this is the best way to proceed, because it will substantially
increase the probability to have updated documentation.
In this scenario, the existing UG will be migrated to DocBook (with
Marc's scripts or with new ones), while the existing RG will be
copy&paste'd (I suppose I will volounteer to do it...) into the sources.
What do you think?
Going the Doxygen route is definitely very appealing for new code,
but converting the existing sources would be a huge amount of work.
The Class Reference is in a pretty good shape with tables, cross
references, etc. How easily could we preserve all that? How hard
to read and maintain would it make the sources?
I guess I need to look at some existing projects that use Doxygen
extensively to get a better feel for what it can do (my experience
with Doxygen is limited to that of a user of the final product).
Do you have any pointers? If you'd like to put together a prototype
of a few non-trivial pages that would be even better.
FWIW, I've started using simple Doxygen-style documentation in the
new test suite driver. The idea is to start with it as the guinea
pig before making a decision on the library. Any help here is also
welcome :)
Martin
