<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN">

<article lang="fr">

  <articleinfo>

    <title>DocBook Install mini-HOWTO</title>
    
    <author>
      <firstname>Robert</firstname>
      <surname>Easter</surname>
      <othername role="mi">B</othername>
      <affiliation>
	<address>
	  <email>reaster@comptechnews.com</email>
	</address>
      </affiliation>
    </author>
    <othercredit>
      <firstname>Sylvain</firstname><surname>Amrani</surname>
      <contrib>pour la traduction française</contrib>
      <affiliation>
	<address><email><ulink url="mailto:traduc@amrani.com.fr">traduc@amrani.com.fr</ulink></email></address>
      </affiliation>
    </othercredit>

    <revhistory>
      <revision>
	<revnumber>v1.7</revnumber>
	<date>2001-03-28</date>
	<authorinitials>rbe</authorinitials>
      </revision>
    </revhistory>
    
    <abstract>
      <para>
	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.
      </para>
    </abstract>

  </articleinfo>
  
  
   <sect1 id="intro">
    <title>Introduction</title>
    
    <sect2 id="versions">
      <title>A propos de ce document</title>
      
      <para>
	La dernière version de ce mini-howto peut être trouvée sur :
      </para>

      <para>
	<ulink url="http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/"></ulink>
      </para>

      <para>
	Reportez-vous à la section <xref linkend="legal"> pour
	des informations sur les copyright, licence et décharge de
	responsabilité relatifs à ce document.
      </para>
    </sect2>

      
      <sect2>
      <title>Qu'est-ce que DocBook&nbsp;?</title>
      
      <para>
	DocBook est une Définition de Type de Documents
	(<acronym>DTD</acronym> - <emphasis>Document Type
	Definition</emphasis>) en Langage Standard de Balisage
	Généralisé (<acronym>SGML</acronym> - <emphasis>Standard Generalized
	Markup Language</emphasis>), qui définit un ensemble de balises pour des
	documents littéraux, et qui fonctionne comme le langage HTML
	utilisé habituellement sur le Web.
      </para>
	<para>
	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
	<sgmltag>&lt;book&gt;</sgmltag> et
	<sgmltag>&lt;article&gt;</sgmltag> sont utilisées pour créer
	les livres et les articles. Dans ces documents, des balises
	<sgmltag>&lt;chapter&gt;</sgmltag>,
	<sgmltag>&lt;sect1&gt;</sgmltag>, et
	<sgmltag>&lt;para&gt;</sgmltag> seront utilisées.  Les fichiers
	SGML DocBook sont stockés dans des fichiers texte avec un
	suffixe .sgml ou .gml
      </para>
      <para>
	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 (<emphasis>stylesheets</emphasis>) 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.
      </para>
      <para>
	DocBook est destiné également à l'écriture de pages de manuel
	unix, en utilisant la balise
	<sgmltag>&lt;refentry&gt;</sgmltag>.
      </para>
    </sect2>
    
    <sect2>
      <title>Aperçu rapide</title>
      <para>
	Voici une description brève des paquetages que nous
	utiliserons dans les prochaines sections :
      </para>
      
      <formalpara>
	<title>OpenJade</title>
	<para>
	  OpenJade est un processeur <acronym>DSSSL</acronym>
	  (<emphasis>Document Style Semantics and Specification
	  Language</emphasis> - Langage de spécification et Sémantique
	  de présentation de document) pour documents
	  <acronym>SGML</acronym> (<emphasis>Standard Generalized
	  Markup Language</emphasis> - 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.
	</para>
      </formalpara>
      
      <formalpara>
	<title>La DTD SGML DocBook</title>
	<para>
          Les fichiers <acronym>DTD</acronym> (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.
	</para>
      </formalpara>

      <formalpara>
	<title>ISO8879 ENTITY SGML</title>
	<para>
	  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 "&amp;eacute;" pour "é","&amp;amp;"
 	  pour "&amp;" et "&amp;gt;" pour "&gt;".
	</para>
      </formalpara>

      <formalpara>
	<title>DSSSL DocBook</title>
	<para>
	  Les fichiers <acronym>DSSSL</acronym> (<emphasis>Document
	  Style Semantics and Specification Language</emphasis>) pour
	  une DTD particulière, en l'occurrence DocBook, spécifient
	  comment convertir le document DocBook en fichiers au format
	  HTML, RTF, TEX, etc.
	</para>
      </formalpara>

      <formalpara>
	<title>SgmlTools-lite</title>
	<para>
	  <application>SgmlTools</application> est une interface pour
	  lancer OpenJade et les macros TeX
	  <application>jadetex</application> et
	  <application>pdfjadetex</application> 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
	  <application>dvips</application>.  Les scripts SgmlTools
	  fournissent une commande unique pour ces tâches.
	</para>
      </formalpara>
      
      <formalpara>
	<title>HTMLdoc</title>
	<para>
	  <application>HTMLdoc</application> est un programme libre
	  pour convertir des fichiers HTML en documents PDF ou PS.
	</para>
      </formalpara>

      <formalpara>
	<title>SGMLSpm and docbook2X</title>
	<para>
	  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
	  <filename>onsgmls</filename>, un programme inclus dans
	  OpenJade. SGMLSpm comprend une application appelée
	  <filename>sgmlspl</filename> permettant d'utiliser la
	  bibliothèque SGMLSpm. <filename>Sgmlspl</filename> nécessite
	  des fichiers de spécification, disponibles sur de nombreux
	  sites internet, pour chaque type de document à transformer.
	  <application>DocBook2X</application> est un paquetage qui
	  fournit des fichiers de spécification pour transformer des
	  fichiers DocBook en pages de manuel.
	</para>
      </formalpara>

    </sect2>
  </sect1>




  <sect1 id="download">
    <title>Télécharger les paquetages</title>
    <para>
      Dans cette section, nous localiserons et téléchargerons les
      logiciels sur Internet.
    </para>


    <sect2>
      <title>OpenJade</title>
      <para>
	OpenJade est un logiciel aux sources libres (open-source),
	activement maintenu, basé sur le paquetage Jade de <ulink
	url="http://www.jclark.com/">James Clark</ulink>. Téléchargez
	la dernière version stable (1.3&nbsp;?) sur&nbsp;:
      </para>
      <para>
	<ulink url="http://openjade.sourceforge.net/">http://openjade.sourceforge.net/</ulink>
      </para>
      <para>
	OpenJade inclut également le paquetage OpenSP et les macros
	TeX <application>jadetex</application> et
	<application>pdfjadetex</application> pour convertir les
	fichiers en DVI et en PDF. Les programmes suivants sont
	installés par ce paquetage&nbsp;:
      </para>
      <itemizedlist>
	<listitem><para><application>openjade</application></para></listitem>
	<listitem><para><application>onsgmls</application></para></listitem>
	<listitem><para><application>osgmlnorm</application></para></listitem>
	<listitem><para><application>ospam</application></para></listitem>
	<listitem><para><application>ospent</application></para></listitem>
	<listitem><para><application>osx</application></para></listitem>
      </itemizedlist>

      <para>
	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
	<application>teTeX</application> depuis :
      </para>
      <para>
	<ulink url="http://www.tug.org/tetex/"></ulink>
      </para>
    </sect2>

    <sect2>
      <title>La DTD SGML DocBook</title>
      
      <para>
	Les DTD DocBook SGML et XML sont maintenues par un comité
	technique à <ulink
	url="http://www.oasis-open.org/">Oasis-Open.ORG</ulink>.
	Téléchargez la dernière version (et les versions anciennes
	dont vous pourriez avoir besoin) de DocBook SGML sur :
      </para>

      <para>
	<ulink url="http://www.oasis-open.org/docbook/sgml/index.html"></ulink>
      </para>
    </sect2>

    <sect2>
      <title>ISO8879 ENTITY SGML</title>
      <para>
	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.
      </para>

      <itemizedlist>
	<listitem>
	<para>Ressources à <ulink url="http://www.oasis-open.org/">OASIS</ulink> :
	    <itemizedlist>
	      <listitem><para>
		  <ulink url="http://www.oasis-open.org/cover/topics.html#entities"></ulink>
		</para></listitem>
	      <listitem><para>
		  <ulink url="http://www.oasis-open.org/cover/ISOEnts.zip"></ulink>
		</para></listitem>
	      <listitem><para>
		  <ulink url="http://www.oasis-open.org/cover/isoENT-tar.gz"></ulink>
		</para></listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </itemizedlist>

      <para>
	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. <xref
	linkend="install"> 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 :
      </para>
      <para>
	<ulink url="http://www.comptechnews.com/~reaster/iso8879-entities.tar.gz"></ulink>
      </para>

    </sect2>
    
    <sect2 id="dsssl">
      <title>DSSSL DocBook</title>
      <para>
	Des fichiers DSSSL (<emphasis>Document Style Semantics and
	Specification Language</emphasis>) pour la DTD DocBook
	(SGML/XML) sont fournis par <ulink
	url="http://www.nwalsh.com/">Norman Walsh</ulink>.  Ces
	fichiers, appelés <ulink
	url="http://nwalsh.com/docbook/dsssl/">Modular DocBook
	Stylesheets</ulink> (feuilles de style modulaires pour
	DocBook), disent à <application>OpenJade</application> comment
	convertir votre fichier SGML DocBook en un autre format. Un
	fichier <filename>dsl</filename> 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é <ulink
	url="http://www.nwalsh.com/">Core Expression Language</ulink>,
	qui est dérivé du <ulink
	url="http://www.gnu.org/manual/elisp-manual-20-2.5/html_chapter/elisp_2.html#SEC5">Scheme</ulink>.
	Le paquetage DSSSL DocBook et sa documentation peuvent être
	téléchargés sur le site de Norman Walsh&nbsp;:
      </para>

      <para>
	<ulink url="http://nwalsh.com/docbook/dsssl/">http://nwalsh.com/docbook/dsssl/</ulink>
      </para>

      <blockquote>
	<para>
	  NdT : Norman Walsh a depuis ouvert un projet sur
	  SourceForge, qui doit maintenant être considéré comme le
	  principal lieu de téléchargement&nbsp;:
	</para>
	<para>
	  <ulink url="http://docbook.sourceforge.net/"></ulink>
	</para>
      </blockquote>
      <para>
	Le <ulink url="http://www.linuxdoc.org/">Projet de
	Documentation Linux</ulink> 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&nbsp;:
      </para>
      <para>
	<ulink url="http://www.linuxdoc.org/authors/tools/ldp.dsl"></ulink>
      </para>
    </sect2>

    <sect2>
      <title>Sgmltools-lite</title>
      <para>
	<application>Sgmltools</application> est une interface pour
	<application>OpenJade</application>,
	<application>jadetex</application>,
	<application>pdfjadetex</application>,
	<application>dvips</application>, 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&nbsp;:
      </para>
      <para><ulink url="http://www.sgmltools.org/"></ulink></para>
      <para><ulink url="http://sourceforge.net/projects/sgmltools-lite/"></ulink></para>
      <para>
	Ce paquetage est optionnel, mais rend parfois les choses plus faciles.
      </para>
    </sect2>

    <sect2>
      <title>HTMLdoc</title>
      <para>
	<application>HTMLdoc</application> est un programme libre pour
	convertir des sites Web en documents au format
	<acronym>PDF</acronym> (<emphasis>Portable Document
	Format</emphasis>) ou <acronym>PS</acronym>
	(<emphasis>Postscript</emphasis>).  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 <xref linkend="quick">
	pour connaître les adresses de téléchargement.
      </para>
    </sect2>

    <sect2>
      <title>DocBook2X</title>
      <para>
	DocBook2X nécessite Perl5 et le module Perl SGMLS.pm,
	disponible sur le CPAN. SGMLS.pm fournit des bibliothèques et
	un programme appelé <filename>sgmlspl</filename> 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.
      </para>
      <para><ulink url="http://www.cpan.org/"></ulink></para>
      <para><ulink url="http://docbook2x.sourceforge.net/"></ulink></para>
    </sect2>

    <sect2 id="quick">
      <title>Liens pour téléchargement direct</title>
      <para>
	Les fichiers ci-dessous sont donnés dans leur dernière version
	au moment de la rédaction de ce document&nbsp;:
      </para>
      <formalpara>
	<title>
	  <ulink url="http://download.sourceforge.net/openjade/openjade-1.3.tar.gz">openjade-1.3.tar.gz</ulink>
	</title>
	<para>
	  OpenJade, version 1.3.
	</para>
      </formalpara>

      <formalpara>
	<title>
	  <ulink url="http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip">docbk41.zip</ulink>
	</title>
	<para>
	  DocBook SGML DTD, version 4.1.
	</para>
      </formalpara>

      <formalpara>
	<title>
	  <ulink url="http://www.comptechnews.com/~reaster/iso8879-entities.tar.gz">iso8879-entities.tar.gz</ulink>
	</title>
	<para>
	  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
	  <filename>.gml</filename>.
	</para>
      </formalpara>

      <formalpara>
	<title>
	  <ulink url="http://nwalsh.com/docbook/dsssl/db160.zip">db160.zip</ulink> 
	  &amp; <ulink url="http://nwalsh.com/docbook/dsssl/db160d.zip">db160d.zip</ulink>
	</title>
	<para>
	  Feuilles de style Modulaires DSSSL DocBook, version 1.60, et leur
	  <ulink url="http://nwalsh.com/docbook/dsssl/doc/">documentation</ulink>.
	</para>
      </formalpara>

      <formalpara>
	<title>
	  <ulink url="http://download.sourceforge.net/sgmltools-lite/sgmltools-lite-3.0.2.tar.gz">sgmltools-lite-3.0.2.tar.gz</ulink>
	</title>
	<para>
	  Sgmltools-lite version 3.0.2.  Je rappelle que c'est un paquetage optionnel.
	</para>
      </formalpara>

      <formalpara>
	<title>
	  <ulink url="ftp://ftp.easysw.com/pub/htmldoc/1.8.9/">ftp://ftp.easysw.com/pub/htmldoc/1.8.9/</ulink>
	</title>
	<para>
	  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&nbsp;:
	  <ulink
	  url="http://www.easysw.com/software.html">http://www.easysw.com/software.html</ulink>
	</para>
      </formalpara>

      <formalpara>
	<title>
	  <ulink url="http://www.cpan.org/authors/id/DMEGG/SGMLSpm-1.03ii.tar.gz">http://www.cpan.org/authors/id/DMEGG/SGMLSpm-1.03ii.tar.gz</ulink>
	</title>
	<para>
	  SGMLS.pm 1.03ii sur CPAN. (sgmlspl)
	</para>
      </formalpara>

      <formalpara>
	<title>
	  <ulink url="http://download.sourceforge.net/docbook2x/docbook2X-0.6.0.tar.gz">http://download.sourceforge.net/docbook2x/docbook2X-0.6.0.tar.gz</ulink>
	</title>
	<para>
	  DocBook2X 0.6.0 (fournit <filename>docbook2man-spec.pl</filename> à utiliser avec 
	  <filename>sgmlspl</filename> vu précédemment)
	</para>
      </formalpara>
    </sect2>
  </sect1>


  <sect1 id="install">
    <title>Installer les paquetages</title>

    <sect2>
      <title>Installer OpenJade</title>

      <sect3>
	<title>OpenJade</title>
	<para>
	  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&nbsp;:

	  <screen>
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
	  </screen>

	  A l'installation, les bibliothèques sont placées dans
	  <filename>/usr/local/openjade-1.3/lib</filename>, aussi,
	  vous voudrez peut-être l'ajouter dans
	  <filename>/etc/ld.so.conf</filename> et lancer
	  <command>ldconfig</command>.  Ajoutez
	  <filename>/usr/local/openjade-1.3/bin</filename> à votre
	  <envar>$PATH</envar>.
	</para>
      </sect3>

      <sect3>
	<title>jadetex &amp; pdfjadetex</title>
	<para>
	  Comme mentionné, jadetex et pdfjadetex sont des macros TeX
	  fournies avec OpenJade. Elles sont placées dans
	  <filename>/usr/local/openjade-3.1/dsssl</filename>.
	  Un guide pratique sur l'installation de ces macros a été écrit par
	  <author>
	    <firstname>Frank</firstname>
	    <othername role="mi">Atanassow</othername>
	    <surname>Christoph</surname>
	    <affiliation>
	      <orgname>Next Solution Co., Ltd.</orgname>
	    </affiliation>
	  </author> et peut être trouvé sur&nbsp;:
	</para>
	<para>
	  <ulink url="ftp://ftp.dante.de/tex-archive/macros/jadetex/install.pdf"></ulink>
	</para>
	<para>
	  <ulink url="http://www.comptechnews.com/~reaster/installjadetex.pdf"></ulink></para>
	<para>
	  Les sections suivantes sont adaptées des instructions
	  trouvées dans <filename>install.pdf</filename>&nbsp;:
	</para>
	
	<sect4>
	  <title>Créer hugelatex (si nécessaire)</title>
	  <para>
	    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,
	    <filename>texmf.cnf</filename>, 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
	    <filename>texmf.cnf</filename> 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 (<command>which
	    hugelatex</command> vous donne l'emplacement de la macro
	    si elle est configurée).
	  </para>
	  <para>
	    Vérifiez qu'une version fonctionnelle de TeX est installée
	    et trouvez son emplacement&nbsp;:
	    <screen>
bash$ which tex
/usr/share/texmf/bin/tex
bash$ kpsewhich -expand-var='$TEXMFMAIN'
/usr/share/texmf
bash$
	    </screen>
	  </para>
	  <para>
	    L'utilisation de <filename>which</filename> devrait
	    trouver l'emplacement du programme TeX.  Si TeX n'est pas
	    trouvé, vous aurez peut-être à installer
	    <application>teTeX</application> puis à revenir ici.
	    <application>kpsewhich</application> est un utilitaire
	    fourni avec teTeX qui donne, si tout va bien, le
	    répertoire TeX principal.
	  </para>
	  <para>
	    Maintenant que le répertoire de texmf est connu, l'installation peut débuter&nbsp;:
	    <screen>
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
	    </screen>
	    Le répertoire <filename class="directory">web2c</filename>
	    contient le fichier de configuration
	    <filename>texmf.cnf</filename>. Faîtes une copie de
	    sauvegarde de ce fichier&nbsp;: <command>cp texmf.cnf
	    texmf.cnf.orig</command>. Editez le fichier en utilisant
	    votre éditeur préféré, et ajoutez les lignes suivantes à
	    la fin&nbsp;:
	    <screen>
% 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
	    </screen>
	    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.
	  </para>
	  <para>
	    Notez que la mise en place de hugelatex n'est prise en
	    compte qu'après avoir lancé le programme
	    <application>texhash</application>
	    <screen>
root# texhash
texhash: Updating /usr/share/texmf/ls-R...
texhash: Updating /var/cache/fonts/ls-R...
texhash: Done.
root#
	    </screen>
	  </para>
	</sect4>

	<sect4>
	  <title>jadetex &amp; pdfjadetex</title>
	<para>
	    La configuration de jadetex et de pdfjadetex est similaire à celle de hugelatex.
	    <screen>
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
	    </screen>
	    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
	    <varname>argv[0]</varname>. Ensuite, il parcourt
	    <filename>texmf.cnf</filename> et utilise les
	    configurations contextuelles qu'il y trouve. Les fichiers
	    de format (.fmt) placés dans <filename
	    class="directory">/usr/share/texmf/web2c</filename> sont
	    également chargés suivant le contexte.
	  </para>
	  <para>
	    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
	    <application>dvips</application> utilise le fichier DVI et
	    crée un fichier postscript (PS).
	  </para>
	</sect4>
      </sect3>
    </sect2>

    <sect2>
      <title>La DTD SGML DocBook</title>
      <sect3>
	<title>Décompresser la DTD SGML  DocBook</title>
	<para>
	  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.
	  <screen>
# 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
	  </screen>
	  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.
	</para>
	<para>
	  Il y a des différences entre les diverses versions de la DTD
	  DocBook. Les fichiers <filename>xxxissues.txt</filename>
	  documentent ces questions. Des balises ont été ajoutées,
	  retirées ou renommées entre les versions.
	</para>
	<para>
	  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/.
	</para>
      </sect3>

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

    <sect2 id="dsssldb">
      <title>Les DSSSL DocBook</title>
      <para>
	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é&nbsp;:
	<screen>
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
	</screen>
	C'est tout ce qu'il y a à faire pour installer les feuilles de
	style DSSSL, hormis la configuration de la variable
	d'environnement <envar>SGML_CATALOG_PATH</envar> 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).
      </para>
    </sect2>

    <sect2>
      <title>sgmltools-lite</title>
      <para>
	Si vous le voulez, vous pouvez installer
	<application>sgmltools-lite</application>, bien que ce soit
	optionnel. Son installation est standard&nbsp;:
	<screen>
cd /usr/src
tar -xvzf ~/sgmltools-lite-3.0.2.tar.gz
cd sgmltools-lite-3.0.2
./configure
make install
	</screen>
	Ceci installe le script python dans <filename
	class="directory">/usr/local/bin</filename>.  Notez que
	sgmltools-lite utilise python, et est donc inutile si vous
	n'avez pas ce paquetage.
      </para>
      <para>
	Pour que le script sgmltools fonctionne il vous faudra
	l'éditer pour corriger le chemin d'accès à OpenJade :
	<command>vi `which sgmltools`</command>. Consultez sa
	documentation pour en savoir plus.
      </para>
    </sect2>

    <sect2>
      <title>htmldoc</title>

      <sect3>
	<title>binaires</title>
	<para>
	  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&nbsp;: décompressez le paquetage et lancez le
	  <filename moreinfo="none">setup</filename>.  Lisez la
	  documentation fournie pour plus d'information.
	</para>
      </sect3>

      <sect3>
	<title>sources</title>
	<para>
	  Si vous avez téléchargé les sources, vous aurez également besoin
	  de la bibliothèque <application moreinfo="none">Fast Light Tool Kit</application>,
	  pour réussir l'édition de liens.
	</para>
	<para>
	  <ulink url="http://www.fltk.org/">http://www.fltk.org/</ulink>
	</para>

	<para>
	  L'installation est de la famille
	  <application>autoconf</application>.  Lancez simplement le
	  script <command>./configure</command>, puis
	  <command>make</command> et <command>make
	  install</command>. Si tout va bien, le programme sera
	  installé dans <filename
	  class="directory">/usr/bin</filename>.
	</para>
      </sect3>

      <sect3>
	<title>ldp_print</title>
	<para>
	  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.
	</para>
	<para>
	  Pour contourner ce problème, un script perl (<ulink
	  url="http://www.linuxdoc.org/authors/tools/ldp_print.tar.gz">ldp_print</ulink>)
	  est disponible sur <ulink
	  url="http://www.linuxdoc.org/">LinuxDoc.org</ulink>.  Le
	  script traite un fichier HTML unique créé par OpenJade et
	  lance htmldoc dessus, pour produire des fichiers aux formats
	  PDF et PS corrects.  
	  <tip>
	    <title>Conseil</title>
	    <para>Adoptez-le&nbsp;!</para>
	  </tip>
	</para>
	<para>
	  <screen>
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
	  </screen>
	  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.
	</para>
      </sect3>

    </sect2>

    <sect2>
      <title>DocBook2X et SGMLS.pm (sgmlspl)</title>
      <sect3>
	<title>sgmlspl</title>
	<para>
	  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 <filename>Makefile</filename> qui doit être édité
	  avant de lancer <command>make</command>.
	  <screen>
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
	  </screen>
	  sgmlspl sera copié dans <filename
	  class="directory">/usr/local/bin</filename>.
	</para>
      </sect3>

      <sect3>
	<title>docbook2X (docbook2man-spec.pl)</title>
	<para>
	  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&nbsp;:
	  <screen>
cd /usr/local/share/sgml
tar -xvzf ~/docbook2X-0.6.0.tar.gz
cd docbook2X
	  </screen>
	  <filename>docbook2man-spec.pl</filename> 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é.
	  <screen>
patch docbook2man-spec.pl docbook2man-spec.pl.patch
	  </screen>
	  Vous verrez par la suite dans la <xref linkend="using">
	  comment utiliser sgmlspl et docbook2man-spec.pl pour générer
	  des pages de manuel depuis un document DocBook
	  <sgmltag>&lt;refentry&gt;</sgmltag>.
	</para>
      </sect3>

    </sect2>


    <sect2>
      <title>$SGML_CATALOG_FILES</title>
      <para>
	La variable d'environnement <envar>SGML_CATALOG_FILES</envar>
	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 <envar>SGML_CATALOG_FILES</envar> peut être
	positionnée dans <filename>/etc/profile</filename>&nbsp;:
	<screen>
######################################################################################
# SGML DocBook - openjade sgmltools-lite
JADE_HOME=/usr/local/openjade-1.3
SGML_SHARE=/usr/local/share/sgml

PATH=$PATH:$JADE_HOME/bin

# feuilles de style DSSSL
#       Modular DocBook Stylesheets de Norman Walsh
SGML_CATALOG_FILES=$SGML_SHARE/dsssl/docbook/catalog
#       Feuilles de style OpenJade
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$JADE_HOME/dsssl/catalog
#       Feuilles de style sgmltools-lite
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/stylesheets/sgmltools/sgmltools.cat

# DTD DocBook
#       D'OASIS-Open.org
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/3.1/catalog
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/4.1/catalog
#       Ces anciennes versions ont été installées par
#       doctools-1.2 d'XFree86.org
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/2.4.1/catalog
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/3.0/catalog

# Catalogues sgmltools-lite pour LinuxDoc
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/dtd/sgmltools/catalog

export JADE_HOME SGML_SHARE PATH SGML_CATALOG_FILES
######################################################################################
	</screen>
	Sauvegardez votre profil, déconnectez-vous et revenez pour que les 
	changements prennent effet.
      </para>
      <para>
	L'installation est terminée&nbsp;! Dans la section suivante,
	nous testerons notre configuration et convertirons quelques
	fichiers DocBook.
      </para>
    </sect2>

  </sect1>

  <sect1 id="using">
    <title>Utiliser DocBook</title>
    <para>
      Maintenant que tout est installé, il est temps de tester notre
      configuration, et de voir comment utiliser OpenJade et les autres
      outils.
    </para>

    <para>
      <figure>
	<title>Exemple de fichier SGML DocBook - test.sgml</title>
	<screen>
&lt;!DOCTYPE article PUBLIC &quot;-//OASIS//DTD DocBook V4.1//EN&quot;&gt;

&lt;article lang=&quot;fr&quot;&gt;
&lt;articleinfo&gt;
	&lt;title&gt;Ceci est un test&lt;/title&gt;

	&lt;author&gt;
		&lt;firstname&gt;John&lt;/firstname&gt;
		&lt;surname&gt;Doe&lt;/surname&gt;
		&lt;othername role=&quot;mi&quot;&gt;L&lt;/othername&gt;
		&lt;affiliation&gt;
			&lt;address&gt;
			&lt;email&gt;j.doe@jdoe dot com&lt;/email&gt;
			&lt;/address&gt;
		&lt;/affiliation&gt;
	&lt;/author&gt;

	&lt;revhistory&gt;
		&lt;revision&gt;
		&lt;revnumber&gt;v1.0&lt;/revnumber&gt;
		&lt;date&gt;2000-12-30&lt;/date&gt;
		&lt;authorinitials&gt;jld&lt;/authorinitials&gt;
		&lt;/revision&gt;
	&lt;/revhistory&gt;

	&lt;abstract&gt;
	&lt;para&gt;
        Ceci est un document DocBook de test.
	&lt;/para&gt;
	&lt;/abstract&gt;

&lt;/articleinfo&gt;

&lt;sect1 id=&quot;test1&quot;&gt;
&lt;title&gt;Test 1&lt;/title&gt;
&lt;para&gt;
Test section 1.
&lt;/para&gt;
	&lt;sect2&gt;
	&lt;title&gt;Test 1.1&lt;/title&gt;
	&lt;para&gt;
	Test section 1.1
	&lt;/para&gt;
	&lt;/sect2&gt;

	&lt;sect2&gt;
	&lt;title&gt;Test 1.2&lt;/title&gt;
	&lt;para&gt;
	&lt;screen&gt;
		-- Test section 1.2
		openjade -t sgml -d $DSLFILE test.sgml
	&lt;/screen&gt;
	&lt;/para&gt;
	&lt;/sect2&gt;

&lt;/sect1&gt;

&lt;sect1 id=&quot;test2&quot;&gt;
&lt;title&gt;Test 2&lt;/title&gt;
&lt;para&gt;
Test section 2.
&lt;/para&gt;

	&lt;sect2&gt;
	&lt;title&gt;Test 2.1&lt;/title&gt;
	&lt;para&gt;
	Test section 2.1
	&lt;/para&gt;
	&lt;/sect2&gt;

	&lt;sect2&gt;
	&lt;title&gt;Test 2.2&lt;/title&gt;
	&lt;para&gt;
	Test section 2.2
	&lt;/para&gt;
	&lt;/sect2&gt;

&lt;/sect1&gt;
&lt;/article&gt;
	</screen>
      </figure>
      Pour un guide sur DocBook et une référence sur les balises
      DocBook, voyez&nbsp;:
    </para>

    <formalpara>
      <title>DocBook: The Definitive Guide</title>
      <para>
	<ulink url="http://www.docbook.org/tdg/html/docbook.html">http://www.docbook.org/tdg/html/docbook.html</ulink>
      </para>
    </formalpara>

	<sect2>
	<title>Générer du HTML</title>
	<sect3>
	<title>docbook.dsl</title>
	<para>
	  <figure>
	    <title>Création de documents HTML avec docbook.dsl</title>
	    <screen>
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$
	    </screen>
	  </figure>
	  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.
	</para>

	<para>
	  Deux fichiers htm sont créés. Un pour chaque
	  &lt;SECT1&gt;. 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,
	  <filename>docbook.dsl</filename>.
	</para>

	<para>
	  Les feuilles de style peuvent être personnalisées pour
	  améliorer ces comportements. Si vous avez téléchargé le
	  fichier <filename>ldp.dsl</filename> du <ulink
	  url="http://www.linuxdoc.org/">Projet de Documentation
	  Linux</ulink>, et l'avez installé comme indiqué à la <xref
	  linkend="dsssldb">, alors vous avez déjà un style
	  personnalisé disponible.
	</para>
      </sect3>

      <sect3>
	<title>ldp.dsl</title>
	<para>
	  <figure>
	    <title>Création de documents HTML avec ldp.dsl</title>
	<screen>
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$
	    </screen>
	  </figure>
	</para>
	<para>
	  En utilisant <filename>ldp.dsl</filename>, le résultat est
	  plus satisfaisant&nbsp;:
	  <itemizedlist>
	    <listitem>
	      <para>
		Un fichier d'index contenant les informations sur
		l'article a été créé.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		Une table des matières a été créée automatiquement.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		A chaque <sgmltag>&lt;SECT1&gt;</sgmltag> correspond
		son propre fichier.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		Les noms de fichier correspondent à l'attribut ID des
		balises <sgmltag>&lt;SECT1&gt;</sgmltag>
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		Les suffixes des noms de fichier sont maintenant
		.html.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		Le contenu des balises
		<sgmltag>&lt;SCREEN&gt;</sgmltag> est grisé.
	      </para>
	    </listitem>
	  </itemizedlist>
	</para>
	
	<para>
	  Remarquez comment le fichier ldp.dsl a été saisi sur la
	  ligne de commande&nbsp;: "<command>#html</command>" lui a
	  été accolé. <filename>ldp.dsl</filename> contient deux balises
	  <sgmltag>&lt;STYLE-SPECIFICATION&gt;</sgmltag>, 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 <xref
	  linkend="dsssldb">, nous avons copié
	  <filename>ldp.dsl</filename> dans les deux répertoires html
	  et print. Quand nous générons du html, le style
	  <emphasis>html</emphasis> 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
	  <emphasis>print</emphasis> doit être sélectionné dans
	  ldp.dsl. Une alternative est de mettre en commentaire ou de
	  supprimer le style <emphasis>print</emphasis> ou
	  <emphasis>html</emphasis> 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
	  <emphasis>print</emphasis>, aussi il est sélectionné par
	  défaut. Ainsi, en reprenant l'exemple précédent, et en
	  omettant le "<command>#html</command>" lorsqu'on spécifie
	  ldp.dsl comme feuille de style DSSSL, les spécifications de
	  style "<emphasis>print</emphasis>" 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 <filename>print/ldp.dsl</filename>, et le
	  formatage sera différent.
	</para>
	
	<para>
	  Pour en savoir plus sur la façon dont les fichiers de
	  personnalisation des feuilles de style sont conçus, lisez la
	  <ulink
	  url="http://nwalsh.com/docbook/dsssl/doc/">documentation des
	  Modular DocBook Stylesheets</ulink>.  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 <ulink
	  url="http://www.mulberrytech.com/dsssl/dsssldoc/tutorials/core-exp/core-exp.html">Core
	  Programming Language</ulink>, comme mentionné dans la <xref
	  linkend="dsssl">.
	</para>

	<para>
	  L'option OpenJade <option>-t type_sortie</option> spécifie
	  le type sortie. L'option <option>-d dsssl_spec</option> est
	  le chemin d'accès à la feuille de style à utiliser. Dans
	  l'exemple précédent, le type de sortie spécifié est
	  <option>sgml</option>, qui est destiné aux transformations
	  SGML vers SGML. Le HTML, comme défini par la <ulink
	  url="http://www.w3.org/TR/html4/sgml/dtd.html">Définition de
	  Type de Document (DTD) HTML</ulink>, est un type de document
	  SGML, tout comme DocBook, aussi, <option>sgml</option> 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 <option>-d
	  dsssl_spec</option> doit spécifier un fichier et non un
	  répertoire.
	</para>
      </sect3>
    </sect2>

    <sect2>
      <title>Générer du RTF et du TEX</title>
      <para>
	<screen>
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.sgml
bash$ openjade -t tex -d $SGML_SHARE/dsssl/docbook/print/ldp.dsl#print test.sgml
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
	</screen>
      </para>
    </sect2>

    <sect2>
      <title>Générer du DVI et du PS</title>
      <para>
	<figure>
	  <title>Utiliser jadetex pour générer un fichier DVI (DeVice
	    Independant)</title>
	  <screen>
-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$
	  </screen>
	</figure>
      </para>
      <para>
	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.
      </para>
      <para>
	<figure>
	  <title>Utiliser dvips pour générer un fichier Postscript (PS)</title>
	  <screen>
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' -&gt; test.ps
&lt;texc.pro&gt;&lt;8r.enc&gt;&lt;texps.pro&gt;&lt;special.pro&gt;&lt;color.pro&gt;. [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$
	  </screen>
	</figure>
      </para>

      <para>
	<figure>
	  <title>Utiliser htmldoc pour générer un fichier Postscript (PS)</title>
	  <screen>
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-htmldoc.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$
	  </screen>
	</figure>
	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.
      </para>
    </sect2>

    <sect2>
      <title>Générer du PDF</title>
      <para>
	<figure>
	  <title>Utiliser pdfjadetex pour générer un fichier PDF
	  (<emphasis>Portable Document Format</emphasis>)</title>
	  <screen>
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) )&lt;8r.enc&gt;
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é]
	  </screen>
	</figure>
	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.
      </para>

      <para>
	<figure>
	  <title>Utiliser htmldoc pour générer un fichier PDF
	    (<emphasis>Portable Document Format</emphasis>)</title>
	  <screen>
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$
	  </screen>
	</figure>
	Si l'option est activée dans le script
	<filename>ldp_print</filename>, un fichier PS sera également
	généré.
      </para>
    </sect2>

    <sect2>
      <title>Utiliser make</title>

      <para>
	La répétition des commandes pour générer les différents
	formats est vite fastidieuse. La commande
	<command>make</command> fonctionne parfaitement pour
	automatiser le processus.
      </para>

      <para>
	<figure>
	  <title>Makefile - automatiser la génération des documents</title>
	  
	  <programlisting>
