NOM
Locale::Po4a::Man - convertit des pages de manuel depuis ou vers des
fichiers PO
DESCRIPTION
L'objectif du projet po4a [PO for anything -- PO pour tout] est de
simplifier la traduction (et de façon plus intéressante, la maintenance
des traductions) en utilisant les outils gettext dans des domaines pour
lesquels ils n'étaient pas destinés, comme la documentation.
Locale::Po4a::Man est un module qui permet d'aider la traduction de
documentations écrites au format nroff (utilisé pour les pages de manuel)
vers d'autres langues.
TRADUIRE AVEC PO4A::MAN
Ce module essaie autant que possible de faciliter le travail des
traducteurs. Dans ce but, il ne présente pas le texte tel qu'il se
trouve dans la page de manuel, mais cache les parties au format nroff
les plus brutes, de façon à ce que les traducteurs ne puissent pas y
mettre la pagaille.
Retours à la ligne
Les paragraphes non indentés sont automatiquement remis en forme pour
les traducteurs. Ceci peut générer de légères différences dans le document
généré parce que les règles de remise en forme utilisées par groff ne sont
pas des plus claires. Par exemple, deux espaces après une parenthèse
peuvent être conservés, alors que les règles typographiques ne demandent
qu'à conserver deux espaces après un point (l'anglais n'étant pas ma
langue natale, des informations sur ce sujet sont les bienvenues).
De toute façon, la seule différence concernera l'emplacement d'espaces
additionnels dans des paragraphes remis en forme, et je pense que ça
vaut le coût.
Spécification de la police
La première modification concerne les demandes de changement de police.
Dans nroff, il y a plusieurs façons d'indiquer qu'un mot doit être affiché
avec une police plus petite, en gras ou en italique. Dans le texte à
traduire, il n'y a qu'une façon, empruntée au format POD (Perl Online
Documentation) :
I<texte> -- texte en italique
équivalent \fItexte\fP ou .Itexte
B<texte> -- texte en gras
équivalent \fBtexte\fP ou .Btexte
R<text> -- texte roman
équivalent \fRtexte\fP
CW<text> -- texte à chasse fixe
équivalent \f(CWtexte\fP ou .CWtexte
Remarque : la police CW n'est pas disponible pour tous les formats de
sortie de groff. Il n'est pas recommandé de l'utiliser, mais elle est
fournie pour vous rendre service.
Modification automatique de caractères
Po4a modifie automatiquement certains caractères afin de faciliter la
traduction ou la revue de la traduction. Voici la liste de ces
modifications :
tirets
Les traits d'union (-) et les signes moins (\-) des pages de manuel
sont changés en simple tiret (-) dans le fichier PO. Par la suite,
tous les tirets sont changés en signes moins roff (\-) lorsque la
traduction est insérée dans le document de sortie.
Les traducteurs peuvent forcer l'utilisation d'un trait d'union en
utilisant le caractère roff '\[hy]' dans leurs traductions.
espaces insécables
Les traducteurs peuvent utiliser des espaces insécables dans leurs
traductions. Ces espaces insécables (0xA0 en latin1) seront modifiés
en un espace insécable roff ('\ ').
modifications de guillemets
`` et '' sont respectivement changés en \*(lq and \*(rq.
Pour éviter ces modifications, les traducteurs peuvent insérer un
espace roff de taille nulle (c'est-à-dire en utilisant
respectivement `\&` ou '\&').
Utiliser des < ou des > dans les traductions
Puisque ces caractères sont utilisés pour délimiter les changements de
police, vous ne pouvez pas les utiliser tels quels. Utilisez E<lt> et
E<gt> à la place (comme pour le format pod, encore une fois).
OPTIONS ACCEPTEES PAR CE MODULE
Voici les options spécifiques à ce module :
debug
Active le débogage pour certains mécanismes internes du module.
Regardez les sources pour savoir ce qui peut être débogué.
verbose
Augmente le niveau de bavardage.
groff_code
Cette option permet de changer le comportement du module lorsqu'il
rencontre une section .de, .ie ou .if. Elle peut prendre les
valeurs suivantes :
fail
Il s'agit de la valeur par défaut. Ce module échouera lorsqu'il
rencontrera une section .de, .ie ou .if.
verbatim
Indique que les sections .de, .ie ou .if doivent être copiées
telles quelles depuis l'original vers le document traduit.
translate
Indique que les sections .de, .ie ou .if doivent être proposées
à la traduction. Vous ne devriez utiliser cette option que si une
de ces sections contient une chaîne à traduire. Sinon, verbatim
doit lui être préférée.
generated
Cette option spécifie que le fichier a été généré, et que po4a ne doit
pas chercher à détecter si la page de manuel a été générée depuis un autre
format. Elle permet d'utiliser po4a sur des pages de manuel générées.
Cette option ne prend aucun paramètre.
mdoc
Cette option n'est utile que pour les pages au format mdoc.
Elle permet de sélectionner une gestion du format mdoc plus stricte,
en demandant à po4a de ne pas traduire la section NAME. En effet,
les pages mdoc dont la section NAME est traduite n'auront ni en-tête
ni pied de page.
D'après la page de manuel groff_mdoc, les sections NAME, SYNOPSIS et
DESCRIPTION sont obligatoires. Aucun symptôme n'est connu pour les
sections SYNOPSIS ou DESCRIPTION traduites, mais vous pouvez les
indiquer de cette façon : -o mdoc=NAME,SYNOPSIS,DESCRIPTION
Ce problème avec les pages mdoc peut aussi être résolu avec un
addendum du même type que le suivant :
PO4A-HEADER:mode=before;position=^.Dd
.TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"
Les options suivantes permettent de spécifier le comportement d'une
nouvelle macro (définie par une requête .de), ou d'une macro non supportée
par po4a. Elles prennent en paramètre une liste de macros séparées par des
virgules. Par exemple :
-o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX
Note : si une macro n'est pas supportée par po4a et si vous considérez
qu'il s'agit d'une macro roff standard, vous devriez la soumettre à
l'équipe de développement de po4a.
untranslated
untranslated indique que cette macro (et ses paramètres) ne doivent
pas être traduits.
noarg
noarg est comme untranslated, à l'exception que po4a vérifiera
qu'aucun paramètre n'est fourni à la macro.
translate_joined
translate_joined indique que po4a doit proposer de traduire les
paramètres de la macro.
translate_each
Avec translate_each, les paramètres de po4a seront également proposés
à la traduction, mais chacun d'entre eux sera traduit séparément.
no_wrap
Cette option prend en paramètre une liste de couples dbut:fin séparés
par des virgules, dans lesquels dbut et fin sont des commandes qui
délimitent le début et la fin d'une section qui ne doit pas être
remise en forme.
Note : aucun test n'est effectué pour s'assurer que la commande fin
correspond à sa commande dbut. Toute commande de fin finit le mode
d'absence de mise en forme. Si vous avez une macro dbut
(respectivement fin), vous pouvez spécifier une fin existante (comme
fi), ou un début existant (comme nf) en contrepartie. Ces macros (et
leurs paramètres) ne seront pas traduites.
inline
Cette option permet de spécifier une liste de macros séparées par des
virgules qui ne doivent pas couper le paragraphe en cours. La chaîne à
traduire contiendra alors tata <.tete titi toto> tutu, où tete est
la commande qui ne doit pas provoquer de coupure.
unknown_macros
Cette option indique à po4a comment traiter les macros inconnues.
Par défaut, po4a échoue en mettant un avertissement. Les valeurs
suivantes sont autorisées : failed (la valeur par défaut),
untranslated, noarg, translate_joined, translate_each.
ECRITURE DE PAGES DE MANUEL COMPATIBLES AVEC PO4A::MAN
Ce module est encore très limité, et le sera probablement toujours, parce
qu'il n'est pas un véritable interpréteur nroff. Il devrait être possible
de faire un vrai interprteur nroff, qui permettrait aux auteurs
d'utiliser toutes les macros existantes ou même d'en définir de nouvelle
dans leurs pages, mais nous n'en avons pas envie. Ce serait trop
difficile, et nous ne pensons pas que cela soit nécessaire. Nous pensons
que si les auteurs de pages de manuel veulent voir leurs travaux
traduits, ils doivent s'adapter pour faciliter le travail des
traducteurs.
Il y a donc des limitations connues de l'analyseur de pages de manuel
implémenté dans po4a, que nous ne sommes pas prêts à corriger, et qui
resteront des difficultés qu'il vous faudra éviter si vous voulez que des
traducteurs s'occupent de votre documentation.
Ne programmez pas en nroff
nroff est un langage de programmation complet, avec des définitions de
macros, des opérations conditionnées, etc. Comme cet analyseur n'est pas
un analyseur complet pour nroff, il ne pourra pas gérer les pages
utilisant ces possibilités (il y en a environ 200 sur ma machine).
Utilisez un jeu de macros simple
Il y a encore quelques macros qui ne sont pas supportées par po4a::man.
La raison à cela est que nous n'arrivons pas à trouver leur
documentation. Voici la liste des macros non supportées mais tout de même
utilisées sur ma machine. Notez que cette liste n'est pas exhaustive
puisque le programme échoue lorsque la première macro non supportée est
rencontrée. Si vous trouvez des informations à propos de ces macros, nous
ajouterons leur support avec plaisir. Ces macros rendent environ 250
pages non utilisables avec po4a::man.
.. ." .AT .b .bank
.BE ..br .Bu .BUGS .BY
.ce .dbmmanage .do .En
.EP .EX .Fi .hw .i
.Id .l .LO .mf
.N .na .NF .nh .nl
.Nm .ns .NXR .OPTIONS .PB
.pp .PR .PRE .PU .REq
.RH .rn .S< .sh .SI
.splitfont .Sx .T .TF .The
.TT .UC .ul .Vb .zZ
Cacher du texte po4a
Parfois, un auteur sait que certaines parties ne peuvent pas être
traduite, et ne doivent pas être extraites par po4a. Par exemple, une
option peut recevoir un paramètre other, qui ne doit pas être traduit et
other est également le dernier élément d'une liste. Dans le premier cas,
other ne doit pas être traduit et dans le second, il doit être traduit.
Dans ce cas, l'auteur peut éviter l'extraction de certaines chaînes par
po4a en utilisant une construction groff particulière :
.if !'po4a'hide' .B other
(nécessite l'option -o groff_code=verbatim) ;
on peut aussi définir une nouvelle macro pour automatiser ceci :
.de IR_untranslated
. IR \\$@
..
.IR_untranslated \-q ", " \-\-quiet
(nécessitera les options -o groff_code=verbatim et -o
untranslated=IR_untranslated ; avec cette construction, la condition
.if !'po4a'hide' n'est pas strictement nécessaire puisque po4a
n'analysera pas le contenu de la définition de la macro) ;
ou en utilisant un alias :
.als IR_untranslated IR
.IR_untranslated \-q ", " \-\-quiet
(nécessitera l'option -o untranslated=als,IR_untranslated).
Conclusion
Pour résumer cette section, faites simple et n'essayez pas d'être trop
astucieux lors de l'écriture de vos pages de manuel. Beaucoup de choses
sont possibles en nroff et ne sont pas supportées par cet analyseur. Par
exemple, n'essayez pas de jouer avec des \c pour interrompre le
traitement du texte (c'est le cas de 40 pages sur ma machine). Aussi,
assurez-vous de spécifier les paramètres des macros sur la même ligne que
la macro. Même si c'est valable en nroff, cela compliquerait trop
l'analyseur pour être géré.
Bien sûr, une autre possibilité est d'utiliser un autre format, plus
pratique pour les traducteurs (comme pod en utilisant po4a::pod ou un
format de la famille XML comme le SGML), mais grâce à po4a::man, ce n'est
plus nécessaire. Cela tant dit, si la documentation provient d'une
source au format POD ou XML, il serait préférable de traduire le format
source et non pas celui généré. Dans la plupart des cas, po4a::man
détectera les pages de manuel générées et affichera un avertissement. Il
refusera même de traiter les pages générées depuis un format POD, parce que
ces pages sont parfaitement traitées par po4a::pod et parce que leur
contrepartie nroff définit beaucoup de nouvelles macros pour lesquelles
je ne veux pas écrire de support. Sur ma machine, 1432 des 4323 pages
sont générées depuis le format pod et seront ignorées par po4a::man.
Dans la plupart des cas, po4a::man détectera le problème et refusera de
traiter la page, en affichant un message d'avertissement. Dans quelques
rares cas, le programme se terminera sans avertissement, mais la sortie
sera erronée. Ces cas sont des bogues ;) Si vous rencontrez un de ces
cas, assurez-vous de le signaler, avec un correctif si possible...
ETAT DE CE MODULE
Ce module peut être utilisé avec presque toutes les pages de manuel
existantes.
Des tests sont régulièrement effectués sur une machine Linux :
o un tiers des pages est refusé parce qu'elles ont été générées à partir
d'un autre format support par po4a (par exemple pod ou SGML) ;
o 10% des pages restantes sont rejetés avec une erreur (par exemple
lorsqu'une macro groff n'est pas supportée) ;
o ensuite, moins d'1% des pages est accepté par po4a, mais présente des
erreurs significatives (c'est-à-dire certains mots disparaissent ou
des mots sont ajoutés) ;
o les autres pages sont généralement supportées sans problème plus
important que des différences d'espacement ou de remise en forme des
lignes (également des problèmes de police dans moins de 10% des pages
sur lesquelles po4a opère).
VOIR AUSSI
po4a(7), Locale::Po4a::TransTractor(3pm), Locale::Po4a::Pod(3pm)
AUTEURS
Denis Barbier <barbier@linuxfr.org>
Nicolas François <nicolas.francois@centraliens.net>
Martin Quinson (mquinson#debian.org)
COPYRIGHT ET LICENCE
Copyright 2002-2008 par SPI, inc.
Ce programme est un logiciel libre ; vous pouvez le copier et / ou le
modifier sous les termes de la GPL (voir le fichier COPYING).