
DocBook Install mini-HOWTO

Robert B Easter

     <reaster@comptechnews.com>

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

   DocBook-Install-mini-HOWTO est un guide pratique et dtaill pour
   permettre aux novices d'installer rapidement DocBook et de gnrer des
   fichiers SGML en HTML, PS et PDF sur un systme GNU/Linux (mais cela
   peut tre similaire sur d'autres systmes). La mise en place de
   DocBook, qui ncessite des fichiers de plusieurs paquetages distribus
   sparment, peut sembler confuse aux dbutants.
     _________________________________________________________________

   _Table des matires_
   1. Introduction

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

   2. Tlcharger 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 tlchargement 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. Gnrer du HTML
        4.2. Gnrer du RTF et du TEX
        4.3. Gnrer du DVI et du PS
        4.4. Gnrer du PDF
        4.5. Utiliser make
        4.6. Crer une page de manuel

   A. Lgalit

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

1. Introduction

1.1. A propos de ce document

   La dernire version de ce mini-howto peut tre trouve sur :

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

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

1.2. Qu'est-ce que DocBook ?

   DocBook est une Dfinition de Type de Documents (DTD - _Document Type
   Definition_) en Langage Standard de Balisage Gnralis (SGML -
   _Standard Generalized Markup Language_), qui dfinit un ensemble de
   balises pour des documents littraux, et qui fonctionne comme le
   langage HTML utilis habituellement sur le Web.

   DocBook est destin  la rdaction de livres et d'articles. Comme tel,
   il fournit des balises (appeles encore marqueurs) penses
   spcifiquement pour dcrire des livres et des articles. Par exemple,
   les balises DocBook <book> et <article> sont utilises pour crer les
   livres et les articles. Dans ces documents, des balises <chapter>,
   <sect1>, et <para> seront utilises. Les fichiers SGML DocBook sont
   stocks 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 rgi par des feuilles de
   style (_stylesheets_) qui peuvent gnrer automatiquement une table
   des matires, la numrotation des pages, la numrotation des chapitres
   et des sections, et bien d'autres possibilits.

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

1.3. Aperu rapide

   Voici une description brve des paquetages que nous utiliserons dans
   les prochaines sections :

   _OpenJade. _OpenJade est un processeur DSSSL (_Document Style
   Semantics and Specification Language_ - Langage de spcification et
   Smantique de prsentation de document) pour documents SGML (_Standard
   Generalized Markup Language_ - Langage Standard de Balisage
   Gnralis). 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 intermdiaire
   pour obtenir des fichiers DVI, PDF et PS par des macros TeX et des
   convertisseurs DVI.

   _La DTD SGML DocBook. _Les fichiers DTD (Dfinition de Type de
   Document) sont des fichiers SGML qui dfinissent le langage DocBook.
   L'ensemble des balises valides et leurs rgles d'utilisation y sont
   dfinis. OpenJade a besoin d'accder aux fichiers DTD des documents
   qu'il doit traiter.

   _ISO8879 ENTITY SGML. _Les entits dfinissent la reprsentation des
   caractres spciaux qui n'ont pas de touche clavier associe ou qui
   ont une signification particulire 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 particulire, en l'occurrence
   DocBook, spcifient 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 cre 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 tches.

   _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 gnrer
   des pages de manuel. SGMLSpm est une bibliothque modulaire Perl5 pour
   traiter les rsultats du travail de onsgmls, un programme inclus dans
   OpenJade. SGMLSpm comprend une application appele sgmlspl permettant
   d'utiliser la bibliothque SGMLSpm. Sgmlspl ncessite des fichiers de
   spcification, disponibles sur de nombreux sites internet, pour chaque
   type de document  transformer. DocBook2X est un paquetage qui fournit
   des fichiers de spcification pour transformer des fichiers DocBook en
   pages de manuel.
     _________________________________________________________________

2. Tlcharger les paquetages

   Dans cette section, nous localiserons et tlchargerons 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. Tlchargez la
   dernire 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 installs par ce paquetage :

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

   Afin de pouvoir utiliser jadetex et pdfjadetex pour crer 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 tlcharger 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. Tlchargez la dernire 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 entits dfinissent la reprsentation de caractres spciaux ou de
   symboles qui ne peuvent tre saisis au clavier, y compris les symboles
   mathmatiques et les entits qui peuvent vous tre familires avec le
   HTML. Ces fichiers d'entits doivent tre installs 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 dcompact dans le rpertoire de la
   DTD DocBook et de rien d'autre, mais les fichiers dans isoENT-tar.gz
   restent ncessaires. Les fichiers de isoENT-tar.gz doivent donc
   galement tre dcompacts dans le rpertoire de la DTD DocBook (cf.
   Section 3 pour les dtails). Mais ces fichiers possdent un suffixe
   ".ent" qui doit tre renomm en ".gml". Vous pouvez le faire
   manuellement, ou bien vous pouvez tlcharger et utiliser le fichier
   ci-dessous, prpar 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, appels Modular DocBook Stylesheets (feuilles de
   style modulaires pour DocBook), disent  OpenJade comment convertir
   votre fichier SGML DocBook en un autre format. Un fichier dsl dcrit
   par exemple la correspondance entre une balise d'une DTD et une autre
   balise d'une autre DTD, ou d'autres conversions programmes, crites
   dans un langage appel Core Expression Language, qui est driv du
   Scheme. Le paquetage DSSSL DocBook et sa documentation peuvent tre
   tlchargs 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 considr comme le principal lieu de
     tlchargement :

     http://docbook.sourceforge.net/

   Le Projet de Documentation Linux a cr un fichier de personnalisation
   des feuilles de style qui active des options de prsentation
   intressantes. Il peut tre tlcharg 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
   gnrer tous les formats possibles avec ces outils. La dernire
   version, v1.3  l'heure o nous crivons ces lignes, peut tre
   tlcharge 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 cre une arborescence de
   signets correspondant aux sections, rendant la navigation plus facile.
   HTMLdoc et pdfjadetex crent tous deux des documents PDF, mais avec
   des rendus lgrement diffrents. Comparez les deux pour voir lequel
   produit le meilleur rsultat pour un fichier DocBook particulier.
   Reportez-vous  la Section 2.8 pour connatre les adresses de
   tlchargement.
     _________________________________________________________________

2.7. DocBook2X

   DocBook2X ncessite Perl5 et le module Perl SGMLS.pm, disponible sur
   le CPAN. SGMLS.pm fournit des bibliothques et un programme appel
   sgmlspl qui convertissent les fichiers DocBook en d'autres formats en
   utilisant des fichiers de spcification. Ces fichiers de spcification
   sont des scripts Perl qui donnent le mcanisme de traduction dans un
   format particulier.

   http://www.cpan.org/

   http://docbook2x.sourceforge.net/
     _________________________________________________________________

2.8. Liens pour tlchargement direct

   Les fichiers ci-dessous sont donns dans leur dernire version au
   moment de la rdaction de ce document :

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

   _docbk41.zip . _DocBook SGML DTD, version 4.1.

   _iso8879-entities.tar.gz . _Entits ISO 8879 SGML. Cet unique fichier
   est plus pratique  utiliser. Vous pouvez sinon tlcharger 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 compiles sont disponibles avec le code source. Choisissez en
   fonction de votre plate-forme. Les versions compiles sont
   recommandes. Pour obtenir une version compile, vous pouvez la
   tlcharger 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 prcdemment)
     _________________________________________________________________

