Irritated by Apache FOP footnote bug

I have managed to become quite productive with a combination of Serna for DocBook editing, and use of Apache FOP for producing PDF output. Except for some small snags that were easily worked around, there is a long standing Apache FOP bug for handling of footnotes in tables and lists - there simply is no easy workaround, so footnotes can't be used in these situations... (crap).

Starting to Use DocBook

I just recently started a documentation project and decided that DocBook was the lesser evil choice of:

• TeX / LaTeX - good formatting, but I want the text to be really reusable in help files, for the web, and for print. Maybe I am wrong, but it seemed backwards to go from typesetting to structured text.
• Wiki - really good for collaborative authoring, but markup gets horribly ugly after a while
• Word - everything in one big document - I guess some open XML format could be used so I can check files into SVN, but I would not want to be the one doing merging of a document that has been through word.
• Commercial Tools like FrameMaker (which is no longer available for Mac) - so I would both have to pay a lot for FrameMaker, and then have the dubious pleasure of running it on Windows.

Anyway, I found a good free tool called Serna that provides visual editing of DocBook in a sort of WYSIWYM (...What You Mean), which works really well.

I found several things to be really annoying, and it took a while to get used to how it works, but I managed to be quite productive (even if there is no spell check as you type).

In addition to using Serna's free distribution, I downloaded the latest XSLT stylesheets for DocBook. I also downloaded the latest Apache FOP (for formatting into PDF). Serna can invoke the FOP scripts, but does not include them in the distribution. Serna's scripts assume version 0.93, so I simply linked the 0.93 directory to the latest 0.95, and then thigns started to work.

It complained about hyphenation, and download of a jar from Offo (an apache project) was also required. I simply dropped the jar into the FOP lib directory to make it work.

Now I have two things to figure out:

• How to customize the style sheets - the output is almost useable as it is, but there are a couple of things I don't like.
• How the !#!#x@ to do cross ref linking between separate documents and still get generated text

The last time I undertook a major documentation project was 1992-1993. Earlier in 1989, I had to write the troff drivers myself as the printer was not supported, and I produced some finished 200 printed pages at the rate of about 2 (finished) pages a day. Working with 'vi' and troff is simply not a very productive environment.

In 1992 we started using Frame Maker, and I was delighted, it was simply the best piece of software I had used. With the release of FrameMaker 4 in 1993, I was very happy, and became very productive as I could do all the authoring, layout and graphics using a single tool. Not only did my productivity increase, the quality of the text increased as it was very fast to make illustrations inline with the text. Since pages were always rendered in full WYSIWYG it was possible to work at blazing speed. I produced some 2000 pages of documentation - about 1/3 was generated from program code (compare to java doc). When the project was all done, I calculated that I produced about 10 pages per day - but it is an unfair comparison as the earlier troff project had almost no graphics.

Today, I have spent about 4 days with DocBook, and I am struggling to learn Serna and the DocBook system, formatting etc. I have not yet started using graphics in my document. I seriously doubt that I will be able to create 10 quality pages per day including graphics.

Amazing how little has happened in 15 years - I am now back to hacking stylesheets to produce printed output... an exercise not very different from writing those troff drivers 20 years ago.