3. Installer les paquetages

3.1. Installer OpenJade

3.1.1. OpenJade

Voici ce qui est nécessaire de faire, mais pensez à lire les fichiers fournis avec OpenJade pour voir s'il n'y a pas des paramètres que vous pourriez personnaliser pour votre plate-forme :
cd /usr/local
tar -xvzf ~/openjade-1.3.tar.gz
cd openjade-1.3
./configure --prefix=/usr/local/openjade-1.3
make
make install
# Une fois installés, les fichiers objets etc.
# peuvent être supprimés
make clean
A l'installation, les bibliothèques sont placées dans /usr/local/openjade-1.3/lib, aussi, vous voudrez peut-être l'ajouter dans /etc/ld.so.conf et lancer ldconfig. Ajoutez /usr/local/openjade-1.3/bin à votre $PATH.

3.1.2. jadetex & pdfjadetex

Comme mentionné, jadetex et pdfjadetex sont des macros TeX fournies avec OpenJade. Elles sont placées dans /usr/local/openjade-3.1/dsssl. Un guide pratique sur l'installation de ces macros a été écrit par Frank Atanassow Christoph et peut être trouvé sur :

ftp://ftp.dante.de/tex-archive/macros/jadetex/install.pdf

http://www.comptechnews.com/~reaster/installjadetex.pdf

Les sections suivantes sont adaptées des instructions trouvées dans install.pdf :

3.1.2.1. Créer hugelatex (si nécessaire)

Les macros TeX jadetex et pdfjadetex nécessitent plus de mémoire qu'une utilisation habituelle de TeX. Souvent, la configuration par défaut des limites d'utilisation mémoire de TeX n'est pas adaptée. Le fichier de configuration de TeX, texmf.cnf, peut être modifié et les valeurs des variables correspondant à la limite d'utilisation de la mémoire par TeX peuvent être augmentées. Cependant, plutôt que de simplement éditer le fichier texmf.cnf pour permettre à TeX d'utiliser plus de mémoire en toutes circonstances, un contexte TeX spécifique peut être créé, appelé hugelatex. Si hugelatex est déjà configuré sur votre système, vous pouvez sauter cette section (which hugelatex vous donne l'emplacement de la macro si elle est configurée).

Vérifiez qu'une version fonctionnelle de TeX est installée et trouvez son emplacement :
bash$ which tex
/usr/share/texmf/bin/tex
bash$ kpsewhich -expand-var='$TEXMFMAIN'
/usr/share/texmf
bash$

L'utilisation de which devrait trouver l'emplacement du programme TeX. Si TeX n'est pas trouvé, vous aurez peut-être à installer teTeX puis à revenir ici. kpsewhich est un utilitaire fourni avec teTeX qui donne, si tout va bien, le répertoire TeX principal.

Maintenant que le répertoire de texmf est connu, l'installation peut débuter :
cd /usr/share/texmf
cd tex/latex
cp -r config config-temp
cd config-temp
tex -ini -progname=hugelatex latex.ini
mv latex.fmt hugelatex.fmt
mv hugelatex.fmt /usr/share/texmf/web2c
cd ..
rm -r config-temp
cd /usr/share/texmf/bin
ln -s tex hugelatex
cd /usr/share/texmf/web2c
Le répertoire web2c contient le fichier de configuration texmf.cnf. Faîtes une copie de sauvegarde de ce fichier : cp texmf.cnf texmf.cnf.orig. Editez le fichier en utilisant votre éditeur préféré, et ajoutez les lignes suivantes à la fin :
% hugelatex settings
extra_mem_top.hugelatex = 8000000
extra_mem_bot.hugelatex = 8000000
hash_extra.hugelatex = 15000
pool_size.hugelatex = 5000000
string_vacancies.hugelatex = 45000
max_strings.hugelatex = 55000
pool_free.hugelatex = 47500
nest_size.hugelatex = 500
param_size.hugelatex = 1500
save_size.hugelatex = 5000
stack_size.hugelatex = 15000
% jadetex
extra_mem_top.jadetex = 8000000
extra_mem_bot.jadetex = 8000000
hash_extra.jadetex = 20000
pool_size.jadetex = 5000000
string_vacancies.jadetex = 45000
max_strings.jadetex = 55000
pool_free.jadetex = 47500
nest_size.jadetex = 500
param_size.jadetex = 1500
save_size.jadetex = 5000
stack_size.jadetex = 15000
% pdfjadetex
extra_mem_top.pdfjadetex = 8000000
extra_mem_bot.pdfjadetex = 8000000
hash_extra.pdfjadetex = 20000
pool_size.pdfjadetex = 5000000
string_vacancies.pdfjadetex = 45000
max_strings.pdfjadetex = 55000
pool_free.pdfjadetex = 47500
nest_size.pdfjadetex = 500
param_size.pdfjadetex = 1500
save_size.pdfjadetex = 5000
stack_size.pdfjadetex = 15000
Nous avons pris de l'avance en ajoutant des entrées pour jadetex et pdfjadetex, lesquels seront configurés ci-dessous. Vous pouvez jouer avec les paramètres mémoire précédents comme vous le voulez si vous rencontrez des problèmes avec ceux-ci.

