Lorsque tout est en place, se placer dans le répertoire doc/src/sgml et lancer une des commandes décrites dans les sections suivantes afin de produire la documentation. (Il est impératif d'utiliser la version GNU de make.)
Pour engendrer la version HTML de la documentation, effectuer :
doc/src/sgml$ gmake html
Il s'agit également de la cible par défaut.
Pour créer un bon index, la construction doit se faire en plusieurs étapes identiques. Si l'index n'est pas utile et qu'il s'agit simplement de vérifier le résultat, on peut utiliser draft :
doc/src/sgml$ gmake draft
Pour simplifier la manipulation de la distribution finale de la documentation, l'ensemble des fichiers, dont la documentation HTML, peut être stocké dans une archive tar décompressée à l'installation. Pour créer le paquetage HTML, on utilise les commandes :
cd doc/src gmake postgres.tar.gz
Dans la distribution de PostgreSQL, cette archive, qui se trouve dans le répertoire doc, est installée par gmake install.
docbook2man-sgmlspl du projet DocBook2X™ est utilisé 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 :
cd doc/src/sgml gmake man D2MDIR=directory
Utilisez la variable D2MDIR pour indiquer le nom du répertoire où se trouve le fichier docbook2man-spec.pl du package docbook2man-sgmlspl. Il n'existe pas de valeur par défaut pour cela. Comme ce paquet n'est pas disponible ou est obsolète pour certains systèmes de paquets, vous pouvez aussi télécharger l'archive tar des sources et la déballer. Aucune compilation n'est nécessaire. Du coup, le chemin ressemble à ceci : D2MDIR=/home/vous/quelquepart/docbook2man-sgmlspl-1.0/perl. Vous pourriez obtenir des avertissements du style :
Warning: unrecognized SDATA '[scaron]': please add definition to docbook2man-spec.pl Warning: unrecognized SDATA '[ouml ]': please add definition to docbook2man-spec.pl
Vous pouvez les ignorer si (mais seulement si) vous utilisez la dernière version de docbook2man-spec.pl et que vous ne voyez pas d'autres avertissements SDATA entre ces deux-là.
Pour créer le paquet des pages man d'une version, utilisez les commandes suivantes :
cd doc/src gmake man.tar.gz D2MDIR=directory
qui produisent un fichier tar placé dans le répertoire doc/src.
Si JadeTex est utilisé pour produire une documentation pour impression, une des commandes suivantes peut être utilisée :
pour produire un fichier PostScript à partir du DVI au format A4 :
doc/src/sgml$ gmake postgres-A4.ps
Au format letter :
doc/src/sgml$ gmake postgres-US.ps
pour créer un PDF :
doc/src/sgml$ gmake postgres-A4.pdf
ou
doc/src/sgml$ gmake postgres-US.pdf
(Bien entendu, la version PDF peut être obtenue à partir d'un document PostScript, mais la génération directe permet de bénéficier des liens et autres fonctionnalités avancées dans le PDF.)
Lors de l'utilisation de JadeTeX pour la construction de la documentation PostgreSQL, il est probablement nécessaire d'augmenter la valeur de certains paramètres internes de TeX. Ils sont configurables dans le fichier texmf.cnf. Les paramètres suivants ont fonctionné quand ce texte a été écrit :
hash_extra.jadetex = 200000 hash_extra.pdfjadetex = 200000 pool_size.jadetex = 2000000 pool_size.pdfjadetex = 2000000 string_vacancies.jadetex = 150000 string_vacancies.pdfjadetex = 150000 max_strings.jadetex = 300000 max_strings.pdfjadetex = 300000 save_size.jadetex = 15000 save_size.pdfjadetex = 15000
Une version imprimable de la documentation de PostgreSQL™ peut être obtenue en la convertissant en RTF et en y appliquant des corrections de formatage mineures à l'aide d'une suite de logiciels de bureau. En fonction des capacités de cette dernière, la documentation peut ensuite être convertie dans les formats PostScript et/ou PDF. La procédure ci-dessous décrit cette procédure pour Applixware™.
![[Note]](images/note.png)
Il apparaît que la version actuelle de la documentation de PostgreSQL™ produit quelques bogues au niveau d'OpenJade, dépassant notamment la taille maximale de traitement. Si le processus de génération de la version RTF reste suspendu un long moment et que le fichier de sortie reste vide, c'est que ce problème est survenu. (Une génération normale doit prendre 5 à 10 minutes, ne pas s'avouer vaincu trop vite.)
Procédure I.1. Nettoyage du RTF avec Applixware™
OpenJade ne précise pas de style par défaut pour le corps du texte. Dans le passé, ce problème non diagnostiqué engendrait un long processus de génération du sommaire. Grâce à la grande aide des gens d'Applixware™, le symptôme a été diagnostiqué et un contournement est disponible.
Produire la version RTF en saisissant :
doc/src/sgml$ gmake postgres.rtf
Réparer le fichier RTF afin de préciser correctement
tous les styles et en particulier le style par défaut
(default). Si le document contient des sections
refentry, il faut
remplacer les éléments de formatage qui relient le
paragraphe précédent au paragraphe courant par un lien
entre le paragraphe courant et le paragraphe suivant.
Un utilitaire, fixrtf, est
disponible dans doc/src/sgml
afin de permettre ces corrections :
doc/src/sgml$ ./fixrtf --refentry postgres.rtf
Le script ajoute {\s0 Normal;}
comme style de rang zéro dans le document. D'après
Applixware™, le
standard RTF prohibe l'utilisation implicite d'un style
de rang 0 alors que Microsoft Word est capable de gérer
ce cas. Afin de réparer les sections refentry, le script remplace
les balises \keepn par
\keep.
Ouvrir un nouveau document dans Applixware Words™ et y importer le fichier RTF.
Produire une nouvelle table des matières avec Applixware™.
sélectionner les lignes existantes de la table des matières, du premier caractère de la table au dernier caractère de la dernière ligne ;
construire une nouvelle table des matières en allant dans le menu → → . Sélectionner les trois premiers niveaux de titres pour l'inclusion dans la table des matières. Cela remplace les lignes existantes importées du RTF en une table des matières issue d'Applixware™ ;
Ajuster le formatage de la table des matières à l'aide de → , en sélectionnant chacun des trois styles de la table des matières et en ajustant les indentations pour First et Left. Utiliser les valeurs suivantes :
| Style | Indentation de First (pouces) | Indentation de Left (pouces) |
|---|---|---|
| TOC-Heading 1 | 0.4 | 0.4 |
| TOC-Heading 2 | 0.8 | 0.8 |
| TOC-Heading 3 | 1.2 | 1.2 |
Sur l'ensemble du document :
ajuster les sauts de page ;
ajuster la largeur des colonnes des tables.
Remplacer les numéros de pages justifiés à droite dans les portions d'exemple et de figures de la table des matières avec les bonnes valeurs. Cela ne prend que quelques minutes.
Supprimer la section d'index du document si elle est vide.
Régénérer et ajuster la table des matières.
sélectionner un champ de la table des matières ;
sélectionner le menu → → ;
délier la table des matières en sélectionnant le menu → → ;
supprimer la première ligne de la table des matières, qui est un des champs de la table elle-même.
Sauvegarder le document au format natif Applixware Words™ pour que les modifications de dernière minute soient plus faciles par la suite.
« Imprimer » le document dans un fichier au format PostScript.
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 15, 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 gmake 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$ gmake check
Ensemble d'outils