[CALL FOR REVIEW] Upgrading to DocBook 5.0

[Gabor Kovesdan]

Hi,

during the last weeks, I've been working on upgrading our documentation 
set to DocBook 5.0 and a higher-quality PDF generation toolchain, 
sponsored by the FreeBSD Foundation. With FF, we have discussed that 
high quality print output was especially important because of the 
upcoming print edition of the FreeBSD Handbook. The best tool available 
for this was Apache FOP, which is Java-based. Java is only required for 
high quality print output but not for validation of documents and XHTML 
generation. Since some committers are concerned about depending on Java, 
I've also added support for dblatex, but it is more limited. The 
deliverables of the overall work are:

1, A DocBook 5.0 tree of the documentation. The basic set is available 
in projects/db5 but still the converter has to be run on a fresh 
checkout. The converter can be obtained from user/gabor/db5 and it has a 
README, which explains how it works. The converted sources are not 
checked in because in this way merges are easier and adjustments of 
conversion parameters is still possible until we merge this to head.

2, A FOP-based rendering toolchain. This gives high quality output and 
after some last touches it will be print quality. I18N support is really 
good, all languages can be rendered in high quality, even CJK languages. 
A full PDF build can be found here:
http://kovesdan.org/files/fop/

3, A dblatex-based rendering toolchain. This toolchain is more limited. 
Its customization is more difficult and non-Latin text is not wrapped 
properly. Also, it fails with programlistings in tables so it cannot 
build the whole documentation set. This is a limitation that is 
explicitly listed in the dblatex documentation. This is a Java-free 
solution but it does not give us full support and such a high quality as 
FOP.
Some sample documents can be found here:
http://kovesdan.org/files/dblatex/

To get the sources, you can checkout the db5 branch and the converter 
from user/gabor/db5 and run it in the top-level directory of the doc 
sources. Or you can grab my snapshot:
http://kovesdan.org/files/doc-db5.tgz

To use this tree, you need for all output types:
textproc/docbook-500
textproc/docbook-xsl-ns

For PDF build in general:
chinese/arphicttf
japanese/ipa
x11-fonts/gentium-plus
x11-fonts/droid-fonts-ttf
x11-fonts/lohit

To test FOP build, you additionally need to install:
textproc/fop

To test dblatex build, you need:
print/texlive-full
textproc/dblatex

To build PDF files with dblatex, run make FORMATS=pdf all.
To do it with FOP: make FORMATS=pdf RENDERENGINE=fop all.

Please let me know about your comments. I plan to merge this changeset 
when I'm back from vacation, after Aug 12.

Gabor