Provided by: po4a_0.32-1_all bug

NOM

       Locale::Po4a::TeX - Convertit les documents TeX (ou dérivés)
       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::TeX est un module qui permet d’aider à traduire des
       documents TeX dans d’autres langues. Il peut aussi servir de base pour
       créer d’autres modules pour des documents basés sur le format TeX.

       Les utilisateurs devraient plutôt utiliser le module LaTeX, qui hérite
       du module TeX et contient les définitions des commandes LaTeX les plus
       courantes.

TRADUCTION AVEC PO4A::TEX

       Ce module peut être utilisé directement pour traiter des documents dans
       un format générique TeX. Il découpera le document en blocs plus petits
       (paragraphes, blocs verbatim, ou des éléments encore plus petits comme
       les titres ou index).

       Il y a quelques options (décrites dans la section suivante) qui peuvent
       permettre de paramétrer ce comportement. Si ça ne correspond pas au
       format de votre document, vous êtes encouragé à écrire votre propre
       module dérivé de celui-ci, pour décrire en détails votre format.
       Consultez la section « Writing derivate modules » plus bas, pour un
       descriptif de la procédure.

       Ce module peut également être configuré à l’aide de lignes commençant
       par « % po4a: » dans le fichier TeX. Ces personnalisations sont
       décrites dans la section PERSONNALISATION EN LIGNE.

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

       no_wrap
           Liste d’environnements, séparés par des virgules, dont les retours
           à la ligne ne doivent pas être modifiés.

           Notez qu’il y a une différence entre un environnement sans remise
           en forme et un environnement verbatim. Il n’y a pas d’analyse des
           commandes et des commentaires dans les blocs verbatim.

           Si cet environnement n’était pas déjà enregistré, po4a considérera
           que cet environnement ne prend pas de paramètre.

       exclude_include
           Liste de fichiers, séparés par des deux-points, qui ne doivent pas
           être inclus par les commandes \input et \include.

       definitions
           Le nom d’un fichier contenant des définitions pour po4a, telles
           qu’elles sont décrites dans la section PERSONNALISATION EN LIGNE.
           Vous pouvez utiliser cette option s’il n’est pas possible de placer
           les définitions dans le document à traduire.

       verbatim
           Liste d’environnements, séparés par des virgules, qui doivent être
           considérés comme verbatim.

           Si cet environnement n’était pas déjà enregistré, po4a considérera
           que cet environnement ne prend pas de paramètre.

       L’utilisation de ces options permet de modifier le comportement des
       commandes des listes par défaut.

