blib::man::TeX(3pm)

NOM
Locale::Po4a::TeX - convertit les documents TeX (ou derives) depuis/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 X Writing derivate modules X plus bas, pour un descriptif de la procedure.

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

OPTIONS ACCEPTEES 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.

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.

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 X % po4a: X. 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 parametres
    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 parametre.

    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 parametres 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 composee que de cette commande.

% po4a: environment env parametres
    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 parametres 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 caractere 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}.

ECRITURE DE MODULES DERIVES

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

    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 X * X. 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 X { X (pour les parametres obligatoires) ou X [ X (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 retourne 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).

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 fichier inclus sont recherches dans le document d'entree ou dans un repertoire liste par la variable d'environnement TEXINPUTS.

    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 X %po4a : X.

    Consultez la section PERSONNALISATION EN LIGNE pour plus de details.

is_closed
docheader

FONCTIONS INTERNES utiliser pour deriver un analyseur (parser)
Les fonctions pour les commandes et les environnement 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 retournent 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 parametres

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

Ces deux fonctions ne traduisent que les parametres qui ont ete indiques comme etant a traduire (avec un X _ X). 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

Autres categories
    Une categorie X verbatim X pourrait etre utile pour indiquer que po4a ne doit pas chercher a remettre en forme les lignes, et que les signes '%' ne sont pas des commentaires, et que les crochets ou accolades peuvent ne pas etres fermes.

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.

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>

TRADUCTION
 Martin Quinson (mquinson#debian.org)

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