Table of Contents

Update the documentation

This how-to applies essentially to project maintainers that are using a po-doc directory for the documentation localization. These projects use the tool xml2po and xsltproc. When the maintainer updates the documentation he must also refresh the PO files. Now when the maintainer receives an updated PO file, he runs the opposite commands to update the localized documentation and also include the new images when there are some.

Check-in a new translation

When you receive a new translation not previously existing you have to create the appropriate directories in the directory that contains the XML documentation and the Makefiles.

1. First set the build configuration ready for documentation compilation:

./autogen.sh --enable-xsltproc --enable-xml2po

The tool xsltproc is used to generate an HTML format from the XML documentations. The tool xml2po is used to update the PO files from the english version, and also at the opposite way to update the localized XML documentations from the PO files.

2. Add the new po file into po-doc/ and update the LINGUAS file.

# example
cp ja.po po-doc/
vim po-doc/LINGUAS

3. Prepare the doc/ directory for the new translation.

# example
mkdir -p doc/ja/images
cp doc/C/Makefile.am doc/C/project.xml.in doc/C/project.html doc/ja
cp doc/C/images/Makefile.am doc/C/images/*.png doc/ja/images
vim configure.ac.in doc/Makefile.am doc/ja/Makefile.am doc/ja/images/Makefile.am

The translations update the XML documentations that is usually put inside a docs/ directory. In that directory you have at least one sub-directory that is the english version named C. You have to edit the appropriate Makefiles. The autoconf script also needs to be updated for the new Makefile.in output files.

4. Regenerate the configure script and new Makefiles.

./autogen.sh --enable-xsltproc --enable-xml2po

5. Now you have to update the XML localized documentation, which is explained in the next section.

Update a translation

When you receive an updated PO file you have to update the XML localized documentation.

1. Update the XML localized documentations.

make -C po-doc update-xml

2. Regenerate the .in files.

./config.status

This is needed for documentations that use autoconf substitutions like @PACKAGE_NAME@, it will only rebuild .in files like Makefile.in and project.xml.in.

3. Generate the HTML output.

make -C doc/ja/

Update the PO files

When you update the C version of the documentation you will have to update the PO files.

make -C po-doc update-po

This will generate the PO template and update all the PO files.