[kaffe] DocBook and Maven proposal

[Jim Pick]

Hi,

I'm trying to figure out a good way of integrating better documentation
into the project.

The first new document I want to check in is Edouard G. Parmelan's
"Porting Kaffe to a new platform" document.  It's a good one to start
with, since it's already a complete document written up in DocBook, and
it's under the GNU Free Documentation License, so we can use it.

Then, over time, we can add additional DocBook documents as people
create them.  We could probably move many of the "FAQ" documents into
more complete documents, eg. user and developer handbooks, etc.

Additionally, we want to support generating and shipping Javadoc
documentation (probably using gjdoc as our Javadoc implemention).

Initially, I was thinking of rolling my own documentation toolchain, and
checking that into the kaffe-extras CVS module.  That's quite a bit of
work though, involving probably a dozen or so external jars from Apache
and elsewhere.

As an alternative, I just spent much of today playing with Maven, which
is an Apache project which puts a whole bunch of project related build,
documentation and release tools under one big umbrella build tool.  It
can be used as a complete Makefile/ant replacement, if a project wants
to use it that way.  It is smart enough to understand dependencies
between projects, and it will download all the needed jar files from a
central repository to satisfy build time dependencies, so it can handle
pretty complicated toolchain tasks.  It's also fairly easy to use,
although the documentation is somewhat weak still (it hasn't reached
version 1.0 yet).

See this site for more info:

  http://maven.apache.org/

What's nice about it is that the impact on the source tree is minimal,
all that is needed is a few files (project.xml, project.properties) to
describe the project layout.  There is no need to check additional JAR
files into CVS or anything ugly like that.  They've got tonnes of
"canned goals" that can be used to generate a lot of cool stuff from the
source code tree. Another nice thing is that they have lots of
recommendations on how to lay things out that don't seem too
objectionable (and can be overridden for legacy locations).

Initially, I'm proposing to just use Maven to build the DocBook
documentation and JavaDocs.  We can look at using the additional
features later - there's a lot of cool stuff there.  It could be used to
generate lots of content for the website, for example.

In order to forge ahead, I'm going to propose that we create some new
directories to hold the documentation:

  kaffe (top-level) -+- FAQ (existing)
                     +- docs -+- html +- docbook
                              |       +- javadoc (not in CVS)
                              |       +- others...
                              +- pdf (not in CVS, or tarballs)
                              +- src -- docbook -+- port-kaffe
                                                 +- other docbook docs...

(sorry for the crappy ascii art)

I imagine most hand-written documentation will exist as Simplified XML
DocBook docs in docs/src/docbook/<document-name-dir>/*

For CVS users, I propose that we have a target that will generate the
HTML versions of the Docbook files (maybe not all of them), and we will
check those into kaffe/docs/html.  I think we should do this, since
enough people build Kaffe out of CVS, and they should have easy access
to basic documentation.  I don't think we should check in other
generated documentation, such as the Javadocs, since that can still be
retrieved from the website, or built by the users, and I'd like to keep
the CVS checkout from getting much more bloated.

When we generate the tarballs for release, the "make dist" target will
regenerate those files using Maven.  It will also generate the Javadocs,
and other things, which will go into the tarball in docs/html/...

Is this OK?  I'd like to get some feedback before checking these
locations into CVS, since CVS isn't nice about deleting directories if
we ultimately choose to put the documentation elsewhere.

As for Maven, I'm still in the early stages of playing with it.  There
are actually two sets of DocBook plugins - I only had success with the
extra one from SourceForge: 

   http://maven-plugins.sf.net/maven-sdocbook-plugin/

Unfortunately, it's external, so it's an additional thing to install on
top of Maven.  I didn't play with the PDF generating too much, but by
default, it has a dependency on Jimi from Sun to handle images (I
think).  And I haven't yet tried to get it running on Kaffe.

Ultimately, I think some portion of the Maven "toolchain" will probably
still have to reside in "kaffe-extras", in order to make it easy for
multiple developers to get set up properly.  I imagine that we will
probably need to do a lot of "tweaks" to it to make it suitable for
integration with "make dist" and for generating content for the website
(primarily my problem).  We could probably push some of our enhancements
upstream to Apache.

Should I go ahead, and check what I've got in?

It's minimal, but I need to create directories.

I can see that there is easily a week's worth of work (or more) to try
to get Maven and friends all working on Kaffe, and integrated into
"kaffe-extras".  But I could at least check in the document sources and
a trivial project descriptor to get us started.

And a reminder, feature freeze for 1.1.3 is tomorrow, with the release
scheduled for Sunday, December 7th.  Of course, I don't consider
documentation to be a "feature", so I'm exempt.  :-)

Cheers,

 - Jim