Date: Fri, 02 Aug 2013 13:33:35 +0200 From: Gabor Kovesdan <gabor@FreeBSD.org> To: doc@freebsd.org Subject: [CALL FOR REVIEW] Upgrading to DocBook 5.0 Message-ID: <51FB990F.6030505@FreeBSD.org>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?51FB990F.6030505>