po4a-build.conf

Autres langues

Langue: fr

Version: 2010-08-07 (ubuntu - 24/10/10)

Section: 5 (Format de fichier)

NOM

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

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

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 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
XML DocBook 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", mais utilisera aussi "po4a" 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".

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