# 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) -
	  </programlisting>

	</figure>
      </para>
      <para>
	On l'utilise comme pour la plupart des projets&nbsp;:
	<figure>
	  <title>Appeler make pour lancer le Makefile</title>
	  <screen>
# 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
	  </screen>
	</figure>
      </para>
      <para>
	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.
      </para>
    </sect2>

    <sect2>
      <title>Créer une page de manuel</title>
      <para>
	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.
      </para>
      <para>
	Un exemple de document DocBook RefEntry pour la commande
	<filename>foo</filename> est donné ci-dessous&nbsp;:
      </para>
      <para>
	<figure>
	  <title>page de manuel foo - source DocBook RefEntry (foo-ref.sgml)</title>
	  <screen>
&lt;!DOCTYPE refentry PUBLIC &quot;-//OASIS//DTD DocBook V4.1//EN&quot;&gt;
&lt;refentry&gt;
&lt;refentryinfo&gt;
	&lt;date&gt;2001-01-01&lt;/date&gt;
&lt;/refentryinfo&gt;
&lt;refmeta&gt;
	&lt;refentrytitle&gt;
		&lt;application&gt;foo&lt;/application&gt;
	&lt;/refentrytitle&gt;
	&lt;manvolnum&gt;1&lt;/manvolnum&gt;
	&lt;refmiscinfo&gt;foo 1.0&lt;/refmiscinfo&gt;