3. Installer les paquetages

3.1. Installer OpenJade

3.1.1. OpenJade

   Voici ce qui est ncessaire de faire, mais pensez  lire les fichiers
   fournis avec OpenJade pour voir s'il n'y a pas des paramtres 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 installs, les fichiers objets etc.
# peuvent tre supprims
make clean

   A l'installation, les bibliothques sont places 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 places 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 adaptes des instructions trouves dans
   install.pdf :
     _________________________________________________________________

3.1.2.1. Crer hugelatex (si ncessaire)

   Les macros TeX jadetex et pdfjadetex ncessitent plus de mmoire
   qu'une utilisation habituelle de TeX. Souvent, la configuration par
   dfaut des limites d'utilisation mmoire de TeX n'est pas adapte. Le
   fichier de configuration de TeX, texmf.cnf, peut tre modifi et les
   valeurs des variables correspondant  la limite d'utilisation de la
   mmoire par TeX peuvent tre augmentes. Cependant, plutt que de
   simplement diter le fichier texmf.cnf pour permettre  TeX d'utiliser
   plus de mmoire en toutes circonstances, un contexte TeX spcifique
   peut tre cr, appel hugelatex. Si hugelatex est dj configur sur
   votre systme, vous pouvez sauter cette section (_which hugelatex_
   vous donne l'emplacement de la macro si elle est configure).

   Vrifiez qu'une version fonctionnelle de TeX est installe 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 rpertoire TeX principal.

   Maintenant que le rpertoire de texmf est connu, l'installation peut
   dbuter :
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 rpertoire web2c contient le fichier de configuration texmf.cnf.
   Fates une copie de sauvegarde de ce fichier : _cp texmf.cnf
   texmf.cnf.orig_. Editez le fichier en utilisant votre diteur prfr,
   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 entres pour jadetex et
   pdfjadetex, lesquels seront configurs ci-dessous. Vous pouvez jouer
   avec les paramtres mmoire prcdents comme vous le voulez si vous
   rencontrez des problmes avec ceux-ci.

   Notez que la mise en place de hugelatex n'est prise en compte qu'aprs
   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 cre et installe les fichiers .fmt
# dans /usr/share/texmf/web2c

# Cration 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 rcupre 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) placs dans /usr/share/texmf/web2c sont galement chargs
   suivant le contexte.

   Jadetex utilise un fichier tex gnr par OpenJade pour crer un DVI.
   De mme pdfjadetex utilise le fichier tex gnr par OpenJade et cre
   un PDF. Le programme dvips utilise le fichier DVI et cre un fichier
   postscript (PS).
     _________________________________________________________________

3.2. La DTD SGML DocBook

3.2.1. Dcompresser la DTD SGML DocBook

   La DTD DocBook n'est constitue que de fichiers texte SGML, aussi il
   n'y a rien  compiler. Dcompressez 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-rpertoires, comme les versions 2.4.1 et 3.0.

   Il y a des diffrences entre les diverses versions de la DTD DocBook.
   Les fichiers xxxissues.txt documentent ces questions. Des balises ont
   t ajoutes, retires ou renommes entre les versions.

   Si vous devez utiliser la DTD DocBook dans sa version 3.1, elle est
   disponible au mme endroit o la version 4.1 se tlcharge. La version
   3.1 est beaucoup utilise, aussi c'est une bonne ide de la
   tlcharger et de la placer dans un sous-rpertoire 3.1/.
     _________________________________________________________________

3.2.2. Dcompresser les entits ISO8879

   Allez dans le rpertoire de chaque version installe de la DTD
   DocBook, et dcompressez-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 rpertoire de chaque version de la DTD DocBook
   un fichier docbook.cat, ou un fichier catalog, ou bien les deux. Si
   les deux sont prsents, ils sont probablement identiques. Si seul
   docbook.cat est prsent, allez dans le rpertoire et crez un lien
   symbolique :
# Si ncessaire...
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 ncessitent que de
   les dcompresser dans un rpertoire appropri :
cd /usr/local/share/sgml
mkdir dsssl; cd dsssl
unzip -a ~/db160.zip

# Si vous avez tlcharg 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 rpertoires

   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 installs et leurs
   groupes/propritaires (qui sont souvent inappropris).
     _________________________________________________________________

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'accs  OpenJade : _vi `which sgmltools`_.
   Consultez sa documentation pour en savoir plus.
     _________________________________________________________________

3.5. htmldoc

3.5.1. binaires

   Prfrez le tlchargement de la version compile de htmldoc pour
   votre plate-forme. L'installation est on ne peut plus simple :
   dcompressez le paquetage et lancez le setup. Lisez la documentation
   fournie pour plus d'information.
     _________________________________________________________________

3.5.2. sources

   Si vous avez tlcharg les sources, vous aurez galement besoin de la
   bibliothque Fast Light Tool Kit, pour russir 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 ombres ne le sont pas toujours.

   Pour contourner ce problme, 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 bibliothque 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 rpar,
   et que ce script ne sera plus ncessaire.
     _________________________________________________________________

3.6. DocBook2X et SGMLS.pm (sgmlspl)

3.6.1. sgmlspl

   Pour que les fichiers de spcifications de DocBook2X soient utiles, le
   module SGMLS.pm pour Perl5 doit tre install, en supposant que Perl5
   est dj install. L'installation de ce module n'est pas autant
   automatise 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
# refltent votre systme.
# 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 dcompresser 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 rpertoire 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 gnrer des pages de manuel depuis un
   document DocBook <refentry>.
     _________________________________________________________________

3.7. $SGML_CATALOG_FILES

   La variable d'environnement SGML_CATALOG_FILES est utilise 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 placs dans de
   nombreux rpertoires. Au point o nous en sommes de notre
   configuration, voici comment SGML_CATALOG_FILES peut tre positionne
   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 installes 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, dconnectez-vous et revenez pour que les
   changements prennent effet.

   L'installation est termine ! 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 rfrence sur les balises DocBook,
   voyez :

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

4.1. Gnrer du HTML

4.1.1. docbook.dsl

   _Figure 2. Cration 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 rpt]
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 ignors.
   Ils peuvent tre lgrement gnants, mais ils sont normaux lorsqu'on
   utilise Jade. Les autres messages d'avertissement et d'erreur doivent
   tre surveills, et indiquent souvent des erreurs de syntaxe qui
   doivent tre corriges.

   Deux fichiers htm sont crs. Un pour chaque <SECT1>. Les noms des
   fichiers ne sont pas trs informatifs. La premire section apparat
   sur la mme page que les informations sur l'article. C'est le rsultat
   de l'utilisation de la feuille de style de base qui est donne avec
   les Modular DocBook Stylesheets, docbook.dsl.

   Les feuilles de style peuvent tre personnalises pour amliorer ces
   comportements. Si vous avez tlcharg le fichier ldp.dsl du Projet de
   Documentation Linux, et l'avez install comme indiqu  la Section
   3.3, alors vous avez dj un style personnalis disponible.
     _________________________________________________________________

