man po4a-build.conf : po4a-build.conf - fichier de configuration pour la construction des contenus traduits

NOM

       po4a-build.conf - fichier de configuration  pour  la  construction  des
       contenus traduits

       po4a-build.conf décrit  comment  po4a-build(1)  devrait  construire  la
       documentation traduite ou non à partir d'un jeu de documents sources et
       des fichiers PO correspondants.

       Tous  les  formats  pris  en  charge,   dans  toutes  les  combinaisons
       possibles, peuvent être traités avec un unique fichier de configuration
       po4a-build.conf  et par un seul appel à  po4a-build.  Toutefois, il est
       possible de choisir  de séparer  les répertoires po/ :  il y aura alors
       plusieurs  fichiers  de  configuration  ;  chaque  appel  sera  du type
       "po4a-build -f FICHIER".

       Voir également le paramètre KEEP plus bas  pour certaines limites  à la
       combinaison de multiples fichiers dans un seul fichier POT et une seule
       exécution de po4a-build.

       Remarquez que  même si po4a-build  permet d'ajouter  la prise en charge
       par  gettext(1)  de  la  traduction  des  messages de sortie de script,
       po4a-build.conf  lui-même  n'a pas de relation  avec  ces  traductions.
       po4a-build.conf ne se  rapporte  qu'à la traduction de contenu statique
       comme les pages de manuel.

       Pour la prise en charge  par po4a-build  de  la traduction des messages
       affichés pendant l'exécution, voir po4a-runtime(7).

FORMATS PRIS EN CHARGE

       Actuellement,   il  est  possible  d'utiliser  po4a-build(1)  pour  les
       combinaisons suivantes :

       XMLDocBook pour sections n°1 et n°3
           XMLDocBook est  utilisé  pour les pages de manuel des scripts shell
           ou  d'autres  interpréteurs  qui  n'ont  pas  leur propre format de
           documentation comme POD.  doclifter  permet de transformer une page
           de manuel existante en un XML correct et po4a-build créera alors un
           fichier  POT  sans  effort  supplémentaire.  Le  fichier  POT  peut
           ensuite  être  proposé  aux traducteurs  et les fichiers PO ajoutés
           dans le  répertoire po/  adéquat.  po4a-build  préparera  alors non
           seulement la page de manuel non traduite  à partir  du  XML issu de
           doclifter(1),  mais utilisera  aussi  po4a(1) pour préparer les XML
           traduits à partir des fichiers PO,  puis construira  les  pages  de
           manuel traduites à partir des XML.

           Les pages de manuel  sont  créées en  utilisant  docbook-xsl  -  la
           feuille de style utilisée peut être modifiée avec "XSLFILE" dans le
           fichier de configuration de po4a-build.

       XMLDocBook vers HTML
           La feuille de style utilisée  pour préparer le HTML final peut être
           modifiée  avec  "HTMLXSL"  dans  le  fichier  de  configuration  de
           po4a-build.

       POD pour sections n°1, 3, 5 et 7
           pod2man(1)  permet  de convertir  le contenu POD  pour  toutes  les
           sections gérées.

           Utiliser "PODFILE" pour la section1, "PODMODULES" pour la section3,
           "POD5FILES" pour la section n°5 et "POD7FILES" pour la section n°7.

           Pour les contenus des sections 5 et 7  (qui ont souvent besoin d'un
           nom de fichier déjà utilisé  par un contenu de la section n°1),  si
           le 5 ou le 7 fait partie du nom de fichier,  il  (ainsi  que  toute
           extension de fichier) sera automatiquement enlevé.

           Par exemple pour préparer /usr/share/man/man7/po4a.7.gz :

            # fichiers POD pour la section n°7
            POD7FILES="doc/po4a.7.pod"

SYNTAXE DU FICHIER

L'ordre des valeurs dans le fichier de configuration est sans
importance.

Tout ce qui suit le caractère # sur une ligne est ignoré.

Toute valeur destinée à rester vide peut être enlevée du fichier.

Certains champs de configuration sont obligatoires - po4a-build risque
de se terminer sans rien faire si des champs obligatoires sont laissés
vides.

CONFIG
Obligatoire.

# nom et emplacement du fichier de configuration
CONFIG="_build/po4a.config"

Nom et emplacement du fichier de configuration (temporaire) de
po4a que po4a-build va créer et maintenir. Ce fichier n'a pas
besoin d'exister dans le système de gestion de version (VCS) et
peut être effacé sans risque pendant la construction du paquet.

