Linux Certif

Toute la documentation sur la certification Linux LPI

Locale::Po4a::TeX.3pm

NOM

Locale::Po4a::TeX - Convertit les documents TeX (ou dA~XrivA~Xs) depuis/vers des fichiers PO

DESCRIPTION

L'objectif du projet po4a [po for anything --- po pour tout] est de simplifier la traduction (et de faA~Xon plus intA~Xressante, la maintenance des traductions) en utilisant les outils gettext dans des domaines pour lesquels ils n'A~Xtaient pas destinA~Xs, 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 crA~Xer d'autres modules pour des documents basA~Xs sur le format TeX.

Les utilisateurs devraient plutA~Xt utiliser le module LaTeX, qui hA~Xrite du module TeX et contient les dA~Xfinitions des commandes LaTeX les plus courantes.

TRADUCTION AVEC PO4A::TEX

Ce module peut A~Xtre utilisA~X directement pour traiter des documents dans un format gA~XnA~Xrique TeX. Il dA~Xcoupera le document en blocs plus petits (paragraphes, blocs verbatim, ou des A~XlA~Xments encore plus petits comme les titres ou index).

Il y a quelques options (dA~Xcrites dans la section suivante) qui peuvent permettre de paramA~Xtrer ce comportement. Si A~Xa ne correspond pas au format de votre document, vous A~Xtes encouragA~X A~  A~Xcrire votre propre module dA~XrivA~X de celui-ci, pour dA~Xcrire en dA~Xtails votre format. Consultez la section AX Writing derivate modules AX plus bas, pour un descriptif de la procA~Xdure.

Ce module peut A~Xgalement A~Xtre configurA~X A~  l'aide de lignes commenA~Xant par AX % po4a: AX dans le fichier TeX. Ces personnalisations sont dA~Xcrites dans la section PERSONNALISATION EN LIGNE.

OPTIONS ACCEPTA~XES PAR CE MODULE

Voici les options particuliA~Xres A~  ce module :

debug

Active le dA~Xbogage pour certains mA~Xcanismes internes du module. Regardez les sources pour savoir ce qui peut A~Xtre dA~XboguA~X.

no_wrap

Liste d'environnements, sA~XparA~Xs par des virgules, dont les retours A~  la ligne ne doivent pas A~Xtre modifiA~Xs.

Notez qu'il y a une diffA~Xrence 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'A~Xtait pas dA~XjA~  enregistrA~X, po4a considA~Xrera que cet environnement ne prend pas de paramA~Xtre.

exclude_include

Liste de fichiers, sA~XparA~Xs par des deux-points, qui ne doivent pas A~Xtre inclus par les commandes \input et \include.

definitions

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

verbatim

Liste d'environnements, sA~XparA~Xs par des virgules, qui doivent A~Xtre considA~XrA~Xs comme verbatim.

Si cet environnement n'A~Xtait pas dA~XjA~  enregistrA~X, po4a considA~Xrera que cet environnement ne prend pas de paramA~Xtre.

L'utilisation de ces options permet de modifier le comportement des commandes des listes par dA~Xfaut.

PERSONNALISATION EN LIGNE

Le module TeX peut A~Xtre personnalisA~X A~  l'aide de lignes commenA~Xant par AX % po4a: AX. Ces lignes sont interprA~XtA~Xes comme des commandes pour l'analyseur. Les commandes suivantes sont reconnues :

% po4a: command commande1 alias commande2

Indique que les paramA~Xtres de la commande commande1 doivent A~Xtre traitA~Xs de la mA~Xme faA~Xon que les paramA~Xtres de la commande commande2.

% po4a: command commande1 paramA~Xtres

Ceci permet de dA~Xcrire en dA~Xtail les paramA~Xtres de la commande commande1. Cette information est ensuite utilisA~Xe pour vA~Xrifier le nombre de paramA~Xtres et leurs types.

Vous pouvez prA~XcA~Xder la commande commande1 <par :>

un astA~Xrisque (*)

po4a extraira cette commande des paragraphes (si elle est situA~Xe A~  une extrA~XmitA~X du paragraphe). Les traducteurs auront alors A~  traduire les paramA~Xtres qui ont A~XtA~X marquA~Xs comme pouvant A~Xtre traduits.

un plus (+)

Comme pour un astA~Xrisque, la commande sera extraite si elle apparaA~Xt A~  une extrA~XmitA~X d'un bloc, mais ses paramA~Xtres ne seront pas traduits sA~XparA~Xment. Le traducteur aura A~  traduire la commande concatA~XnA~Xe A~  tous ses paramA~Xtres. Ceci permet de conserver plus de contexte, et est utile pour les commandes avec des mots courts en paramA~Xtre, qui peuvent avoir plusieurs significations (et traductions).

