blib::man::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 facon plus interessante, la maintenance des traductions) en utilisant les outils gettext dans des domaines pour lesquels ils n'etaient pas destines, comme la documentation.

Locale::Po4a::Man est un module qui permet d'aider la traduction de documentations ecrites au format nroff (utilise 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 presente pas le texte tel qu'il se trouve dans la page de manuel, mais cache les parties au format nroff les plus brutes, de facon a ce que les traducteurs ne puissent pas y mettre la pagaille.

  Retours a la ligne
Les paragraphes non indentes sont automatiquement remis en forme pour les traducteurs. Ceci peut generer de legeres differences dans le document genere parce que les regles de remise en forme utilisees par groff ne sont pas des plus claires. Par exemple, deux espaces apres une parenthese peuvent etre conserves, alors que les regle typographiques ne demandent qu'a conserver deux espaces apres un point (l'anglais n'etant pas ma langue natale, des informations sur ce sujet sont les bienvenues).

De toute facon, la seule difference concernera l'emplacement d'espaces additionnels dans des paragraphes remis en forme, et je pense que ca vaut le cout.

  Specification de la police
La premiere modification concerne les demandes de changement de police. Dans nroff, il y a plusieurs facon de specifier qu'un mot doit etre affiche avec une police plus petite, en gras ou en italique. Dans le texte a traduire, il n'y a qu'une facon, empruntee au format pod (Perl Online Documentation) :

I<texte> -- texte en italique
    equivalent a \fItexte\fP ou X .I texte X

B<texte> -- texte en gras
    equivalent a \fBtexte\fP ou X .B texte X

R<text> -- texte roman
    equivalent a \fRtexte\fP

