Documentation PostgreSQL 14.22 » Annexes » Documentation » Ensemble d'outils

Précédent | Niveau supérieur | Suivant
J.1. DocBook | Sommaire | J.3. Construire la documentation

## J.2. Ensemble d'outils

Les outils qui suivent sont utilisés pour produire la documentation. Certains sont optionnels (comme mentionné).

DTD DocBook

  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.

DocBook XSL Stylesheets

  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 disponible pour de meilleurs résultats.

Libxml2 for `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é.

Libxslt pour `xsltproc`

  `xsltproc` est un processeur XSLT, c'est-à-dire, un programme pour convertir le XML vers d'autres formats en utilisant des fichiers de style XSLT.

FOP

  Il s'agit d'un programme pour convertir, entre autres choses, du XML vers du PDF. Il est uniquement nécessaire si vous voulez construire la documentation au format 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é auprès de la liste de discussion de la documentation, afin d'inclure ces informations ici-même.

### J.2.1. Installation sur Fedora, RHEL et dérivés

Pour installer les packages requis, lancez :

    yum install docbook-dtds docbook-style-xsl libxslt fop

### J.2.2. Installation sur FreeBSD

Pour installer les paquets requis avec `pkg`, utiliser :

    pkg install docbook-xml docbook-xsl libxslt fop

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.

### J.2.3. Paquetages Debian

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 libxml2-utils xsltproc fop

### J.2.4. macOS

Si vous utilisez MacPorts, les commandes suivantes vous aideront à la configuration du système :

    sudo port install docbook-xml docbook-xsl-nons libxslt fop

Si vous utilisez Homebrew, utilisez plutôt ceci :

    brew install docbook docbook-xsl libxslt fop

Le programme fourni par Homebrew requiert la configuration de la variable d'environnement suivante :

    export XML_CATALOG_FILES=/usr/local/etc/xml/catalog

Sur les machines Apple Silicon, utilisez ceci :

    export XML_CATALOG_FILES=/opt/homebrew/etc/xml/catalog

Sans cela, `xsltproc` renverra ce genre d'erreurs :

    I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
    postgres.sgml:21: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
    ...

Alors qu'il est possible d'utiliser les versions fournies par Apple de `xmllint` et `xsltproc` à la place de celles fournies par MacPorts ou Homebrew, vous aurez toujours besoin d'installer les DTD et feuilles de style DocBook, et de configurer un fichier catalogue qui pointe vers eux.

### J.2.5. Installation manuelle à partir des sources

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.

#### J.2.5.1. Installer OpenSP

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

#### J.2.5.2. Installation du kit DTD de DocBook

1. Récupérer la distribution DocBook V4.2.

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

3. Décompresser l'archive.

       $ unzip -a ...../docbook-4.2.zip

   (L'archive décompresse ses fichier dans le répertoire courant.)

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

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

6. 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.)

### J.2.6. Détection par `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 ...