
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NOM

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

=head1 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.

=head1 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 B<É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 B<PERSONNALISATION EN LIGNE>.

=head1 OPTIONS ACCEPTÉES PAR CE MODULE

Voici les options particulières à ce module :

=over 4

=item B<debug>

Active le débogage pour certains mécanismes internes du module. Regardez les sources pour savoir ce qui peut être débogué.

=item B<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.

=item B<exclude_include>

Liste de fichiers, séparés par des deux-points, qui ne doivent pas être inclus par les commandes \input et \include.

=item B<definitions>

Le nom d’un fichier contenant des définitions pour po4a, telles qu’elles sont décrites dans la section B<PERSONNALISATION EN LIGNE>. Vous pouvez utiliser cette option s’il n’est pas possible de placer les définitions dans le document à traduire.

=item B<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.

=back

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

=head1 PERSONNALISATION EN LIGNE

Le module TeX peut être personnalisé à l’aide de lignes commençant par B<% po4a:>. Ces lignes sont interprétées comme des commandes pour l’analyseur. Les commandes suivantes sont reconnues :

=over 4

=item B<% po4a: command> I<commande1> B<alias> I<commande2>

Indique que les paramètres de la commande I<commande1> doivent être traités de la même façon que les paramètres de la commande I<commande2>.

=item B<% po4a: commande> I<commande1> I<paramètres>

Ceci permet de décrire en détail les paramètres de la commande I<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 I<commande1> S<par :>

=over 4

=item un astérisque (B<*>)

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.

=item un plus (B<+>)

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

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

=item un moins (B<->)

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 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 le traducteur avec ces commandes si la chaîne entière est englobée dans cette commande.

=back

Le paramètre I<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.

=item B<% po4a: environnent> I<env> I<paramètres>

Ceci définit les paramètres acceptés par l'environnement I<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 I<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, I<env> peut être précédé d’un plus (+) pour indiquer que la commande \begin doit être traduite avec tous ses paramètres.

=item B<% po4a: séparateur> I<env> B<">I<regex>B<">

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

=item B<% po4a: verbatim environnent> I<env>

Indique que I<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.

=back

=head1 ÉCRITURE DE MODULES DÉRIVÉS

=over 4

=item B<pre_trans>

=item B<post_trans>

=item B<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.

=item B<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.

=item B<get_leading_command>($buffer)

Cette fonction renvoie :

=over 4

=item 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.

=item 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<« * »>. S’il n’y a pas de variante, ce champ est une chaîne vide.

=item Un tableau de couples (type de paramètre, paramètre)

Le type de paramètre peut être soit S<« { »> (pour les paramètres obligatoires) ou S<« [ »> (pour les paramètres optionnels).

=item 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.

=back

=item B<get_trailing_command>($buffer)

Comme B<get_leading_command>, mais pour les commandes à la fin du buffer.

=item B<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().

=item B<read>

Surcharge la fonction read() du module Transtractor.

=item B<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 B<kpsewhich> de la bibliothèque Kpathsea.

Mis à part l’insertion des fichiers, c’est un simple copier-coller de la fonction read du Transtractor.

=back



=over 4

=item B<parse_definition_file>

Sous-routine permettant d’analyser un fichier contenant des directives pour po4a (par exemple pour les nouvelles commandes).

=item B<parse_definition_line>

Analyse une ligne de configuration de la forme S<« %po4a : »>.

Consultez la section B<PERSONNALISATION EN LIGNE> pour plus de détails.

=item B<is_closed>

=item B<parse>

=item B<docheader>

=back

=head1 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 :

=over 

=item Un nom de commande

=item Une variante

=item Un tableau de couples (type, paramètre)

=item L’environnement actuel

=back

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 S<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 I<commande1> I<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 I<commande1> I<paramètres>

Ces deux fonctions ne traduisent que les paramètres qui ont été indiqués comme étant à traduire (avec un S<« _ »>). 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]).

=head1 ÉTAT DE CE MODULE

Ce module a besoin de plus de tests.

Il a été testé avec un livre et la documentation Python.

=head1 LISTE DES CHOSES À FAIRE

=over 4

=item 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.

=item 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.

=item Certaines commandes devraient être ajoutées à la pile des environnements

These commands should be specified by couples.  This can be used to specify commands beginning or ending a verbatim environment.

=item Autres

Divers autres points sont marqués TODO dans les sources.

=back

=head1 BOGUES CONNUS

Divers points sont marqués FIXME dans les sources.

=head1 VOIR AUSSI

L<Locale::Po4a::LaTeX(3pm)|Locale::Po4a::LaTeX>, L<Locale::Po4a::TransTractor(3pm)|Locale::Po4a::TransTractor>, L<po4a(7)|po4a.7>

=head1 AUTEURS

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


=head1 TRADUCTION

 Martin Quinson (mquinson#debian.org)

=head1 COPYRIGHT ET LICENCE

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

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

