Provided by: po4a_0.41-1_all bug

NOM

       Locale::Po4a::TeX - Convertir les documents TeX (ou derives) 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::TeX est un module qui permet d'aider a traduire des
       documents TeX dans d'autres langues. Il peut aussi servir de base pour
       creer d'autres modules pour des documents bases sur le format TeX.

       Les utilisateurs devraient plutot utiliser le module LaTeX, qui herite
       du module TeX et contient les definitions des commandes LaTeX les plus
       courantes.

TRADUCTION AVEC PO4A::TEX

       Ce module peut etre utilise directement pour traiter des documents dans
       un format generique TeX. Il decoupera le document en blocs plus petits
       (paragraphes, blocs verbatim, ou des elements encore plus petits comme
       les titres ou index).

       Il y a quelques options (decrites dans la section suivante) qui peuvent
       permettre de parametrer ce comportement. Si ca ne correspond pas au
       format de votre document, vous etes encourage a ecrire votre propre
       module derive de celui-ci, pour decrire en details votre format.
       Consultez la section 'ECRITURE DE MODULES D'ERIV'ES plus bas, pour un
       descriptif de la procedure.

       Ce module peut egalement etre configure a l'aide de lignes commencant
       par <<%po4a:>> dans le fichier TeX. Ces personnalisations sont decrites
       dans la section PERSONNALISATION EN LIGNE.

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.

       no_wrap
           Liste d'environnements, separes par des virgules, dont les retours
           a la ligne ne doivent pas etre modifies.

           Notez qu'il y a une difference 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'etait pas deja enregistre, po4a considerera
           que cet environnement ne prend pas de parametre.

       exclude_include
           Liste de fichiers, separes par des deux-points, qui ne doivent pas
           etre inclus par les commandes \input et \include.

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

       verbatim
           Liste d'environnements, separes par des virgules, qui doivent etre
           consideres comme verbatim.

           Si cet environnement n'etait pas deja enregistre, po4a considerera
           que cet environnement ne prend pas de parametre.

       L'utilisation de ces options permet de modifier le comportement des
       commandes des listes par defaut.

