NAME
po4a-build - construit la documentation traduite
SYNOPSIS
po4a-build [[-f] | [--file] FICHIER] [[--pot-only]]
po4a-build [[-?] | [-h] | [--help] | [--version]]
L'objectif de po4a-build est d'aider à bâtir de la documentation
traduite aussi facilement que de la documentation en cours non
traduite.
Lorsque po4a(1) prépare le contenu traduit au format POD ou XMLDocBook,
la documentation finale peut ensuite être construite avec po4a-build.
Le contenu traduit et celui qui ne l'est pas sont tous deux construits
en une unique étape, avec mise à jour des fichiers POT en même temps.
Les directives de construction existantes sont remplacées par un unique
appel à po4a-build et un fichier de configuration tout simple indique
à po4a-build comment construire chaque élément et quel paquet binaire
doit intégrer les contenus traduits ou non.
Une fois construit, le contenu sera disponible dans le répertoire
spécifique au paquet à l'intérieur de BASEDIR (indiqué dans le fichier
de configuration). Pour un paquet truc, avec des traductions en
allemand et français, cela donnerait par exemple :
BASEDIR/truc/man/man1/truc.1
BASEDIR/truc/man/de/man1/truc.1
BASEDIR/truc/man/fr/man1/truc.1
Le contenu créé peut ensuite être facilement intégré au paquet binaire
avec un seul emplacement d'installation, par exemple :
doc/truc/man/* ./usr/share/man/
doc/truc/html/* ./usr/share/doc/truc/
Cette règle n'aura pas besoin d'être mise à jour lors de l'ajout de
nouvelles traductions. Quand un autre paquet binaire (bidule) est
ajouté, le contenu de ce paquet peut être séparé.
Formats pris en charge
Actuellement, il est possible d'utiliser po4a-build pour les
combinaisons suivantes :
1. XML DocBook vers section n°1.
2. XML DocBook vers section n°3.
3. XML DocBook vers HTML.
4. POD vers section n°1.
5. POD vers section n°3.
6. POD vers section n°5.
7. POD vers section n°7.
Tous les formats pris en charge (toutes combinaisons possibles) peuvent
être traités avec un unique fichier de configuration po4a-build.conf et
un seul appel à po4a-build. Voir po4a-build.conf(5).
CONFIGURATION
po4a-build(1) utilise un fichier de configuration par défaut,
po4a-build.conf qui devrait se trouver dans le répertoire de plus haut
niveau du système de gestion de version (VCS) du paquet (l'option -f
permet d'indiquer un autre fichier). Voir po4a-build.conf(5).
Exemple n°1. Exemple de fichier de configuration.
Un exemple de fichier de configuration est disponible en :
/usr/share/doc/po4a/examples/po4a-build.conf.example
Format du fichier de configuration
Le fichier de configuration comporte plusieurs parties : généralités,
prise en charge XML et XSL, prise en charge POD et prise en charge
HTML.
La partie généralités contient le nom et emplacement du fichier de
configuration de po4a (il est préférable de garder po4a.config), le
répertoire po contenant les fichiers PO de documentation (souvent
doc/po), le nom complet du fichier POT utilisé pour les traductions,
BASEDIR pour créer la sortie, les informations si le paquet contient
des pages de manuel en section n°3 plutôt que seulement en section n°1,
ainsi que les noms des paquets binaires qui vont receler le contenu
généré en sortie.
La partie prise en charge XML et XSL indique les paquets binaires qui
utilisent la prise en charge XSL dans la variable XMLPACKAGES, le
fichier DocBook de plus haut niveau qui servira de paramètre xsltproc
et l'emplacement des fichiers XML ou DocBook. XSLFILE peut être
modifiée si besoin.
La partie prise en charge POD indique les paquets binaires qui
utilisent la prise en charge POD dans la variable PODPACKAGES et le nom
complet du fichier POD.
La partie prise en charge HTML indique les sous-répertoires à créer
dans BASEDIR pour les contenus HTML traduits ou pas, ainsi que le
fichier DocBook pour créer le HTML. Le fichier HTMLXSL peut être
modifié si besoin.
COMMANDES
--pot-only
Met à jour seulement le ou les fichiers POT. L'objectif de
--pot-only est de prendre en charge les paquets contenant tous les
fichiers POT dans le paquet source. Un fichier POT peut facilement
être ajouté aux paquets utilisant les Autotools avec EXTRA_DIST
mais ce peut être plus compliqué avec les paquets utilisant un
Makefile ou certains assistants de VCS sans ajouter le fichier POT
(créé pendant la construction) au VCS. Pour éviter ce bidouillage
inutile, po4a-build peut mettre à jour le ou les fichiers POT au
début de la construction afin que dpkg-source(1) les intègre à
l'archive source.
Exemple n°2. Exemple avec svn-buildpackage.
svn-buildpackage(1) prend en charge explicitement ce genre d'ajout,
avec la propriété SVN useNativeDist et la cible Make native-dist.
# ajoute le fichier POT à l'archive source
native-dist: Makefile
po4a-build --pot-only
$ svn propset useNativeDist 1 debian
-h | --help
Affiche le message d'aide puis quitte.
--version
Affiche le message d'aide puis quitte.
OPTIONS
-f | --file FICHIER
Remplacer le fichier de configuration de po4a-build par défaut
(po4a-build.conf) par FICHIER.
AUTEUR
po4a-build a été écrit par Neil Williams codehelp@debian.org
Cette page de manuel a été écrite par Neil Williams codehelp@debian.org