Les outils qui suivent sont utilisés pour produire la documentation. Certains sont optionnels (comme mentionné).
Il s'agit de la définition de DocBook elle-même. C'est actuellement la version 4.2 qui est utilisée. Vous avez besoin des variantes SGML et XML de la DTD DocBook de même version. Ils seront généralement dans des paquets séparés.
Celles-ci sont nécessaires à DocBook SGML mais sont distribuées à part car maintenues par l'ISO.
Ils contiennent les instructions de traitement pour convertir les sources DocBook vers d'autres formats, comme par exemple le HTML.
La version minimale requise est actuellement la 1.77.0, mais il est recommandé d'utiliser la dernière version disponibles pour de meilleurs résultats.
C'est le paquetage de base pour le traitement de SGML. Veuillez noter que nous n'avons plus besoin d'OpenJade, le processeur DSSSL , uniquement du paquet OpenSP pour convertir le SGML en XML.
Cette bibliothèque et l'outil xmllint qu'il contient sont utilisés pour traiter du XML. Beaucoup de développeurs ont déjà Libxml2 installé car il est aussi utilisé lors de la compilation de PostgreSQL. Néanmoins, notez que xmllint doit être installé à partir d'un sous-paquet séparé.
xsltproc est un processeur XSLT, c'est-à-dire, un programme pour convertir le XML vers d'autres formats en utilisant de fichiers de style XSLT.
Il s'agit d'un programme pour convertir, entre autres choses, du XML vers du PDF.
Différentes méthodes d'installation sont détaillées ci-après pour les divers outils nécessaires au traitement de la documentation. Il peut exister d'autres types de distributions empaquetées de ces outils. Tout changement du statut d'un paquetage peut être rapportée auprés de la liste de discussion de la documentation, afin d'inclure ces informations ici-même.
Vous pouvez vous en sortir en n'installant ni DocBook XML ni les feuilles de style DocBook XSLT localement, puisque les fichiers nécessaires seront téléchargé par Internet et mis en cache localement. Cela pourrait en fait être la solution préférable si les paquets de votre système d'exploitation ne fournissent qu'une version ancienne des feuilles de style spécifiquement, ou si aucun paquet n'est disponible. Voir les options --nonet pour xmllint et xsltproc pour plus d'informations.
Pour installer les packages requis, lancez :
yum install docbook-dtds docbook-style-xsl fop libxslt opensp
Le projet de documentation FreeBSD (FreeBSD Documentation Project) est lui-même un utilisateur intensif de DocBook, et c'est sans surprise que l'on retrouve en son sein un ensemble complet de « portages » des outils de documentation sur FreeBSD. Les portages suivants doivent être installés afin de produire la documentation sur FreeBSD :
textproc/docbook-sgml ;
textproc/docbook-xml ;
textproc/docbook-xsl ;
textproc/dsssl-docbook-modular.
textproc/libxslt
textproc/fop
textproc/opensp
Pour installer les paquets requis avec pkg, utiliser :
pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp
Quand vous compilez la documentation depuis le répertoire doc vous aurez besoin d'utiliser gmake, car le makefile fourni n'est pas correct pour le make de FreeBSD.
De plus amples informations sur les outils dédiés à la documentation de FreeBSD se trouvent dans les instructions du projet de documentation de FreeBSD.
Un ensemble complet de paquetages d'outils de documentation est disponible pour Debian GNU/Linux™. Pour l'installer, il suffit de taper :
apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc
Si vous utilisez MacPorts, utilisez la commande suivante pour faire votre configuration :
sudo port install docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl fop libxslt opensp
L'installation manuelle des outils DocBook est quelque peu complexe. Il est donc préférable d'utiliser des paquetages pré-compilés. Seule une procédure de mise en œuvre standard, qui utilise des répertoires d'installation standard et sans fonctionnalités particulières, est ici décrite. Pour les détails, on peut étudier la documentation respective de chaque paquetage et lire les documents d'introduction à SGML.
L'installation d'OpenSP fournit un processus de compilation ./configure; make; make install de style GNU. Les détails peuvent être trouvés dans la distribution source d'OpenSP. En un mot :
./configure --enable-default-catalog=/usr/local/etc/sgml/catalog make make install
Veillez à vous rappeler de l'endroit où vous stockez le « catalogue par défaut »; vous en aurez besoin ci-dessous. Vous pouvez également le laisser de côté, mais vous aurez alors besoin de positionner la variable d'environnement SGML_CATALOG_FILES pour qu'elle point vers le fichier à chaque fois que vous utilisez l'un des programme d'OpenSP. (Cette méthode est également envisageable si OpenSP est déjà installé et que vous voulez installer le reste de la suite d'outil localement.)
Récupérer la distribution DocBook V4.2.
Créer le répertoire /usr/local/share/sgml/docbook-4.2 et s'y placer. (L'emplacement exact importe peu mais celui-ci a le bénéfice d'être cohérent avec le schéma d'installation proposé ici.)
$ mkdir /usr/local/share/sgml/docbook-4.2 $ cd /usr/local/share/sgml/docbook-4.2
Décompresser l'archive.
$ unzip -a ...../docbook-4.2.zip
(L'archive décompresse ses fichier dans le répertoire courant.)
Éditer le fichier /usr/local/share/sgml/catalog (ou celui précisé à jade lors de l'installation) et y placer une ligne similaire à celle-ci :
CATALOG "docbook-4.2/docbook.cat"
Télécharger l'archive contenant les entités de caractères ISO 8879, la décompresser et placer les fichiers dans le même répertoire que celui des fichiers de DocBook.
$ cd /usr/local/share/sgml/docbook-4.2 $ unzip ...../ISOEnts.zip
Lancer la commande suivante dans le répertoire contenant les fichiers DocBook et ISO :
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
(Cette opération permet de corriger les mélanges entre le fichier de catalogue de DocBook et les noms réels des fichiers contenant les entités de caractères ISO.)
Avant de pouvoir engendrer la documentation, le script configure doit être lancé, comme cela se fait pour la génération des programmes PostgreSQL™ eux-mêmes. La fin de l'affichage de l'exécution de ce script doit ressembler à :
checking for onsgmls... onsgmls checking for DocBook V4.2... yes checking for dbtoepub... dbtoepub checking for xmllint... xmllint checking for xsltproc... xsltproc checking for osx... osx checking for fop... fop
Si ni onsgmls ni nsgmls n'ont été trouvés, certains des tests suivants seront ignorés. onsgmls fait partie du paquetage OpenSP. La variable d'environnement NSGMLS peut être renseignée pour indiquer les emplacements des programmes s'ils ne sont pas trouvés automatiquement. Si « DocBook V4.2 » n'a pas été trouvé, c'est que le kit de la DTD DocBook n'est pas installé à un endroit où OpenSP peut le trouver ou que les fichiers catalogues ne sont pas correctement configurés. Il convient, dans ce cas, de se reporter aux conseils donnés plus haut.
Documentation
