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

18May/092

Generating multilingual PDF files out of GNOME documentation

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?

Comments (2) Trackbacks (0)
  1. XeTeX uses the system fontconfig fonts.

    Like or Dislike: Thumb up 0 Thumb down 0

  2. @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.

    Like or Dislike: Thumb up 0 Thumb down 0


Leave a comment

Comments are filtered through Akismet for spam detection. Use of a non-personal web site or blog URL in the field below and/or comments that are off-topic or personal attacks will likely be removed at my discretion. Your opinions are welcome but please keep them polite and constructive.

No trackbacks yet.

Switch to our mobile site