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
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?
