[kaffe] DocBook and Maven proposal

[Dalibor Topic]

Jim Pick wrote:
> 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.

Yep. Ean should be notified to take it out of the debian package, 
though, as the GFDL is not DFSG compatible.

> 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 think that's a great idea!

> 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.

yep.

> 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.

It sounds very good to me. How much of that is possible with 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?

Yes, please! I'd like to start doing some work on kaffe-extras as well, 
when 1.1.3 is out. Given thet Graydon published a JUnit wrapper class 
for mauve, I was thinking about using adding a task to build.xml to 
download & run mauve with kaffe.

> 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.  :-)

I still have a fe re-syncs to do before release (Classpath, Jessie, 
JAXP, tritonus, etc.), and then it's all bug fixing till Sunday.

cheers,
dalibor topic