Une fois que tout est en place, placez-vous dans le répertoire doc/src/sgml et lancez une des commandes décrites dans les sections suivantes afin de générer la documentation. (Souvenez-vous bien d'utiliser la version GNU de make.)
Pour générer la version HTML de la documentation, effectuez ce qui suit :
doc/src/sgml$ gmake html
Il s'agit également de la cible par défaut.
Lorsque la documentation HTML est générée, le processus produit également des informations de liaison pour les entrées de l'index. Ainsi, si vous souhaitez disposer d'un index des concepts à la fin de votre documentation, vous devrez produire une première fois la documentation HTML, puis relancer la production de la documentation avec le format que vous souhaitez obtenir.
Pour un côté plus pratique lors de la manipulation de la distribution finale de la documentation, l'ensemble des fichiers y compris la documentation HTML est stockée dans une archive tar qui est décompressée lors de l'installation. Pour créer le paquetage HTML, utilisez les commandes :
cd doc/src gmake postgres.tar.gz
Dans la distribution de PostgreSQL, cette archive se trouve dans le répertoire doc et peut être installée grace à gmake install.
Afin de convertir les pages de références de la documentation DocBook™ en pages man nous utilisons docbook2man pour les convertir dans un format compatible avec *roff. Les pages man sont également distribuées sous la forme d'une archive tar, à l'instar de la version HTML. Pour créer le paquetage de pages man, utilisez les commandes :
cd doc/src gmake man.tar.gz
qui résulteront en un fichier tar généré dans le répertoire doc/src.
Afin de générer des pages man de qualité, il sera peut-être nécessaire d'utiliser une version modifiée de l'utilitaire de conversion ou de faire des modification manuelles en post-production. Toutes les pages man doivent être manuellement vérifiées avant toute distribution.
Si vous souhaitez utiliser JadeTex pour produire une documentation à destination de l'impression, vous pouvez utiliser une des commandes suivantes :
Pour créer une version DVI :
doc/src/sgml$ gmake postgres.dvi
Pour générer un fichier Postscript à partir du DVI :
doc/src/sgml$ gmake postgres.ps
Pour créer un PDF :
doc/src/sgml$ gmake postgres.pdf
(Bien entendu, vous pouvez également créer une version PDF à partir d'un document Postscript, mais si vous le générez directement, votre PDF bénéficiera des liens actifs et de fonctionnalités supérieures.)
Vous pouvez aussi créer une version imprimable de la documentation de PostgreSQL™ en la convertissant en RTF et en y appliquant des corrections de formatage en utilisant une suite de logiciels de bureau. En fonction des capacité de cette dernière, vous pourrez convertir la documentation aux formats Postscript ou PDF. La procédure ci-dessous décrit une telle procédure en utilisant Applixware™.
![[Note]](images/note.png)
Il apparaît que la version actuelle de la documentation de PostgreSQL™ génère 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 la sortie garde une taille de 0, c'est que vous devez vous trouver face à ce problème. (Considérez cependant qu'une génération normale doit prendre 5 à 10 minutes, n'abandonnez donc pas trop tôt.)
Procédure G.1. Nettoyage du RTF pour Applixware™
OpenJade oublie de spécifier un style par défaut pour le corps du texte. Dans le passé, ce problème non diagnostiqué a amené un processus très long pour la génération du sommaire. Néanmoins, avec un grande aide des gens de Applixware™, le symptôme a été diagnostiqué et un contournement est disponible.
Produisez la version RTF en saisissant :
doc/src/sgml$ gmake postgres.rtf
Réparez le fichier RTF afin de spécifier correctement
tous les styles et en particulier le style par défaut
(default). Si le document contient des sections
refentry, vous
devrez également supprimer les éléments de formatage
qui relient le paragraphe précédent au paragraphe
courant. À la place, il faudra relier le paragraphe
précédent au paragraphe courant. 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;}
en temps que 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 cette éventualité. Afin de réparer les sections
refentry, le
script remplace les balises \keepn par \keep.
Ouvrez un nouveau document dans Applixware Words™ puis importez le fichier RTF.
Générez une nouvelle table des matières en utilisant Applixware™.
Sélectionnez 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.
Construisez une nouvelle table des matières en allant dans le menu → → . Sélectionnez les trois premiers niveaux de titres pour l'inclusion dans la table des matières. Cela remplacera les lignes existantes importées du RTF en une table des matières issue d'Applixware™.
Ajustez le formatage de la table des matières en utilisant le menu → , en sélectionnant chacun des trois styles de la table des matières et en ajustant les indentations pour First et Left. En utilisant 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 |
Travaillez la totalité du document en :
Ajustant les sauts de page.
Ajustant la largeur des colonnes des tables.
Remplacez 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.
Supprimez la section d'index du document si elle est vide.
Régénérez et ajustez la table des matières.
Sélectionnez un champ de la table des matières.
Sélectionnez le menu → → .
Déliez la table des matières en sélectionnant le menu → → .
Supprimez la première ligne de la table des matières, qui est un des champs de la table elle-même.
Sauvegardez le document au format natif de Applixware Words™ afin de pouvoir faire des modifications facilement dans le futur.
« Imprimez » le document dans un fichier au format Postscript.
Plusieurs fichiers textes sont distribués comme fichiers pour la lecture durant le processus d'installation. Le fichier INSTALL correspond au Chapitre 14, Procédure d'installation, avec quelques changements mineurs à mettre sur le compte d'un contexte différent. Pour recréer le fichier, placez-vous dans le répertoire doc/src/sgml et entrez la commande suivante gmake INSTALL. Ceci créera un fichier INSTALL.html que vous pourrez sauvegarder au format texte avec Netscape Navigator™ et remplacer le fichier existant. Netscape™ semble fournir la meilleure qualité pour la conversion du HTML en texte (comparé à lynx et à w3m).
Le fichier HISTORY peut être créé de manière similaire en utilisant la commande gmake HISTORY. Pour le fichier src/test/regress/README, la commande est gmake regress_README.
Fabriquer la documentation peut prendre beaucoup de temps. Il existe cependant une méthode ne prenant que quelques secondes et permettant juste de vérifier que la syntaxe est correcte dans les fichiers de documentation :
doc/src/sgml$ gmake check
Ensemble d'outils