DocBook Install mini-HOWTO

Robert B Easter

     <reaster@comptechnews.com>

   _Sylvain Amrani - _pour la traduction française
   _Historique des versions_
   Version v1.7 2001-03-28 Revu par : rbe

   DocBook-Install-mini-HOWTO est un guide pratique et détaillé pour
   permettre aux novices d'installer rapidement DocBook et de générer des
   fichiers SGML en HTML, PS et PDF sur un système GNU/Linux (mais cela
   peut être similaire sur d'autres systèmes). La mise en place de
   DocBook, qui nécessite des fichiers de plusieurs paquetages distribués
   séparément, peut sembler confuse aux débutants.
     _________________________________________________________________

   _Table des matières_
   1. Introduction

        1.1. A propos de ce document
        1.2. Qu'est-ce que DocBook ?
        1.3. Aperçu rapide

   2. Télécharger les paquetages

        2.1. OpenJade
        2.2. La DTD SGML DocBook
        2.3. ISO8879 ENTITY SGML
        2.4. DSSSL DocBook
        2.5. Sgmltools-lite
        2.6. HTMLdoc
        2.7. DocBook2X
        2.8. Liens pour téléchargement direct

   3. Installer les paquetages

        3.1. Installer OpenJade
        3.2. La DTD SGML DocBook
        3.3. Les DSSSL DocBook
        3.4. sgmltools-lite
        3.5. htmldoc
        3.6. DocBook2X et SGMLS.pm (sgmlspl)
        3.7. $SGML_CATALOG_FILES

   4. Utiliser DocBook

        4.1. Générer du HTML
        4.2. Générer du RTF et du TEX
        4.3. Générer du DVI et du PS
        4.4. Générer du PDF
        4.5. Utiliser make
        4.6. Créer une page de manuel

   A. Légalité

        A.1. Copyright et Licences
        A.2. Décharge de responsabilité
        A.3. La licence GNU Free Documentation License

1. Introduction

1.1. A propos de ce document

   La dernière version de ce mini-howto peut être trouvée sur :

   http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/

   Reportez-vous à la section Annexe A pour des informations sur les
   copyright, licence et décharge de responsabilité relatifs à ce
   document.
     _________________________________________________________________

1.2. Qu'est-ce que DocBook ?

   DocBook est une Définition de Type de Documents (DTD - _Document Type
   Definition_) en Langage Standard de Balisage Généralisé (SGML -
   _Standard Generalized Markup Language_), qui définit un ensemble de
   balises pour des documents littéraux, et qui fonctionne comme le
   langage HTML utilisé habituellement sur le Web.

   DocBook est destiné à la rédaction de livres et d'articles. Comme tel,
   il fournit des balises (appelées encore marqueurs) pensées
   spécifiquement pour décrire des livres et des articles. Par exemple,
   les balises DocBook <book> et <article> sont utilisées pour créer les
   livres et les articles. Dans ces documents, des balises <chapter>,
   <sect1>, et <para> seront utilisées. Les fichiers SGML DocBook sont
   stockés dans des fichiers texte avec un suffixe .sgml ou .gml

   Lors de son traitement, un unique fichier SGML DocBook peut produire
   des fichiers HTML, PDF, PS, TXT ou d'autres formats de publication
   papier ou électronique. Le traitement est régi par des feuilles de
   style (_stylesheets_) qui peuvent générer automatiquement une table
   des matières, la numérotation des pages, la numérotation des chapitres
   et des sections, et bien d'autres possibilités.

   DocBook est destiné également à l'écriture de pages de manuel unix, en
   utilisant la balise <refentry>.
     _________________________________________________________________

1.3. Aperçu rapide

   Voici une description brève des paquetages que nous utiliserons dans
   les prochaines sections :

   _OpenJade. _OpenJade est un processeur DSSSL (_Document Style
   Semantics and Specification Language_ - Langage de spécification et
   Sémantique de présentation de document) pour documents SGML (_Standard
   Generalized Markup Language_ - Langage Standard de Balisage
   Généralisé). Il transforme des fichiers source SGML DocBook en
   fichiers HTML, TEX, RTF, TXT et autres formats. OpenJade est l'outil
   essentiel pour convertir un fichier DocBook dans d'autres formats. Le
   format de sortie TEX est utilisé surtout comme format intermédiaire
   pour obtenir des fichiers DVI, PDF et PS par des macros TeX et des
   convertisseurs DVI.

   _La DTD SGML DocBook. _Les fichiers DTD (Définition de Type de
   Document) sont des fichiers SGML qui définissent le langage DocBook.
   L'ensemble des balises valides et leurs règles d'utilisation y sont
   définis. OpenJade a besoin d'accéder aux fichiers DTD des documents
   qu'il doit traiter.

   _ISO8879 ENTITY SGML. _Les entités définissent la représentation des
   caractères spéciaux qui n'ont pas de touche clavier associée ou qui
   ont une signification particulière en SGML. Des exemples connus en
   HTML sont "&eacute;" pour "é","&amp;" pour "&" et "&gt;" pour ">".

   _DSSSL DocBook. _Les fichiers DSSSL (_Document Style Semantics and
   Specification Language_) pour une DTD particulière, en l'occurrence
   DocBook, spécifient comment convertir le document DocBook en fichiers
   au format HTML, RTF, TEX, etc.

   _SgmlTools-lite. _SgmlTools est une interface pour lancer OpenJade et
   les macros TeX jadetex et pdfjadetex qui en font partie. La conversion
   d'un fichier DocBook en format PS ou PDF est un traitement en deux ou
   trois étapes. OpenJade crée un fichier TEX qu'utilise jadetex pour
   produire un DVI, et pdfjadetex pour produire un document PDF. Un
   fichier PS s'obtient en transformant le fichier DVI avec dvips. Les
   scripts SgmlTools fournissent une commande unique pour ces tâches.

   _HTMLdoc. _HTMLdoc est un programme libre pour convertir des fichiers
   HTML en documents PDF ou PS.

   _SGMLSpm and docbook2X. _Ces deux outils sont à utiliser pour générer
   des pages de manuel. SGMLSpm est une bibliothèque modulaire Perl5 pour
   traiter les résultats du travail de onsgmls, un programme inclus dans
   OpenJade. SGMLSpm comprend une application appelée sgmlspl permettant
   d'utiliser la bibliothèque SGMLSpm. Sgmlspl nécessite des fichiers de
   spécification, disponibles sur de nombreux sites internet, pour chaque
   type de document à transformer. DocBook2X est un paquetage qui fournit
   des fichiers de spécification pour transformer des fichiers DocBook en
   pages de manuel.
     _________________________________________________________________

2. Télécharger les paquetages

   Dans cette section, nous localiserons et téléchargerons les logiciels
   sur Internet.
     _________________________________________________________________

2.1. OpenJade

   OpenJade est un logiciel aux sources libres (open-source), activement
   maintenu, basé sur le paquetage Jade de James Clark. Téléchargez la
   dernière version stable (1.3 ?) sur :

   http://openjade.sourceforge.net/

   OpenJade inclut également le paquetage OpenSP et les macros TeX
   jadetex et pdfjadetex pour convertir les fichiers en DVI et en PDF.
   Les programmes suivants sont installés par ce paquetage :

     * openjade
     * onsgmls
     * osgmlnorm
     * ospam
     * ospent
     * osx

   Afin de pouvoir utiliser jadetex et pdfjadetex pour créer du DVI, PS
   et PDF, vous devez avoir une installation de TeX qui fonctionne. Si
   vous n'avez pas TeX, cherchez dans votre distribution Linux le
   paquetage à installer. Sinon, vous pouvez télécharger la distribution
   TeX teTeX depuis :

   http://www.tug.org/tetex/
     _________________________________________________________________

2.2. La DTD SGML DocBook

   Les DTD DocBook SGML et XML sont maintenues par un comité technique à
   Oasis-Open.ORG. Téléchargez la dernière version (et les versions
   anciennes dont vous pourriez avoir besoin) de DocBook SGML sur :

   http://www.oasis-open.org/docbook/sgml/index.html
     _________________________________________________________________

2.3. ISO8879 ENTITY SGML

   Les entités définissent la représentation de caractères spéciaux ou de
   symboles qui ne peuvent être saisis au clavier, y compris les symboles
   mathématiques et les entités qui peuvent vous être familières avec le
   HTML. Ces fichiers d'entités doivent être installés pour avoir une
   configuration correcte.

     * Ressources à OASIS :
          + http://www.oasis-open.org/cover/topics.html#entities
          + http://www.oasis-open.org/cover/ISOEnts.zip
          + http://www.oasis-open.org/cover/isoENT-tar.gz

   ISOEnts.zip n'a besoin que d'être décompacté dans le répertoire de la
   DTD DocBook et de rien d'autre, mais les fichiers dans isoENT-tar.gz
   restent nécessaires. Les fichiers de isoENT-tar.gz doivent donc
   également être décompactés dans le répertoire de la DTD DocBook (cf.
   Section 3 pour les détails). Mais ces fichiers possèdent un suffixe
   ".ent" qui doit être renommé en ".gml". Vous pouvez le faire
   manuellement, ou bien vous pouvez télécharger et utiliser le fichier
   ci-dessous, préparé par l'auteur, qui contient les fichiers des deux
   archives ISOEnts.zip et isoENT-tar.gz :

   http://www.comptechnews.com/~reaster/iso8879-entities.tar.gz
     _________________________________________________________________

2.4. DSSSL DocBook

   Des fichiers DSSSL (_Document Style Semantics and Specification
   Language_) pour la DTD DocBook (SGML/XML) sont fournis par Norman
   Walsh. Ces fichiers, appelés Modular DocBook Stylesheets (feuilles de
   style modulaires pour DocBook), disent à OpenJade comment convertir
   votre fichier SGML DocBook en un autre format. Un fichier dsl décrit
   par exemple la correspondance entre une balise d'une DTD et une autre
   balise d'une autre DTD, ou d'autres conversions programmées, écrites
   dans un langage appelé Core Expression Language, qui est dérivé du
   Scheme. Le paquetage DSSSL DocBook et sa documentation peuvent être
   téléchargés sur le site de Norman Walsh :

   http://nwalsh.com/docbook/dsssl/

     NdT : Norman Walsh a depuis ouvert un projet sur SourceForge, qui
     doit maintenant être considéré comme le principal lieu de
     téléchargement :

     http://docbook.sourceforge.net/

   Le Projet de Documentation Linux a créé un fichier de personnalisation
   des feuilles de style qui active des options de présentation
   intéressantes. Il peut être téléchargé sur :

   http://www.linuxdoc.org/authors/tools/ldp.dsl
     _________________________________________________________________

2.5. Sgmltools-lite

   Sgmltools est une interface pour OpenJade, jadetex, pdfjadetex, dvips,
   et d'autres programmes. Sgmltools offre une commande unique pour
   générer tous les formats possibles avec ces outils. La dernière
   version, v1.3 à l'heure où nous écrivons ces lignes, peut être
   téléchargée sur :

   http://www.sgmltools.org/

   http://sourceforge.net/projects/sgmltools-lite/

   Ce paquetage est optionnel, mais rend parfois les choses plus faciles.
     _________________________________________________________________

2.6. HTMLdoc

   HTMLdoc est un programme libre pour convertir des sites Web en
   documents au format PDF (_Portable Document Format_) ou PS
   (_Postscript_). Concernant le format PDF, il crée une arborescence de
   signets correspondant aux sections, rendant la navigation plus facile.
   HTMLdoc et pdfjadetex créent tous deux des documents PDF, mais avec
   des rendus légèrement différents. Comparez les deux pour voir lequel
   produit le meilleur résultat pour un fichier DocBook particulier.
   Reportez-vous à la Section 2.8 pour connaître les adresses de
   téléchargement.
     _________________________________________________________________

2.7. DocBook2X

   DocBook2X nécessite Perl5 et le module Perl SGMLS.pm, disponible sur
   le CPAN. SGMLS.pm fournit des bibliothèques et un programme appelé
   sgmlspl qui convertissent les fichiers DocBook en d'autres formats en
   utilisant des fichiers de spécification. Ces fichiers de spécification
   sont des scripts Perl qui donnent le mécanisme de traduction dans un
   format particulier.

   http://www.cpan.org/

   http://docbook2x.sourceforge.net/
     _________________________________________________________________

2.8. Liens pour téléchargement direct

   Les fichiers ci-dessous sont donnés dans leur dernière version au
   moment de la rédaction de ce document :

   _openjade-1.3.tar.gz . _OpenJade, version 1.3.

   _docbk41.zip . _DocBook SGML DTD, version 4.1.

   _iso8879-entities.tar.gz . _Entités ISO 8879 SGML. Cet unique fichier
   est plus pratique à utiliser. Vous pouvez sinon télécharger les deux
   autres fichiers et changer les suffixes des fichiers en .gml.

   _db160.zip & db160d.zip . _Feuilles de style Modulaires DSSSL DocBook,
   version 1.60, et leur documentation.

   _sgmltools-lite-3.0.2.tar.gz . _Sgmltools-lite version 3.0.2. Je
   rappelle que c'est un paquetage optionnel.

   _ftp://ftp.easysw.com/pub/htmldoc/1.8.9/ . _HTMLdod 1.8.6. Des
   versions compilées sont disponibles avec le code source. Choisissez en
   fonction de votre plate-forme. Les versions compilées sont
   recommandées. Pour obtenir une version compilée, vous pouvez la
   télécharger directement par FTP sur les liens ci-dessous. Si le choix
   n'est pas évident, consultez le site Internet de EasySw :
   http://www.easysw.com/software.html

   _http://www.cpan.org/authors/id/DMEGG/SGMLSpm-1.03ii.tar.gz .
   _SGMLS.pm 1.03ii sur CPAN. (sgmlspl)

   _http://download.sourceforge.net/docbook2x/docbook2X-0.6.0.tar.gz .
   _DocBook2X 0.6.0 (fournit docbook2man-spec.pl à utiliser avec sgmlspl
   vu précédemment)
     _________________________________________________________________

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.

   Astuce _Conseil_


   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/sgmlto
ols.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.
     _________________________________________________________________

4. Utiliser DocBook

   Maintenant que tout est installé, il est temps de tester notre
   configuration, et de voir comment utiliser OpenJade et les autres
   outils.

   _Figure 1. Exemple de fichier SGML DocBook - test.sgml_
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

<article lang="fr">
<articleinfo>
        <title>Ceci est un test</title>

        <author>
                <firstname>John</firstname>
                <surname>Doe</surname>
                <othername role="mi">L</othername>
                <affiliation>
                        <address>
                        <email>j.doe@jdoe dot com</email>
                        </address>
                </affiliation>
        </author>

        <revhistory>
                <revision>
                <revnumber>v1.0</revnumber>
                <date>2000-12-30</date>
                <authorinitials>jld</authorinitials>
                </revision>
        </revhistory>

        <abstract>
        <para>
        Ceci est un document DocBook de test.
        </para>
        </abstract>

</articleinfo>

<sect1 id="test1">
<title>Test 1</title>
<para>
Test section 1.
</para>
        <sect2>
        <title>Test 1.1</title>
        <para>
        Test section 1.1
        </para>
        </sect2>

        <sect2>
        <title>Test 1.2</title>
        <para>
        <screen>
                -- Test section 1.2
                openjade -t sgml -d $DSLFILE test.sgml
        </screen>
        </para>
        </sect2>

</sect1>

<sect1 id="test2">
<title>Test 2</title>
<para>
Test section 2.
</para>

        <sect2>
        <title>Test 2.1</title>
        <para>
        Test section 2.1
        </para>
        </sect2>

        <sect2>
        <title>Test 2.2</title>
        <para>
        Test section 2.2
        </para>
        </sect2>

</sect1>
</article>

   Pour un guide sur DocBook et une référence sur les balises DocBook,
   voyez :

   _DocBook: The Definitive Guide.
   _http://www.docbook.org/tdg/html/docbook.html
     _________________________________________________________________

4.1. Générer du HTML

4.1.1. docbook.dsl

   _Figure 2. Création de documents HTML avec docbook.dsl_
bash$ ls -l
total 4
-rw-r--r--   1 reaster  users        1077 Dec 31 16:25 test.sgml
bash$ echo $SGML_SHARE
/usr/local/share/sgml
bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/docbook.dsl test.sgml
[Coupé - "DTDDECL catalog entries are not supported" - Message répété]
bash$ ls -l
total 12
-rw-r--r--   1 reaster  users        1885 Dec 31 17:34 t1.htm
-rw-r--r--   1 reaster  users        1077 Dec 31 16:25 test.sgml
-rw-r--r--   1 reaster  users        1544 Dec 31 17:34 x27.htm
bash$

   Les messages d'avertissement concernant DTDDECL peuvent être ignorés.
   Ils peuvent être légèrement gênants, mais ils sont normaux lorsqu'on
   utilise Jade. Les autres messages d'avertissement et d'erreur doivent
   être surveillés, et indiquent souvent des erreurs de syntaxe qui
   doivent être corrigées.

   Deux fichiers htm sont créés. Un pour chaque <SECT1>. Les noms des
   fichiers ne sont pas très informatifs. La première section apparaît
   sur la même page que les informations sur l'article. C'est le résultat
   de l'utilisation de la feuille de style de base qui est donnée avec
   les Modular DocBook Stylesheets, docbook.dsl.

   Les feuilles de style peuvent être personnalisées pour améliorer ces
   comportements. Si vous avez téléchargé le fichier ldp.dsl du Projet de
   Documentation Linux, et l'avez installé comme indiqué à la Section
   3.3, alors vous avez déjà un style personnalisé disponible.
     _________________________________________________________________

4.1.2. ldp.dsl

   _Figure 3. Création de documents HTML avec ldp.dsl_
bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/ldp.dsl#html test.sgml
bash$ ls -l
total 16
-rw-r--r--   1 reaster  users        2006 Dec 31 18:00 index.html
-rw-r--r--   1 reaster  users        1077 Dec 31 16:25 test.sgml
-rw-r--r--   1 reaster  users        1677 Dec 31 18:00 test1.html
-rw-r--r--   1 reaster  users        1598 Dec 31 18:00 test2.html
bash$

   En utilisant ldp.dsl, le résultat est plus satisfaisant :

     * Un fichier d'index contenant les informations sur l'article a été
       créé.
     * Une table des matières a été créée automatiquement.
     * A chaque <SECT1> correspond son propre fichier.
     * Les noms de fichier correspondent à l'attribut ID des balises
       <SECT1>
     * Les suffixes des noms de fichier sont maintenant .html.
     * Le contenu des balises <SCREEN> est grisé.

   Remarquez comment le fichier ldp.dsl a été saisi sur la ligne de
   commande : "_#html_" lui a été accolé. ldp.dsl contient deux balises
   <STYLE-SPECIFICATION>, une avec un attribut ID="html" et l'autre avec
   un ID="print". Notre commande permet ainsi de sélectionner le style
   html dans ldp.dsl. Les DSSSL DocBook permettent de convertir les
   fichiers DocBook en html ou en format papier. Dans la Section 3.3,
   nous avons copié ldp.dsl dans les deux répertoires html et print.
   Quand nous générons du html, le style _html_ doit être sélectionné
   comme précédemment. La génération d'autres formats comme RTF ou TEX
   est du ressort de la documentation papier et aussi le style _print_
   doit être sélectionné dans ldp.dsl. Une alternative est de mettre en
   commentaire ou de supprimer le style _print_ ou _html_ suivant le cas,
   dans les répertoires respectifs. Si un fichier dsl comporte plus d'une
   spécification de style, mais qu'aucune n'est sélectionnée comme
   l'exemple précédent, alors c'est le premier style rencontré dans le
   fichier qui sera sélectionné. Concernant ldp.dsl, les premières
   spécifications sont pour le style _print_, aussi il est sélectionné
   par défaut. Ainsi, en reprenant l'exemple précédent, et en omettant le
   "_#html_" lorsqu'on spécifie ldp.dsl comme feuille de style DSSSL, les
   spécifications de style "_print_" seront sélectionnées et utilisées
   lors de la génération de HTML. Ces feuilles fonctionneront, mais sont
   normalement prévues pour être appelées par print/ldp.dsl, et le
   formatage sera différent.

   Pour en savoir plus sur la façon dont les fichiers de personnalisation
   des feuilles de style sont conçus, lisez la documentation des Modular
   DocBook Stylesheets. La personnalisation consiste principalement au
   positionnement de paramètres booléens pour activer ou non des options
   de style. Une nouvelle logique de style peut également être programmée
   en utilisant le langage DSSSL Core Programming Language, comme
   mentionné dans la Section 2.4.

   L'option OpenJade -t type_sortie spécifie le type sortie. L'option -d
   dsssl_spec est le chemin d'accès à la feuille de style à utiliser.
   Dans l'exemple précédent, le type de sortie spécifié est sgml, qui est
   destiné aux transformations SGML vers SGML. Le HTML, comme défini par
   la Définition de Type de Document (DTD) HTML, est un type de document
   SGML, tout comme DocBook, aussi, sgml est le type de sortie approprié.
   Les deux autres types de sortie communément utilisés sont "rtf" et
   "tex". Le type tex sera utilisé plus tard comme format intermédiaire
   pour la génération de formats PDF et PS. L'option -d dsssl_spec doit
   spécifier un fichier et non un répertoire.
     _________________________________________________________________

4.2. Générer du RTF et du TEX

bash$ ls -l
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
bash$ openjade -t rtf -d $SGML_SHARE/dsssl/docbook/print/ldp.dsl#print test.sgm
l
bash$ openjade -t tex -d $SGML_SHARE/dsssl/docbook/print/ldp.dsl#print test.sgm
l
bash$ ls -l
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
     _________________________________________________________________

4.3. Générer du DVI et du PS

   _Figure 4. Utiliser jadetex pour générer un fichier DVI (DeVice
   Independant)_
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$ jadetex test.tex
This is TeX, Version 3.14159 (Web2C 7.3.1)
(test.tex
JadeTeX 1999/06/29: 2.7
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
(/usr/share/texmf/tex/jadetex/isoents.tex)
Elements will be labelled
Jade begin document sequence at 19
No file test.aux.
(/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
(/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
(/usr/share/texmf/tex/latex/hyperref/nameref.sty)
(/usr/share/texmf/tex/latex/psnfss/t1phv.fd)

LaTeX Warning: Reference `TEST1' on page 1 undefined on input line 238.


LaTeX Warning: Reference `20' on page 1 undefined on input line 262.


LaTeX Warning: Reference `23' on page 1 undefined on input line 285.


LaTeX Warning: Reference `TEST2' on page 1 undefined on input line 316.


LaTeX Warning: Reference `30' on page 1 undefined on input line 340.


LaTeX Warning: Reference `33' on page 1 undefined on input line 363.

[1.0.46] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46]
(test.aux)

LaTeX Warning: There were undefined references.

 )
Output written on test.dvi (3 pages, 34984 bytes).
Transcript written on test.log.
bash$ ls -l
total 80
-rw-r--r--   1 reaster  users         771 Dec 31 20:55 test.aux
-rw-r--r--   1 reaster  users       34984 Dec 31 20:55 test.dvi
-rw-r--r--   1 reaster  users        5072 Dec 31 20:55 test.log
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$ jadetex test.tex
This is TeX, Version 3.14159 (Web2C 7.3.1)
(test.tex
JadeTeX 1999/06/29: 2.7
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
(/usr/share/texmf/tex/jadetex/isoents.tex)
Elements will be labelled
Jade begin document sequence at 19
(test.aux) (/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
(/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
(/usr/share/texmf/tex/latex/hyperref/nameref.sty)
(/usr/share/texmf/tex/latex/psnfss/t1phv.fd) [1.0.46]
(/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46] (test.aux) )
Output written on test.dvi (3 pages, 34148 bytes).
Transcript written on test.log.
You have new mail in /var/spool/mail/reaster
bash$ ls -l
total 80
-rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$

   La première fois que jadetex est lancé sur un fichier, des
   avertissements sont imprimés. Ils peuvent être ignorés. Lancez-le une
   seconde fois sur le même fichier et ils n'apparaissent plus.

   _Figure 5. Utiliser dvips pour générer un fichier Postscript (PS)_
bash$ ls -l
total 80
-rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$ dvips test.dvi
This is dvips(k) 5.86 Copyright 1999 Radical Eye Software (www.radicaleye.com)
' TeX output 2000.12.31:2058' -> test.ps
<texc.pro><8r.enc><texps.pro><special.pro><color.pro>. [1] [2] [3]
bash$ ls -l
total 116
-rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
-rw-r--r--   1 reaster  users       34817 Dec 31 21:06 test.ps
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$

   _Figure 6. Utiliser htmldoc pour générer un fichier Postscript (PS)_
bash$ ls -l
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
bash$ export DSL_HTML=$SGML_SHARE/dsssl/docbook/html/ldp.dsl\#html
bash$ openjade -t sgml -V nochunks -d $DSL_HTML test.sgml | htmldoc -f test-htm
ldoc.ps -
bash$ ls -l
-rw-r--r--   1 reaster  users        9050 Jan  1 00:44 test-htmldoc.ps
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
bash$

   Si le fichier PS n'offre pas le résultat attendu, cela est dû à des
   bugs dans htmldoc. Examinez le script ldp_print si vous voulez
   l'utiliser pour faire du poscript.
     _________________________________________________________________

4.4. Générer du PDF

   _Figure 7. Utiliser pdfjadetex pour générer un fichier PDF (Portable
   Document Format)_
bash$ ls -l
-rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
-rw-r--r--   1 reaster  users       34817 Dec 31 21:06 test.ps
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$ pdfjadetex test.tex
This is pdfTeX, Version 3.14159-13d (Web2C 7.3.1)
(test.tex[/usr/share/texmf/pdftex/config/pdftex.cfg]
JadeTeX 1999/06/29: 2.7
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
(/usr/share/texmf/tex/jadetex/isoents.tex)
Elements will be labelled
Jade begin document sequence at 19
(test.aux) (/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
(/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
(/usr/share/texmf/tex/context/base/supp-pdf.tex
(/usr/share/texmf/tex/context/base/supp-mis.tex
loading : Context Support Macros / Missing
)
loading : Context Support Macros / PDF
) (/usr/share/texmf/tex/latex/hyperref/nameref.sty)
(/usr/share/texmf/tex/latex/psnfss/t1phv.fd) [1.0.46[/usr/share/texmf/dvips/con
fig/pdftex.map]] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46]
 (test.aux) )<8r.enc>
Output written on test.pdf (3 pages, 9912 bytes).
Transcript written on test.log.
bash$ ls -l
total 128
-rw-r--r--   1 reaster  users         753 Dec 31 21:13 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        5075 Dec 31 21:13 test.log
-rw-r--r--   1 reaster  users        9912 Dec 31 21:13 test.pdf
-rw-r--r--   1 reaster  users       34817 Dec 31 21:06 test.ps
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$
bash$ pdfjadetex test.tex
[coupé]
bash$ pdfjadetex test.tex
[coupé]

   Pdfjadetex doit être lancé jusqu'à trois fois pour résoudre toutes les
   références internes comme les numéros de pages dans les tables des
   matières.

   _Figure 8. Utiliser htmldoc pour générer un fichier PDF (Portable
   Document Format)_
bash$ ls -l
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
bash$ export DSL_HTML=$SGML_SHARE/dsssl/docbook/html/ldp.dsl\#html
bash$ openjade -t sgml -V nochunks -d $DSL_HTML test.sgml > test-htmldoc.htm
bash$ ldp_print test-htmldoc.htm
bash$ ls -l
-rw-r--r--   1 reaster  users        9050 Jan  1 01:17 test-htmldoc.pdf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
bash$

   Si l'option est activée dans le script ldp_print, un fichier PS sera
   également généré.
     _________________________________________________________________

4.5. Utiliser make

   La répétition des commandes pour générer les différents formats est
   vite fastidieuse. La commande _make_ fonctionne parfaitement pour
   automatiser le processus.

   _Figure 9. Makefile - automatiser la génération des documents_
# Génère des versions en-ligne et papier depuis un fichier source SGML
BASENAME=DocBook-Install

# fichier source SGML.
SGML_FILE=$(BASENAME).sgml

# Feuilles de style
DSL_PRINT=$(SGML_SHARE)/dsssl/docbook/print/ldp.dsl\#print
DSL_HTML=$(SGML_SHARE)/dsssl/docbook/html/ldp.dsl\#html

# Fichiers générés
HTML_FILE=index.html
HTM_FILE=$(BASENAME).htm
TEX_FILE=$(BASENAME).tex
RTF_FILE=$(BASENAME).rtf
PDF_FILE=$(BASENAME).pdf
DVI_FILE=$(BASENAME).dvi
PS_FILE=$(BASENAME).ps


# Règles de création

html: $(HTML_FILE)

htm: $(HTM_FILE)

tex: $(TEX_FILE)

rtf: $(RTF_FILE)

pdf: $(PDF_FILE)

dvi: $(DVI_FILE)

ps: $(PS_FILE)

all: html htm tex rtf pdf dvi ps

clean:
        rm -f $(BASENAME).{htm,log,aux,ps,pdf,tex,dvi,rtf,fot}
        rm -f *.html

distclean: clean
        rm -f $(BASENAME).tgz

package:
        rm -f $(BASENAME).tgz
        tar -C .. -czf /tmp/$(BASENAME).tgz $(BASENAME)
        mv /tmp/$(BASENAME).tgz .

dist: clean package

distall: all package


# Règles de compilation

$(HTML_FILE): $(SGML_FILE)
        openjade -t sgml -d $(DSL_HTML) $(SGML_FILE)

$(HTM_FILE): $(SGML_FILE)
        openjade -t sgml -V nochunks -d $(DSL_HTML) \
        $(SGML_FILE) > $(HTM_FILE)

$(TEX_FILE): $(SGML_FILE)
        openjade -t tex -d $(DSL_PRINT) $(SGML_FILE)

$(RTF_FILE): $(SGML_FILE)
        openjade -t rtf -d $(DSL_PRINT) $(SGML_FILE)

# [pdf]jadetex est lancé trois fois pour résoudre les références
#$(PDF_FILE): $(TEX_FILE)
#       pdfjadetex $(TEX_FILE)
#       pdfjadetex $(TEX_FILE)
#       pdfjadetex $(TEX_FILE)

# Cela *devrait* fonctionner, mais htmldoc a des bugs...
#$(PDF_FILE): $(SGML_FILE)
#       openjade -t sgml -V nochunks -d $(DSL_HTML) \
#       $(SGML_FILE) | htmldoc -f $(PDF_FILE) -

# Utiliser ldp_print pour pallier les bugs de htmldoc
# ldp_print peut aussi générer un fichier PS - voir le script
$(PDF_FILE): $(HTM_FILE)
        ldp_print $(HTM_FILE)

$(DVI_FILE): $(TEX_FILE)
        jadetex $(TEX_FILE)
        jadetex $(TEX_FILE)
        jadetex $(TEX_FILE)

$(PS_FILE): $(DVI_FILE)
        dvips $(DVI_FILE)

#$(PS_FILE): $(SGML_FILE)
#       openjade -t sgml -V nochunks -d $(DSL_HTML) \
#       $(SGML_FILE) | htmldoc -f $(PS_FILE) -

   On l'utilise comme pour la plupart des projets :

   _Figure 10. Appeler make pour lancer le Makefile_
# générer du html (par défaut)
make
# générer du PDF uniquement
make pdf
# générer tous les formats
make all
# supprimer tous les fichiers générés
make clean
# créer un paquetage tgz
# sans génération de fichiers
make dist
# créer un paquetage tgz
# comprenant tous les formats générés
make distall

   Notez la présence de règles de compilation de PDF et de PS mises en
   commentaire, qui offrent des alternatives sur les moyens de générer
   ces fichiers.
     _________________________________________________________________

4.6. Créer une page de manuel

   Lors de l'installation des paquetages, nous avons installé le module
   Perl5 SGMLSpm. Ensuite nous avons installé docbook2X qui fournit les
   fichiers spec.pl nécessaires à la transformation des documents DocBook
   RefEntry en fichiers au format nroff (page de manuel) à l'aide de
   sgmlspl.

   Un exemple de document DocBook RefEntry pour la commande foo est donné
   ci-dessous :

   _Figure 11. page de manuel foo - source DocBook RefEntry
   (foo-ref.sgml)_
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<refentry>
<refentryinfo>
        <date>2001-01-01</date>
</refentryinfo>
<refmeta>
        <refentrytitle>
                <application>foo</application>
        </refentrytitle>
        <manvolnum>1</manvolnum>
        <refmiscinfo>foo 1.0</refmiscinfo>
</refmeta>
<refnamediv>
        <refname>
                <application>foo</application>
        </refname>
        <refpurpose>
        Ne fait rien d'utile.
        </refpurpose>
</refnamediv>
<refsynopsisdiv>
        <refsynopsisdivinfo>
                <date>2001-01-01</date>
        </refsynopsisdivinfo>
        <cmdsynopsis>
        <command>foo</command>
<arg><option>-f </option><replaceable class="parameter">bar</replaceable></arg>
<arg><option>-d<replaceable class="parameter">n</replaceable></option></arg>
<arg rep="repeat"><replaceable class="parameter">fichier</replaceable></arg>
        </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
        <refsect1info>
                <date>2001-01-01</date>
        </refsect1info>
        <title>DESCRIPTION</title>
        <para>
        <command>foo</command> ne fait rien d'utile.
        </para>
</refsect1>
<refsect1>
        <title>OPTIONS</title>
        <variablelist>
        <varlistentry>
                <term>-f <replaceable class="parameter">bar</replaceable></term
>
                <listitem>
                        <para>
                        Prend <filename>bar</filename> comme
                        fichier de contrôle à l'exécution. S'il s'agissait
                        d'un véritable programme, il y aurait plus à dire ici
                        sur ce qu'est le fichier bar et comment il serait utili
sé.
                        </para>
                </listitem>
        </varlistentry>
        <varlistentry>
                <term>-d<replaceable class="parameter">n</replaceable></term>
                <listitem>
                        <para>
                        Fait quelque chose, où le nombre entier
                        <replaceable class="parameter">n</replaceable>
                        spécifie combien de fois.
                        </para>
                </listitem>
        </varlistentry>
        <varlistentry>
                <term><replaceable class="parameter">fichier...</replaceable></
term>
                <listitem>
                        <para>
                        Traite les fichiers dans l'ordre de leur apparition
                        et envoie le résultat sur stdout.
                        </para>
                </listitem>
        </varlistentry>
        </variablelist>
</refsect1>
<refsect1>
        <title>UTILISATION</title>
        <para>
        <command>foo</command> -f foo.conf -d2 foodata.foo
        </para>
</refsect1>
<refsect1>
        <title>MISE EN GARDE</title>
        <para>
        D'autres programmes appelés <command>foo</command> peuvent exister
        et faire réellement quelque chose !
        </para>
</refsect1>
<refsect1>
        <title>BUGS</title>
        <para>
        Aucun. Le programme ne fait rien.
        </para>
</refsect1>
<refsect1>
        <title>AUTEUR</title>
        <para>
        <author>
                <firstname>Foo</firstname>
                <othername role="mi">E</othername>
                <surname>Bar</surname>
                <contrib>Auteur original</contrib>
        </author>
        </para>
</refsect1>
</refentry>

   _Figure 12. Créer une page de manuel avec onsgmls, sgmlspl et
   docbook2man-spec.pl_
bash$ ls -l
-rw-r--r--   1 reaster  users        2434 Jan  3 03:51 foo-ref.sgml
bash$ onsgmls foo-ref.sgml | sgmlspl $SGML_SHARE/docbook2X/docbook2man-spec.pl
bash$ ls -l
-rw-r--r--   1 reaster  users        2434 Jan  3 03:51 foo-ref.sgml
-rw-r--r--   1 reaster  users        1129 Jan  3 04:03 foo.1
-rw-r--r--   1 reaster  users           0 Jan  3 04:03 manpage.links
-rw-r--r--   1 reaster  users           0 Jan  3 04:03 manpage.log
-rw-r--r--   1 reaster  users          15 Jan  3 04:03 manpage.refs
bash$ groff -mandoc -Tascii foo.1

FOO(1)                                                     FOO(1)


NAME
       foo - Ne fait rien d'utile.

SYNOPSIS
       foo [ -f bar ]  [ -dn ]  [ fichier... ]

DESCRIPTION
       foo ne fait rien d'utile.

OPTIONS
       -f bar Prend bar comme fichier de contrôle à l'exécution.
              S'il s'agissait d'un véritable programme, il y
              aurait plus à dire ici sur ce qu'est le fichier
              bar et comment il serait utilisé.

       -dn    Fait quelque chose, où le nombre entier n spécifie
              combien de fois.

       fichier...
              Traite les fichiers dans l'ordre de leur apparition
              et envoie le résultat sur stdout.

UTILISATION
       foo -f foo.conf -d2 foodata.foo

MISE EN GARDE
       D'autres programmes appelés foo peuvent exister et faire
       réellement quelque chose !

BUGS
       Aucun. Le programme ne fait rien.

AUTEUR
       Foo E Bar (Auteur original)

[coupé - plusieurs lignes blanches que man ne montrera pas]
foo 1.0                     2001-01-01                          1
bash$ groff -mandoc -Tascii foo.1 | less
bash$ less foo.1

   La page de manuel foo.1 est générée comme une page de la Section 1. La
   commande _groff_ est utilisée pour donner un aperçu de son apparence
   finale.

   Pour être installée, cette page de manuel doit être placée dans un
   répertoire man/man1, où le répertoire man/ est ajouté à la variable
   d'environnement $MANPATH. L'emplacement standard est
   /usr/local/man/man1. Les sections standard du système de pages de
   manuel sont numérotées de 1 à 9. Chacune est destinée à recevoir des
   documents d'une catégorie spécifique.

   _Tableau 1. Sections des pages de manuel_
   Section                Catégorie
   man1    Programmes et commandes
   man2    Appels système
   man3    Fonctions et routines des bibliothèques
   man4    Périphériques et fichiers spéciaux
   man5    Formats de fichier et conventions
   man6    Jeux
   man7    Divers
   man8    Administration système
   man9    Variables et fonctions internes du noyau

   Astuce _Astuce_


   Le fichier source d'une page de manuel, comme foo-ref.sgml, peut être
   converti dans tous les autres formats, exactement comme tout autre
   fichier DocBook. Aussi, l'utilisation des mêmes commandes présentées
   auparavant pour générer des fichiers au format HTML et papier, permet
   de sortir des pages de manuel en HTML et RTF, TEX, PDF, DVI et PS.
   Cela peut vous épargner un long travail de conversion !

   Et maintenant, amusez-vous !
     _________________________________________________________________

A. Légalité

A.1. Copyright et Licences

     Copyright (c) 2001 Robert B. Easter

     _Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.1 or any later version published by the Free Software
     Foundation; with no Invariant Sections, with no Front-Cover Texts,
     and with no Back-Cover Texts. A copy of the license is included in
     the section entitled "GNU Free Documentation License"._

     Permission vous est donnée de copier, distribuer et/ou modifier ce
     document selon les termes de la Licence GNU Free Documentation
     License, Version 1.1 ou ultérieure publiée par la Free Software
     Foundation ; sans section inaltérable, sans texte inaltérable de
     première page de couverture, sans texte inaltérable de dernière
     page de couverture. Une copie de cette licence est incluse dans la
     Section A.3.
     _________________________________________________________________

A.2. Décharge de responsabilité

   Aucune responsabilité pour le contenu de ce document ne peut être
   acceptée. Utilisez les concepts, exemples et autre contenu à vos
   propres risques.

   Tous les copyrights sont détenus par leurs propriétaires respectifs,
   sauf mention contraire expresse. L'utilisation d'un terme dans ce
   document ne doit pas être vue comme affectant la valeur d'une marque
   de fabrique ou de service.

   La mention d'un produit particulier ou d'une marque ne doit pas être
   considérée comme un acte d'approbation.
     _________________________________________________________________

A.3. La licence GNU Free Documentation License

   Avertissement _Avertissement_


   NdT - Pour des raisons de droit, la seule licence applicable
   concernant ce document est la licence _GNU Free Documentation
   License_, dans sa version originale en langue anglaise, retranscrite
   ci-après.

   Le lecteur francophone pourra, à titre d'information, se reporter sur
   le site de la copyleft de la Free Software Foundation, et en
   particulier sur la page
   http://www.gnu.org/copyleft/copyleft.html#translationsGFDL pour
   trouver des liens sur plusieurs traductions françaises de cette
   licence, tout en sachant que seule la version originale fait foi.
     _________________________________________________________________

A.3.1. GNU Free Documentation License

   Version 1.1, March 2000

     Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place,
     Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy
     and distribute verbatim copies of this license document, but
     changing it is not allowed.
     _________________________________________________________________

0. PREAMBLE

   The purpose of this License is to make a manual, textbook, or other
   written document "free" in the sense of freedom: to assure everyone
   the effective freedom to copy and redistribute it, with or without
   modifying it, either commercially or noncommercially. Secondarily,
   this License preserves for the author and publisher a way to get
   credit for their work, while not being considered responsible for
   modifications made by others.

   This License is a kind of "copyleft", which means that derivative
   works of the document must themselves be free in the same sense. It
   complements the GNU General Public License, which is a copyleft
   license designed for free software.

   We have designed this License in order to use it for manuals for free
   software, because free software needs free documentation: a free
   program should come with manuals providing the same freedoms that the
   software does. But this License is not limited to software manuals; it
   can be used for any textual work, regardless of subject matter or
   whether it is published as a printed book. We recommend this License
   principally for works whose purpose is instruction or reference.
     _________________________________________________________________

1. APPLICABILITY AND DEFINITIONS

   This License applies to any manual or other work that contains a
   notice placed by the copyright holder saying it can be distributed
   under the terms of this License. The "Document", below, refers to any
   such manual or work. Any member of the public is a licensee, and is
   addressed as "you".

   A "Modified Version" of the Document means any work containing the
   Document or a portion of it, either copied verbatim, or with
   modifications and/or translated into another language.

   A "Secondary Section" is a named appendix or a front-matter section of
   the Document that deals exclusively with the relationship of the
   publishers or authors of the Document to the Document's overall
   subject (or to related matters) and contains nothing that could fall
   directly within that overall subject. (For example, if the Document is
   in part a textbook of mathematics, a Secondary Section may not explain
   any mathematics.) The relationship could be a matter of historical
   connection with the subject or with related matters, or of legal,
   commercial, philosophical, ethical or political position regarding
   them.

   The "Invariant Sections" are certain Secondary Sections whose titles
   are designated, as being those of Invariant Sections, in the notice
   that says that the Document is released under this License.

   The "Cover Texts" are certain short passages of text that are listed,
   as Front-Cover Texts or Back-Cover Texts, in the notice that says that
   the Document is released under this License.

   A "Transparent" copy of the Document means a machine-readable copy,
   represented in a format whose specification is available to the
   general public, whose contents can be viewed and edited directly and
   straightforwardly with generic text editors or (for images composed of
   pixels) generic paint programs or (for drawings) some widely available
   drawing editor, and that is suitable for input to text formatters or
   for automatic translation to a variety of formats suitable for input
   to text formatters. A copy made in an otherwise Transparent file
   format whose markup has been designed to thwart or discourage
   subsequent modification by readers is not Transparent. A copy that is
   not "Transparent" is called "Opaque".

   Examples of suitable formats for Transparent copies include plain
   ASCII without markup, Texinfo input format, LaTeX input format, SGML
   or XML using a publicly available DTD, and standard-conforming simple
   HTML designed for human modification. Opaque formats include
   PostScript, PDF, proprietary formats that can be read and edited only
   by proprietary word processors, SGML or XML for which the DTD and/or
   processing tools are not generally available, and the
   machine-generated HTML produced by some word processors for output
   purposes only.

   The "Title Page" means, for a printed book, the title page itself,
   plus such following pages as are needed to hold, legibly, the material
   this License requires to appear in the title page. For works in
   formats which do not have any title page as such, "Title Page" means
   the text near the most prominent appearance of the work's title,
   preceding the beginning of the body of the text.
     _________________________________________________________________

2. VERBATIM COPYING

   You may copy and distribute the Document in any medium, either
   commercially or noncommercially, provided that this License, the
   copyright notices, and the license notice saying this License applies
   to the Document are reproduced in all copies, and that you add no
   other conditions whatsoever to those of this License. You may not use
   technical measures to obstruct or control the reading or further
   copying of the copies you make or distribute. However, you may accept
   compensation in exchange for copies. If you distribute a large enough
   number of copies you must also follow the conditions in section 3.

   You may also lend copies, under the same conditions stated above, and
   you may publicly display copies.
     _________________________________________________________________

3. COPYING IN QUANTITY

   If you publish printed copies of the Document numbering more than 100,
   and the Document's license notice requires Cover Texts, you must
   enclose the copies in covers that carry, clearly and legibly, all
   these Cover Texts: Front-Cover Texts on the front cover, and
   Back-Cover Texts on the back cover. Both covers must also clearly and
   legibly identify you as the publisher of these copies. The front cover
   must present the full title with all words of the title equally
   prominent and visible. You may add other material on the covers in
   addition. Copying with changes limited to the covers, as long as they
   preserve the title of the Document and satisfy these conditions, can
   be treated as verbatim copying in other respects.

   If the required texts for either cover are too voluminous to fit
   legibly, you should put the first ones listed (as many as fit
   reasonably) on the actual cover, and continue the rest onto adjacent
   pages.

   If you publish or distribute Opaque copies of the Document numbering
   more than 100, you must either include a machine-readable Transparent
   copy along with each Opaque copy, or state in or with each Opaque copy
   a publicly-accessible computer-network location containing a complete
   Transparent copy of the Document, free of added material, which the
   general network-using public has access to download anonymously at no
   charge using public-standard network protocols. If you use the latter
   option, you must take reasonably prudent steps, when you begin
   distribution of Opaque copies in quantity, to ensure that this
   Transparent copy will remain thus accessible at the stated location
   until at least one year after the last time you distribute an Opaque
   copy (directly or through your agents or retailers) of that edition to
   the public.

   It is requested, but not required, that you contact the authors of the
   Document well before redistributing any large number of copies, to
   give them a chance to provide you with an updated version of the
   Document.
     _________________________________________________________________

4. MODIFICATIONS

   You may copy and distribute a Modified Version of the Document under
   the conditions of sections 2 and 3 above, provided that you release
   the Modified Version under precisely this License, with the Modified
   Version filling the role of the Document, thus licensing distribution
   and modification of the Modified Version to whoever possesses a copy
   of it. In addition, you must do these things in the Modified Version:

    A. Use in the Title Page (and on the covers, if any) a title distinct
       from that of the Document, and from those of previous versions
       (which should, if there were any, be listed in the History section
       of the Document). You may use the same title as a previous version
       if the original publisher of that version gives permission.
    B. List on the Title Page, as authors, one or more persons or
       entities responsible for authorship of the modifications in the
       Modified Version, together with at least five of the principal
       authors of the Document (all of its principal authors, if it has
       less than five).
    C. State on the Title page the name of the publisher of the Modified
       Version, as the publisher.
    D. Preserve all the copyright notices of the Document.
    E. Add an appropriate copyright notice for your modifications
       adjacent to the other copyright notices.
    F. Include, immediately after the copyright notices, a license notice
       giving the public permission to use the Modified Version under the
       terms of this License, in the form shown in the Addendum below.
    G. Preserve in that license notice the full lists of Invariant
       Sections and required Cover Texts given in the Document's license
       notice.
    H. Include an unaltered copy of this License.
    I. Preserve the section entitled "History", and its title, and add to
       it an item stating at least the title, year, new authors, and
       publisher of the Modified Version as given on the Title Page. If
       there is no section entitled "History" in the Document, create one
       stating the title, year, authors, and publisher of the Document as
       given on its Title Page, then add an item describing the Modified
       Version as stated in the previous sentence.
    J. Preserve the network location, if any, given in the Document for
       public access to a Transparent copy of the Document, and likewise
       the network locations given in the Document for previous versions
       it was based on. These may be placed in the "History" section. You
       may omit a network location for a work that was published at least
       four years before the Document itself, or if the original
       publisher of the version it refers to gives permission.
    K. In any section entitled "Acknowledgements" or "Dedications",
       preserve the section's title, and preserve in the section all the
       substance and tone of each of the contributor acknowledgements
       and/or dedications given therein.
    L. Preserve all the Invariant Sections of the Document, unaltered in
       their text and in their titles. Section numbers or the equivalent
       are not considered part of the section titles.
    M. Delete any section entitled "Endorsements". Such a section may not
       be included in the Modified Version.
    N. Do not retitle any existing section as "Endorsements" or to
       conflict in title with any Invariant Section.

   If the Modified Version includes new front-matter sections or
   appendices that qualify as Secondary Sections and contain no material
   copied from the Document, you may at your option designate some or all
   of these sections as invariant. To do this, add their titles to the
   list of Invariant Sections in the Modified Version's license notice.
   These titles must be distinct from any other section titles.

   You may add a section entitled "Endorsements", provided it contains
   nothing but endorsements of your Modified Version by various
   parties--for example, statements of peer review or that the text has
   been approved by an organization as the authoritative definition of a
   standard.

   You may add a passage of up to five words as a Front-Cover Text, and a
   passage of up to 25 words as a Back-Cover Text, to the end of the list
   of Cover Texts in the Modified Version. Only one passage of
   Front-Cover Text and one of Back-Cover Text may be added by (or
   through arrangements made by) any one entity. If the Document already
   includes a cover text for the same cover, previously added by you or
   by arrangement made by the same entity you are acting on behalf of,
   you may not add another; but you may replace the old one, on explicit
   permission from the previous publisher that added the old one.

   The author(s) and publisher(s) of the Document do not by this License
   give permission to use their names for publicity for or to assert or
   imply endorsement of any Modified Version.
     _________________________________________________________________

5. COMBINING DOCUMENTS

   You may combine the Document with other documents released under this
   License, under the terms defined in section 4 above for modified
   versions, provided that you include in the combination all of the
   Invariant Sections of all of the original documents, unmodified, and
   list them all as Invariant Sections of your combined work in its
   license notice.

   The combined work need only contain one copy of this License, and
   multiple identical Invariant Sections may be replaced with a single
   copy. If there are multiple Invariant Sections with the same name but
   different contents, make the title of each such section unique by
   adding at the end of it, in parentheses, the name of the original
   author or publisher of that section if known, or else a unique number.
   Make the same adjustment to the section titles in the list of
   Invariant Sections in the license notice of the combined work.

   In the combination, you must combine any sections entitled "History"
   in the various original documents, forming one section entitled
   "History"; likewise combine any sections entitled "Acknowledgements",
   and any sections entitled "Dedications". You must delete all sections
   entitled "Endorsements."
     _________________________________________________________________

6. COLLECTIONS OF DOCUMENTS

   You may make a collection consisting of the Document and other
   documents released under this License, and replace the individual
   copies of this License in the various documents with a single copy
   that is included in the collection, provided that you follow the rules
   of this License for verbatim copying of each of the documents in all
   other respects.

   You may extract a single document from such a collection, and
   distribute it individually under this License, provided you insert a
   copy of this License into the extracted document, and follow this
   License in all other respects regarding verbatim copying of that
   document.
     _________________________________________________________________

7. AGGREGATION WITH INDEPENDENT WORKS

   A compilation of the Document or its derivatives with other separate
   and independent documents or works, in or on a volume of a storage or
   distribution medium, does not as a whole count as a Modified Version
   of the Document, provided no compilation copyright is claimed for the
   compilation. Such a compilation is called an "aggregate", and this
   License does not apply to the other self-contained works thus compiled
   with the Document, on account of their being thus compiled, if they
   are not themselves derivative works of the Document.

   If the Cover Text requirement of section 3 is applicable to these
   copies of the Document, then if the Document is less than one quarter
   of the entire aggregate, the Document's Cover Texts may be placed on
   covers that surround only the Document within the aggregate. Otherwise
   they must appear on covers around the whole aggregate.
     _________________________________________________________________

8. TRANSLATION

   Translation is considered a kind of modification, so you may
   distribute translations of the Document under the terms of section 4.
   Replacing Invariant Sections with translations requires special
   permission from their copyright holders, but you may include
   translations of some or all Invariant Sections in addition to the
   original versions of these Invariant Sections. You may include a
   translation of this License provided that you also include the
   original English version of this License. In case of a disagreement
   between the translation and the original English version of this
   License, the original English version will prevail.
     _________________________________________________________________

9. TERMINATION

   You may not copy, modify, sublicense, or distribute the Document
   except as expressly provided for under this License. Any other attempt
   to copy, modify, sublicense or distribute the Document is void, and
   will automatically terminate your rights under this License. However,
   parties who have received copies, or rights, from you under this
   License will not have their licenses terminated so long as such
   parties remain in full compliance.
     _________________________________________________________________

10. FUTURE REVISIONS OF THIS LICENSE

   The Free Software Foundation may publish new, revised versions of the
   GNU Free Documentation License from time to time. Such new versions
   will be similar in spirit to the present version, but may differ in
   detail to address new problems or concerns. See
   http://www.gnu.org/copyleft/.

   Each version of the License is given a distinguishing version number.
   If the Document specifies that a particular numbered version of this
   License "or any later version" applies to it, you have the option of
   following the terms and conditions either of that specified version or
   of any later version that has been published (not as a draft) by the
   Free Software Foundation. If the Document does not specify a version
   number of this License, you may choose any version ever published (not
   as a draft) by the Free Software Foundation.
     _________________________________________________________________

How to use this License for your documents

   To use this License in a document you have written, include a copy of
   the License in the document and put the following copyright and
   license notices just after the title page:

     Copyright (c) YEAR YOUR NAME. Permission is granted to copy,
     distribute and/or modify this document under the terms of the GNU
     Free Documentation License, Version 1.1 or any later version
     published by the Free Software Foundation; with the Invariant
     Sections being LIST THEIR TITLES, with the Front-Cover Texts being
     LIST, and with the Back-Cover Texts being LIST. A copy of the
     license is included in the section entitled "GNU Free Documentation
     License".

   If you have no Invariant Sections, write "with no Invariant Sections"
   instead of saying which ones are invariant. If you have no Front-Cover
   Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts
   being LIST"; likewise for Back-Cover Texts.

   If your document contains nontrivial examples of program code, we
   recommend releasing these examples in parallel under your choice of
   free software license, such as the GNU General Public License, to
   permit their use in free software.