Note : dans ce cas, vous n'avez pas A~  prA~Xciser quels paramA~Xtres sont traduisibles, mais po4a doit connaA~Xtre les types et le nombre de paramA~Xtres.

un moins (-)

Dans ce cas, la commande ne sera jamais extraite d'un bloc. Mais si elle apparaA~Xt seule dans un bloc, alors seuls les paramA~Xtres marquA~Xs comme traduisibles seront prA~XsentA~Xs au traducteur. C'est utile pour les commandes pour les polices. Ces commandes ne doivent gA~XnA~Xralement pas A~Xtre sA~XparA~Xes de leur paragraphe (pour conserver le contexte), mais il n'y a pas de raison de dA~Xranger le traducteur avec ces commandes si la chaA~Xne entiA~Xre est englobA~Xe dans cette commande.

Le paramA~Xtre paramA~Xtres est une suite de [] (pour indiquer un paramA~Xtre optionnel) ou {} (pour indiquer un paramA~Xtre obligatoire). Vous pouvez placer un tiret-bas (_) entre ces crochets ou accolades pour indiquer que ce paramA~Xtre doit A~Xtre traduit. Par exemple:
 % po4a: command *chapter [_]{_}
Ceci indique que la commande chapter a deux paramA~Xtres : un optionnel (titre court) et un obligatoire, qui doivent tous deux A~Xtre traduits. Si vous voulez indiquer que la commande href a deux paramA~Xtres obligatoires, que vous ne voulez pas traduire l'URL (le premier paramA~Xtre), et que vous ne voulez pas que cette commande soit sA~XparA~Xe d'un paragraphe (ce qui permet au traducteur de dA~Xplacer le lien dans une phrase), vous pouvez utiliser :
 % po4a: command -href {}{_}
Dans ce cas, l'information indiquant quels paramA~Xtres doivent A~Xtre traduits n'est utilisA~Xe que si un paragraphe n'est composA~X que de cette commande.

% po4a: environment env paramA~Xtres

Ceci permet de dA~Xfinir les paramA~Xtres acceptA~Xs par l'environnement env. Cette information sera ensuite utilisA~Xe pour vA~Xrifier le nombre de paramA~Xtres de la commande \begin, et permet de prA~Xciser quels paramA~Xtres doivent A~Xtre traduits. La syntaxe du paramA~Xtre paramA~Xtres est la mA~Xme que celle dA~Xcrite pour les commandes. Le premier paramA~Xtre de la commande \begin est le nom de l'environnement. Ce paramA~Xtre ne doit pas A~Xtre spA~XcifiA~X dans la liste des paramA~Xtres. Voici quelques exemples :
 % po4a: environment multicols {}
 % po4a: environment equation

Comme pour les commandes, env peut A~Xtre prA~XcA~XdA~X d'un plus (+) pour indiquer que la commande \begin doit A~Xtre traduite avec tous ses paramA~Xtres.

% po4a: separator env "regex"

Indique que l'environnement doit A~Xtre dA~XcoupA~X suivant l'expression rationnelle donnA~Xe.

L'expression rationnelle doit A~Xtre dA~XlimitA~Xe par des guillemets droits. Elle ne doit pas crA~Xer de rA~XfA~Xrence arriA~Xre. Vous devez donc utiliser (?:) si vous avez besoin d'un groupe. Elle peut nA~Xcessiter des caractA~Xres d'A~Xchappement.

Par exemple, le module LaTeX utilise l'expression rationnelle ``(?:&|\\\\)'' pour traduire sA~XparA~Xment chaque cellule d'un tableau (les lignes sont sA~XparA~Xes par '\\' et les cellules par '&').

La notion d'environnement est A~Xtendue au type affichA~X dans le fichier PO. Ceci peut A~Xtre utilisA~X pour rA~Xaliser un dA~Xcoupage suivant ``\\\\'' dans le premier paramA~Xtre 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 ignorA~Xs dans cet environnement.

Si cet environnement n'A~Xtait pas dA~XjA~  enregistrA~X, po4a considA~Xrera que cet environnement ne prend pas de paramA~Xtre.

A~XCRITURE DE MODULES DA~XRIVA~XS

pre_trans

post_trans

translate

Encapsulation de l'appel A~  la fonction translate du module Transtractor, en ajoutant des filtres avant et aprA~Xs la traduction.