PERSONNALISATION EN LIGNE

       Le module TeX peut être personnalisé à l’aide de lignes commençant par
       « % po4a: ». Ces lignes sont interprétées comme des commandes pour
       l’analyseur. Les commandes suivantes sont reconnues :

       % po4a: command commande1 alias commande2
           Indique que les paramètres de la commande commande1 doivent être
           traités de la même façon que les paramètres de la commande
           commande2.

       % po4a: command commande1 paramtres
           Ceci permet de décrire en détail les paramètres de la commande
           commande1. Cette information est ensuite utilisée pour vérifier le
           nombre de paramètres et leurs types.

           Vous pouvez précéder la commande commande1 <par :>

           un astérisque (*)
               po4a extraira cette commande des paragraphes (si elle est
               située à une extrémité du paragraphe). Les traducteurs auront
               alors à traduire les paramètres qui ont été marqués comme
               pouvant être traduits.

           un plus (+)
               Comme pour un astérisque, la commande sera extraite si elle
               apparaît à une extrémité d’un bloc, mais ses paramètres ne
               seront pas traduits séparément. Le traducteur aura à traduire
               la commande concaténée à tous ses paramètres. Ceci permet de
               conserver plus de contexte, et est utile pour les commandes
               avec des mots courts en paramètre, qui peuvent avoir plusieurs
               significations (et traductions).

               Note : dans ce cas, vous n’avez pas à préciser quels paramètres
               sont traduisibles, mais po4a doit connaître les types et le
               nombre de paramètres.

           un moins (-)
               Dans ce cas, la commande ne sera jamais extraite d’un bloc.
               Mais si elle apparaît seule dans un bloc, alors seuls les
               paramètres marqués comme traduisibles seront présentés au
               traducteur. C’est utile pour les commandes pour les polices.
               Ces commandes ne doivent généralement pas être séparées de leur
               paragraphe (pour conserver le contexte), mais il n’y a pas de
               raison de déranger le traducteur avec ces commandes si la
               chaîne entière est englobée dans cette commande.

           Le paramètre paramtres est une suite de [] (pour indiquer un
           paramètre optionnel) ou {} (pour indiquer un paramètre
           obligatoire). Vous pouvez placer un tiret-bas (_) entre ces
           crochets ou accolades pour indiquer que ce paramètre doit être
           traduit. Par exemple:
            % po4a: command *chapter [_]{_}

           Ceci indique que la commande chapter a deux paramètres : un
           optionnel (titre court) et un obligatoire, qui doivent tous deux
           être traduits. Si vous voulez indiquer que la commande href a deux
           paramètres obligatoires, que vous ne voulez pas traduire l’URL (le
           premier paramètre), et que vous ne voulez pas que cette commande
           soit séparée d’un paragraphe (ce qui permet au traducteur de
           déplacer le lien dans une phrase), vous pouvez utiliser :
            % po4a: command -href {}{_}

           Dans ce cas, l’information indiquant quels paramètres doivent être
           traduits n’est utilisée que si un paragraphe n’est composé que de
           cette commande.

       % po4a: environment env paramtres
           Ceci permet de définir les paramètres acceptés par l’environnement
           env. Cette information sera ensuite utilisée pour vérifier le
           nombre de paramètres de la commande \begin, et permet de préciser
           quels paramètres doivent être traduits. La syntaxe du paramètre
           paramtres est la même que celle décrite pour les commandes. Le
           premier paramètre de la commande \begin est le nom de
           l’environnement. Ce paramètre ne doit pas être spécifié dans la
           liste des paramètres. Voici quelques exemples :
            % po4a: environment multicols {}
            % po4a: environment equation

           Comme pour les commandes, env peut être précédé d’un plus (+) pour
           indiquer que la commande \begin doit être traduite avec tous ses
           paramètres.

       % po4a: separator env "regex"
           Indique que l’environnement doit être découpé suivant l’expression
           rationnelle donnée.

           L’expression rationnelle doit être délimitée par des guillemets
           droits. Elle ne doit pas créer de référence arrière. Vous devez
           donc utiliser (?:) si vous avez besoin d’un groupe. Elle peut
           nécessiter des caractères d’échappement.

           Par exemple, le module LaTeX utilise l’expression rationnelle
           "(?:&|\\\\)" pour traduire séparément chaque cellule d’un tableau
           (les lignes sont séparées par ’\\’ et les cellules par ’&’).

           La notion d’environnement est étendue au type affiché dans le
           fichier PO. Ceci peut être utilisé pour réaliser un découpage
           suivant "\\\\" dans le premier paramètre obligatoire de la commande
           title. Dans ce cas, l’environnement à utiliser est title{#1}.

       % po4a: verbatim environment env
           Indique que env est un environnement verbatim. Les commentaires et
           les commandes seront ignorés dans cet environnement.

           Si cet environnement n’était pas déjà enregistré, po4a considérera
           que cet environnement ne prend pas de paramètre.

ÉCRITURE DE MODULES DÉRIVÉS

       pre_trans
       post_trans
       translate
           Encapsulation de l’appel à la fonction translate du module
           Transtractor, en ajoutant des filtres avant et après la traduction.

           Les commentaires d’un paragraphe sont insérés comme commentaires au
           fichier PO pour la première chaîne de ce paragraphe.

       get_leading_command($buffer)
           Cette fonction retourne :

           Un nom de commande
               Si aucune commande n’est trouvée au début du buffer, cette
               chaîne sera vide. Seules les commandes qui peuvent être
               séparées sont prises en compte. La table de hachage
               %separated_command contient la liste de ces commandes.

           Une variante
               Indique si une variante est utilisée. Par exemple, un
               astérisque (*) peut être ajouté à la fin des commandes de
               section pour indiquer qu’elles ne doivent pas être numérotées.
               Dans ce cas, ce champ contiendra « * ». S’il n’y a pas de
               variante, ce champ est une chaîne vide.

           Un tableau de couples (type de paramètre, paramètre)
               Le type de paramètre peut être soit « { » (pour les paramètres
               obligatoires) ou « [ » (pour les paramètres optionnels).

           Le reste du buffer
               Le reste du buffer après le retrait de la commande de tête et
               de ses paramètres. Si aucune commande n’est trouvée, le buffer
               original n’est pas modifié et est retourné dans ce champ.

       get_trailing_command($buffer)
           Comme get_leading_command, mais pour les commandes à la fin du
           buffer.

       translate_buffer
           Traduit récursivement un buffer en séparant du buffer les commandes
           de tête et de queue (pour celles qui peuvent être traduites
           séparément).

       read
           Surcharge la fonction read du module Transtractor.

       read_file
           Lit récursivement un fichier, en insérant les fichiers inclus
           (s’ils ne sont pas listés dans le tableau @exclude_include. Les
           fichier inclus sont recherchés dans le document d’entrée ou dans un
           répertoire listé par la variable d’environnement TEXINPUTS.

           Mis à part l’insertion des fichiers, c’est un simple copier-coller
           de la fonction read du Transtractor.

       parse_definition_file
           Sous-routine permettant d’analyser un fichier contenant des
           directives pour po4a (par exemple pour les nouvelles commandes).

       parse_definition_line
           Analyse une ligne de configuration de la forme « %po4a : ».

           Consultez la section PERSONNALISATION EN LIGNE pour plus de
           détails.

       is_closed
       docheader

FONCTIONS INTERNES utiliser pour dériver un analyseur (parser)

       Les fonctions pour les commandes et les environnements prennent, en
       plus de l’objet $self, les paramètres suivants :

       Un nom de commande
       Une variante
       Un tableau de couples (type, paramètre)
       L’environnement actuel

       Les 3 premiers paramètres sont extraits par get_leading_command ou
       get_trailing_command.

       Les fonctions pour les environnements ou les commandes retournent la
       traduction de la commande avec ses paramètres et le nouvel
       environnement.

       Les fonctions pour les environnements sont appelées lorsqu’une commande
       \begin est trouvée. Elles sont appelées avec la commande \begin et ses
       paramètres.

       Le module TeX ne fournit qu’une fonction pour les commandes et une
       fonction pour les environnements : generic_command et
       generic_environment.

       generic_command utilise les informations spécifiées par
       register_generic_command ou par une définition dans le fichier TeX :
        % po4a: command commande1 paramtres

       generic_environment utilise les informations spécifiées par
       register_generic_environment ou par une définition dans le fichier
       TeX :
        % po4a: command commande1 paramtres

       Ces deux fonctions ne traduisent que les paramètres qui ont été
       indiqués comme étant à traduire (avec un « _ »). generic_environment
       ajoutera le nom de l’environnement à la pile des environnements et
       generic_command ajoutera le nom de la commande suivi par un identifiant
       du paramètre (comme {#7} ou [#2]).

ÉTAT DE CE MODULE

       Ce module a besoin de plus de tests.

       Il a été testé avec un livre et la documentation Python.

LISTE DES CHOSES À FAIRE

       Détection automatique des nouvelles commandes
           Le module TeX pourrait analyser les paramètres de la commande
           newcommand et essayer de trouver le nombre de paramètres, leurs
           types et si oui ou non ils doivent être traduits.

       Traduction des séparateurs dans les environnements
           Quand \item est utilisé comme séparateur dans un environnement, le
           paramètre de item est attaché à la chaîne qui suit.

       Certaines commandes devraient être ajoutées à la pile des
       environnements
           Ces commandes devraient être fournies par paires. Ceci permettrait
           de définir des commandes qui débutent ou terminent un environnement
           verbatim.

       Autres
           Divers autres points sont marqués TODO dans les sources.

BOGUES CONNUS

       Divers points sont marqués FIXME dans les sources.

VOIR AUSSI

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

AUTEURS

        Nicolas François <nicolas.francois@centraliens.net>

TRADUCTION

        Martin Quinson (mquinson#debian.org)

COPYRIGHT ET LICENCE

       Copyright 2004, 2005 par Nicolas FRANÇOIS
       <nicolas.francois@centraliens.net>.

       Ce programme est un logiciel libre ; vous pouvez le copier et / ou le
       modifier sous les termes de la GPL (voir le fichier COPYING).