PostgreSQLLa base de données la plus sophistiquée au monde.

Documentation PostgreSQL 8.2.23 > Annexes > Documentation > Construire la documentation
PrécédentEnsemble d'outils Écriture de la documentationSuivant

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

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

Lorsque la documentation HTML est produite, le processus engendre également les informations de liaison pour les entrées de l'index. Ainsi, pour disposer d'un index des concepts à la fin de la documentation, il est nécessaire de produire une première fois la documentation HTML, puis de relancer la production de la documentation avec le format souhaité.

Pour simplifier la manipulation de la distribution finale de la documentation, l'ensemble des fichiers, dont la documentation HTML, est stocké dans une archive tar qui est 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.

G.3.2. Pages man (de manuel)

docbook2man 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 le paquetage de pages man, utiliser les commandes : 

cd doc/src
gmake man.tar.gz

qui produisent un fichier tar placé dans le répertoire doc/src.

Afin de produire des pages man de qualité, il peut être nécessaire d'utiliser une version modifiée de l'utilitaire de conversion ou de faire des modification manuelles post-production. Toutes les pages man doivent être manuellement vérifiées avant toute distribution.

G.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 créer une version DVI : 

    doc/src/sgml$ gmake postgres.dvi

  • pour produire 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, 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.)

G.3.4. 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é 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]

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

  1. Produire la version RTF en saisissant : 

    doc/src/sgml$ gmake postgres.rtf

  2. Réparer 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, 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 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.

  3. Ouvrir un nouveau document dans Applixware Words™ et y importer le fichier RTF.

  4. Produire une nouvelle table des matières avec Applixware™.

    1. 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 ;

    2. 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™ ;

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

  5. Sur l'ensemble du document :

    • ajuster les sauts de page ;

    • ajuster la largeur des colonnes des tables.

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

  7. Supprimer la section d'index du document si elle est vide.

  8. Régénérer et ajuster la table des matières.

    1. sélectionner un champ de la table des matières ;

    2. sélectionnez 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.

  9. Sauvegarder le document au format natif Applixware Words™ pour que les modifications de dernière minute soient plus faciles par la suite.

  10. « Imprimer » le document dans un fichier au format Postscript.

G.3.5. 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 14, Procédure d'installation, 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.

G.3.6. 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