J.3. Construire la documentation

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

J.3.1. HTML

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

J.3.2. Pages man (de manuel)

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

J.3.3. Sortie pour l'impression via JadeTex

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

J.3.4. Texte dépassant du cadre

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.

J.3.5. Version imprimable via RTF

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

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 Tools → Book Building → Create Table of Contents. 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 Format → Style, 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.
1. sélectionner un champ de la table des matières ;
2. sélectionner le menu Tools → Book Building → Create Table of Contents ;
3. délier la table des matières en sélectionnant le menu Tools → Field Editing → Unprotect ;
4. 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.

J.3.6. Fichiers texte

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.

J.3.7. Vérification syntaxique

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

Écriture de la documentation Suivant