Linux Certif

Toute la documentation sur la certification Linux LPI

Locale::Po4a::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 personnalisations 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.

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

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>
 
 

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