Linux Certif

Toute la documentation sur la certification Linux LPI

Locale::Po4a::Man.3pm

NOM

Locale::Po4a::Man - convertit des pages de manuels depuis/vers des fichiers PO

DESCRIPTION

L'objectif du projet po4a [po for anything --- po pour tout] est de simplifier la traduction (et de faA~Xon plus intA~Xressante, la maintenance des traductions) en utilisant les outils gettext dans des domaines pour lesquels ils n'A~Xtaient pas destinA~Xs, comme la documentation.

Locale::Po4a::Man est un module qui permet d'aider la traduction de documentations A~Xcrites au format nroff (utilisA~X 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 prA~Xsente pas le texte tel qu'il se trouve dans la page de manuel, mais cache les parties au format nroff les plus brutes, de faA~Xon A~  ce que les traducteurs ne puissent pas y mettre la pagaille.

Retours A~  la ligne

Les paragraphes non indentA~Xs sont automatiquement remis en forme pour les traducteurs. Ceci peut gA~XnA~Xrer de lA~XgA~Xres diffA~Xrences dans le document gA~XnA~XrA~X parce que les rA~Xgles de remise en forme utilisA~Xes par groff ne sont pas des plus claires. Par exemple, deux espaces aprA~Xs une parenthA~Xse peuvent A~Xtre conservA~Xs, alors que les rA~Xgles typographiques ne demandent qu'A~  conserver deux espaces aprA~Xs un point (l'anglais n'A~Xtant pas ma langue natale, des informations sur ce sujet sont les bienvenues).

De toute faA~Xon, la seule diffA~Xrence concernera l'emplacement d'espaces additionnels dans des paragraphes remis en forme, et je pense que A~Xa vaut le coA~Xt.

SpA~Xcification de la police

La premiA~Xre modification concerne les demandes de changement de police. Dans nroff, il y a plusieurs faA~Xon de spA~Xcifier qu'un mot doit A~Xtre affichA~X avec une police plus petite, en gras ou en italique. Dans le texte A~  traduire, il n'y a qu'une faA~Xon, empruntA~Xe au format pod (Perl Online Documentation) :

I<texte> --- texte en italique

A~Xquivalent A~  \fItexte\fP ou AX .I texte AX

B<texte> --- texte en gras

A~Xquivalent A~  \fBtexte\fP ou AX .B texte AX

R<text> --- texte roman

A~Xquivalent A~  \fRtexte\fP

CW<text> --- texte A~  chasse fixe

