[DDR] doc po-debiandoc (fut: developers-reference.sgml)
Attention, y'a un piege. Ce mail est bien une demande de relecture, mais de
la doc en anglais du paquet po-debiandoc, qui sert à traduire les debiandoc
sans heurs. Merci aux relecteurs/testeurs.
On Thu, Nov 14, 2002 at 02:48:36AM +0100, Frédéric Bothamy wrote:
> * Martin Quinson <Martin.Quinson@tuxfamily.org> [2002-11-12 14:37] :
> > On Tue, Nov 12, 2002 at 02:00:55PM +0100, Antoine Hulin wrote:
> > > > Au passage, on pourrait imaginer de passer à po-debiandoc, qui est (comme
> > > > chacun le sait) l'incarnation pour debiandoc de la famille d'outils po4a.
> > >
> > > J'avais déjà transmis tes longues explications à Frédéric ;^)
> >
> > Merci, Frédéric, dit moi si cette doc est suffisante, et ce qu'il faudrait
> > ajouter pour qu'elle le soit [encore plus].
>
> Ouf, je trouve enfin le temps de répondre (entre 2 traductions).
>
> Ta doc est vraiment bien faite. Trois petits suggestions :
>
> - le schéma fait croire que la procédure est compliquée et lourde à
> mettre en place, ce qui n'est pas la cas. Il faudrait peut-être un
> conseil au lecteur en lui indiquant les 3 méthodes importantes de
> travail : à partir de rien, en reprenant une traduction déjà faite en
> sgml et à partir d'une traduction déjà faite en po (qui sera
> clairement la plus utilisée) pour qu'il puisse se repérer plus
> facilement et puisse suivre une liste d'étapes bien définies,
J'ai passé le schéma à la fin, en résumé graphique pour pas faire fuir le
lecteur. Il faudrait mettre de la couleur, mais en ASCII pur, c'est pas
simple ;)
> - indiquer les paquets debian à installer (oui, je sais, c'est
> évident, mais bon), je propose gettext (en suggérant gettext-el) et
> po-debiandoc (debiandoc-sgml et autres sont nécessaires, mais dans
> l'étape suivate),
po-debiandoc est suffisant (avec ses dépendances), alors j'ai rien mis à ce
sujet. Tu crois vraiment que c'est necessaire ?
> - la placer quelque part sur le Web pour que l'on puisse y faire
> référence facilement.
D'ici peu, ca sera la page de manuel de po-debiandoc (section 7), donc ca
devrait etre bon, non ?
> > Je signale que le po dispo sur ma page est plus à jour que celle que je
> > t'avais filé, puisqu'il est syncronisé sur la derniere version en cvs alors
> > que celle que je t'avais filé correspondait à la version du paquet.
>
> Merci pour le découpage. Tu a fait comment pour les paragraphes
> présents dans la traduction et pas dans l'original ? Il faudra que je
> les rajoute à la fin, je suppose.
Oui, pour l'instant, tu es obligé d'éditer le sgml en fin de processus pour
les ajouter. Mais c'est peut etre temporaire (j'ai soumis une idée à Denis,
et j'attend de savoir ce qu'il en pense -- c'est lui l'implementeur en chef
;)
> En fait, si je peux proposer ma (très) petite expérience de ce soir
> (qui consiste à refaire le travail que tu as décrit pour la dernière
> version traduite par Antoine), au niveau des corrections à appliquer
> pour que debiandoc2po passe bien (découpage d'un sgml traduit
> existant), il suffit de comptabiliser les balises <p> dans le
> paragraphe précédant l'erreur indiquée (d'ailleurs, Emacs fait très
> bien la compilation avec renvoi vers la ligne du fichier d'origine, un
> bonheur. Astuce : compiler avec debiandoc2po fichier_original
> fichier_traduit > /dev/null).
C'est noté.
> Un truc un peu bizarre, c'est que le po généré par ls msgmerge
> contient les paragraphes d'origine sur une seule ligne au lieu de les
> garder comme elles étaient dans le po d'origine. Peut-être une option
> de msgmerge ?
Voir mon mail sur gettext et la normalisation, ca vient peut etre de là.
Ceci dit, ce que tu dis me semble impossible. msgmerge normalise les
fichiers. T'es sur que tu parles pas de l'un des outils po-debiandoc? Eux ne
normalisent rien du tout.
> Donc, là, pour le moment, il me suffit de prendre ton fichier mis à
> jour, de traduire les "fuzzy" et de recomposer le fichier .sgml et le
> tour est joué ? Ça paraît trop facile comme ça ...
Et pourtant, c'est ca. [à ceci près qu'il faut ajouter les morceaux qui ne
sont pas des traductions à la main pour l'instant]
C'est la magie de PO4A ;)
En attachement, j'ai collé le pod qui servira à généré la page man
d'introduction à po-debiandoc. Si tu voulais bien la relire et la commenter,
ca serait cool.
Oui, je sais, elle est en anglais, et ca fait pas sérieux pour un outil de
traduction. Mais, question d'honneur, je la traduirais avec po-pod (quand ca
marchera ;)
Bye, Mt.
PS: Denis, j'ai commité cette page dans po-debiandoc/doc/po-debiandoc.7.pod
J'ai essayé de faire des mails de commit comme expliqué sur les pages de
savannah, mais j'ai visiblement merdé quelque part...
PPS: désolé pour le léger hors sujet.
--
Dans un pays d'extrême droite, On y parle beaucoup de Dieu, parce que ça
fait longtemps, qu'il a quitté les lieux.
-- Frères misère
=head1 NAME
po-debiandoc - introduction
=head1 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 formated 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 to apply them to the translation. Diff'ing the original can
sometime do the trick, but in case of major reorganisation, with chapters
being moving around, updating the translation proved to be a real pain, and
no tool where 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 supposed in this document. If
needed, you may refer to the documentation of this package, available in the
B<gettext-doc> package.
=head1 HOW TO BEGIN A NEW TRANSLATION USING PO-DEBIANDOC?
To begin a new translation using po-debiandoc, you have to do the following
steps:
=over 2
=item -
Make a new pot file, representing the text which have to be translated under
the gettext format. For that, use the I<debiandoc2pot> program like that:
$ debiandoc2pot original.sgml > original.pot
=item -
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 usefull to use the po mode of emacs, 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.
=back
=head1 HOW TO 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 I<po2debiandoc> program like that (where XX is the
language code):
$ po2debiandoc original.sgml XX.po > XX.sgml
That's it, you have your translated sgml file, which you can now convert to
the format you want.
=head1 WHAT TO DO WHEN THE ORIGINAL CHANGED?
Debian documentation often evolves, and thing becomes complicated when the
original author change the english document. To update your translation when
the original change, do the following steps:
=over 2
=item -
Regenerate a new C<pot> file using the I<debiandoc2pot> command again:
$ debiandoc2pot original.new.sgml > original.new.pot
=item -
Syncronize the C<po> file you translated against this new C<pot> file:
$ msgmerge XX.po original.new.pot > XX.new.po && mv XX.new.po XX.po
=item -
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 C<po> file
manually. Likewise, you may have to rework the translation for paragraph
which were modified a bit (to make sure you won't miss any of them,
I<msgmerge> mark them as "fuzzy").
So, you have to update manually the resulting C<po> file using your
favourite po editor. Make sure all strings are translated, and that you
removed all the fuzzy marks (after reviewing the corresponding
translations).
=back
Once your C<po> file is up-to-date again, without any untranslated or fuzzy
string, you can generate a translated sgml file, like explained in the
previous section.
=head1 HOW TO CONVERT AN EXISTING TRANSLATION TO THIS SYSTEM?
Often, you used to translate manually the document happily until a major
reorganization of the original document. When it happens, you want to
convert to po-debiandoc, but you don't want to redo your translation from
the scratch.
Don't worry, this case is also handeled by po-debiandoc, but be warned that
this operation is a bit more error prone than the rest. (Note: if the
document use conditional inclusion of file, please refere to the
corresponding section below) Here is the procedure for that:
=over 2
=item -
First, you have to get the original.sgml you used to do your translation. It
has to have exactly the same content than 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, B<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).
=item -
Then, remove every part you added in the translation and which were not in
the original document. For example, if you added you name to the authors,
you need to remove that. Likewise, remove all the extra chapters you added
(like "about this translation"). Don't worry, you'll be able to add them
again afterward (see section "HOW TO ADD CONTENT TO THE TRANSLATION").
=item -
Generate a completely translated, but not up to date C<po> file from your
XX.sgml translation and the original.old.sgml files using the following
command:
$ debiandoc2po original.old.sgml XX.sgml > XX.po
This command should not generate any warning. If there is some, that means
that the translated and the original files don't have exactly the same
structure. In that case, you need to edit them to correct the problem (or
I<debiandoc2po> would not be able to do its job).
There is two possible warning here: "untranslated text found in original" or
"extra text found in translation", indicating that the translation have less
(respectivelly, more) paragraphs than the original. The line number where
the desyncronisation was detected is also reported for the two files. Go
edit the files to make sure to correct that and try again.
You may also find usefull to check in the generated C<po> file to see when
the desyncronisation actually occured (ie, when the msgstr isn't 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 + debiandoc2po original.sgml translated.sgml > /dev/null), so that
you can jump on the faulty line typing enter in the logs of "compilation".
=back
Once again, you should fix the files and retry until I<debiandoc2po> 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
TO DO WHEN THE ORIGINAL CHANGED?" above.
=head1 HOW TO HANDLE CONDITIONAL FILE INCLUSION?
FIXME: Denis, I forgot ;)
=head1 HOW TO ADD EXTRA CONTENT TO THE TRANSLATION?
For now, it's impossible using the system. So, you'll have to edit the sgml
file resulting of the I<po2debiandoc> invocation in order to add what you want
to.
We are actually working on adding two options to the I<po2debiandoc> script
to allow user to add extra content. Here is the planed 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 don'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.
=head1 SHORTCOMMINGS OF THIS SYSTEM
=over 2
=item -
For now, it's impossible to add extra content to the resulting file (but we
are working on this point ;).
=item -
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).
=item -
If the original is using conditional inclusion, you're going into problems.
But it's still possible to use po-debiandoc in this case. The document
"release-notes" is full of such construction (so that the same source
produce the release notes for each architectures), and we use po-debiandoc
successfully on it to produce the french version.
=back
=head1 GRAPHICAL SUMMARY
In the following schema, you'll find a summary of all scripts, files and
operations involved in po-debiandoc. Don't be afraid by its apparent
complexity, it comes from the fact that the I<whole> system is represented
here. Once you converted your project to po-debiandoc, only the bottom right
part of the script (ie, I<debiandoc2pot>, I<msgmerge>, manual editing and
I<po2debiandoc>).
Legende: "[blabla]" indicates that blabla is a program. "{blibli}" indicates
that blibli is a manual action, either from the translator or from the original
author. And "blublu (bloblo)" indicates that blublu is a file in the bloblo
state.
fr.sgml original.sgml ---->--------+------>------------+
| | | |
| | { update of original } |
+---<---<---+ | |
| | V |
[debian | original.new.sgml------>----+
doc2po] 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)
=head1 AUTHORS
Denis Barbier <barbier@linuxfr.org>
Martin Quinson <Martin.Quinson@ens-lyon.fr>
Reply to: