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?

2 Responses to “Generating multilingual PDF files out of GNOME documentation”

  1. wolverian Says:

    XeTeX uses the system fontconfig fonts.

  2. simos Says:

    @wolverian: It appears it is an issue of the xetex configuration not being able to use another font if the default font does not support the script.

    On Ubuntu 8.10, the generated files with the default system settings use the DejaVu fonts (in evince properties), which are only fine for Latin, Greek and Cyrillic.


Leave a Reply