Notez que la mise en place de hugelatex n'est prise en compte qu'après avoir lancé le programme texhash
root# texhash
texhash: Updating /usr/share/texmf/ls-R...
texhash: Updating /var/cache/fonts/ls-R...
texhash: Done.
root#

3.1.2.2. jadetex & pdfjadetex

La configuration de jadetex et de pdfjadetex est similaire à celle de hugelatex.
cd /usr/local/openjade-1.3/dsssl
make -f Makefile.jadetex install
# make crée et installe les fichiers .fmt
# dans /usr/share/texmf/web2c
# Création des liens symboliques...
cd /usr/share/texmf/bin
ln -s tex jadetex
ln -s pdftex pdfjadetex
# Enfin, lancement de texhash.
root# texhash
Le Makefile utilise hugelatex, aussi hugelatex doit avoir été configuré avant. Quand tex est lancé par hugelatex, jadetex ou pdfjadetex, il récupère le nom de la commande (donc le contexte) dans la variable argv[0]. Ensuite, il parcourt texmf.cnf et utilise les configurations contextuelles qu'il y trouve. Les fichiers de format (.fmt) placés dans /usr/share/texmf/web2c sont également chargés suivant le contexte.

Jadetex utilise un fichier tex généré par OpenJade pour créer un DVI. De même pdfjadetex utilise le fichier tex généré par OpenJade et crée un PDF. Le programme dvips utilise le fichier DVI et crée un fichier postscript (PS).

3.2. La DTD SGML DocBook

3.2.1. Décompresser la DTD SGML DocBook

La DTD DocBook n'est constituée que de fichiers texte SGML, aussi il n'y a rien à compiler. Décompressez uniquement ces fichiers dans un endroit choisi.
# DocBook DTD V4.1 placé dans
# /usr/local/share/sgml/docbook/4.1
cd /usr/local/share
mkdir sgml; cd sgml
mkdir docbook; cd docbook
mkdir 4.1; cd 4.1
unzip -a ~/docbk41.zip
Si vous installez doctools-1.2 de la distribution XFree86, cela installera d'anciennes versions de la DTD DocBook dans des sous-répertoires, comme les versions 2.4.1 et 3.0.

Il y a des différences entre les diverses versions de la DTD DocBook. Les fichiers xxxissues.txt documentent ces questions. Des balises ont été ajoutées, retirées ou renommées entre les versions.

Si vous devez utiliser la DTD DocBook dans sa version 3.1, elle est disponible au même endroit où la version 4.1 se télécharge. La version 3.1 est beaucoup utilisée, aussi c'est une bonne idée de la télécharger et de la placer dans un sous-répertoire 3.1/.

3.2.2. Décompresser les entités ISO8879

Allez dans le répertoire de chaque version installée de la DTD DocBook, et décompressez-y le fichier iso8879-entities.tar.gz :
cd /usr/local/share/sgml/docbook/4.1
tar -xvzf ~/iso8879-entities.tar.gz
Il doit y avoir dans le répertoire de chaque version de la DTD DocBook un fichier docbook.cat, ou un fichier catalog, ou bien les deux. Si les deux sont présents, ils sont probablement identiques. Si seul docbook.cat est présent, allez dans le répertoire et créez un lien symbolique :
# Si nécessaire...
cd /usr/local/share/sgml/docbook/4.1
ln -s docbook.cat catalog

3.3. Les DSSSL DocBook

L'installation des feuilles de style DSSSL DocBook, qui sont compatibles avec toutes les versions de DocBook, ne nécessitent que de les décompresser dans un répertoire approprié :
cd /usr/local/share/sgml
mkdir dsssl; cd dsssl
unzip -a ~/db160.zip
# Si vous avez téléchargé ldp.dsl le fichier de personnalisation
# des feuilles de style, copiez-le dans...
cd docbook
cp ~/ldp.dsl html
cp ~/ldp.dsl print
# ces deux répertoires
C'est tout ce qu'il y a à faire pour installer les feuilles de style DSSSL, hormis la configuration de la variable d'environnement SGML_CATALOG_PATH que nous aborderons plus tard. N'oubliez pas de corriger les droits sur les fichiers installés et leurs groupes/propriétaires (qui sont souvent inappropriés).

3.4. sgmltools-lite

Si vous le voulez, vous pouvez installer sgmltools-lite, bien que ce soit optionnel. Son installation est standard :
cd /usr/src
tar -xvzf ~/sgmltools-lite-3.0.2.tar.gz
cd sgmltools-lite-3.0.2
./configure
make install
Ceci installe le script python dans /usr/local/bin. Notez que sgmltools-lite utilise python, et est donc inutile si vous n'avez pas ce paquetage.

Pour que le script sgmltools fonctionne il vous faudra l'éditer pour corriger le chemin d'accès à OpenJade : vi `which sgmltools`. Consultez sa documentation pour en savoir plus.

3.5. htmldoc

3.5.1. binaires

Préférez le téléchargement de la version compilée de htmldoc pour votre plate-forme. L'installation est on ne peut plus simple : décompressez le paquetage et lancez le setup. Lisez la documentation fournie pour plus d'information.

