J.3. Construire la documentation

Pour engendrer la version HTML de la documentation, effectuer :

doc/src/sgml$ make html

Il s'agit également de la cible par défaut. La sortie apparaît dans le sous-répertoire html.

Pour générer la documentation HTML avec la feuille de style utilisée sur postgresql.org à la place de la feuille de style par défaut, utilisez :

doc/src/sgml$ make STYLE=website html

Nous utilisons les feuilles de style XSL DocBook pour convertir les pages de références DocBook™ dans un format *roff compatible avec les pages man. Les pages man sont également distribuées sous la forme d'une archive tar, à l'instar de la version HTML. Pour créer les pages man, utiliser les commandes :

doc/src/sgml$ make man

Pour produire un rendu PDF de la documentation en utilisant FOP™, vous pouvez utiliser l'une des commandes suivantes, en fonction du format de papier préféré :

Puisque la documentation de PostgreSQL est assez grosse, FOP™ nécessitera une quantité de mémoire significative. À cause de ça, sur certains systèmes, la compilation échouera avec un message d'erreur lié à la mémoire. Cela peut généralement être corrigé en configurant les réglages de mémoire Java dans le fichier de configuration ~/.foprc, par exemple :

# FOP binary distribution
FOP_OPTS='-Xmx1000m'
# Debian
JAVA_ARGS='-Xmx1000m'
# Red Hat
ADDITIONAL_FLAGS='-Xmx1000m'
 

Il y a une quantité minimale de mémoire qui est nécessaire, et utiliser plus de mémoire à l'air de rendre les choses plus rapides jusqu'à un certain point. Sur les systèmes disposant de très peu de mémoire (moins d'1 Go), la compilation sera soit très lente du faire de l'utilisation du SWAP ou ne fonctionnera pas du tout.

D'autres processeurs XSL-FO peuvent également être utilisés manuellement, mais le processus de compilation automatique ne supporte que FOP.

Les instructions d'installation sont aussi distribuées sous la forme d'un fichier texte, au cas où cela se révélerait nécessaire (par exemple si des outils plus avancés n'étaient pas disponibles). Le fichier INSTALL correspond au Chapitre 16, Procédure d'installation de PostgreSQL™ du code source, avec quelques changements mineurs pour tenir compte de contextes différents. Pour recréer le fichier, se placer dans le répertoire doc/src/sgml et entrer la commande make INSTALL.

Dans le passé, les notes de versions et les instructions pour les tests de régression étaient aussi distribuées sous la forme de fichiers textes mais ce n'est plus le cas.

Fabriquer la documentation peut prendre beaucoup de temps. Il existe cependant une méthode, qui ne prend que quelques secondes, permettant juste de vérifier que la syntaxe est correcte dans les fichiers de documentation :

doc/src/sgml$ make check