Ubuntu Manpage: Locale::Po4a::TeX - Convertir les documents TeX (ou dérivés) depuis ou vers des fichiers PO

NOM

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

       Il est préférable d’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 cela ne correspond pas au format de votre document, je vous encourage à écrire votre
       propre module dérivé de celui-ci, pour décrire en détails votre format. Consultez la section ÉCRITURE DE
       MODULES DÉRIVÉS 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. Ce processus est décrit dans la section PERSONNALISATION EN LIGNE.

OPTIONS ACCEPTÉES PAR CE MODULE

Voici les options particulières à 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.

Utilisez ces options pour remplacer le comportement par défaut des commandes définies.

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: commande 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 équipes de traduction 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. Les équipes de traduction auront à
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 aux équipes de
traduction. C’est utile pour les commandes de police. 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 les équipes de traduction 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: environnent env paramètres
Ceci définit les paramètres acceptés par l'environnement env et spécifie ceux à traduire. Cette
information est ensuite utilisée pour vérifier le nombre d'arguments de la commande \begin. La
syntaxe de l'argument paramètres est la même que celle décrite pour les autres 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: séparateur 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. Elle ne doit pas créer de
rétro-référence. Vous devriez utiliser (?:) si vous avez besoin d’un groupe. Elle peut aussi
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 environnent 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.

ÉCRITURE DE MODULES DÉRIVÉS

pre_trans
post_trans
add_comment
Ajoute une chaîne en tant que commentaire à ajouter autour du prochain élément traduit. Ceci est
surtout utile pour le module texinfo, car les commentaires sont automatiquement gérés dans TeX.

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 en savoir plus.

is_closed
parse
docheader

FONCTIONS INTERNES utilisées pour écrire un analyseur (parser) dérivé

       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  spécifiées  par  register_generic_environment  ou  par  une
       définition dans le fichier TeX :
        % po4a: commande 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]).

ÉTAT 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 À 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 peut être utilisé pour 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

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

AUTEURS

        Nicolas François <nicolas.francois@centraliens.net>

TRADUCTION

        Martin Quinson (mquinson#debian.org)

COPYRIGHT ET LICENCE

       Copyright © 2004, 2005 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.

       Ce programme est un logiciel libre ; vous pouvez le copier et / ou le modifier sous les termes de la  GPL
       v2.0 ou suivante (voir le fichier COPYING).

perl v5.38.2                                       2024-08-28                           LOCALE::PO4A::TEX.3PM(1)