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

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…