po-debiandoc - introduction

Debiandoc is an SGML-based documentation formatting package used for the Debian manuals. po-debiandoc is a set of scripts to ease the translation of documents formatted using debiandoc.

Until now the only solution to translate debiandoc-based document was to make another document with exactly the same content, but translated. This solution, while very easy at the first glance, have some major drawbacks. For example, it was very difficult to keep track of the changes in the original document to apply them to the translation. Diff'ing the original can sometime do the trick, but in case of a major reorganisation, with chapters being moving around, updating the translation proved to be a real pain, and no tool were available to help translators.

po-debiandoc was designed to solve this problem, among others, using some ideas which proved to be useful in the context of messages translation. Some background about gettext and its use is required to understand this document. If needed, you may refer to the documentation of this package, available in the gettext-doc package.

To begin a new translation using po-debiandoc, you have to do the following steps:

-

Make a new pot file, representing the text which have to be translated under the gettext format. For that, use the debiandoc2pot program like that:

  $ debiandoc2pot original.sgml > original.pot

-

Actually translate what should be translated. For that, you have to rename the pot file to XX.po (where XX is the ISO639 code of the language you are translating to. Use for example fr for french), and edit the resulting file. To achieve this task, you may find useful to use the Emacs po mode, or kbabel (KDE based) or gtranslator (GNOME based). If you need more information about this task, you definitively need to refer to the gettext documentation, cited above.

Once you have an up-to-date and completely translated po file, you need to convert it to an up-to-date and completely translated sgml file, so that you can generate the html format (or latex, or whatever).

For that, use the po2debiandoc program like that (where XX is the language code):

  $ po2debiandoc original.sgml XX.po > XX.sgml

That's it, you have your new translated sgml file, that you can now convert to any format you want.

Debian documentation often evolves, and things become complicated when the original author changes the english document. To update your translation when the original file has changed, do the following steps:

-

Regenerate a new CWpot file using the debiandoc2pot command again:

  $ debiandoc2pot original.new.sgml > original.new.pot

-

Synchronize the CWpo file you translated against this new CWpot file:

  $ msgmerge XX.po original.new.pot > XX.new.po && mv XX.new.po XX.po

-