&lt;/refmeta&gt;
&lt;refnamediv&gt;
	&lt;refname&gt;
		&lt;application&gt;foo&lt;/application&gt;
	&lt;/refname&gt;
	&lt;refpurpose&gt;
	Ne fait rien d'utile. 
	&lt;/refpurpose&gt;
&lt;/refnamediv&gt;
&lt;refsynopsisdiv&gt;
	&lt;refsynopsisdivinfo&gt;
		&lt;date&gt;2001-01-01&lt;/date&gt;
	&lt;/refsynopsisdivinfo&gt;
	&lt;cmdsynopsis&gt;
	&lt;command&gt;foo&lt;/command&gt;
&lt;arg&gt;&lt;option&gt;-f &lt;/option&gt;&lt;replaceable class=&quot;parameter&quot;&gt;bar&lt;/replaceable&gt;&lt;/arg&gt;
&lt;arg&gt;&lt;option&gt;-d&lt;replaceable class=&quot;parameter&quot;&gt;n&lt;/replaceable&gt;&lt;/option&gt;&lt;/arg&gt;
&lt;arg rep=&quot;repeat&quot;&gt;&lt;replaceable class=&quot;parameter&quot;&gt;fichier&lt;/replaceable&gt;&lt;/arg&gt;
	&lt;/cmdsynopsis&gt;
