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 de la variante SGML de la DTD DocBook mais, pour construire les pages man, vous avez aussi besoin de la variante XML de la même version.
Celles-ci sont nécessaires à DocBook 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.
C'est une autre feuille de style pour convertir DocBook vers d'autres formats. Nous l'utilisons actuellement pour produire les pages man et les pages HTMLHelp en option. Vous pouvez aussi utiliser cette chaîne de production pour produire une sortie HTML ou PDF, mais les versions officielles de PostgreSQL utilisent les feuilles de style DSSSL pour cela.
La version minimale requise est actuellement la 1.74.0.
C'est le paquetage de base pour le traitement de SGML. Il contient un analyseur SGML, un processeur DSSSL (programme qui permet la conversion de documents SGML en d'autres formats à l'aide de feuilles de styles DSSSL), ainsi qu'un certain nombre d'autres outils. Jade™ est actuellement maintenu par le groupe OpenJade et non plus par James Clark.
C'est l'outil de traitement à utiliser avec les feuilles de style XSLT (alors que jade est l'outil de traitement des feuilles de style DSSSL).
JadeTeX™ peut être installé pour utiliser TeX™ comme outil de formatage pour Jade™. JadeTeX est capable de créer des fichiers au formats PostScript ou PDF (ce dernier avec les signets).
Cependant, une sortie JadeTeX est de moindre qualité qu'une sortie RTF. Les principaux problèmes que l'on peut rencontrer concernent les tables et les éléments de placements verticaux et horizontaux. Il n'y a aucune possibilité de corriger manuellement le résultat.
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.
La plupart des revendeurs mettent à disposition des utilisateurs un ensemble complet de paquetages RPM pour le traitement de DocBook au sein de leur distribution. Lors de l'installation, il faut recherche une option « SGML » ou les paquetages suivants : sgml-common, docbook, stylesheets, openjade. sgml-tools est probablement requis. Si le fournisseur de la distribution ne les fournit pas, il doit être possible d'utiliser des paquetages issus d'une distribution compatible.
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/sp ;
textproc/openjade ;
textproc/iso8879 ;
textproc/dsssl-docbook-modular.
textproc/docbook-420
Un intérêt particulier peut également être porté aux différents éléments de /usr/ports/print (tex, jadetex).
Il est probable que les portages ne mettent pas à jour le fichier de catalogue général dans /usr/local/share/sgml/catalog.ports ou que l'ordre ne soit pas le bon. Les lignes suivantes doivent figurent au début :
CATALOG "openjade/catalog" CATALOG "iso8879/catalog" CATALOG "docbook/dsssl/modular/catalog" CATALOG "docbook/4.2/catalog"
Pour ne pas éditer ce fichier, il est possible de positionner la variable d'environnement SGML_CATALOG_FILES en y mettant une liste de fichiers catalogues séparés par des caractères « deux points ».
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 :
Documentation
apt-get install docbook docbook-dsssl docbook-xsl openjade1.3 opensp xsltproc
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'OpenJade se fait par l'intermédiaire des outils de construction ./configure; make; make install classiques de GNU. Les détails sont dans la distribution des sources d'OpenJade. En quelques mots :
./configure --enable-default-catalog=/usr/local/share/sgml/catalog
make
make install
L'emplacement du « catalogue par défaut » a son importance ; il est utilisé par la suite. Il est possible de ne pas s'en souvenir, mais dans ce cas, la variable d'environnement SGML_CATALOG_FILES doit être définie de façon à pointer vers le bon fichier à chaque fois que jade est exécuté. (Cette méthode est également possible si OpenJade est déjà installé et que le reste de l'environnement de publication est installé localement.)
![[Note]](images/note.png)
Certains utilisateurs ont rencontré une faute de segmentation avec l'utilisation d'OpenJade 1.4devel pour construire les PDF. Le message renvoyé est :
openjade:./stylesheet.dsl:664:2:E: flow object not accepted by port; only display flow objects accepted make: *** [postgres-A4.tex-pdf] Segmentation fault
L'utilisation d'OpenJade 1.3 suffit pour se débarasser de ce problème.
De même, les fichiers dsssl.dtd, fot.dtd, style-sheet.dtd et catalog du répertoire dsssl doivent être installés quelque part, dans /usr/local/share/sgml/dsssl, par exemple. Il est certainement plus facile de copier le répertoire entier.
cp -R dsssl /usr/local/share/sgml
Enfin, le fichier /usr/local/share/sgml/catalog doit être créé pour y ajouter la ligne suivante :
CATALOG "dsssl/catalog"
(Il s'agit d'un chemin relatif référençant le fichier installé dans l'Étape 2. Ce chemin doit être correctement renseigné si un répertoire d'installation différent est utilisé.)
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.)
Pour installer les feuilles de style, décompresser et dépaqueter la distribution, la déplacer à un endroit convenable de l'aborescence comme, par exemple, /usr/local/share/sgml. (L'archive crée automatiquement un sous-répertoire.)
$ gunzip docbook-dsssl-1.xx.tar.gz $ tar -C /usr/local/share/sgml -xf docbook-dsssl-1.xx.tar
L'entrée de catalogue communément admise dans /usr/local/share/sgml/catalog peut également être réalisée :
CATALOG "docbook-dsssl-1.xx/catalog"
Comme les feuilles de styles changent assez souvent et qu'il est parfois avantageux d'essayer des versions alternatives, PostgreSQL™ n'utilise pas cette entrée du catalogue. Regarder dans la Section J.2.5, « Détection par configure » pour tout renseignement sur la manière de sélectionner une feuille de style.
Pour installer et utiliser JadeTeX™, il faut une installation fonctionnelle de TeX™ et de LaTeX2e™, incluant également les paquetages tools™ et graphics™, Babel™, les polices AMS™ et AMS-LaTeX™, l'extension PSNFSS™ et le kit d'accompagnement de « 35 polices », le programme dvips™ pour la production de PostScript™, le paquetage de macros fancyhdr™, hyperref™, minitoc™, url™ et enfin ot2enc™. Tous peuvent être trouvés sur le site web du CTAN. L'installation du système TeX de base est en dehors du périmètre de cette introduction. Des paquetages binaires sont probablement disponibles pour tout système pouvant exécuter TeX.
Avant de pouvoir utiliser JadeTeX avec les sources de la documentation de PostgreSQL™, il va falloir augmenter la taille des structures de données internes de TeX. Des explications plus détaillées sont fournies dans les instructions d'installation de JadeTeX.
Lorsque tout cela est réalisé, JadeTeX peut être installé :
$ gunzip jadetex-xxx.tar.gz $ tar xf jadetex-xxx.tar $ cd jadetex $ make install $ mktexlsr
Les deux dernières commandes doivent être exécutées en root.
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 openjade... openjade checking for DocBook V4.2... yes checking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modular checking for collateindex.pl... /usr/bin/collateindex.pl checking for xsltproc... xsltproc checking for osx... osx
Si ni onsgmls ni nsgmls n'ont été trouvés, certains des tests suivants seront ignorés. onsgmls fait partie du paquetage Jade. Les variables d'environnement JADE et NSGMLS peuvent être renseignées 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ù Jade 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. Les feuilles de style DocBook sont recherchées dans un certain nombre d'endroits standard, mais si elles sont placées en un autre endroit, il faut configurer la variable d'environnement DOCBOOKSTYLE avec cet emplacement et relancer configure.