Mi blog lah! Το ιστολόγιό μου

Robert describes how to generate PDF files from GNOME documentation source files.

We describe here how to manually generate PDF files from translated documentation.

The relevant gnome-doc-utils files for documentation generation is at http://git.gnome.org/cgit/gnome-doc-utils/tree/tools. As far as I understand from reading the makefile, there is no support yet to build PDFs out of localised documentation.

Let’s assume we want to generate PDF documentation for the GNOME 2 User Guide, for the Greek language.

1. We clone the relevant repository

$ git clone git://git.gnome.org/gnome-user-docs

2. Then,

cd gnome-user-docs/gnome2-user-guide/

and now generate the equivalent XML files found in C/ with the localisation for the Greek language (found in el/),

\ls C/*.xml | perl -n -e 'chop; $a=$_; print "xml2po -p el/el.po $a > el/`basename $a`\n"' | sh

3. Let’s see what we created,

$ ls el/
el.po    glossary.xml  goscustdesk.xml     
gosfeedback.xml  gosoverview.xml  gosstartsession.xml 
legal.xml  figures  gosbasic.xml  goseditmainmenu.xml 
gosnautilus.xml  gospanel.xml     gostools.xml        
user-guide.xml
$ _

The main file is user-guide.xml, which references the rest of the XML files.

4. One additional step I like to do is convert all those individual .xml in a single big XML file just before performing the conversion to PDF. This helps to figure out any markup mistakes that could have been caused during the translation.

cd el/

xmllint --noent user-guide.xml --output documentation-user-guide.xml

This step does not have the desired effect with the XML in the user-guide because the include files are referenced with “<include xmlns=”http://www.w3.org/2001/XInclude” href=”gosbasic.xml”/>” rather than the “&gosbasic;” which “xmllint –noent” appears to like. Other GNOME documentation use the latter style. Lazyweb, any tips so that xmllint can create a single big fat XML file?

4. You may want to manually populate the figures/ directory. That is, copy any C/figures/* files that are not present in your LL/figures/ directory.

5. In order to create PDF files in NON-iso-8859-1, we need to use the xetex backend,

dblatex --backend=xetex --verbose documentation-user-guide.xml

If all go well, you are greeted with a documentation-user-guide.pdf document.

Two things may go wrong here; there is either an invalid construct in the XML file or you have stumbled on a XeTex bug for your language.

For the Greek language there is a known bug and a workaround for XeTex.

Here is the GNOME2 User Guide (PDF) for

1. Greek (bit messy hyphenation due to workaround), and
2. Russian.

I also tried the user-guide with

Chinese: Fails to compile, encoding problem or most probably limitation in XeTeX.

Thai: Compiles just fine but no Thai font is available. How do you add fonts to XeTeX?

Punjabi: Compiles just fine but no Hindi font is available. How do you add fonts to XeTeX?