&lt;/refsynopsisdiv&gt;
&lt;refsect1&gt;
	&lt;refsect1info&gt;
		&lt;date&gt;2001-01-01&lt;/date&gt;
	&lt;/refsect1info&gt;
	&lt;title&gt;DESCRIPTION&lt;/title&gt;
	&lt;para&gt;
	&lt;command&gt;foo&lt;/command&gt; ne fait rien d'utile.
	&lt;/para&gt;
&lt;/refsect1&gt;
&lt;refsect1&gt;
	&lt;title&gt;OPTIONS&lt;/title&gt;
	&lt;variablelist&gt;
	&lt;varlistentry&gt;
		&lt;term&gt;-f &lt;replaceable class=&quot;parameter&quot;&gt;bar&lt;/replaceable&gt;&lt;/term&gt;
		&lt;listitem&gt;
			&lt;para&gt;
			Prend &lt;filename&gt;bar&lt;/filename&gt; 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é.
			&lt;/para&gt;
		&lt;/listitem&gt;
	&lt;/varlistentry&gt;
	&lt;varlistentry&gt;
		&lt;term&gt;-d&lt;replaceable class=&quot;parameter&quot;&gt;n&lt;/replaceable&gt;&lt;/term&gt;
		&lt;listitem&gt;
			&lt;para&gt;
			Fait quelque chose, où le nombre entier
			&lt;replaceable class=&quot;parameter&quot;&gt;n&lt;/replaceable&gt;
			spécifie combien de fois.
			&lt;/para&gt;
		&lt;/listitem&gt;
	&lt;/varlistentry&gt;
	&lt;varlistentry&gt;
		&lt;term&gt;&lt;replaceable class=&quot;parameter&quot;&gt;fichier...&lt;/replaceable&gt;&lt;/term&gt;
		&lt;listitem&gt;
			&lt;para&gt;
			Traite les fichiers dans l'ordre de leur apparition
			et envoie le résultat sur stdout.
			&lt;/para&gt;
		&lt;/listitem&gt;
	&lt;/varlistentry&gt;
	&lt;/variablelist&gt;
