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. La sortie apparaît dans le sous-répertoire html.
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 construire la documentation sous la forme d'une seule page HTML, utilisez :
doc/src/sgml$ gmake postgres.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 :
cd doc/src/sgml gmake man
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
Quelque fois, le texte est trop long pour tenir dans les marges d'impression. Dans certains cas extrêmes, il est trop long pour tenir sur la page imprimée. Cela arrive principalement avec du code et des gros tableaux. Ce texte génère des messages « Overfull hbox » dans les traces de TeX, c'est-à-dire dans postgres-US.log ou dans postgres-A4.log. Un pouce contient 72 points, donc tout ce qui dépasse 72 points ne tiendra probablement pas dans la page imprimée (en supposant une marge d'un pouce). Pour retrouver le texte SGML causant cette surcharge, recherchez le premier numéro de page mentionné au-dessus du message d'erreur, par exemple [50 ###] (page 50), puis regardez à la page suivante (toujours dans notre exemple, la page 51) dans le fichier PDF pour voir le texte dépassant et ajustez ainsi le fichier SGML.
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™.
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 J.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 Applixware™ ;
→ → . 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'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.
Plusieurs fichiers sont distribués comme fichiers texte pour être lus lors de la phase d'installation. 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. Ceci crée un fichier INSTALL.html qui peut être enregistré au format texte avec Netscape Navigator™ pour 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, 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