CW<text> -- texte a chasse fixe
    equivalent a \f(CWtexte\fP ou X .CW texte X

Remarque : La police CW n'est pas disponible pour tous les formats de sortie de groff. Il n'est pas recommande de l'utiliser, mais est fourni pour vous rendre service.

  Modification automatique de caracteres
Po4a modifie automatiquement certains caracteres 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 changes en simple tiret (-) dans le fichier PO. Par la suite, tous les tirets sont changes en signes moins roff (\-) lorsque la traduction est inseree dans le document de sortie.

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

espaces insecables
    Les traducteurs peuvent utiliser des espaces insecables dans leurs traductions. Ces espaces insecables (0xA0) seront modifies en un espace insecable roff ('\ ').

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

    Pour eviter ces modifications, les traducteurs peuvent inserer un espace roff de taille nulle (c'est-a-dire en utilisant respectivement `\&` ou '\&').

  Utiliser des X < X ou des X > X dans les traductions
Puisque ces caracteres sont utilises pour delimiter 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 ACCEPTEES PAR CE MODULE
Voici les options particulieres a ce module :

debug
    Active le debogage pour certains mecanismes internes du module. Regardez les sources pour savoir ce qui peut etre debogue.

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 defaut. Ce module echouera lorsqu'il rencontrera une section .de, .ie ou .if.

    verbatim
        Indique que les sections .de, .ie ou .if doivent etre copiees telles quelles depuis l'original vers le document traduit.

    translate
        Indique que les sections .de, .ie ou .if doivent etre proposees a la traduction. Vous ne devriez utiliser cette option que si une de ces sections contient une chaine a traduire. Sinon, verbatim doit lui etre preferee.

untranslated
noarg
translate_joined
translate_each
    Ces options permettent de specifier le comportement d'une nouvelle macro (definie par une requete .de), ou d'une macro non supportee par po4a. Elles prennent en parametre une liste de macros separees par des virgules. Par exemple :

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

    Note : si une macro n'est pas supportee par po4a, et si vous considerez qu'il s'agit d'une macro groff standard, vous devriez la soumettre a l'equipe de developpement de po4a.

    untranslated indique que cette macro (et ses parametres) ne doivent pas etre traduits.

    noarg est comme untranslated, a l'exception que po4a verifiera qu'aucun parametre n'est fourni a la macro.

    translate_joined indique que po4a doit proposer de traduire les parametres de la macro.

    Avec translate_each, les parametres de po4a seront egalement proposes a la traduction, mais chacun d'entre eux sera traduit separement.

no_wrap
    Cette option prend en parametre une liste de couples debut:fin separes par des virgules, dans lesquels debut et fin sont des commandes qui delimitent le debut et la fin d'une section qui ne doit pas etre remise en forme.

    Note : aucun test n'est effectue pour s'assurer que la commande fin correspond a sa commande debut. Toute commande de fin finit le mode d'absence de mise en forme. Si vous avez une macro debut (respectivement fin), vous pouvez specifier une fin existante (comme fi), ou un debut existant (comme nf) en contrepartie. Ces macros (et leurs parametres) ne seront pas traduites.

inline
    Cette option permet de specifier une liste de macros separees par des virgules qui ne doivent pas couper le paragraphe en cours. La chaine a traduire contiendra alors tata <.tete titi toto> tutu, ou tata est la commande qui ne doit pas provoquer de coupure.

ECRITURE DE PAGES DE MANUEL COMPATIBLES AVEC PO4A::MAN
Ce module est encore tres limite, et le sera probablement toujours, parce qu'il n'est pas un veritable interpreteur nroff. Il devrait etre possible de faire un vrai interpreteur nroff, qui permettrait aux auteurs d'utiliser toutes les macros existantes ou meme d'en definir de nouvelle dans leurs pages, mais nous n'en avons pas envie. Ce serait trop difficile, et nous ne pensons pas que cela soit necessaire. 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 implemente dans po4a, que nous ne sommes pas prets a corriger, et qui resteront des difficultes qu'il vous faudra eviter si vous voulez que des traducteurs s'occupent de votre documentation.

  N'utilisez pas les macros definies par mdoc
L'ensemble des macros decrites dans mdoc(7) (qui sont beaucoup utilisees par les BSD) n'est pas supporte par po4a, et ne le sera probablement pas. Il necessiterait un analyseur completement different, que nous ne sommes pas prets a fournir. Sur ma machine, il n'y a que 63 pages utilisant mdoc, sur un total de 4323. Cependant, si quelqu'un veut implementer un support pour mdoc, nous l'inclurons avec plaisir.

  Ne programmez pas en nroff
nroff est un langage de programmation complet, avec des definitions de macros, des operations conditionnees, etc. Comme cet analyseur n'est pas un analyseur complet pour nroff, il ne pourra pas gerer les pages utilisant ces possibilites (il y en a environ 200 sur ma machine).

  Evitez d'inclure des fichiers si possible
La macro groff X .so X permettant d'inclure un autre fichier est supportee, mais, de ma propre experience, elle rend la manipulation de la page de manuel plus compliquee, puisque tous les fichiers doivent etre installes au bon endroit pour pouvoir visualiser le resultat (c'est-a-dire, qu'il casse d'une certaine facon l'option X -l X de man).

  Utilisez un jeu de macros simple
Il y a encore quelques macros qui ne sont pas supportees par po4a::man. La raison a cela est que nous n'arrivons pas a trouver leur documentation. Voici la liste des macros non supportees mais tout de meme utilisees sur ma machine. Notez que cette liste n'est pas exhaustive puisque le programme echoue lorsque la premiere macro non supportee est rencontree. 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

  Conclusion
Pour resumer cette section, faites simple et n'essayez pas d'etre trop astucieux lors de l'ecriture de vos pages de manuel. Beaucoup de choses sont possibles en nroff et ne sont pas supportees 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 specifier les parametres des macros sur la meme ligne que la macro. Meme si c'est valable en nroff, cela compliquerait trop l'analyseur pour etre gere.

Bien sur, une autre possibilite 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 grace a po4a::man, ce n'est plus necessaire. Cela etant dit, si la documentation provient d'une source au format pod ou xml, il serait preferable de traduire le format source et non pas celui genere. Dans la plupart des cas, po4a::man detectera les pages de manuel generees et affichera un avertissement. Il refusera meme de traiter les pages generees depuis un format Pod, parce que ces pages sont parfaitement traitees par po4a::pod et parce que leur contrepartie nroff definit beaucoup de nouvelles macros pour lesquelles je ne veux pas ecrire de support. Sur ma machine, 1432 des 4323 pages sont generees depuis le format pod et seront ignorees par po4a::man.

Dans la plupart des cas, po4a::man detectera le probleme 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 erronee. Ces cas sont des X bogues X ;) Si vous rencontrez un de ces cas, assurez-vous de le signaler, avec un correctif si possible...

ETAT DE CE MODULE
Je pense que ce module est encore a l'etat beta, mais peut etre utilise pour la plupart des pages existantes. J'ai lance des tests, qui traitent toutes les pages de ma machine et comparent l'original avec la version traitee avec po4a. Voici les resultats :

 nombre de pages      : 5060

 Pages ignorees       : 1742 (34%)
 Echec de l'analyseur :  530 (12% ; 18% des non ignorees)

 fonctionne
 parfaitement         : 1947 (39% ; 59% des non ignorees ; 70% des traitees)
 retours a la ligne   :  409 ( 8% ; 12% des non ignorees ; 15% des traitees)
 retours a la ligne et/ou
 changement de police :  364 ( 7% ; 11% des non ignorees ; 13% des traitees)

 problemes non
 detectes             :   68 ( 1% ;  2% des non ignorees ;  2% des traitees)

Les pages ignorees le sont parce que ce ne sont pas les fichiers sources. Elles sont par exemple generees depuis un fichier POD ou SGML. Dans ce cas, vous devriez traduire le [veritable] fichier source avec le module po4a correspondant a la place de la page de manuel.

Les echecs de l'analyseur sont dus aux pages utilisant mdoc(7), qui utilisent des conditions avec .if, qui definissent de nouvelles macros, qui utilisent des polices non standard ou, de facon plus generale, qui ne suivent pas les conseils de la section precedente.

Les pages avec des problemes non detectes sont traitees sans avertissement par po4a::man, mais la sortie generee est differente de l'original (des chaines sont presentes dans l'original, mais pas dans la version normalisee par po4a, ou le contraire). Il s'agit de bogues de po4a, mais indique le plus souvent des problemes dans la page d'origine.

La plupart des pages de la categorie X retours a la ligne et/ou changement de police X n'ont que l'emplacement des retours a la ligne de change (mais il etait trop difficile de le detecter automatiquement) ou souffrent d'autres problemes de formatage plus serieux (c'est-a-dire des passages en italique ou gras, etc.).

Donc, il semble que puisque les pages ignorees sont traduisibles avec po4a::pod et puisque les changements de retours a la ligne sont acceptables dans la plupart des cas, la version actuelle de po4a peut traduire 80% des pages de manuel de ma machine. De plus, la plupart des pages non traduisibles peuvent etre corrigees avec les simples astuces donnees ci-dessus. N'est-ce pas formidable ?

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

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

TRADUCTION
 Martin Quinson (mquinson#debian.org)

COPYRIGHT ET LICENCE
Copyright 2002, 2003, 2004, 2005 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).