4.1.2. ldp.dsl

   _Figure 3. Cration 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 rsultat est plus satisfaisant :

     * Un fichier d'index contenant les informations sur l'article a t
       cr.
     * Une table des matires a t cre 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 slectionner 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 rpertoires html et print.
   Quand nous gnrons du html, le style _html_ doit tre slectionn
   comme prcdemment. La gnration d'autres formats comme RTF ou TEX
   est du ressort de la documentation papier et aussi le style _print_
   doit tre slectionn dans ldp.dsl. Une alternative est de mettre en
   commentaire ou de supprimer le style _print_ ou _html_ suivant le cas,
   dans les rpertoires respectifs. Si un fichier dsl comporte plus d'une
   spcification de style, mais qu'aucune n'est slectionne comme
   l'exemple prcdent, alors c'est le premier style rencontr dans le
   fichier qui sera slectionn. Concernant ldp.dsl, les premires
   spcifications sont pour le style _print_, aussi il est slectionn
   par dfaut. Ainsi, en reprenant l'exemple prcdent, et en omettant le
   "_#html_" lorsqu'on spcifie ldp.dsl comme feuille de style DSSSL, les
   spcifications de style "_print_" seront slectionnes et utilises
   lors de la gnration de HTML. Ces feuilles fonctionneront, mais sont
   normalement prvues pour tre appeles par print/ldp.dsl, et le
   formatage sera diffrent.

   Pour en savoir plus sur la faon dont les fichiers de personnalisation
   des feuilles de style sont conus, lisez la documentation des Modular
   DocBook Stylesheets. La personnalisation consiste principalement au
   positionnement de paramtres boolens pour activer ou non des options
   de style. Une nouvelle logique de style peut galement tre programme
   en utilisant le langage DSSSL Core Programming Language, comme
   mentionn dans la Section 2.4.

   L'option OpenJade -t type_sortie spcifie le type sortie. L'option -d
   dsssl_spec est le chemin d'accs  la feuille de style  utiliser.
   Dans l'exemple prcdent, le type de sortie spcifi est sgml, qui est
   destin aux transformations SGML vers SGML. Le HTML, comme dfini par
   la Dfinition 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 communment utiliss sont "rtf" et
   "tex". Le type tex sera utilis plus tard comme format intermdiaire
   pour la gnration de formats PDF et PS. L'option -d dsssl_spec doit
   spcifier un fichier et non un rpertoire.
     _________________________________________________________________

