
        *****************************************************
        *           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::Man - Convertir des pages de manuel 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::Man est un module qui permet d’aider la traduction de
documentations écrites au format nroff (utilisé pour les pages de manuel)
vers d’autres langues.

=head1 TRADUIRE AVEC PO4A::MAN

Ce module essaie autant que possible de faciliter le travail des équipes de
traduction. Dans ce but, il ne présente pas le texte tel qu’il se trouve
dans la page de manuel, mais cache les parties au format nroff les plus
brutes, de façon à ce qu’elles soient protégées des maladresses des équipes
de traduction.

=head2 Retours à la ligne

Les paragraphes non indentés sont automatiquement remis en forme pour les
équipes de traduction. Ceci peut générer de légères différences dans le
document généré parce que les règles de remise en forme utilisées par groff
ne sont pas des plus claires. Par exemple, deux espaces après une parenthèse
peuvent être conservés.

De toute façon, la seule différence concernera l’emplacement d’espaces
additionnelles dans des paragraphes remis en forme, et je pense que cela en
vaut le cout.

=head2 Spécification de la police

La première modification concerne les demandes de changement de police. Dans
nroff, il y a plusieurs façons d’indiquer qu’un mot doit être affiché avec
une police plus petite, en gras ou en italique. Dans le texte à traduire, il
n’y a qu’une façon, empruntée au format POD (Perl Online Documentation) :

=over

=item IE<lt>texteE<gt> -- texte en italique

équivalent à \fItexte\fP ou S<« .I texte »>

=item BE<lt>texteE<gt> -- texte en gras

équivalent à \fBtexte\fP ou S<« .B texte »>

=item RE<lt>textE<gt> -- texte roman

équivalent à \fRtexte\fP

=item CWE<lt>textE<gt> -- texte à chasse fixe

