Provided by:
po4a_0.41-1_all 
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).