Provided by: po4a_0.55-1_all bug

NOM

       Locale::Po4a::TeX - Convertir les documents TeX (ou dérivés) 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::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 ÉCRITURE DE MODULES DÉRIVÉS 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 paramètres
           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 de police. 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 paramètres 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 paramètres
           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 paramètres est la même que celle décrite pour les autres 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 renvoie :

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

           Si une fonction est définie dans %translate_buffer_env pour l’environnement en cours,
           cette fonction sera utilisée pour traduire le bloc au lieu d’utiliser
           translate_buffer().

       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 fichiers inclus sont recherchés à l’aide
           de la commande kpsewhich de la bibliothèque Kpathsea.

           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 utilisées 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 renvoient 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 paramètres

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

       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

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

AUTEURS

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

TRADUCTION

        Martin Quinson (mquinson#debian.org)

COPYRIGHT ET LICENCE

       Copyright © 2004, 2005 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).