Re: [Hibernate-devel] Documentation in DocBook

[Christian B. <chr...@bl...>]

On 20 Jul (03:26), Gavin_King/Cirrus%CI...@ci... wrote:

> >- Move chapters and sections around for a more consistent read

Done. I hope this is an improvement. I still have some ideas left and
like to rewrite some chapters (especially the transaction and
association handling, which seems most confusing for hibernate
beginners, including myself).

> >- Convert graphics to vector and make a small styleguide for this

Done. We are using OpenOffice Draw, because it's the only cross platform
vector drawing tool. Try it, it's not that bad if you know how to use
it.

> >- Improve DSSSL stylesheet for PDF generation

Well, I did the best I could. Some things are still not nice (the
Revision history) but difficult to fix. I think we should stay with the
current layout until next time...

> >- Prepare stylesheets for HTML version

Modified stylesheets. Sorry, I didn't use the hibernate css (blue
background), because the images are not transparent and I don't have
time to fix this. It doesn't lock that bad either and could be easily
changed later.

> >- Add "Best Practices" chapter

Done.

> >- Write makefiles and documentation for automatic output generation

Still pending because I haven't decided for make or Ant. This stuff is
really complex and involves about 10 different shell commands for a
complete conversion with about 8 different tools. My current helper
scripts and all stylesheets (PDF and HTML) are _not_ in CVS. The
stylesheets require some serious cleanup before everything is in the
right place and ready for the repository.

> >- Checkin to CVS

Done, with a lot of cursing about CVS over ssh. I cannot use any
graphical client with Unix... any solution for this problem?

So, if everyone agrees that the new documentation can replace the old
"Programming Guide", the following steps would be neccessary:

- Change the link on the left frame from "Programming Guide" to
  "Documentation"

- Link it to doc/reference/index.html in the right frame

Thats it. Hm, the "Toolset Guide" could be integrated as a separate
chapter? The website itself could do with little reorg, too. I think the
whole Q&A and feature list is really one big block itself. 

-- 
Christian Bauer
tu...@in...