Provided by: po4a_0.41-1_all bug

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

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

   Sp'ecification de la police
       La premiere modification concerne les demandes de changement de police.
       Dans nroff, il y a plusieurs facons d'indiquer 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 <<.Itexte>>

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

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

       CW<text> -- texte a chasse fixe
           equivalent a \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 recommande de l'utiliser, mais elle est
       fournie pour vous rendre service.

   Modification automatique de caract`eres
       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 en latin1) seront
           modifiees en une espace insecable roff ('\ ').

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

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

   Utiliser des <<<>> ou des <<>>> 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 ACCEPT'EES 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.

       generated
           Cette option specifie que le fichier a ete genere, et que po4a ne
           doit pas chercher a detecter si la page de manuel a ete genere
           depuis un autre format. Elle permet d'utiliser po4a sur des pages
           de manuel generees. Cette option ne prend aucun parametre.

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

           Elle permet de selectionner une gestion du format mdoc plus
           stricte, en demandant a po4a de ne pas traduire la section
           <<NAME>>. En effet, les pages mdoc dont la section <<NAME>> est
           traduite n'auront ni en-tete ni pied de page.

           D'apres 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 facon: -o mdoc=NAME,SYNOPSIS,DESCRIPTION

           Ce probleme avec les pages mdoc peut aussi etre resolu avec un
           addendum du meme 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 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 roff standard, vous devriez la soumettre a
       l'equipe de developpement de po4a.

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

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

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

       translate_each
           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 d'ebut:fin
           separes par des virgules, dans lesquels d'ebut 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 d'ebut. Toute commande de fin finit le mode
           d'absence de mise en forme. Si vous avez une macro d'ebut
           (respectivement fin), vous pouvez specifier une fin existante
           (comme fi), ou un d'ebut 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
           tete est la commande qui ne doit pas provoquer de coupure.

       unknown_macros
           Cette option indique a po4a comment traiter les macros inconnues.
           Par defaut, po4a echoue en emettant un avertissement. Les valeurs
           suivantes sont autorisees: failed (la valeur par defaut),
           untranslated, noarg, translate_joined, translate_each.

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

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

   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

   Cacher du texte `a po4a
       Parfois, un auteur sait que certaines parties ne peuvent pas etre
       traduite, et ne doivent pas etre extraites par po4a. Par exemple, une
       option peut recevoir un parametre other, qui ne doit pas etre traduit
       et other est egalement le dernier element d'une liste. Dans le premier
       cas, other ne doit pas etre traduit et dans le second, il doit etre
       traduit.

       Dans ce cas, l'auteur peut eviter l'extraction de certaines chaines par
       po4a en utilisant une construction groff particuliere:

        .if !'po4a'hide' .B other

       (necessite l'option -o groff_code=verbatim) ;

       on peut aussi definir une nouvelle macro pour automatiser ceci:
        .de IR_untranslated
        .    IR \\$@
        ..

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

       (necessitera les options -o groff_code=verbatim et -o
       untranslated=IR_untranslated ; avec cette construction, la condition
       .if !'po4a'hide' n'est pas strictement necessaire puisque po4a
       n'analysera pas le contenu de la definition de la macro);

       ou en utilisant un alias:
        .als IR_untranslated IR

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

       (necessitera l'option -o untranslated=als,IR_untranslated).

   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 <<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 etre utilise avec presque toutes les pages de manuel
       existantes.

       Des tests sont regulierement effectues sur une machine Linux:

       o   un tiers des pages est refuse parce qu'elles ont ete generees a
           partir d'un autre format supporte par po4a (par exemple POD ou
           SGML);

       o   10% des pages restantes sont rejetes avec une erreur (par exemple
           lorsqu'une macro groff n'est pas supportee);

       o   ensuite, moins d'1% des pages est accepte par po4a, mais presente
           des erreurs significatives (c'est-a-dire certains mots
           disparaissent ou des mots sont ajoutes);

       o   les autres pages sont generalement supportees sans probleme plus
           important que des differences d'espacement ou de remise en forme
           des lignes (egalement des problemes de police dans moins de 10% des
           pages sur lesquelles po4a opere).

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)

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