Les commentaires d'un paragraphe sont insA~XrA~Xs comme commentaires au fichier PO pour la premiA~Xre chaA~Xne de ce paragraphe.

get_leading_command($buffer)

Cette fonction retourne :

Un nom de commande

Si aucune commande n'est trouvA~Xe au dA~Xbut du buffer, cette chaA~Xne sera vide. Seules les commandes qui peuvent A~Xtre sA~XparA~Xes sont prises en compte. La table de hachage %separated_command contient la liste de ces commandes.

Une variante

Indique si une variante est utilisA~Xe. Par exemple, un astA~Xrisque (*) peut A~Xtre ajoutA~X A~  la fin des commandes de section pour indiquer qu'elles ne doivent pas A~Xtre numA~XrotA~Xes. Dans ce cas, ce champ contiendra AX * AX. S'il n'y a pas de variante, ce champ est une chaA~Xne vide.

Un tableau de couples (type de paramA~Xtre, paramA~Xtre)

Le type de paramA~Xtre peut A~Xtre soit AX { AX (pour les paramA~Xtres obligatoires) ou AX [ AX (pour les paramA~Xtres optionnels).

Le reste du buffer

Le reste du buffer aprA~Xs le retrait de la commande de tA~Xte et de ses paramA~Xtres. Si aucune commande n'est trouvA~Xe, le buffer original n'est pas modifiA~X et est retournA~X dans ce champ.

get_trailing_command($buffer)

Comme get_leading_command, mais pour les commandes A~  la fin du buffer.

translate_buffer

Traduit rA~Xcursivement un buffer en sA~Xparant du buffer les commandes de tA~Xte et de queue (pour celles qui peuvent A~Xtre traduites sA~XparA~Xment).

If a function is defined in %translate_buffer_env for the current environment, this function will be used to translate the buffer instead of translate_buffer().

read

Surcharge la fonction read du module Transtractor.

read_file

Lit rA~Xcursivement un fichier, en insA~Xrant les fichiers inclus (s'ils ne sont pas listA~Xs dans le tableau @exclude_include. Les fichier inclus sont recherchA~Xs dans le document d'entrA~Xe ou dans un rA~Xpertoire listA~X 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 AX %po4a : AX.

Consultez la section PERSONNALISATION EN LIGNE pour plus de dA~Xtails.

is_closed

docheader

FONCTIONS INTERNES utiliser pour dA~Xriver un analyseur (parser)

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

Un nom de commande

Une variante

Un tableau de couples (type, paramA~Xtre)

L'environnement actuel

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

Les fonctions pour les environnements sont appelA~Xes lorsqu'une commande \begin est trouvA~Xe. Elles sont appelA~Xes avec la commande \begin et ses paramA~Xtres.

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 spA~XcifiA~Xes par register_generic_command ou par une dA~Xfinition dans le fichier TeX :
 % po4a: command commande1 paramA~Xtres

generic_environment utilise les informations spA~XcifiA~Xes par register_generic_environment ou par une dA~Xfinition dans le fichier TeX :
 % po4a: command commande1 paramA~Xtres

Ces deux fonctions ne traduisent que les paramA~Xtres qui ont A~XtA~X indiquA~Xs comme A~Xtant A~  traduire (avec un AX _ AX). 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 paramA~Xtre (comme {#7} ou [#2]).

A~XTAT DE CE MODULE

Ce module a besoin de plus de tests.

Il a A~XtA~X testA~X avec un livre et la documentation Python.

LISTE DES CHOSES A~X FAIRE

DA~Xtection automatique des nouvelles commandes

Le module TeX pourrait analyser les paramA~Xtres de la commande newcommand et essayer de trouver le nombre de paramA~Xtres, leurs types et si oui ou non ils doivent A~Xtre traduits.

Traduction des sA~Xparateurs dans les environnements

Quand \item est utilisA~X comme sA~Xparateur dans un environnement, le paramA~Xtre de item est attachA~X A~  la chaA~Xne qui suit.

Certaines commandes devraient A~Xtre ajoutA~Xes A~  la pile des environnements

Ces commandes devraient A~Xtre fournies par paires. Ceci permettrait de dA~Xfinir des commandes qui dA~Xbutent ou terminent un environnement verbatim.

Autres

Divers autres points sont marquA~Xs TODO dans les sources.

BOGUES CONNUS

Divers points sont marquA~Xs FIXME dans les sources.

VOIR AUSSI

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

AUTEURS

  Nicolas FranA~Xois <nicolas.francois@centraliens.net>
 
 

TRADUCTION

  Martin Quinson (mquinson#debian.org)
 
 

COPYRIGHT ET LICENCE

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