4.2. Gnrer 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. Gnrer du DVI et du PS

   _Figure 4. Utiliser jadetex pour gnrer 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 premire fois que jadetex est lanc sur un fichier, des
   avertissements sont imprims. Ils peuvent tre ignors. Lancez-le une
   seconde fois sur le mme fichier et ils n'apparaissent plus.

   _Figure 5. Utiliser dvips pour gnrer 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 gnrer 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 rsultat attendu, cela est d  des
   bugs dans htmldoc. Examinez le script ldp_print si vous voulez
   l'utiliser pour faire du poscript.
     _________________________________________________________________

4.4. Gnrer du PDF

   _Figure 7. Utiliser pdfjadetex pour gnrer 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 rsoudre toutes les
   rfrences internes comme les numros de pages dans les tables des
   matires.

   _Figure 8. Utiliser htmldoc pour gnrer 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 active dans le script ldp_print, un fichier PS sera
   galement gnr.
     _________________________________________________________________

4.5. Utiliser make

   La rptition des commandes pour gnrer les diffrents formats est
   vite fastidieuse. La commande _make_ fonctionne parfaitement pour
   automatiser le processus.

   _Figure 9. Makefile - automatiser la gnration des documents_
# Gnre 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 gnrs
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


# Rgles de cration

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