PODIR
Obligatoire.

# répertoire po pour les pages de manuel et la documentation
PODIR="po/pod"

Répertoire contenant les fichiers PO de toutes les traductions
prises en charge par ce fichier de configuration. Toutes les
chaînes doivent être rassemblées dans un fichier POT de ce
répertoire et tous les fichiers PO fusionnés avec ce fichier POT.
Tout seuil à dépasser KEEP (voir plus bas) sera respecté pour
toutes les chaînes de tous les fichiers d'entrée indiqués dans ce
fichier et tous les fichiers PO de ce répertoire. Le répertoire ne
doit pas forcément s'appeler po.

POTFILE
Obligatoire.

Chemin vers le fichier POT (par rapport à l'emplacement de ce
fichier de configuration) qui sera créé, maintenu et mis à jour par
po4a-build pour ces traductions.

# chemin vers le fichier POT
POTFILE="po/pod/po4a-pod.pot"

BASEDIR
Obligatoire.

Répertoire de base où placer le contenu traduit.

# répertoire de base pour les fichiers créés : doc, ...
BASEDIR="_build"

BINARIES
Obligatoire.

Même si un seul paquet binaire est construit, au moins une valeur
est obligatoire ici.

La chaîne elle-même est arbitraire mais comporte généralement le
nom du paquet. Le contenu créé apparaîtra ensuite dans un
sous-répertoire de BASEDIR/BINARIES :

_build/po4a/man/man1/foo.1

Si le paquet construit plus d'un paquet binaire (c'est-à-dire un
paquet source et de multiples fichiers .deb ou .rpm), ce champ
permet d'isoler le contenu destiné à chaque cible, facilitant
l'automatisation du processus de construction.

Les chaînes sont séparées par des espaces.

# paquets binaires contenant les pages de manuel créées
BINARIES="po4a"

KEEP
Valeur fournie directement à "po4a -k" pour indiquer le seuil (en
pourcent) de traduction exact en dessous duquel une traduction doit
être omise de la construction. Si laissé vide, la valeur par défaut
(80) est utilisée. Zéro permet de forcer l'intégration de tous les
contenus, même s'ils ne sont pas traduits du tout.

Pour contrôler parfaitement un tel comportement, veuillez choisir
avec précaution les fichiers à gérer par chaque fichier de
configuration po4a-build.conf. Chaque fichier indiqué dans un des
fichiers po4a-build.conf sera pris en compte dans le calcul de
pourcentage de chaînes correctement traduites. S'il existe un gros
fichier avec peu de chaînes traduites, il empêchera les autres
fichiers, plus petits, d'être inclus dans la construction même
s'ils sont individuellement traduits à 100%.

D'un autre côté, rassembler de nombreux fichiers en un seul fichier
POT peut être plus pratique pour les traducteurs, en particulier si
les fichiers ont des chaînes en commun. Inversement, des fichiers
POT avec des milliers de longues chaînes sont redoutables pour les
traducteurs, et mènent généralement à de longs gels des messages
(string freeze).

# seuil à dépasser pour que le fichier créé soit conservé
KEEP=

XMLMAN1
Fichiers XMLDocBook pour créer les pages de manuel de la section
n°1. Les noms des fichiers sont séparés par des espaces. Tous les
fichiers nécessaires doivent être dans le répertoire XMLDIR.

C'est une pratique courante d'intégrer plusieurs fichiers XML dans
un livre, afin de fournir une table des matières, etc. Si le livre
contient des fichiers aussi indiqués dans XMLMAN3, indiquez ici
seulement les fichiers pour la section n°1, pas le livre lui-même.
Si le livre contient uniquement du contenu à destination de la
section n°1, indiquez seulement le fichier du livre.

# fichiers XML DocBook pour la section 1
XMLMAN1="po4a-build.xml po4aman-display-po.xml po4apod-display-po.xml"

XMLMAN3
Fichiers XMLDocBook pour créer les pages de manuel de la section
n°3. Les noms des fichiers sont séparés par des espaces. Tous les
fichiers nécessaires doivent être dans le répertoire XMLDIR.

C'est une pratique courante d'intégrer plusieurs fichiers XML dans
un livre, afin de fournir une table des matières, etc. Si le livre
contient des fichiers aussi indiqués dans XMLMAN1, indiquez ici
seulement les fichiers pour la section n°3, pas le livre lui-même.
Si le livre contient uniquement du contenu à destination de la
section n°1, indiquez seulement le fichier du livre.

