Build PDFs

You can build:

• non-localized pdf
• localized pdfs (if certain conditions are met)

What is a Localized PDF?

At this time, it is a pdf built from:

• The source tex file (main.tex)

• With translations from the target lingua's po file (if any -- that is, the lingua-specific po file can contain zero or more translated messages, and whatever is present and matches the source file string ("message") is used).
• With localized images found by looking in the following sibling directories in the following order:

  • images-<lingua>

  • images-draft

Note: Updating the pot file from main.tex is done manually on an as needed basis by maintainers. po files will be exported from Launchpad translations to trunk (thanks to Ubuntu Translators) and should not be modified.

What is a non-Localized PDF?

It is a pdf built from the the source tex file with no translations applied.

Caveats

• The toolchain does not presently support all linguas (also called "locales"), notably (some) non-Latin ones such as Chinese.
• Figure placement in LaTeX is approximate and may result in Figures not being positioned exactly following the text. That is, if there is tex content, as follows, the figure (the screenshot) may not be between the two paragraphs:

a paragraph
\screenshot{file.png}{ss:filereflable}{My Caption}
another paragraph

• The Ubuntu Manual folks suggest that to make figures appear exactly where the author intended, it is necessary to build each lingua's PDF separately, inserting page breaks (or the equivalent) manually into tex files.

• If latex special characters ($, %, _, {, }, &, #) are inserted through a translation unescaped (not preceded by a backslash) in a context that is invalid for LaTeX, the pdf build breaks. Despite an effort to fix this programatically (trunk revision 64), it turns out to be unfeasible (only LaTex can deduce the context -- there's no simple rule). Thus, translators will need to be aware and educated.

Build Non-Localized PDF

Just run make in the root directory, as in:

make

This produces main.pdf.

Build Localized PDF(s)

Requirements

1. LINGUAS file in root directory must contain the target locale code.

   • Note: For clarity, let's keep this with one locale per line and in alphabetical order.

2. po/ must contain a po file for the target locale code.

   • Note: It is probably best that no one create po files and commit them to trunk. The plan is that po files will be exported to trunk (through Launchpad) based on the work of Ubuntu Translators.

The following requirements are met, if possible, by the langs_pdf script (see below).

1. If building for publication, you must have the images-<lingua> branch for each target lingua as a sibling directory to your trunk directory, if it exists. For example, for French: https://code.edge.launchpad.net/~ubuntu-developer-manual/ubuntu-developer-manual/images-fr.

2. If building for writing purposes, you must have the images-draft branch as a sibling directory: https://code.edge.launchpad.net/~ubuntu-developer-manual/ubuntu-developer-manual/images-draft

Build All Target Lingua PDFs

Build PDFs for all configured target locales as follows.

1. Be in trunk's root directory
2. Create all PDFs:

   • ./lang_pdfs

This:

• Uses bzr branch or pull to update sibling image branches, if they exist, for each lingua in LINGUAS and for images-draft.

• Generates pdf files for each (valid and configured) lingua in LINGUAS file, named as follows:

main-<lingua>.pdf

For example, the generated French pdf filename is: main-fr.pdf (because the LINGUAS file contains "fr" and the po/fr.po exists).

• The generated Spanish pdf filename is: main-es.pdf.

• The generated Portuguese/Brazil pdf filename is: main-pt_BR.pdf.

Build A Single Lingua PDF

In this case, we execute make and also specify the make target (langpdf). We also must pass a LANG=<lingua> argument to specify the language we want.

For example, to build a Spanish pdf:

make langpdf LANG=es

This generates: main-es.pdf

Note: One must first build the non-localized pdf with make at least once in a pristine branch.