Provided by:
po-debiandoc_0.7.0_all 
NAME
po-debiandoc - introduction
DESCRIPTION
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.
HOW DO I BEGIN A NEW TRANSLATION USING PO-DEBIANDOC?
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.
HOW DO I CONVERT BACK THE TRANSLATION TO A SGML FILE?
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.
WHAT DO I DO WHEN THE ORIGINAL FILE HAS CHANGED?
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 "pot" file using the debiandoc2pot command again:
$ debiandoc2pot original.new.sgml > original.new.pot
- Synchronize the "po" file you translated against this new "pot" 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 C"po" file with this operation, and you’ll need to
update the "po" 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 "po" 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 "po" 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.
HOW DO I CONVERT AN EXISTING TRANSLATION TO THIS SYSTEM?
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 "po" 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 "po" 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.
HOW DO I ADD EXTRA CONTENT TO THE TRANSLATION?
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.
SHORTCOMINGS OF THIS SYSTEM
- 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.
GRAPHICAL SUMMARY
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)
AUTHORS
Denis Barbier <barbier@linuxfr.org>
Martin Quinson <Martin.Quinson@ens-lyon.fr>