| Documentation PostgreSQL 7.4.29 | ||||
|---|---|---|---|---|
| Précédent | Arrière rapide | Annexe G. Documentation | Avance rapide | Suivant |
Les outils suivants sont utilisés pour générer la documentation. Certains sont optionnels (comme mentionné).
Il s'agit de la définition de DocBook elle-même. Nous utilisons actuellement la version 3.1. Vous ne pouvez pas utiliser des versions plus récentes ou plus anciennes. Notez qu'il existe également une version XML de DocBook -- ne l'utilisez pas !
Celles-ci sont nécessaires à DocBook mais sont distribués à part car elles sont maintenues par l'ISO.
C'est le paquetage de base pour le traitement de SGML. Il contient un analyseur SGML, un processeur DSSSL (qui est un programme permettant la conversion de documents SGML en d'autres formats en utilisant des feuilles de styles DSSSL), ainsi qu'un certain nombre d'autres outils. Jade est actuellement maintenu par le groupe OpenJade et non plus par James Clark.
Celles-ci contiennent les instructions permettant la conversion des sources DocBook en d'autres formats tels que le HTML.
Ce paquetage est utilisé pour créer les pages de manuel. Un certain nombre d'autres paquetages sont nécessaires pour le faire fonctionner. Pour plus d'informations, vérifiez sur le site web.
Si vous le souhaitez, vous pouvez installer JadeTeX qui s'appuie sur TeX en tant qu'outil de formatage pour Jade. JadeTeX est capable de créer des fichiers au formats Postscript ou PDF (pour ce dernier, il implante les signets).
Cependant, une sortie JadeTeX est de qualité moindre par rapport à ce que vous pouvez obtenir d'une sortie RTF. Les principaux problèmes que l'on peut rencontrer se situent autour des tables et des éléments de placements verticaux et horizontaux. Il est à noter qu'il n'y a aucun recours de correction afin de corriger manuellement ces problèmes.
Nous avons pris le soin de documenter, ci-aprés, plusieurs types de méthodes d'installation pour les différents outils nécessaires au traitement de la documentation. Il peut exister d'autres types de distributions empaquetées de ces outils. Veuillez notifier tout changement de paquetage auprés de la liste de discussion de la documentation, nous tâcherons d'inclure ces informations ici-même.
La plupart des fabriquants de distributions mettent à disposition des utilisateurs un ensemble complet de paquetages RPM pour le traitement de DocBook au sein de leur distribution. Lors de l'installation, recherchez une option << SGML >> ou les paquetages suivants : sgml-common, docbook, stylesheets, openjade. Vous aurez probablement besoin de sgml-tools. Si le fournisseur de la distribution ne permet pas de disposer de ceux-ci, vous devriez être capable d'utiliser des paquetages issus d'une autre distribution compatible.
Le projet de documentation FreeBSD (FreeBSD Documentation Projetc) est lui-même un utilisateur intensif de DocBook, et c'est sans surprise que l'on retrouve en son sein un ensemble complet de << portages >> des outils de documentation sur FreeBSD. Les portages suivants devront être installés afin de produire la documentation sur FreeBSD.
textproc/sp
textproc/openjade
textproc/docbook-310
textproc/iso8879
textproc/dsssl-docbook-modular
Vous pourrez également porter un intérêt particulier aux différents éléments de /usr/ports/print (tex ou jadetex).
Il est probable que les portages ne mettent pas à jour le fichier de catalogue général dans /usr/local/share/sgml/catalog. Assurez-vous que la ligne suivante y figure bien :
CATALOG "/usr/local/share/sgml/docbook/3.1/catalog"
Si vous ne voulez pas éditer ce fichier, vous pouvez également modifier la variable d'environnement SGML_CATALOG_FILES en y mettant une liste de fichiers catalogues séparés par des caractères << deux points >>.
Vous pourrez trouver plus d'informations sur les outils dédiés à la documentation de FreeBSD dans les instructions du projet de documentation de FreeBSD.
Un ensemble complet de paquetages d'outils de documentation sont disponibles pour Debian GNU/Linux. Pour l'installer, utilisez simplement :
apt-get install jade apt-get install docbook apt-get install docbook-stylesheets
L'installation manuelle des outils DocBook est quelque peu complexe. Il est donc préférable que vous utilisiez des paquetages pré-compilés. Nous ne décrivons ici que la mise en œuvre standard utilisant des répertoires d'installation standards et sans fonctionnalités particulières. Pour entrer dans les détails, nous vous recommandons d'étudier la documentation respective de chaque paquetage et de lire les document d'introduction à SGML.
L'installation d'OpenJade se fait par l'intermédiaire des outils de construction ./configure;make;make install classique de GNU. Vous pourrez trouver des informations détaillées dans la distribution des sources d'OpenJade. En quelques mots :
./configure --enable-default-catalog=/usr/local/share/sgml/catalog make make install
Assurez-vous de bien vous souvenir de l'endroit où vous placez le << catalogue par défaut >> ; vous en aurez besoin par la suite. Vous pouvez également vous passer de renseigner cette option. Dans ce cas, vous devrez définir la variable d'environnement SGML_CATALOG_FILES afin qu'elle pointe vers le bon fichier à chaque fois que vous lancerez jade. (Cette méthode est également possible si OpenJade est déjà installé et que vous souhaitez installer le reste de l'environnement de publication localement.)
Par ailleurs, vous devez installer les fichiers dsssl.dtd, fot.dtd, style-sheet.dtd et catalog du répertoire dsssl quelque part, par exemple dans /usr/local/share/sgml/dsssl. Il vous sera certainement plus facile de copier le répertoire entier.
cp -R dsssl /usr/local/share/sgml
Enfin, créez le fichier /usr/local/share/sgml/catalog et ajoutez-y la ligne suivante :
CATALOG "dsssl/catalog"
(Il s'agit d'un chemin relatif référençant le fichier installé dans l'étape 2. Assurez-vous de bien avoir renseigné ce chemin si vous avez utilisé un répertoire d'installation différent.)
Récupérez la distribution DocBook V3.1.
Créez le répertoire /usr/local/share/sgml/docbook31 et placez-y vous. (L'emplacement importe peu en fait mais celle-ci a le bénéfice d'être cohérente avec le schéma d'installation que nous vous proposons ici.)
$ mkdir /usr/local/share/sgml/docbook31 $ cd /usr/local/share/sgml/docbook31
Décompressez l'archive.
$ unzip -a ...../docbk31.zip
(L'archive décompressera ses fichier dans le répertoire courant.)
Éditez le fichier /usr/local/share/sgml/catalog (ou ce que vous aurez dit à jade lors de l'installation) et placez-y une ligne similaire à celle-ci :
CATALOG "docbook31/docbook.cat"
Éventuellement, vous pouvez éditer le fichier docbook.cat et commenter ou supprimer la ligne contenant DTDDECL. Si vous ne le faites pas, jade générera des avertissements qui ne seront pas réellement un obstacle pour le but que nous nous sommes fixés.
Téléchargez l'archive contenant les entités de caractères ISO 8879, décompressez-la et placez les fichiers dans le même répertoire que celui des fichiers de DocBook.
$ cd /usr/local/share/sgml/docbook31 $ unzip ...../ISOEnts.zip
Lancez la commande suivante dans le répertoire contenant les fichiers DocBook et ISO :
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
(Cette opération permet de corriger les mélanges entre le fichier de catalogue de DocBook et les noms réels des fichiers contenant les entités de caractères ISO.)
Pour installer les feuilles de style, décompressez et déballez la distribution et déplacez-la à un endroit convenable de votre aborescence comme, par exemple, /usr/local/share/sgml. (L'archive créera automatiquement un sous-répertoire.)
$ gunzip docbook-dsssl-1.xx.tar.gz $ tar -C /usr/local/share/sgml -xf docbook-dsssl-1.xx.tar
L'entrée de catalogue communément admise dans /usr/local/share/sgml/catalog peut également être réalisée :
CATALOG "docbook-dsssl--1.xx/catalog
Comme les feuilles de styles changent assez souvent et qu'il est parfois avantageux d'essayer des versions alternatives, PostgreSQL n'utilise pas cette entrée dans le catalogue. Regardez dans la Section G.2.5 pour tout renseignement sur la manière de sélectionner une feuille de style.
Pour installer et utiliser JadeTeX, vous devez disposer d'une installation fonctionnelle de TeX et de LaTeX2e, incluant également les paquetages d'outils de support, la bibliothèque graphics, Babel, les polices AMS et AMS-LaTeX, l'extension PSNFSS et le kit d'accompagnement de << 35 polices >>, le programme dvips permettant de générer du PostScript, le paquetage de macros fancyhdr, hyperref, minitoc, url et enfin ot2enc. Tous ceux-ci peuvent être trouvé sur le site web de CTAN . L'installation de base pour le système TeX va au-delà des buts visés par cette introduction. Des paquetages binaires devraient être disponibles pour tout système pouvant exécuter TeX.
Avant que vous soyez en mesure d'utiliser JadeTeX avec les sources de la documentation de PostgreSQL, vous devrez augmenter la taille des structures de données internes de TeX. Des explications plus détaillées sur JadeTeX pourront être trouvées sur les instructions d'installation de ce produit.
Une fois ceci terminé, vous pouvez installer JadeTeX :
$ gunzip jadetex-xxx.tar.gz $ tar xf jadetex-xxx.tar $ cd jadetex $ make install $ mktexlsr
Les deux dernières commandes doivent être exécutées en temps que root.
Avant de pouvoir générer la documentation, vous devrez lancer le script configure comme vous le feriez lors de la génération des programmes PostgreSQL eux-même. Vérifiez la sortie de l'exécution de ce script vers la fin, vous trouverez quelque chose de similaire à ce qui suit :
checking for onsgmls... onsgmls checking for openjade... openjade checking for DocBook V3.1... yes checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular checking for sgmlspl... sgmlspl
Si ni onsgmls ni nsgmls n'ont été trouvés, vous ne verrez pas les quatre dernières lignes. onsgmls fait partie du paquetage Jade. Si << DocBook V3.1 >> n'a pas été trouvé, cela signifie que le kit de DTD DocBook n'a pas été placé à l'endroit où jade peut le trouver ou que vous n'avez pas configuré les fichiers de catalogue correctement. Regardez les indications d'installation ci-dessus. Les feuilles de style DocBook sont recherchées dans un certain nombre d'endroits relativement standardisés, mais si vous les avez placées ailleurs, vous devrez modifier la variable d'environnement DOCBOOKSTYLE à cet emplacement et relancer configure juste aprés.
| Précédent | Sommaire | Suivant |
| Documentation | Niveau supérieur | Génération de la documentation |