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.5 qui est utilisée. Vous avez besoin de la variante XML de la DTD DocBook, et non pas SGML, de même version. Ils seront généralement dans des paquets séparés.
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.
xmllint
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
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 de ces fichiers ou si aucun paquet
n'est disponible. Si vous voulez empêcher toute tentative d'accàs à
Internet lors de la construction de la documentation, vous devrez passer
l'option --nonet à xmllint et
xsltproc ; voir ci-dessous pour un exemple.
Pour installer les packages requis, lancez :
yum install docbook-dtds docbook-style-xsl fop libxslt
Pour installer les paquets requis avec pkg, utiliser :
pkg install docbook-xml docbook-xsl fop libxslt
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.
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-xml docbook-xsl fop libxml2-utils xsltproc
Sur macOS, vous pouvez construire la documentation HTML et man sans installation supplémentaire. Si vous voulez construire les PDF ou si vous voulez installer une copie locale de DocBook, vous pouvez les obtenir de votre gestionnaire de paquets préféré.
Si vous utilisez MacPorts, voici comment configurer cela :
sudo port install docbook-xml-4.5 docbook-xsl fop
Si vous utilisez Homebrew, utilisez ceci :
brew install docbook docbook-xsl fop
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.)
configure
Avant de pouvoir construire la documentation, le script
configure doit être lancé, comme cela se fait pour la
construction des programmes PostgreSQL
eux-mêmes. La fin de l'affichage de l'exécution de ce script doit
ressembler à :
checking for xmllint... xmllint
checking for xsltproc... xsltproc
checking for fop... fop
checking for dbtoepub... dbtoepub
Si xmllint ou xsltproc est
introuvable, vous ne pourrez pas construire la documentation.
fop est seulement nécessaire pour construire la
documentation en PDF. dbtoepub est seulement
nécessaire pour construire la documentation en EPUB.
Si nécessaire, vous pouvez indiquer à configure où
trouver ces programmes, par exemple
./configure ... XMLLINT=/opt/local/bin/xmllint ...
De plus, si vous voulez vous assurer que xmllint et
xsltproc ne réaliseront aucun accès réseau, vous
pouvez le faire ainsi
./configure ... XMLLINT="xmllint --nonet" XSLTPROC="xsltproc --nonet" ...