3.5.2. sources

Si vous avez téléchargé les sources, vous aurez également besoin de la bibliothèque Fast Light Tool Kit, pour réussir l'édition de liens.

http://www.fltk.org/

L'installation est de la famille autoconf. Lancez simplement le script ./configure, puis make et make install. Si tout va bien, le programme sera installé dans /usr/bin.

3.5.3. ldp_print

Le programme htmldoc a quelques soucis pour traiter les fichiers HTML d'OpenJade. Par exemple, les puces des listes ne sont pas rendues correctement, et les zones ombrées ne le sont pas toujours.

Pour contourner ce problème, un script perl (ldp_print) est disponible sur LinuxDoc.org. Le script traite un fichier HTML unique créé par OpenJade et lance htmldoc dessus, pour produire des fichiers aux formats PDF et PS corrects.

AstuceConseil
 

Adoptez-le !

tar -xvzf ldp_print.tar.gz
cd ldp_print
# Copiez la bibliothèque dans le chemin
# de recherche de Perl.
cp fix_print_html.lib /usr/lib/perl5/site_perl
cp ldp_print /usr/local/bin
Jetez un oeil aux scripts au cas où il y aurait des lignes que vous devriez adapter. Peut-être qu'un jour le bogue d'htmldoc sera réparé, et que ce script ne sera plus nécessaire.

3.6. DocBook2X et SGMLS.pm (sgmlspl)

3.6.1. sgmlspl

Pour que les fichiers de spécifications de DocBook2X soient utiles, le module SGMLS.pm pour Perl5 doit être installé, en supposant que Perl5 est déjà installé. L'installation de ce module n'est pas autant automatisée que le sont les installations de la plupart des modules Perl. Il utilise un fichier Makefile qui doit être édité avant de lancer make.
cd /usr/src
tar -xvzf ~/SGMLSpm-1.03ii.tar.gz
cd SGMLSpm
# Editez Makefile
vi Makefile
# Adaptez la section du Makefile relative
# aux options utilisateurs afin qu'elles
# reflètent votre système.
# Exemple :
#	PERL = /usr/bin/perl
#	BINDIR = /usr/local/bin
#	PERL5DIR = /usr/lib/perl5/site_perl
#	MODULEDIR = ${PERL5DIR}/SGMLS
#	SPECDIR = ${PERL5DIR}
#	HTMLDIR= /usr/local/apache/htdocs
make install
sgmlspl sera copié dans /usr/local/bin.

3.6.2. docbook2X (docbook2man-spec.pl)

DocBook2X ne contient aucun programme à compiler ou installer, mais des scripts que vous voudrez certainement examiner, aussi, tout ce qu'il y a à faire est de décompresser le paquetage quelque part :
cd /usr/local/share/sgml
tar -xvzf ~/docbook2X-0.6.0.tar.gz
cd docbook2X
docbook2man-spec.pl se trouvera dans le répertoire de l'archive, avec un fichier patch qui corrige quelques petites choses. Appliquer le patch reste optionnel mais est recommandé.
patch docbook2man-spec.pl docbook2man-spec.pl.patch
Vous verrez par la suite dans la Section 4 comment utiliser sgmlspl et docbook2man-spec.pl pour générer des pages de manuel depuis un document DocBook <refentry>.

3.7. $SGML_CATALOG_FILES

La variable d'environnement SGML_CATALOG_FILES est utilisée par OpenJade (ainsi que d'autres logiciels SGML) pour localiser les DTD et les feuilles de style DSSSL. Les logiciels SGML ne peuvent pas travailler sans trouver ces fichiers, lesquels ont été placés dans de nombreux répertoires. Au point où nous en sommes de notre configuration, voici comment SGML_CATALOG_FILES peut être positionnée dans /etc/profile :
######################################################################################
# SGML DocBook - openjade sgmltools-lite
JADE_HOME=/usr/local/openjade-1.3
SGML_SHARE=/usr/local/share/sgml
PATH=$PATH:$JADE_HOME/bin
# feuilles de style DSSSL
#       Modular DocBook Stylesheets de Norman Walsh
SGML_CATALOG_FILES=$SGML_SHARE/dsssl/docbook/catalog
#       Feuilles de style OpenJade
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$JADE_HOME/dsssl/catalog
#       Feuilles de style sgmltools-lite
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/stylesheets/sgmltools/sgmltools.cat
# DTD DocBook
#       D'OASIS-Open.org
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/3.1/catalog
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/4.1/catalog
#       Ces anciennes versions ont été installées par
#       doctools-1.2 d'XFree86.org
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/2.4.1/catalog
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/3.0/catalog
# Catalogues sgmltools-lite pour LinuxDoc
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/dtd/sgmltools/catalog
export JADE_HOME SGML_SHARE PATH SGML_CATALOG_FILES
######################################################################################
Sauvegardez votre profil, déconnectez-vous et revenez pour que les changements prennent effet.

L'installation est terminée ! Dans la section suivante, nous testerons notre configuration et convertirons quelques fichiers DocBook.