NOM
Locale::Po4a::TeX - convertit 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 ECRITURE DE MODULES DERIVES 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 ACCEPTEES PAR CE MODULE
Voici les options spécifiques à 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 pour les polices.
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 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.
ECRITURE DE MODULES DERIVES
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 UTILISEES POUR DERIVER 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 spcifié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]).
ETAT 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 A 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
po4a(7), Locale::Po4a::TransTractor(3pm), Locale::Po4a::LaTeX(3pm)
AUTEURS
Nicolas François <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).