Provided by: po-debiandoc_0.7.0_all bug

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>