Provided by: po4a_0.69-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 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.

       De toute façon, la seule différence concernera l’emplacement d’espaces additionnelles 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ç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 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 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 traducteurs 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).

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 contrôle 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.

       generated
           Cette option spécifie que le fichier a été généré, et que po4a ne doit pas chercher à
           détecter si la page de manuel à été généré depuis un autre format. Elle est
           obligatoire pour utiliser po4a sur des pages de manuel générées. Notez que la
           traduction des pages générées au lieu des pages sources est souvent plus fragile, et
           donc une mauvaise idée.

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

           Elle permet de sélectionner une gestion du format mdoc plus stricte, en demandant à
           po4a de ne pas traduire la section « NAME ». En effet, les pages mdoc dont la section
           « NAME » est traduite n’auront ni en-tête ni pied de page.

           D’après la page de manuel groff_mdoc, les sections NAME, SYNOPSIS et DESCRIPTION sont
           obligatoires. Aucun symptôme n’est connu pour les sections SYNOPSIS ou DESCRIPTION
           traduites, mais vous pouvez les indiquer de cette façon : -o
           mdoc=NAME,SYNOPSIS,DESCRIPTION

           Ce problème avec les pages mdoc peut aussi être résolu avec un addendum du même type
           que le suivant :
            PO4A-HEADER:mode=before;position=^.Dd
            .TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"

       The following options specify the behavior of a user-defined macro (with a .de request),
       or of a classical macro that is not supported by po4a. They take as argument a comma-
       separated list of macros. For example:

        -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 roff standard, vous devriez la soumettre à l’équipe de développement de po4a.

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

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

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

       translate_each
           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 début:fin séparés par des
           virgules, dans lesquels début 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 end correspond à sa
           commande begin ; toute commande de fin termine le mode d’absence de renvoi à la ligne.
           Si vous avez une macro début (respectivement fin) qui n'a pas de end (respectivement
           begin), vous pouvez spécifier une fin existante (comme fi), ou un début existant
           (comme nf) comme correspondance. 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ù tete est la commande qui ne doit pas provoquer de coupure.

       unknown_macros
           Cette option indique à po4a comment traiter les macros inconnues. Par défaut, po4a
           échoue en émettant un avertissement. Les valeurs suivantes sont autorisées : failed
           (la valeur par défaut), untranslated, noarg, translate_joined, translate_each
           (veuillez consulter les définitions de ces valeurs ci-dessus).

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

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

       Ce module peut être utilisé avec presque toutes les pages de manuel existantes.

       Des tests sont régulièrement effectués sur une machine Linux :

       •   un tiers des pages est refusé parce qu’elles ont été générées à partir d’un autre
           format supporté par po4a (par exemple POD ou SGML).

       •   10% des pages restantes sont rejetées avec une erreur (par exemple lorsqu’une macro
           groff n’est pas supportée).

       •   Ensuite, moins d’1% des pages est accepté par po4a, mais présente des erreurs
           significatives (c’est-à-dire certains mots disparaissent ou des mots sont ajoutés)

       •   les autres pages sont généralement supportées sans problème plus important que des
           différences d’espacement ou de remise en forme des lignes (également des problèmes de
           police dans moins de 10% des pages sur lesquelles po4a opère).

VOIR AUSSI

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

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