G.2. Ensemble d'outils
Les outils qui suivent sont utilisés pour produire la documentation.
Certains sont optionnels (comme mentionné).
-
DTD
DocBook
-
Il s'agit de la définition de DocBook elle-même. C'est
actuellement la version 4.2 qui est utilisée ; il n'est pas
posiible d'en utiliser une autre (plus récente ou plus
ancienne). Il existe également une version XML de DocBook -- elle ne doit pas être
utilisée.
-
Les entités de
caractère ISO 8879
-
Celles-ci sont nécessaires à DocBook mais sont distribuées à
part car maintenues par l'ISO.
-
OpenJade
-
C'est le paquetage de base pour le traitement de
SGML. Il contient un
analyseur SGML, un
processeur DSSSL (programme
qui permet la conversion de documents SGML en d'autres formats à l'aide de
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.
-
Feuilles
de styles DocBook DSSSL
-
Celles-ci contiennent les instructions de conversion des
sources DocBook en d'autres formats, tel le HTML.
-
Les outils
DocBook2X
-
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érifier sur le
site web.
-
JadeTeX
-
JadeTeX™ peut être
installé pour utiliser TeX™ comme outil de formatage pour
Jade™. JadeTeX est capable de créer des fichiers
au formats Postscript ou PDF
(ce dernier avec les signets).
Cependant, une sortie JadeTeX
est de moindre qualité qu'une sortie RTF. Les principaux problèmes que l'on peut
rencontrer concernent les tables et les éléments de placements
verticaux et horizontaux. Il n'y a aucune possibilité de
corriger manuellement le résultat.
Différentes méthodes d'installation sont détaillées ci-après pour les
divers outils nécessaires au traitement de la documentation. Il peut
exister d'autres types de distributions empaquetées de ces outils.
Tout changement du statut d'un paquetage peut être rapportée auprés
de la liste de discussion de la documentation, afin d'inclurees ces
informations ici-même.
G.2.1. Installation par RPM Linux
La plupart des revendeurs mettent à disposition des utilisateurs un
ensemble complet de paquetages RPM pour le traitement de DocBook au
sein de leur distribution. Lors de l'installation, il faut
recherche une option « SGML »
ou les paquetages suivants : sgml-common,
docbook, stylesheets, openjade.
sgml-tools est probablement requis. Si le
fournisseur de la distribution ne les fournit pas, il doit être
possible d'utiliser des paquetages issus d'une distribution
compatible.
G.2.2. Installation sous FreeBSD
Le projet de documentation FreeBSD (FreeBSD Documentation Project)
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 doivent être
installés afin de produire la documentation sur FreeBSD :
Apparamment, il n'existe pas, à ce jour, de port pour la DTD de
DocBook V4.2 SGML. Elle doit être installée manuellement.
Un intérêt particulier peut également être porté aux différents
éléments de /usr/ports/print (tex, jadetex).
Il est probable que les portages ne mettent pas à jour le fichier
de catalogue général dans /usr/local/share/sgml/catalog. La ligne suivante
doit y figurer :
CATALOG "/usr/local/share/sgml/docbook/4.2/docbook.cat"
Pour ne pas éditer ce fichier, il est possible de positionner la
variable d'environnement SGML_CATALOG_FILES
en y mettant une liste de fichiers catalogues séparés par des
caractères « deux points ».
De plus amples informations sur les outils dédiés à la
documentation de FreeBSD se trouvent dans les
instructions du projet de documentation de FreeBSD
.
G.2.3. Paquetages Debian
Un ensemble complet de paquetages d'outils de documentation est
disponible pour Debian
GNU/Linux™. Pour l'installer, il suffit de taper :
apt-get install jade
apt-get install docbook
apt-get install docbook-stylesheets
G.2.4. Installation manuelle à partir des sources
L'installation manuelle des outils DocBook est quelque peu
complexe. Il est donc préférable d'utiliser des paquetages
pré-compilés. Seule une procédure de mise en oeuvre standard, qui
utilise des répertoires d'installation standard et sans
fonctionnalités particulières, est ici décrite. Pour les détails,
on peut étudier la documentation respective de chaque paquetage et
lire les documents d'introduction à SGML.
G.2.4.1. Installer OpenJade
-
L'installation d'OpenJade se fait par l'intermédiaire des
outils de construction ./configure;
make; make install classiques de GNU. Les détails sont
dans la distribution des sources d'OpenJade. En quelques
mots :
./configure --enable-default-catalog=/usr/local/share/sgml/catalog
make
make install
L'emplacement du « catalogue par
défaut » a son importance ; il est utilisé par
la suite. Il est possible de ne pas s'en souvenir, mais
dans ce cas, la variable d'environnement SGML_CATALOG_FILES doit être définie de façon
à pointer vers le bon fichier à chaque fois que
jade est exécuté. (Cette
méthode est également possible si OpenJade est déjà
installé et que le reste de l'environnement de publication
est installé localement.)
-
De même, les fichiers dsssl.dtd,
fot.dtd, style-sheet.dtd et catalog du répertoire dsssl doivent être installés quelque part,
dans /usr/local/share/sgml/dsssl,
par exemple. Il est certainement plus facile de copier le
répertoire entier.
cp -R dsssl /usr/local/share/sgml
-
Enfin, le fichier /usr/local/share/sgml/catalog doit être
créé pour y ajouter la ligne suivante :
CATALOG "dsssl/catalog"
(Il s'agit d'un chemin relatif référençant le fichier
installé dans l'Étape 2. Ce chemin doit être correctement
renseigné si un répertoire d'installation différent est
utilisé.)
G.2.4.2. Installation du kit
DTD de DocBook™
-
Récupérer la distribution
DocBook
V4.2
.
-
Créer le répertoire /usr/local/share/sgml/docbook-4.2 et s'y
placer. (L'emplacement exact importe peu mais celui-ci a le
bénéfice d'être cohérent avec le schéma d'installation
proposé ici.)
$ mkdir /usr/local/share/sgml/docbook-4.2
$ cd /usr/local/share/sgml/docbook-4.2
-
Décompresser l'archive.
$ unzip -a ...../docbook-4.2.zip
(L'archive décompresse ses fichier dans le répertoire
courant.)
-
Éditer le fichier /usr/local/share/sgml/catalog (ou celui
précisé à jade lors de l'installation) et y placer une
ligne similaire à celle-ci :
CATALOG "docbook-4.2/docbook.cat"
-
Télécharger l'archive contenant les
entités de
caractères ISO 8879
, la décompresser et placer les
fichiers dans le même répertoire que celui des fichiers de
DocBook.
$ cd /usr/local/share/sgml/docbook-4.2
$ unzip ...../ISOEnts.zip
-
Lancer 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.)
G.2.4.3. Installation des feuilles de
style DSSSL DocBook
Pour installer les feuilles de style, décompresser et dépaqueter
la distribution, la déplacer à un endroit convenable de
l'aborescence comme, par exemple, /usr/local/share/sgml. (L'archive crée
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 du catalogue. Regarder dans la Section G.2.5,
« Détection par
configure
» pour tout
renseignement sur la manière de sélectionner une feuille de
style.
G.2.4.4. Intallation de JadeTeX™
Pour installer et utiliser JadeTeX™, il faut une installation
fonctionnelle de TeX™ et
de LaTeX2e™, incluant
également les paquetages tools™ et graphics™, Babel™, les
polices AMS
™ et
AMS-LaTeX™, l'extension
PSNFSS
™ et le kit
d'accompagnement de « 35
polices », le programme dvips™ pour la production de
PostScript™, le paquetage
de macros fancyhdr™,
hyperref™, minitoc™, url™ et enfin ot2enc™. Tous ceux-ci peuvent être
trouvé sur le
site web du
CTAN
. L'installation
du système TeX de base est en
dehors du périmètre de cette introduction. Des paquetages
binaires sont probablement disponibles pour tout système pouvant
exécuter TeX.
Avant de pouvoir utiliser JadeTeX avec les sources de la documentation
de PostgreSQL™, il va
falloir augmenter la taille des structures de données internes de
TeX. Des explications plus
détaillées sont fournies dans les instructions d'installation de
JadeTeX.
Lorsque tout cela est réalisé, JadeTeX peut être installé :
$ 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 root.
G.2.5. Détection par configure
Avant de pouvoir engendrer la documentation, le script configure doit être lancé, comme cela se fait pour
la génération des programmes PostgreSQL™ eux-mêmes. La fin de
l'affichage de l'exécution de ce script doit ressembler à :
checking for onsgmls... onsgmls
checking for openjade... openjade
checking for DocBook V4.2... yes
checking for DocBook stylesheets... /usr/lib/sgstylesheets/nwalsh-modular
checking for sgmlspl... sgmlspl
Si ni onsgmls ni nsgmls n'ont été trouvés, les quatre dernières
lignes ne sont pas affichées. onsgmls
fait partie du paquetage Jade. Les variables d'environnement
JADE et NSGMLS
peuvent être renseignées pour indiquer les emplacements des
programmes s'ils ne sont pas trouvés automatiquement. Si
« DocBook V4.2 » n'a pas été
trouvé, c'est que le kit de la DTD DocBook n'est pas installé à un
endroit où Jade peut le trouver ou que les fichiers catalogues ne
sont pas correctement configurés. Il convient, dans ce cas, de se
reporter aux conseils donnés plus haut. Les feuilles de style
DocBook sont recherchées dans un certain nombre d'endroits
standard, mais si elles sont placées en un autre endroit, il faut
configurer la variable d'environnement DOCBOOKSTYLE avec cet emplacement et relancer
configure.
|
Documentation