A~Xquivalent A~  \f(CWtexte\fP ou AX .CW texte AX

Remarque : La police CW n'est pas disponible pour tous les formats de sortie de groff. Il n'est pas recommandA~X de l'utiliser, mais elle est fournie pour vous rendre service.

Modification automatique de caractA~Xres

Po4a modifie automatiquement certains caractA~Xres 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 changA~Xs en simple tiret (-) dans le fichier PO. Par la suite, tous les tirets sont changA~Xs en signes moins roff (\-) lorsque la traduction est insA~XrA~Xe dans le document de sortie.

Les traducteurs peuvent forcer l'utilisation d'un trait d'union en utilisant le caractA~Xre roff '\[hy]' dans leurs traductions.

espaces insA~Xcables

Les traducteurs peuvent utiliser des espaces insA~Xcables dans leurs traductions. Ces espaces insA~Xcables (0xA0 en latin1) seront modifiA~Xs en un espace insA~Xcable roff ('\ ').

modifications de guillemets

`` et '' sont respectivement changA~Xs en \*(lq and \*(rq.

Pour A~Xviter ces modifications, les traducteurs peuvent insA~Xrer un espace roff de taille nulle (c'est-A~ -dire en utilisant respectivement `\&` ou '\&').

Utiliser des AX < AX ou des AX > AX dans les traductions

Puisque ces caractA~Xres sont utilisA~Xs pour dA~Xlimiter les changements de police, vous ne pouvez pas les utiliser tels quels. Utilisez E<lt> et E<gt> A~  la place (comme pour le format pod, encore une fois).

OPTIONS ACCEPTA~XES PAR CE MODULE

Voici les options particuliA~Xres A~  ce module :

debug

Active le dA~Xbogage pour certains mA~Xcanismes internes du module. Regardez les sources pour savoir ce qui peut A~Xtre dA~XboguA~X.

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 dA~Xfaut. Ce module A~Xchouera lorsqu'il rencontrera une section .de, .ie ou .if.

verbatim

Indique que les sections .de, .ie ou .if doivent A~Xtre copiA~Xes telles quelles depuis l'original vers le document traduit.

translate

Indique que les sections .de, .ie ou .if doivent A~Xtre proposA~Xes A~  la traduction. Vous ne devriez utiliser cette option que si une de ces sections contient une chaA~Xne A~  traduire. Sinon, verbatim doit lui A~Xtre prA~XfA~XrA~Xe.

generated

Cette option spA~Xcifie que le fichier a A~XtA~X gA~XnA~XrA~X, et que po4a ne doit pas chercher A~  dA~Xtecter si la page de manuel A~  A~XtA~X gA~XnA~XrA~X depuis un autre format. Elle permet d'utiliser po4a sur des pages de manuel gA~XnA~XrA~Xes. Cette option ne prend aucun paramA~Xtre.

mdoc

Cette option n'est utile que pour les pages au format mdoc.

Elle permet de sA~Xlectionner une gestion du format mdoc plus stricte, en demandant A~  po4a de ne pas traduire la section AX NAME AX. En effet, les pages mdoc dont la section AX NAME AX est traduite n'auront ni en-tA~Xte ni pied de page.

D'aprA~Xs la page de manuel groff_mdoc, les sections NAME, SYNOPSIS et DESCRIPTION sont obligatoires. Aucun symptome n'est connu pour les sections SYNOPSIS ou DESCRIPTION traduites, mais vous pouvez les indiquer de cette faA~Xon : -o mdoc=NAME,SYNOPSIS,DESCRIPTION

Ce problA~Xme avec les pages mdoc peut aussi A~Xtre rA~Xsolu avec un addendum du mA~Xme 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 spA~Xcifier le comportement d'une nouvelle macro (dA~Xfinie par une requA~Xte .de), ou d'une macro non supportA~Xe par po4a. Elles prennent en paramA~Xtre une liste de macros sA~XparA~Xes par des virgules. Par exemple :

  -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX
 
 

Note : si une macro n'est pas supportA~Xe par po4a, et si vous considA~Xrez qu'il s'agit d'une macro groff standard, vous devriez la soumettre A~  l'A~Xquipe de dA~Xveloppement de po4a.

untranslated

untranslated indique que cette macro (et ses paramA~Xtres) ne doivent pas A~Xtre traduits.

noarg

noarg est comme untranslated, A~  l'exception que po4a vA~Xrifiera qu'aucun paramA~Xtre n'est fourni A~  la macro.

translate_joined

translate_joined indique que po4a doit proposer de traduire les paramA~Xtres de la macro.

translate_each

Avec translate_each, les paramA~Xtres de po4a seront A~Xgalement proposA~Xs A~  la traduction, mais chacun d'entre eux sera traduit sA~XparA~Xment.

no_wrap

Cette option prend en paramA~Xtre une liste de couples dA~Xbut:fin sA~XparA~Xs par des virgules, dans lesquels dA~Xbut et fin sont des commandes qui dA~Xlimitent le dA~Xbut et la fin d'une section qui ne doit pas A~Xtre remise en forme.

Note : aucun test n'est effectuA~X pour s'assurer que la commande fin correspond A~  sa commande dA~Xbut. Toute commande de fin finit le mode d'absence de mise en forme. Si vous avez une macro dA~Xbut (respectivement fin), vous pouvez spA~Xcifier une fin existante (comme fi), ou un dA~Xbut existant (comme nf) en contrepartie. Ces macros (et leurs paramA~Xtres) ne seront pas traduites.

inline

Cette option permet de spA~Xcifier une liste de macros sA~XparA~Xes par des virgules qui ne doivent pas couper le paragraphe en cours. La chaA~Xne A~  traduire contiendra alors tata <.tete titi toto> tutu, oA~X tete est la commande qui ne doit pas provoquer de coupure.

unknown_macros

Cette option indique A~  po4a comment traiter les macros inconnues. Par dA~Xfaut, po4a A~Xchoue en A~Xmettant un avertissement. Les valeurs suivantes sont autorisA~Xes : failed (la valeur par dA~Xfaut), untranslated, noarg, translate_joined, translate_each.

A~XCRITURE DE PAGES DE MANUEL COMPATIBLES AVEC PO4A::MAN

Ce module est encore trA~Xs limitA~X, et le sera probablement toujours, parce qu'il n'est pas un vA~Xritable interprA~Xteur nroff. Il devrait A~Xtre possible de faire un vrai interprA~Xteur nroff, qui permettrait aux auteurs d'utiliser toutes les macros existantes ou mA~Xme d'en dA~Xfinir de nouvelle dans leurs pages, mais nous n'en avons pas envie. Ce serait trop difficile, et nous ne pensons pas que cela soit nA~Xcessaire. 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 implA~XmentA~X dans po4a, que nous ne sommes pas prA~Xts A~  corriger, et qui resteront des difficultA~Xs qu'il vous faudra A~Xviter 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 dA~Xfinitions de macros, des opA~Xrations conditionnA~Xes, etc. Comme cet analyseur n'est pas un analyseur complet pour nroff, il ne pourra pas gA~Xrer les pages utilisant ces possibilitA~Xs (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 supportA~Xes par po4a::man. La raison A~  cela est que nous n'arrivons pas A~  trouver leur documentation. Voici la liste des macros non supportA~Xes mais tout de mA~Xme utilisA~Xes sur ma machine. Notez que cette liste n'est pas exhaustive puisque le programme A~Xchoue lorsque la premiA~Xre macro non supportA~Xe est rencontrA~Xe. Si vous trouvez des informations A~  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
 
 

Hiding text to po4a

Sometimes, the author knows that some parts are not translatable, and should not be extracted by po4a. For example, an option may accept an other argument, and other may also appear as the last item of a list. In the first case, other should be not be translatable. And in the second case, other should be translated.

In such case, the author can avoid po4a to extract some strings, using some special groff constructs:

  .if !'po4a'hide' .B other
 
 

(this will require the -o groff_code=verbatim option)

A new macro can also be defined to automate this:
 .de IR_untranslated
 .    IR \\$@
 ..

  .IR_untranslated \-q ", " \-\-quiet
 
 

(this will require the options -o groff_code=verbatim and -o untranslated=IR_untranslated; with this construct, the .if !'po4a'hide' conditional is not strictly needed since po4a will not parse the internal of the macro definition)

or using an alias:
 .als IR_untranslated IR

  .IR_untranslated \-q ", " \-\-quiet
 
 

(this will require the -o untranslated=als,IR_untranslated option)

Conclusion

Pour rA~Xsumer cette section, faites simple et n'essayez pas d'A~Xtre trop astucieux lors de l'A~Xcriture de vos pages de manuel. Beaucoup de choses sont possibles en nroff et ne sont pas supportA~Xes 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 spA~Xcifier les paramA~Xtres des macros sur la mA~Xme ligne que la macro. MA~Xme si c'est valable en nroff, cela compliquerait trop l'analyseur pour A~Xtre gA~XrA~X.

Bien sA~Xr, une autre possibilitA~X 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 grA~Xce A~  po4a::man, ce n'est plus nA~Xcessaire. Cela A~Xtant dit, si la documentation provient d'une source au format pod ou xml, il serait prA~XfA~Xrable de traduire le format source et non pas celui gA~XnA~XrA~X. Dans la plupart des cas, po4a::man dA~Xtectera les pages de manuel gA~XnA~XrA~Xes et affichera un avertissement. Il refusera mA~Xme de traiter les pages gA~XnA~XrA~Xes depuis un format Pod, parce que ces pages sont parfaitement traitA~Xes par po4a::pod et parce que leur contrepartie nroff dA~Xfinit beaucoup de nouvelles macros pour lesquelles je ne veux pas A~Xcrire de support. Sur ma machine, 1432 des 4323 pages sont gA~XnA~XrA~Xes depuis le format pod et seront ignorA~Xes par po4a::man.

Dans la plupart des cas, po4a::man dA~Xtectera le problA~Xme 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 erronA~Xe. Ces cas sont des AX bogues AX ;) Si vous rencontrez un de ces cas, assurez-vous de le signaler, avec un correctif si possible...

A~XTAT DE CE MODULE

Ce module peut A~Xtre utilisA~X avec presque toutes les pages de manuel existantes

Des tests sont rA~XguliA~Xrement effectuA~Xs sur une machine Linux :

•

un tiers des pages est refusA~X parce qu'elles ont A~XtA~X gA~XnA~XrA~Xes A~  partir d'un autre format supportA~X par po4a (par exemple pod ou SGML).

•

10% des pages restantes sont rejetA~Xs avec une erreur (par exemple lorsqu'une macro groff n'est pas supportA~Xe).

•

Ensuite, moins d'1% des pages est acceptA~X par po4a, mais prA~Xsente des erreurs significatives (c'est-A~ -dire certains mots disparaissent ou des mots sont ajoutA~Xs).

•

Les autres pages sont gA~XnA~Xralement supportA~Xes sans problA~Xme plus important que des diffA~Xrences d'espacement ou de remise en forme des lignes (A~Xgalement des problA~Xmes de police dans moins de 10% des pages sur lesquelles po4a opA~Xre).

VOIR AUSSI

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

AUTEURS

  Denis Barbier <barbier@linuxfr.org>
  Nicolas FranA~Xois <nicolas.francois@centraliens.net>
  Martin Quinson (mquinson#debian.org)
 
 

TRADUCTION

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