# Rgles 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 rsoudre les rfrences
#$(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 gnrer 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_
# gnrer du html (par dfaut)
make
# gnrer du PDF uniquement
make pdf
# gnrer tous les formats
make all
# supprimer tous les fichiers gnrs
make clean
# crer un paquetage tgz
# sans gnration de fichiers
make dist
# crer un paquetage tgz
# comprenant tous les formats gnrs
make distall

   Notez la prsence de rgles de compilation de PDF et de PS mises en
   commentaire, qui offrent des alternatives sur les moyens de gnrer
   ces fichiers.
     _________________________________________________________________

4.6. Crer 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 ncessaires  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 contrle  l'excution. S'il s'agissait
                        d'un vritable 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>
                        spcifie 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 rsultat 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 appels <command>foo</command> peuvent exister
        et faire rellement 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. Crer 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 contrle  l'excution.
              S'il s'agissait d'un vritable 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 spcifie
              combien de fois.

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

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

MISE EN GARDE
       D'autres programmes appels foo peuvent exister et faire
       rellement 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 gnre comme une page de la Section 1. La
   commande _groff_ est utilise pour donner un aperu de son apparence
   finale.

   Pour tre installe, cette page de manuel doit tre place dans un
   rpertoire man/man1, o le rpertoire man/ est ajout  la variable
   d'environnement $MANPATH. L'emplacement standard est
   /usr/local/man/man1. Les sections standard du systme de pages de
   manuel sont numrotes de 1  9. Chacune est destine  recevoir des
   documents d'une catgorie spcifique.

   _Tableau 1. Sections des pages de manuel_
   Section                Catgorie
   man1    Programmes et commandes
   man2    Appels systme
   man3    Fonctions et routines des bibliothques
   man4    Priphriques et fichiers spciaux
   man5    Formats de fichier et conventions
   man6    Jeux
   man7    Divers
   man8    Administration systme
   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 mmes commandes prsentes
   auparavant pour gnrer 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. Lgalit

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 donne de copier, distribuer et/ou modifier ce
     document selon les termes de la Licence GNU Free Documentation
     License, Version 1.1 ou ultrieure publie par la Free Software
     Foundation ; sans section inaltrable, sans texte inaltrable de
     premire page de couverture, sans texte inaltrable de dernire
     page de couverture. Une copie de cette licence est incluse dans la
     Section A.3.
     _________________________________________________________________

A.2. Dcharge de responsabilit

   Aucune responsabilit pour le contenu de ce document ne peut tre
   accepte. Utilisez les concepts, exemples et autre contenu  vos
   propres risques.

   Tous les copyrights sont dtenus par leurs propritaires 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
   considre 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-aprs.

   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 franaises 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.