&lt;/refsect1&gt;
&lt;refsect1&gt;
	&lt;title&gt;UTILISATION&lt;/title&gt;
	&lt;para&gt;
	&lt;command&gt;foo&lt;/command&gt; -f foo.conf -d2 foodata.foo
	&lt;/para&gt;
&lt;/refsect1&gt;
&lt;refsect1&gt;
	&lt;title&gt;MISE EN GARDE&lt;/title&gt;
	&lt;para&gt;
	D'autres programmes appelés &lt;command&gt;foo&lt;/command&gt; peuvent exister
	et faire réellement quelque chose !
	&lt;/para&gt;
&lt;/refsect1&gt;
&lt;refsect1&gt;
	&lt;title&gt;BUGS&lt;/title&gt;
	&lt;para&gt;
	Aucun. Le programme ne fait rien.
	&lt;/para&gt;
&lt;/refsect1&gt;
&lt;refsect1&gt;
	&lt;title&gt;AUTEUR&lt;/title&gt;
	&lt;para&gt;
	&lt;author&gt;
		&lt;firstname&gt;Foo&lt;/firstname&gt;
		&lt;othername role=&quot;mi&quot;&gt;E&lt;/othername&gt;
		&lt;surname&gt;Bar&lt;/surname&gt;
		&lt;contrib&gt;Auteur original&lt;/contrib&gt;
	&lt;/author&gt;
	&lt;/para&gt;
