openmicroscopy/bioformats — pull request #389 by rleigh-dundee (2013-02-21 16:41:51+00:00)
Title: docs: Use XeLaTeX for PDF documentation

This patch switches Sphinx "make latexpdf" from using pdfLaTeX to using XeLaTeX. While the output is similar, this has a number of advantages, and will make processing the generated input from Sphinx much more robust and flexible.

- native UTF-8 support inside TeX
- modern font support (fontconfig)
- these fix all the historical fragility of input and font encodings [while pdfLaTeX used utf8x, this was a limited hack]
- initially use TeX Gyre fonts which are distributed with TeX [Times equivalent]
- replace babel with polyglossia
- enable extended unicode input
- configure the page margins and tighten spacing and line wrapping
- enable support for hard spaces in unicode

This will need TeXLive 2010 or newer to process correctly. 2009 and earlier have bugs in XeLaTeX, dependent packages and/or the fonts themselves which mess things up. We'll need hudson to be using a current TeX version, e.g. 2012.

Also split out the preamble from conf.py into a separate preamble.tex, primarily to avoid encoding issues [python chokes on non-ASCII input], but it also provides a means for much finer control over the LaTeX parameters. Initially, I've added margin settings using the geometry package, and tweaked the line wrapping parameters, but we can potentially do anything we want here to customise LaTeX for our needs.