# fichiers XML DocBook pour la section 3
XMLMAN3=""

XMLDIR
Emplacement de tous les fichiers XMLDocBook. Pour le moment,
"po4a-build" s'attend à trouver tous les fichiers décrits dans
XMLMAN1 et XMLMAN3 en cherchant les fichiers *.xml dans ce
répertoire.

Obligatoire si XMLMAN1 ou XMLMAN3 sont utilisés. Les chemins sont
relatifs à l'emplacement du fichier de configuration.

# emplacement des fichiers XML
XMLDIR="share/doc/"

XMLPACKAGES
Paquets, parmi ceux indiqués dans BINARIES, qui utilisent des
sources XML.

Obligatoire si XMLMAN1 ou XMLMAN3 sont utilisés.

# paquets binaires utilisant XML DocBook et xsltproc
XMLPACKAGES="po4a"

DOCBOOKDIR
Similaire à XMLDIR, mais utilisé seulement pour préparer les
fichiers DocBook traduits. Si vous avez l'intention d'utiliser des
fichiers .sgml, veuillez discuter la façon dont ils devraient être
construits sur la liste de discussion po4a-devel.

# motif pour trouver les fichiers .docbook
DOCBOOKDIR=""

XSLFILE
Feuille de style XSL utilisée pour préparer les contenus traduits
ou non à partir des fichiers XMLDocBook.

# fichier XSL à utiliser pour Docbook XSL
XSLFILE="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"

PODFILE
Fichiers POD pour créer les pages de manuel de la section n°1. Les
noms des fichiers POD sont séparés par des espaces. Les chemins,
s'ils sont utilisés, sont relatifs à l'emplacement de ce fichier de
configuration.

# fichiers POD pour la section 1
PODFILE="po4a po4a-gettextize po4a-normalize scripts/msguntypot"

PODMODULES
Prise en charge spécifique pour les modules Perl utilisant du
contenu POD - le nom du module sera reconstruit en fonction du
chemin (ce devrait être le format habituel pour Perl) et les pages
de manuel sont automatiquement placées en section n°3.

# fichiers POD pour s.3 -noms de module recréés à partir du chemin
PODMODULES="lib/Locale/Po4a/*.pm"

POD5FILES
Contenu POD arbitraire pour créer les pages de manuel de la section
n°5. Les chemins, s'ils sont utilisés, sont relatifs à
l'emplacement de ce fichier de configuration.

Pour les contenus des sections n°5 et 7 (qui ont souvent besoin
d'un nom de fichier déjà utilisé par un contenu de la section n°1),
si le 5 ou le 7 fait partie du nom de fichier, il (ainsi que toute
extension de fichier) sera automatiquement enlevé.

# fichiers POD pour la section 5
POD5FILES="doc/po4a-build.conf.5.pod"

POD7FILES
Contenu POD arbitraire pour créer les pages de manuel de la section
n°7. Les chemins, s'ils sont utilisés, sont relatifs à
l'emplacement de ce fichier de configuration.

# fichiers POD pour la section 7
POD7FILES="doc/po4a.7.pod"

PODPACKAGES
Similaire à XMLPACKAGES - tout paquet dont du contenu doit être
construit à partir de fichiers POD doit contenir une valeur dans
PODPACKAGES. Obligatoire si PODFILE, PODMODULES, POD5FILES ou
POD7FILES sont utilisés.

# paquets binaires utilisant POD
PODPACKAGES="="po4a"

HTMLDIR
Sous-répertoire de BASEDIR à utiliser pour créer les documents HTML
traduits ou non.

# répertoire HTML (sous-répertoire de BASEDIR)
HTMLDIR=""

HTMLFILE
Fichiers DocBook à convertir en HTML (peuvent être les mêmes que
ceux indiqués dans XMLMAN1 ou XMLMAN3). Les sections n'ont pas de
signification pour les documents HTML, donc n'hésitez pas à
utiliser le fichier du livre entier ici pour intégrer une table des
matières, etc.

# fichiers HTML DocBook
HTMLFILE=""

HTMLXSL
La feuille de style XSL utilisée par défaut est partitionnée
(chunked). Il n'est pour l'instant pas possible d'utiliser plus
d'une feuille de style par conversion HTML.

# fichier XSL à utiliser pour XSL Docbook
HTMLXSL="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"

AUTEURS

       Neil Williams <linux@codehelp.co.uk>