Provided by: po4a_0.23-1_all bug

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 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
       traducteurs. 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 que les traducteurs ne puissent pas y
       mettre la pagaille.

       Retours à la ligne

       Les paragraphes non indentés sont automatiquement remis en forme pour
       les traducteurs. 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, alors que les règle typographiques
       ne demandent qu’à conserver deux espaces après un point (l’anglais
       n’étant pas ma langue natale, des informations sur ce sujet sont les
       bienvenues).

       De toute façon, la seule différence concernera l’emplacement d’espaces
       additionnels dans des paragraphes remis en forme, et je pense que ça
       vaut le coût.

       Spécification de la police

       La première modification concerne les demandes de changement de police.
       Dans nroff, il y a plusieurs façon de spécifier 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 est fourni
       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 traducteurs peuvent forcer l’utilisation d’un trait d’union en
           utilisant le caractère roff ’\[hy]’ dans leurs traductions.

       espaces insécables
           Les traducteurs peuvent utiliser des espaces insécables dans leurs
           traductions. Ces espaces insécables (0xA0) seront modifiés en un
           espace insécable roff (’\ ’).

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

           Pour éviter ces modifications, les traducteurs peuvent insérer un
           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 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 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.

       untranslated
       noarg
       translate_joined
       translate_each
           Ces options permettent de spécifier le comportement d’une nouvelle
           macro (définie par une requête .de), ou d’une macro non 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 groff standard, vous devriez la
           soumettre à l’équipe de développement de po4a.

           untranslated indique que cette macro (et ses paramètres) ne doivent
           pas être traduits.

           noarg est comme untranslated, à l’exception que po4a vérifiera
           qu’aucun paramètre n’est fourni à la macro.

           translate_joined indique que po4a doit proposer de traduire les
           paramètres de la macro.

           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 dbut:fin
           séparés par des virgules, dans lesquels dbut 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 fin
           correspond à sa commande dbut. Toute commande de fin finit le mode
           d’absence de mise en forme. Si vous avez une macro dbut
           (respectivement fin), vous pouvez spécifier une fin existante
           (comme fi), ou un dbut existant (comme nf) en contrepartie. 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ù
           tata est la commande qui ne doit pas provoquer de coupure.

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

       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 traducteurs s’occupent de votre documentation.

       Nutilisez pas les macros définies par mdoc

       L’ensemble des macros décrites dans mdoc(7) (qui sont beaucoup
       utilisées par les BSD) n’est pas supporté par po4a, et ne le sera
       probablement pas. Il nécessiterait un analyseur complètement différent,
       que nous ne sommes pas prêts à fournir. Sur ma machine, il n’y a que 63
       pages utilisant mdoc, sur un total de 4323. Cependant, si quelqu’un
       veut implémenter un support pour mdoc, nous l’inclurons avec plaisir.

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

       Èvitez dinclure des fichiers si possible

       La macro groff « .so » permettant d’inclure un autre fichier est
       supportée, mais, de ma propre expérience, elle rend la manipulation de
       la page de manuel plus compliquée, puisque tous les fichiers doivent
       être installés au bon endroit pour pouvoir visualiser le résultat
       (c’est-à-dire, qu’il casse d’une certaine façon l’option « -l » de
       man).

       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

       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 traducteurs (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

       Je pense que ce module est encore à l’état bêta, mais peut être utilisé
       pour la plupart des pages existantes. J’ai lancé des tests, qui
       traitent toutes les pages de ma machine et comparent l’original avec la
       version traitée avec po4a. Voici les résultats :

        nombre de pages      : 5060

        Pages ignorées       : 1742 (34%)
        Échec de l’analyseur :  530 (12% ; 18% des non ignorées)

        fonctionne
        parfaitement         : 1947 (39% ; 59% des non ignorées ; 70% des traitées)
        retours à la ligne   :  409 ( 8% ; 12% des non ignorées ; 15% des traitées)
        retours à la ligne et/ou
        changement de police :  364 ( 7% ; 11% des non ignorées ; 13% des traitées)

        problèmes non
        détectés             :   68 ( 1% ;  2% des non ignorées ;  2% des traitées)

       Les pages ignorées le sont parce que ce ne sont pas les fichiers
       sources. Elles sont par exemple générées depuis un fichier POD ou SGML.
       Dans ce cas, vous devriez traduire le [véritable] fichier source avec
       le module po4a correspondant à la place de la page de manuel.

       Les échecs de l’analyseur sont dus aux pages utilisant mdoc(7), qui
       utilisent des conditions avec .if, qui définissent de nouvelles macros,
       qui utilisent des polices non standard ou, de façon plus générale, qui
       ne suivent pas les conseils de la section précédente.

       Les pages avec des problèmes non détectés sont traitées sans
       avertissement par po4a::man, mais la sortie générée est différente de
       l’original (des chaînes sont présentes dans l’original, mais pas dans
       la version normalisée par po4a, ou le contraire). Il s’agit de bogues
       de po4a, mais indique le plus souvent des problèmes dans la page
       d’origine.

       La plupart des pages de la catégorie « retours à la ligne et/ou
       changement de police » n’ont que l’emplacement des retours à la ligne
       de changé (mais il était trop difficile de le détecter automatiquement)
       ou souffrent d’autres problèmes de formatage plus sérieux (c’est-à-dire
       des passages en italique ou gras, etc.).

       Donc, il semble que puisque les pages ignorées sont traduisibles avec
       po4a::pod et puisque les changements de retours à 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 être corrigées avec les simples astuces
       données 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 François <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).