Introduction

po4a-build.conf décrit comment "po4a-build" 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 séparer les répertoires po/, chacun avec un fichier de configuration, appelé par "po4a-build -f FICHIER".

Remarquez que même si po4a-build permet d'ajouter la prise en charge par gettext 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" pour les combinaisons suivantes :

XML DocBook vers section 1 et 3

Typically used for manpages for shell scripts or other interpreters that do not have their own documentation format like POD. Suitable XML can be generated directly from an existing manpage using "doclifter"(1) and "po4a-build" will then generate a POT file with no extra workload. The POT file can then be offered for translation and the PO files added to the relevant po/ directory. "po4a-build" will then prepare not only the untranslated manpage from the "doclifter" XML but also use "po4a" to prepare translated XML from the PO files and then build translated manpages from the 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".

XML DocBook 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 vers section 1, 3, 5 et 7

pod2man permet de convertir le contenu POD pour toutes les sections gérées.

Utiliser "PODFILE" pour la section 1, "PODMODULES" pour la section 3, "POD5FILES" pour la section 5 et "POD7FILES" pour la section 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 1), si le 5 ou 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 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 (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.

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

PODIR

Obligatoire.

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 ». Remarquez cependant que certains outils de statistiques s'attendent à trouver ce nom, il est donc conseillé de le garder.

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

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, par exemple la documentation
 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é. 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.

Rassembler beaucoup de fichiers dans 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 XML DocBook pour créer les pages de manuel de la section 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 1, pas le livre lui-même. Si le livre contient uniquement du contenu à destination de la section 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 XML DocBook pour créer les pages de manuel de la section 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 3, pas le livre lui-même. Si le livre contient uniquement du contenu à destination de la section 1, indiquez seulement le fichier du livre.

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

XMLDIR

Emplacement de tous les fichiers XML DocBook. 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 XML DocBook.

 # fichier XSL à utiliser pour S<XML DocBook>
 XSLFILE="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"

PODFILE

Fichiers POD pour créer les pages de manuel de la section 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 3.

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

POD5FILES

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

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 1), si le 5 ou 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 7. Les chemins, s'ils sont utilisés, sont relatifs à l'emplacement de ce fichier de configuration.

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 1), si le 5 ou 7 fait partie du nom de fichier, il (ainsi que toute extension de fichier) sera automatiquement enlevé.

 # 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

Fichier DocBook à convertir en HTML (peut être le même qu'un de 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.

 # fichier 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 HTML
 HTMLXSL="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"

AUTEURS

 Neil Williams <[email protected]>

TRADUCTION

 Martin Quinson (mquinson#debian.org)