PERSONNALISATION EN LIGNE

       Le module TeX peut etre personnalise a l'aide de lignes commencant par
       % po4a:. Ces lignes sont interpretees comme des commandes pour
       l'analyseur. Les commandes suivantes sont reconnues:

       % po4a: command commande1 alias commande2
           Indique que les parametres de la commande commande1 doivent etre
           traites de la meme facon que les parametres de la commande
           commande2.

       % po4a: command commande1 param`etres
           Ceci permet de decrire en detail les parametres de la commande
           commande1. Cette information est ensuite utilisee pour verifier le
           nombre de parametres et leurs types.

           Vous pouvez preceder la commande commande1 <par :>

           un asterisque (*)
               po4a extraira cette commande des paragraphes (si elle est
               situee a une extremite du paragraphe). Les traducteurs auront
               alors a traduire les parametres qui ont ete marques comme
               pouvant etre traduits.

           un plus (+)
               Comme pour un asterisque, la commande sera extraite si elle
               apparait a une extremite d'un bloc, mais ses parametres ne
               seront pas traduits separement. Le traducteur aura a traduire
               la commande concatenee a tous ses parametres. Ceci permet de
               conserver plus de contexte, et est utile pour les commandes
               avec des mots courts en parametre, qui peuvent avoir plusieurs
               significations (et traductions).

               Note: dans ce cas, vous n'avez pas a preciser quels parametres
               sont traduisibles, mais po4a doit connaitre les types et le
               nombre de parametres.

           un moins (-)
               Dans ce cas, la commande ne sera jamais extraite d'un bloc.
               Mais si elle apparait seule dans un bloc, alors seuls les
               parametres marques comme traduisibles seront presentes au
               traducteur. C'est utile pour les commandes pour les polices.
               Ces commandes ne doivent generalement pas etre separees de leur
               paragraphe (pour conserver le contexte), mais il n'y a pas de
               raison de deranger le traducteur avec ces commandes si la
               chaine entiere est englobee dans cette commande.

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

           Ceci indique que la commande chapter a deux parametres: un
           optionnel (titre court) et un obligatoire, qui doivent tous deux
           etre traduits. Si vous voulez indiquer que la commande href a deux
           parametres obligatoires, que vous ne voulez pas traduire l'URL (le
           premier parametre), et que vous ne voulez pas que cette commande
           soit separee d'un paragraphe (ce qui permet au traducteur de
           deplacer le lien dans une phrase), vous pouvez utiliser:
            % po4a: command -href {}{_}

           Dans ce cas, l'information indiquant quels parametres doivent etre
           traduits n'est utilisee que si un paragraphe n'est compose que de
           cette commande.

       % po4a: environment env param`etres
           Ceci permet de definir les parametres acceptes par l'environnement
           env. Cette information sera ensuite utilisee pour verifier le
           nombre de parametres de la commande \begin, et permet de preciser
           quels parametres doivent etre traduits. La syntaxe du parametre
           param`etres est la meme que celle decrite pour les commandes. Le
           premier parametre de la commande \begin est le nom de
           l'environnement. Ce parametre ne doit pas etre specifie dans la
           liste des parametres. Voici quelques exemples:
            % po4a: environment multicols {}
            % po4a: environment equation

           Comme pour les commandes, env peut etre precede d'un plus (+) pour
           indiquer que la commande \begin doit etre traduite avec tous ses
           parametres.

       % po4a: separator env "regex"
           Indique que l'environnement doit etre decoupe suivant l'expression
           rationnelle donnee.

           L'expression rationnelle doit etre delimitee par des guillemets
           droits. Elle ne doit pas creer de reference arriere. Vous devez
           donc utiliser (?:) si vous avez besoin d'un groupe. Elle peut
           necessiter des caracteres d'echappement.

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

           La notion d'environnement est etendue au type affiche dans le
           fichier PO. Ceci peut etre utilise pour realiser un decoupage
           suivant "\\\\" dans le premier parametre obligatoire de la commande
           title. Dans ce cas, l'environnement a utiliser est title{#1}.

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

           Si cet environnement n'etait pas deja enregistre, po4a considerera
           que cet environnement ne prend pas de parametre.

'ECRITURE DE MODULES D'ERIV'ES

       pre_trans
       post_trans
       translate
           Encapsulation de l'appel a la fonction translate du module
           Transtractor, en ajoutant des filtres avant et apres la traduction.

           Les commentaires d'un paragraphe sont inseres comme commentaires au
           fichier PO pour la premiere chaine de ce paragraphe.

       get_leading_command($buffer)
           Cette fonction renvoie:

           Un nom de commande
               Si aucune commande n'est trouvee au debut du buffer, cette
               chaine sera vide. Seules les commandes qui peuvent etre
               separees sont prises en compte. La table de hachage
               %separated_command contient la liste de ces commandes.

           Une variante
               Indique si une variante est utilisee. Par exemple, un
               asterisque (*) peut etre ajoute a la fin des commandes de
               section pour indiquer qu'elles ne doivent pas etre numerotees.
               Dans ce cas, ce champ contiendra <<*>>. S'il n'y a pas de
               variante, ce champ est une chaine vide.

           Un tableau de couples (type de parametre, parametre)
               Le type de parametre peut etre soit <<{>> (pour les parametres
               obligatoires) ou <<[>> (pour les parametres optionnels).

           Le reste du buffer
               Le reste du buffer apres le retrait de la commande de tete et
               de ses parametres. Si aucune commande n'est trouvee, le buffer
               original n'est pas modifie et est renvoye dans ce champ.

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

       translate_buffer
           Traduit recursivement un buffer en separant du buffer les commandes
           de tete et de queue (pour celles qui peuvent etre traduites
           separement).

           Si une fonction est definie dans %translate_buffer_env pour
           l'environnement en cours, cette fonction sera utilisee pour
           traduire le bloc au lieu d'utiliser translate_buffer().

       read
           Surcharge la fonction read du module Transtractor.

       read_file
           Lit recursivement un fichier, en inserant les fichiers inclus
           (s'ils ne sont pas listes dans le tableau @exclude_include. Les
           fichiers inclus sont recherches a l'aide de la commande kpsewhich
           de la bibliotheque Kpathsea.

           Mis a 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
           details.

       is_closed
       docheader

FONCTIONS INTERNES utilis'ees pour d'eriver un analyseur (parser)

       Les fonctions pour les commandes et les environnements prennent, en
       plus de l'objet $self, les parametres suivants:

       Un nom de commande
       Une variante
       Un tableau de couples (type, parametre)
       L'environnement actuel

       Les 3 premiers parametres 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 parametres et le nouvel
       environnement.

       Les fonctions pour les environnements sont appelees lorsqu'une commande
       \begin est trouvee. Elles sont appelees avec la commande \begin et ses
       parametres.

       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 specifiees par
       register_generic_command ou par une definition dans le fichier TeX:
        % po4a: command commande1 param`etres

       generic_environment utilise les informations specifiees par
       register_generic_environment ou par une definition dans le fichier TeX:
        % po4a: command commande1 param`etres

       Ces deux fonctions ne traduisent que les parametres qui ont ete
       indiques comme etant a traduire (avec un <<_>>). generic_environment
       ajoutera le nom de l'environnement a la pile des environnements et
       generic_command ajoutera le nom de la commande suivi par un identifiant
       du parametre (comme {#7} ou [#2]).

'ETAT DE CE MODULE

       Ce module a besoin de plus de tests.

       Il a ete teste avec un livre et la documentation Python.

LISTE DES CHOSES `A FAIRE

       Detection automatique des nouvelles commandes
           Le module TeX pourrait analyser les parametres de la commande
           newcommand et essayer de trouver le nombre de parametres, leurs
           types et si oui ou non ils doivent etre traduits.

       Traduction des separateurs dans les environnements
           Quand \item est utilise comme separateur dans un environnement, le
           parametre de item est attache a la chaine qui suit.

       Certaines commandes devraient etre ajoutees a la pile des
       environnements
           Ces commandes devraient etre fournies par paires. Ceci permettrait
           de definir des commandes qui debutent ou terminent un environnement
           verbatim.

       Autres
           Divers autres points sont marques TODO dans les sources.

BOGUES CONNUS

       Divers points sont marques FIXME dans les sources.

VOIR AUSSI

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

AUTEURS

        Nicolas Francois <nicolas.francois@centraliens.net>

COPYRIGHT ET LICENCE

       Copyright 2004, 2005 par Nicolas FRANCOIS
       <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).