&lt;/refsect1&gt;
&lt;/refentry&gt;
	  </screen>
	</figure>
      </para>

      <para>
	<figure>
	  <title>Créer une page de manuel avec onsgmls, sgmlspl et
	  docbook2man-spec.pl</title>
	  <screen>
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
	  </screen>
	</figure>
      </para>

      <para>
	La page de manuel <filename>foo.1</filename> est générée comme une page
	de la Section 1. La commande <command>groff</command> est utilisée pour
	donner un aperçu de son apparence finale.
      </para>
      <para>
	Pour être installée, cette page de manuel doit être placée dans
	un répertoire <filename class="directory">man/man1</filename>, où le répertoire
	<filename class="directory">man/</filename> est ajouté à la variable
	d'environnement <envar>$MANPATH</envar>. L'emplacement standard est
	<filename>/usr/local/man/man1</filename>.
	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.
      </para>

      <table>
	<title>Sections des pages de manuel</title>
	<tgroup cols="2" align="center">
	  <thead>
	    <row>
	      <entry>Section</entry>
	      <entry>Catégorie</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry>man1</entry>
	      <entry>Programmes et commandes</entry>
	    </row>
	    <row>
	      <entry>man2</entry>
	      <entry>Appels système</entry>
	    </row>
	    <row>
	      <entry>man3</entry>
	      <entry>Fonctions et routines des bibliothèques</entry>
	    </row>
	    <row>
	      <entry>man4</entry>
	      <entry>Périphériques et fichiers spéciaux</entry>
	    </row>
	    <row>
	      <entry>man5</entry>
	      <entry>Formats de fichier et conventions</entry>
	    </row>
	    <row>
	      <entry>man6</entry>
	      <entry>Jeux</entry>
	    </row>
	    <row>
	      <entry>man7</entry>
	      <entry>Divers</entry>
	    </row>
	    <row>
	      <entry>man8</entry>
	      <entry>Administration système</entry>
	    </row>
	    <row>
	      <entry>man9</entry>
	      <entry>Variables et fonctions internes du noyau</entry>
	    </row>
	  </tbody>
	</tgroup>
	</table>
      
      <tip>
	<title>Astuce</title>
	<para>
	  Le fichier source d'une page de manuel, comme
	  <filename>foo-ref.sgml</filename>, 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&nbsp;!
	</para>
      </tip>

      <para>
	Et maintenant, amusez-vous&nbsp;!
      </para>
    </sect2>
  </sect1>

  <appendix id="legal">
    <title>Légalité</title>
    <section id="copyright">
      <title>Copyright et Licences</title>

      <blockquote>
	<para>
	  Copyright (c)  2001  Robert B. Easter
	</para>
	<para>
	  <emphasis>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".</emphasis>
	</para>
	<para>
	  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&nbsp;; 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 <xref linkend="licence">.
	</para>
      </blockquote>
    </section>
    
    <section id="disclaimer">
      <title>Décharge de responsabilité</title>

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

      <para>
	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.
      </para>

      <para>
	La mention d'un produit particulier ou d'une marque ne doit
	pas être considérée comme un acte d'approbation.
      </para>
    </section>

    <section id="licence">
      <title>La licence GNU Free Documentation License</title>
      <warning>
	<title>Avertissement</title> 
	<para>
	  NdT - Pour des raisons de droit, la seule licence applicable
	  concernant ce document est la licence <emphasis>GNU Free
	  Documentation License</emphasis>, dans sa version originale
	  en langue anglaise, retranscrite ci-après.
	</para>
	<para>
	  Le lecteur francophone pourra, à titre d'information, se
	  reporter sur le site de la <ulink
	  url="http://www.gnu.org/copyleft/">copyleft</ulink> de la
	  <ulink url="http://www.gnu.org/fsf/fsf.html">
	  Free Software Foundation</ulink>, et en particulier sur la page
	  <ulink url="http://www.gnu.org/copyleft/copyleft.html#translationsGFDL"></ulink>
	  pour trouver des liens sur plusieurs traductions françaises
	  de cette licence, tout en sachant que seule la version
	  originale fait foi.
	</para>
      </warning>
      <para></para>
  <section id="gfdl">
    <title>GNU Free Documentation License</title>