équivalent à \f(CWtexte\fP ou S<« .CW texte »>

=back

S<Remarque :> La police CW n’est pas disponible pour tous les formats de
sortie de groff. Il n’est pas recommandé de l’utiliser, mais elle est
fournie pour vous rendre service.

=head2 Modification automatique de caractères

Po4a modifie automatiquement certains caractères afin de faciliter la
traduction ou la revue de la traduction. Voici la liste de ces modifications
:

=over

=item tirets

Les traits d’union (-) et les signes moins (\-) des pages de manuel sont
changés en simple tiret (-) dans le fichier PO. Par la suite, tous les
tirets sont changés en signes moins roff (\-) lorsque la traduction est
insérée dans le document de sortie.

Les équipes de traduction peuvent forcer l’utilisation d’un trait d’union en
utilisant le caractère roff « \[hy] » dans leurs traductions.

=item espaces insécables

Les équipes de traduction peuvent utiliser des espaces insécables dans leurs
traductions. Ces espaces insécables (0xA0 en latin1) seront modifiées en une
espace insécable roff ('\ ').

=item modifications de guillemets

`` et '' sont respectivement changés en \*(lq and \*(rq.

Pour éviter ces modifications, les équipes de traduction peuvent insérer une
espace roff de taille nulle (c’est-à-dire en utilisant respectivement `\&`
ou '\&').

=back

=head2 Utiliser des S<« E<lt> »> ou des S<« E<gt> »> dans les traductions

Puisque ces caractères sont utilisés pour délimiter les changements de
police, vous ne pouvez pas les utiliser tels quels. Utilisez EE<lt>ltE<gt>
et EE<lt>gtE<gt> à la place (comme pour le format POD, encore une fois).

=head1 OPTIONS ACCEPTÉES PAR CE MODULE

Voici les options particulières à ce module :

=over

=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<verbose>

Augmente le niveau de bavardage.

=item B<groff_code>

Cette option contrôle le comportement du module lorsqu’il rencontre une
section .de, .ie ou .if. Elle peut prendre les valeurs suivantes :

=over

=item I<fail>

Il s’agit de la valeur par défaut. Ce module échouera lorsqu’il rencontrera
une section .de, .ie ou .if.

=item I<verbatim>

Indique que les sections .de, .ie ou .if doivent être copiées telles quelles
depuis l’original vers le document traduit.

=item I<translate>

Indique que les sections .de, .ie ou .if doivent être proposées à la
traduction. Vous ne devriez utiliser cette option que si une de ces sections
contient une chaîne à traduire. Sinon, I<verbatim> doit lui être préférée.

=back

=item B<generated>

Cette option spécifie que le fichier a été généré, et que po4a ne doit pas
chercher à détecter si la page de manuel à été généré depuis un autre
format. Elle est obligatoire pour utiliser po4a sur des pages de manuel
générées. Notez que la traduction des pages générées au lieu des pages
sources est souvent plus fragile, et donc une mauvaise idée.

=item B<mdoc>

Cette option n’est utile que pour les pages au format mdoc.

Elle permet de sélectionner une gestion du format mdoc plus stricte, en
demandant à po4a de ne pas traduire la section « NAME ». En effet, les pages
mdoc dont la section « NAME » est traduite n’auront ni en-tête ni pied de
page.

According to the groff_mdoc page, the NAME, SYNOPSIS and DESCRIPTION
sections are mandatory.
There are no known issues with translated SYNOPSIS or DESCRIPTION section,
but you can also specify these sections this way:
 -o mdoc=NAME,SYNOPSIS,DESCRIPTION

This mdoc issue can also be solved with an addendum like this one:
 PO4A-HEADER:mode=before;position=^.Dd
 .TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"

=back

Les options suivantes spécifient le comportement d’une macro utilisateur
(avec une requête .de), ou d’une macro classique qui n'est pas supportée par
po4a. Elles prennent en paramètre une liste de macros séparées par des
virgules. Par exemple :

 -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX

S<Note :> si une macro n’est pas supportée par po4a, et si vous considérez
qu’il s’agit d’une macro roff standard, vous devriez la soumettre à l’équipe
de développement de po4a.

=over

=item B<untranslated>

B<untranslated> indique que cette macro (et ses paramètres) ne doivent pas
être traduits.

=item B<noarg>

B<noarg> est comme B<untranslated>, à l’exception que po4a vérifiera
qu’aucun paramètre n’est fourni à la macro.

=item B<translate_joined>

B<translate_joined> indique que po4a doit proposer de traduire les
paramètres de la macro.

=item B<translate_each>

Avec B<translate_each>, les paramètres de po4a seront également proposés à
la traduction, mais chacun d’entre eux sera traduit séparément.

=item B<no_wrap>

Cette option prend en paramètre une liste de couples I<début>:I<fin> séparés
par des virgules, dans lesquels I<début> et I<fin> sont des commandes qui
délimitent le début et la fin d’une section qui ne doit pas être remise en
forme.

S<Note :> aucun test n’est effectué pour s’assurer que la commande I<end>
correspond à sa commande I<begin> ; toute commande de fin termine le mode
d’absence de renvoi à la ligne. Si vous avez une macro I<début>
(respectivement I<fin>) qui n'a pas de I<end> (respectivement I<begin>),
vous pouvez spécifier une I<fin> existante (comme fi), ou un I<début>
existant (comme nf) comme correspondance. Ces macros (et leurs paramètres)
ne seront pas traduites.

=item B<inline>

Cette option permet de spécifier une liste de macros séparées par des
virgules qui ne doivent pas couper le paragraphe en cours. La chaîne à
traduire contiendra alors I<tata E<lt>.tete titi totoE<gt> tutu>, où I<tete>
est la commande qui ne doit pas provoquer de coupure.

=item B<unknown_macros>

Cette option indique à po4a comment traiter les macros inconnues. Par
défaut, po4a échoue en émettant un avertissement. Les valeurs suivantes sont
autorisées : B<failed> (la valeur par défaut), B<untranslated>, B<noarg>,
B<translate_joined>, B<translate_each> (consultez les définitions de ces
valeurs ci-dessus).

=back

=head1 ÉCRITURE DE PAGES DE MANUEL COMPATIBLES AVEC PO4A::MAN

Ce module est encore très limité, et le sera probablement toujours, parce
qu’il n’est pas un véritable interpréteur nroff. Il devrait être possible de
faire un vrai interpréteur nroff, qui permettrait aux auteurs d’utiliser
toutes les macros existantes ou même d’en définir de nouvelle dans leurs
pages, mais nous n’en avons pas envie. Ce serait trop difficile, et nous ne
pensons pas que cela soit nécessaire. Nous pensons que si les auteurs de
pages de manuel veulent voir leurs travaux traduits, ils doivent s’adapter
pour faciliter le travail des équipes de traduction.

Il y a donc des limitations connues de l’analyseur de pages de manuel
implémenté dans po4a, que nous ne sommes pas prêts à corriger, et qui
resteront des difficultés qu’il vous faudra éviter si vous voulez que des
personnes s’occupent de la traduction de votre documentation.

=head2 Ne programmez pas en nroff

nroff est un langage de programmation complet, avec des définitions de
macros, des opérations conditionnées, etc. Comme cet analyseur n’est pas un
analyseur complet pour nroff, il ne pourra pas gérer les pages utilisant ces
possibilités (il y en a environ 200 sur ma machine).

=head2 Utilisez un jeu de macros simple

Il y a encore quelques macros qui ne sont pas supportées par po4a::man. La
raison à cela est que nous n’arrivons pas à trouver leur
documentation. Voici la liste des macros non supportées mais tout de même
utilisées sur ma machine. Notez que cette liste n’est pas exhaustive puisque
le programme échoue lorsque la première macro non supportée est
rencontrée. Si vous trouvez des informations à propos de ces macros, nous
ajouterons leur support avec plaisir. Ces macros rendent environ 250 pages
non utilisables avec po4a::man.

 ..               ."              .AT             .b              .bank
 .BE              ..br            .Bu             .BUGS           .BY
 .ce              .dbmmanage      .do                             .En
 .EP              .EX             .Fi             .hw             .i
 .Id              .l              .LO             .mf
 .N               .na             .NF             .nh             .nl
 .Nm              .ns             .NXR            .OPTIONS        .PB
 .pp              .PR             .PRE            .PU             .REq
 .RH              .rn             .S<             .sh             .SI
 .splitfont       .Sx             .T              .TF             .The
 .TT              .UC             .ul             .Vb             .zZ

=head2 Cacher du texte à po4a

Parfois, un auteur sait que certaines parties ne peuvent pas être traduite,
et ne doivent pas être extraites par po4a. Par exemple, une option peut
recevoir un paramètre I<other>, qui ne doit pas être traduit et I<other> est
également le dernier élément d’une liste. Dans le premier cas, I<other> ne
doit pas être traduit et dans le second, il doit être traduit.

Dans ce cas, l’auteur peut éviter l’extraction de certaines chaînes par po4a
en utilisant une construction groff particulière :

 .if !'po4a'hide' .B other

(nécessite l’option B<-o groff_code=verbatim>)

A new macro can also be defined to automate this:
 .de IR_untranslated
 .    IR \\$@
 ..

 .IR_untranslated \-q ", " \-\-quiet

(nécessitera les options B<-o groff_code=verbatim> et B<-o
untranslated=IR_untranslated> ; avec cette construction, la condition B<.if
!'po4a'hide'> n’est pas strictement nécessaire puisque po4a n’analysera pas
le contenu de la définition de la macro)

or using an alias:
 .als IR_untranslated IR

 .IR_untranslated \-q ", " \-\-quiet

Cela nécessitera l’option B<-o untranslated=als,IR_untranslated>.

=head2 Conclusion

Pour résumer cette section, faites simple et n’essayez pas d’être trop
astucieux lors de l’écriture de vos pages de manuel. Beaucoup de choses sont
possibles en nroff et ne sont pas supportées par cet analyseur. Par exemple,
n’essayez pas de jouer avec des \c pour interrompre le traitement du texte
(c’est le cas de 40 pages sur ma machine). Aussi, assurez-vous de spécifier
les paramètres des macros sur la même ligne que la macro. Même si c’est
valable en nroff, cela compliquerait trop l’analyseur pour être géré.

Bien sûr, une autre possibilité est d’utiliser un autre format, plus
pratique pour les équipes de traduction (comme POD en utilisant po4a::pod ou
un format de la famille XML comme le SGML), mais grâce à po4a::man, ce n’est
plus nécessaire. Cela étant dit, si la documentation provient d’une source
au format POD ou XML, il serait préférable de traduire le format source et
non pas celui généré. Dans la plupart des cas, po4a::man détectera les pages
de manuel générées et affichera un avertissement. Il refusera même de
traiter les pages générées depuis un format POD, parce que ces pages sont
parfaitement traitées par po4a::pod et parce que leur contrepartie nroff
définit beaucoup de nouvelles macros pour lesquelles je ne veux pas écrire
de support. Sur ma machine, 1432 des 4323 pages sont générées depuis le
format POD et seront ignorées par po4a::man.

Dans la plupart des cas, po4a::man détectera le problème et refusera de
traiter la page, en affichant un message d’avertissement. Dans quelques
rares cas, le programme se terminera sans avertissement, mais la sortie sera
erronée. Ces cas sont des S<« bogues » ;)> Si vous rencontrez un de ces cas,
assurez-vous de le signaler, avec un correctif si possible…

=head1 ÉTAT DE CE MODULE

Ce module peut être utilisé avec presque toutes les pages de manuel
existantes.

Des tests sont régulièrement effectués sur une machine Linux :

=over 4

=item *

un tiers des pages est refusé parce qu’elles ont été générées à partir d’un
autre format supporté par po4a (par exemple POD ou SGML).

=item *

10% des pages restantes sont rejetées avec une erreur (par exemple
lorsqu’une macro groff n’est pas supportée).

=item *

Ensuite, moins d’1% des pages est accepté par po4a, mais présente des
erreurs significatives (c’est-à-dire certains mots disparaissent ou des mots
sont ajoutés)

=item *

les autres pages sont généralement supportées sans problème plus important
que des différences d’espacement ou de remise en forme des lignes (également
des problèmes de police dans moins de 10% des pages sur lesquelles po4a
opère).

=back

=head1 VOIR AUSSI

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

=head1 AUTEURS

 Denis Barbier <barbier@linuxfr.org>
 Nicolas François <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)


=head1 TRADUCTION

 Martin Quinson (mquinson#debian.org)

=head1 COPYRIGHT ET LICENCE

Copyright © 2002-2008 SPI, Inc.

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