Naturally, the new paragraph in the sgml won't get magically translated in the Cpo file with this operation, and you'll need to update the CWpo file manually. Likewise, you may have to rework the translation for paragraphs which were modified a bit (to make sure you won't miss any of them, msgmerge marks them as fuzzy). So, you have to update manually the resulting CWpo file using your favorite po editor. Make sure all strings are translated, and that you removed all the fuzzy marks (after reviewing the corresponding translations).

Once your CWpo file is up-to-date again, without any untranslated or fuzzy string left, you can generate a translated sgml file, as explained in the previous section.

Often, you used to translate manually the document happily until a major reorganization of the original document happened. When it happens, you want to convert to po-debiandoc, but you don't want to redo your translation from scratch.

Don't worry, this case is also handled by po-debiandoc, but be warned that this operation is a bit more error prone than the rest. (Note: if the document uses conditional inclusion of file, please refer to the corresponding section below) Here is the procedure for that:

-

First, you have to get the original.sgml you used to do your translation. It has to have exactly the same content as your translation. That is to say that if you translated the cvs version 1.34 of the original, and you want to use po-debiandoc to translate version 1.124, you have to use the version 1.34 of the original here, not version 1.124. You may even have to manually edit both the original and the translation so that they have exactly the same structure (the scripts will help you in this task).

-

Then, remove every part you added in the translation and which was not in the original document. For example, if you added your name to the authors' list, you need to remove that. Likewise, remove all the extra chapters you added (such as about this translation). Don't worry, you'll be able to add them again afterward (see section HOW DO I ADD CONTENT TO THE TRANSLATION?).

-

Generate a completely translated, but not up-to-date CWpo file from your XX.sgml translation and the original.old.sgml files using the following command:

 $ debiandoc-gettextize original.old.sgml XX.sgml > XX.po

This command should not generate any warning. If there are some, that means that the translated and the original files don't have the exact same structure. In that case, you need to edit them to correct the problem (or debiandoc-gettextize will not be able to do its job). There are two possible warnings here: untranslated text found in original or extra text found in translation, indicating that the translation has less (respectively, more) paragraphs than the original. The line number where the desynchronisation was detected is also reported for both files. Go edit the files to make sure to correct this and try again. You may also find useful to check in the generated CWpo file to see when the desynchronisation actually occurred (ie, when the msgstr is not the translation of the said msgid, but the one before or after). Another useful trick is to do that in a compilation buffer in emacs (M-x compile + debiandoc-gettextize original.sgml translated.sgml > /dev/null), so that you can jump to the faulty line typing enter in the logs of compilation.

Once again, you should fix the files and retry until debiandoc-gettextize runs without any warning.

After this difficult step, you successfully converted your translation to the po-debiandoc system. The next step will be to update your work to the current version of the original document, as explained in the section WHAT DO I DO WHEN THE ORIGINAL CHANGED? above.

It is not possible now using the system. So, you will have to edit the sgml file resulting from the po2debiandoc invocation in order to add what you want to.

We are currently working on adding two options to the po2debiandoc script that will allow the user to add extra content. Here is the planned syntax :

   --extra-author="text to add verbatim after the last author in original"
   --extra-section="filename:where should it be added"

The second one would add verbatim the content of the given file (containing for example your About this translation section) at the indicated point. This point is the number of section which should be assigned to the addendum. For example, if position is 0, the file should be added before anything else. If it is 1.4, it should be added in the first chapter, after 3 sections of the original. Note that the given point doesn't have to exist. For example, position 9999 refers to the end of the document, and 1.3.999 is the last sect2 of the third sect1 of the first chapter.

-

For now, it is impossible to add extra content to the resulting file (but we are working on this point ;).

-

SGML is sometimes very permissive, and the scripts may be somehow fragile. If you encounter some strange problems, you may want to normalize the original and/or translation using emacs in the psgml mode (in the package of same name).

-

If the original is using conditional inclusion, you are going into problems. But it is still possible to use po-debiandoc in this case. The document release-notes is full of such construction (so that the same source produces the release notes for each architecture), and we use po-debiandoc successfully on it to produce the french version.

In the following schema, you will find a summary of all scripts, files and operations involved in po-debiandoc. Do not be afraid by its apparent complexity, it comes from the fact that the whole system is represented here. Once you converted your project to po-debiandoc, only the bottom right part of the script is relevant (ie, debiandoc2pot, msgmerge, manual editing and po2debiandoc).

Legend: [foo] indicates that foo is a program. {bar} indicates that bar is a manual action, either from the translator or from the original author. And foobar (baz) indicates that foobar is a file in the baz state.

  fr.sgml    original.sgml ---->--------+------>------------+
     |           |                      |                   |
     |           |           { update of original }         |
     +---<---<---+                      |                   |
     |           |                      V                   |
  [debiandoc-    |              original.new.sgml------>----+
  gettextize]    V                      |                   |
     |     [debiandoc2pot]              |                   |
     |           |                      |                   |
     |           |               [debiandoc2pot]            |
     |           V                      |                   |
     V      original.pot                V                   V
     |           |               original.new.pot           |
     |           |                      |                   |
     |    { translation }  +--->---->---+                   |
     |           |         |            V                   |
     |           |         |       [msgmerge]               V
     V           V         ^            |                   |
     |           |         |            V                   |
     |           |         |          fr.po                 |
     |           |         |         (fuzzy)                V
     |           |         |            |                   |
     V           V         ^            V                   |
     |           |         |     {manual editing}           |
     |           |         |            |                   |
     |           |         |            V                   V
     |           |         +--<---    fr.po           original.sgml
     +----->-----+----->------>---> (up-to-date)       (up-to-date)
                                        |                   |
                                        |                   V
                                        +--->-----+-----<---+
                                                  |
                                                  V
                                           [po2debiandoc]
                                                  |
                                                  V
                                               fr.sgml
                                            (up-to-date)

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson <Martin.Quinson@ens-lyon.fr>