<!-- - GNU Project - Free Software Foundation (FSF) -->
<!-- LINK REV="made" HREF="mailto:webmasters@gnu.org" -->


  <!-- sect1>
    <title>GNU Free Documentation License</title -->

    <para>Version 1.1, March 2000</para>

    <blockquote>
      <para>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.</para>
    </blockquote>

  <section label="0">
    <title>PREAMBLE</title>

    <para>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.</para>

    <para>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.</para>

    <para>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.</para>
  </section>

  <section label="1">
    <title>APPLICABILITY AND DEFINITIONS</title>

    <para>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".</para>

    <para>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.</para>

    <para>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.</para>

    <para>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.</para>

    <para>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.</para>

    <para>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".</para>

    <para>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.</para>

    <para>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.</para>
  </section>

  <section label="2">
    <title>VERBATIM COPYING</title>

    <para>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.</para>

    <para>You may also lend copies, under the same conditions stated
    above, and you may publicly display copies.</para>
  </section>

  <section label="3">
    <title>COPYING IN QUANTITY</title>

    <para>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.</para>

    <para>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.</para>

    <para>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.</para>

    <para>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.</para>
  </section>

  <section label="4">
    <title>MODIFICATIONS</title>

    <para>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:</para>

    <orderedlist numeration="upperalpha">
      <listitem><para>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.</para>
      </listitem>

      <listitem><para>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).</para>
      </listitem>

      <listitem><para>State on the Title page
      the name of the publisher of the Modified Version, as the
      publisher.</para>
      </listitem>

      <listitem><para>Preserve all the
      copyright notices of the Document.</para>
      </listitem>

      <listitem><para>Add an appropriate
      copyright notice for your modifications adjacent to the other
      copyright notices.</para>
      </listitem>

      <listitem><para>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.</para>
      </listitem>

      <listitem><para>Preserve in that license
      notice the full lists of Invariant Sections and required Cover
      Texts given in the Document's license notice.</para>
      </listitem>

      <listitem><para>Include an unaltered
      copy of this License.</para>
      </listitem>

      <listitem><para>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.</para>
      </listitem>

      <listitem><para>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.</para>
      </listitem>

      <listitem><para>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.</para>
      </listitem>

      <listitem><para>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.</para>
      </listitem>

      <listitem><para>Delete any section
      entitled "Endorsements".  Such a section may not be included in
      the Modified Version.</para>
      </listitem>

      <listitem><para>Do not retitle any
      existing section as "Endorsements" or to conflict in title with
      any Invariant Section.</para>
      </listitem>
    </orderedlist>

    <para>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.</para>

    <para>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.</para>

    <para>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.</para>

    <para>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.</para>
  </section>

  <section label="5">
    <title>COMBINING DOCUMENTS</title>

    <para>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.</para>

    <para>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.</para>

    <para>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."</para>
  </section>

  <section label="6">
    <title>COLLECTIONS OF DOCUMENTS</title>

    <para>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.</para>

    <para>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.</para>
  </section>

  <section label="7">
    <title>AGGREGATION WITH INDEPENDENT WORKS</title>

    <para>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.</para>

    <para>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.</para>
  </section>

  <section label="8">
    <title>TRANSLATION</title>

    <para>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.</para>
  </section>

  <section label="9">
    <title>TERMINATION</title>

    <para>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.</para>
  </section>

  <section label="10">
    <title>FUTURE REVISIONS OF THIS LICENSE</title>

    <para>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 <ulink
    url="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</ulink>.</para>

    <para>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.</para>
  </section>

  <section label="">
    <title>How to use this License for your documents</title>

    <para>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:</para>

<blockquote><para>
      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".
</para></blockquote>

    <para>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.</para>

    <para>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.</para>
	</section>
      </section>
    </section>
  </appendix>
</article>
