J.3. Construire la documentation avec Make

» » »

Précédent	Niveau supérieur	Suivant
J.2. Ensemble d'outils	Sommaire	J.4. Construire la documentation avec Meson

J.3. Construire la documentation avec Make #

J.3.1. HTML
J.3.2. Pages man (de manuel)
J.3.3. PDF
J.3.4. Fichiers texte
J.3.5. Vérification syntaxique

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$ make html

Il s'agit également de la cible par défaut. La sortie apparaît dans le sous-répertoire html.

Pour générer la documentation HTML avec la feuille de style utilisée sur postgresql.org à la place de la feuille de style par défaut, utilisez :

doc/src/sgml$ make STYLE=website html

Si l'option STYLE=website est utilisé, les fichiers HTML générés incluent des références aux feuilles de style intégrées sur postgresql.org et nécessite l'accès réseau pour les visualiser.

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. Pour créer les pages man, utiliser les commandes :

doc/src/sgml$ make man

J.3.3. PDF #

Pour produire un rendu PDF de la documentation en utilisant FOP, vous pouvez utiliser l'une des commandes suivantes, en fonction du format de papier préféré :

Pour un format A4 :
```
doc/src/sgml$ make postgres-A4.pdf
```
Pour un format U.S. letter :
```
doc/src/sgml$ make postgres-US.pdf
```

Puisque la documentation de PostgreSQL est assez grosse, FOP nécessitera une quantité de mémoire significative. À cause de ça, sur certains systèmes, la compilation échouera avec un message d'erreur lié à la mémoire. Cela peut généralement être corrigé en configurant les réglages de mémoire Java dans le fichier de configuration ~/.foprc, par exemple :

# FOP binary distribution
FOP_OPTS='-Xmx1500m'
# Debian
JAVA_ARGS='-Xmx1500m'
# Red Hat
ADDITIONAL_FLAGS='-Xmx1500m'

Il y a une quantité minimale de mémoire qui est nécessaire, et utiliser plus de mémoire à l'air de rendre les choses plus rapides jusqu'à un certain point. Sur les systèmes disposant de très peu de mémoire (moins d'1 Go), la compilation sera soit très lente du faire de l'utilisation du SWAP ou ne fonctionnera pas du tout.

Dans sa configuration par défaut, FOP émettra un message INFO pour chaque page. Le niveau de trace peut être changé via le fichier ~/.foprc :

LOGCHOICE=-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN

D'autres processeurs XSL-FO peuvent également être utilisés manuellement, mais le processus de compilation automatique ne supporte que FOP.

J.3.4. Fichiers texte #

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 17, 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 make INSTALL. Pour construire la sortie texte, il faut disposer de Pandoc version 1.13, ou une version ultérieure, en tant qu'outil de construction supplémentaire.

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.

J.3.5. 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$ make check