[Howto] Build PDF for the Server guide

[Gabor Kelemen]

Hi

Last week, I finished translating the Ubuntu Server Guide to Hungarian. 
The most frequent question under my announcement was: PDF? So, I tried 
to build it, but it turned out not that this is not really simple. As 
other teams are nearly at 100%, I think it would be useful for them to 
know how to build the PDF.

1, You need a copy of the source tree, grab the tarball of the latest 
Lucid package from here: 
https://launchpad.net/ubuntu/+source/ubuntu-docs and extract it.
2, Export the translation you just finished, put it to the 
serverguide/po directory as ll.po
3, Modify Makefile, replace LN=C with LN=ll, to your language code.
4, You need to run "make serverguide-pdf" and it will put the pdf to 
build/serverguide/ll/serverguide.pdf - and you are done :).

This was the ideal case, but there are some quirks that need to be 
addressed.

First, the build failed for me with a message like this:

  org.apache.fop.fo.ValidationException: 
file:/home/gabor/tmp/udlucid/build/serverguide/C/serverguide.fo:9946:1886 <file:/home/gabor/tmp/udlucid/build/serverguide/C/serverguide.fo:9946:1886>: 
A table-cell is spanning more rows than available in its parent element.

This is reported as https://bugs.launchpad.net/bugs/575771 (I think :)). 
To fix this, you can use this patch: 
http://people.ubuntu.com/~kelemeng/sg-build/fix-pdf-build-bug%23575771.patch

This was the easy fix, now the build should be successful, but the 
resulting PDF may not look the best. This is because fop, the tool we 
use to generate the PDF, uses by default only latin-1 fonts, if your 
language contains characters not in this code page (őű for my case), 
they will appear as #. This is documented here: 
http://xmlgraphics.apache.org/fop/faq.html#pdf-characters
To solve this, you need to change the fonts used.

First file to modify is libs/ubuntu-pdf.xsl. You should select some nice 
fonts for your language than contains all your characters - for the 
variables to change, see my patch (this should work for other 
Central-European langugaes with latin-2):
http://people.ubuntu.com/~kelemeng/sg-build/ubuntu-pdf.xsl.patch

Now, you need to tell fop to use these fonts. You need a configuration 
file for this, I took and modified the example configuration file of 
fop, the end result is here: 
http://people.ubuntu.com/~kelemeng/sg-build/fop.xconf. The interesting 
part is the <fonts> section, you need to add a few lines like this:

         <font kerning="yes" embed-url="file:///usr/share/fonts/truetype/ttf-liberation/LiberationSerif-Regular.ttf">
           <font-triplet name="LiberationSerif" style="normal" weight="normal"/>

You need to use the embed-url property, so that it will be embedded into 
the PDF (not the default behavior). Also, you need the full path of the 
ttf of your font chosen in ubuntu-pdf.xsl, and you need such lines for 
all of the selected fonts - for my case, there were two fonts. You find 
the diff between the example file and my config file here: 
http://people.ubuntu.com/~kelemeng/sg-build/fop.xconf.diff
(contains some cruft at the end, ignore that :))

The last thing is to tell fop to use the config file. To do this, you 
will modify the Makefile like this:

-        fop -fo $(BASE)serverguide/$(LN)/serverguide.fo -pdf 
$(BASE)serverguide/$(LN)/serverguide.pdf; \
+        fop -c fop.xconf -fo $(BASE)serverguide/$(LN)/serverguide.fo 
-pdf $(BASE)serverguide/$(LN)/serverguide.pdf; \

I have put fop.xconf to the root directory of the ubuntu-docs packages 
tree. This can be found in a patch format (along with the language code 
change mentioned in step 3) here: 
http://people.ubuntu.com/~kelemeng/sg-build/makefile.patch

Now, you can run make serverguide-pdf, and the resulting PDF should show 
up with the new fonts and all your "special" characters.

I think that's all, feel free to ask if something is not clear :).

Regards
Gabor Kelemen