Ubuntu Manpage: Locale::Po4a::Man - Convertir des pages de manuel depuis ou vers des fichiers PO

NOM

       Locale::Po4a::Man - Convertir 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 équipes de traduction. 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 qu’elles soient protégées des maladresses des équipes de traduction.

Retours à la ligne
Les paragraphes non indentés sont automatiquement remis en forme pour les équipes de traduction. 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.

De toute façon, la seule différence concernera l’emplacement d’espaces additionnelles dans des
paragraphes remis en forme, et je pense que cela en vaut le cout.

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 « .I texte »

B<texte> -- texte en gras
équivalent à \fBtexte\fP ou « .B texte »

R<text> -- texte roman
équivalent à \fRtexte\fP

CW<text> -- texte à chasse fixe
équivalent à \f(CWtexte\fP ou « .CW texte »

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 équipes de traduction peuvent forcer l’utilisation d’un trait d’union en utilisant le caractère
roff « \[hy] » dans leurs traductions.

espaces insécables
Les équipes de traduction peuvent utiliser des espaces insécables dans leurs traductions. Ces espaces
insécables (0xA0 en latin1) seront modifiées en une espace insécable roff ('\ ').

modifications de guillemets
`` et '' sont respectivement changés en \*(lq and \*(rq.

Pour éviter ces modifications, les équipes de traduction peuvent insérer une 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 ACCEPTÉES PAR CE MODULE

Voici les options particulières à 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 contrôle 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 à été généré depuis un autre format. Elle est obligatoire pour utiliser po4a sur des
pages de manuel générées. Notez que la traduction des pages générées au lieu des pages sources est
souvent plus fragile, et donc une mauvaise idée.

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 spécifient le comportement d’une macro utilisateur (avec une requête .de), ou d’une
macro classique qui n'est pas 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 début:fin séparés par des virgules, dans
lesquels début 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 end correspond à sa commande begin ;
toute commande de fin termine le mode d’absence de renvoi à la ligne. Si vous avez une macro début
(respectivement fin) qui n'a pas de end (respectivement begin), vous pouvez spécifier une fin
existante (comme fi), ou un début existant (comme nf) comme correspondance. 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 (consultez les définitions de ces valeurs ci-
dessus).

ÉCRITURE 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 interpréteur 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 équipes de traduction.

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 personnes s’occupent de la traduction 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

Cela 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 équipes de
traduction (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…

ÉTAT 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 :

       •   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).

       •   10%  des  pages restantes sont rejetées avec une erreur (par exemple lorsqu’une macro groff n’est pas
           supportée).

       •   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)

       •   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

       Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)

AUTEURS

        Denis Barbier <barbier@linuxfr.org>
        Nicolas François <nicolas.francois@centraliens.net>
        Martin Quinson (mquinson#debian.org)

TRADUCTION

        Martin Quinson (mquinson#debian.org)

COPYRIGHT ET LICENCE

       Copyright © 2002-2008 SPI, Inc.

       Ce  programme est un logiciel libre ; vous pouvez le copier et / ou le modifier sous les termes de la GPL
       v2.0 ou suivante (voir le fichier COPYING).

perl v5.38.2                                       2024-08-28                           LOCALE::PO4A::MAN.3PM(1)