root/traduc/branches/bv747/manuel/docguide.sgml

<!-- $Header: /var/lib/cvs/pgsql-fr/sgml/docguide.sgml,v 1.6.2.1 2005/07/15 06:33:37 guillaume Exp $ -->

<appendix id="docguide">
 <title>Documentation</title>

 <para>
  <productname>PostgreSQL</productname> fournit quatre formats de documentation
  de base&nbsp;:

  <itemizedlist>
   <listitem>
    <para>
     Texte brut, pour les information de pré-installation&nbsp;;
    </para>
   </listitem>
   <listitem>
    <para>
     <acronym>HTML</acronym>, pour la lecture en ligne et les références&nbsp;;
    </para>
   </listitem>
   <listitem>
    <para>
     PDF ou Postscript, pour l'impression&nbsp;;
    </para>
   </listitem>
   <listitem>
    <para>
     les pages man (de manuel), pour la référence rapide.
    </para>
   </listitem>
  </itemizedlist>

  De plus, un certain nombre de fichiers <filename>README</filename> pourront
  être trouvés à divers endroits de l'arbre des sources de
  <productname>PostgreSQL</productname>. Ils renseigneront
  l'utilisateur sur différents points d'implémentation.
 </para>

 <para>
  La documentation <acronym>HTML</acronym> et les pages de manuel
  font parties de la distribution standard et sont installées par
  défaut. Les documents au format PDF et Postscript sont disponibles
  indépendemment par le biais du téléchargement.
 </para>

 <sect1 id="docguide-docbook">
  <title>DocBook</title>
  <para>
   Les sources de la documentation sont écrites en
   <firstterm>DocBook</firstterm>, qui est un langage semblable au
   <acronym>HTML</acronym> au premier abord. Ces deux langages sont
   des applications de <firstterm>Standard Generalized Markup
   Language</firstterm>, <acronym>SGML</acronym>, qui est
   essentiellement un langage décrivant d'autres langages. Dans ce
   qui suivra, les termes DocBook et SGML seront utilisés, ils ne
   sont cependant pas techniquement interchangeables.
  </para>

  <para>
  <productname>DocBook</productname> permet à l'auteur de spécifier
  la structure et le contenu d'un document technique sans qu'il ait
  besoin de se soucier du détail de la présentation. Un style de
  document définit la manière dont le contenu sera rendu dans un des
  formats de sortie finaux. DocBook est maintenu par le groupe
  <ulink url="http://www.oasis-open.org">OASIS</ulink> . Le <ulink
  url="http://www.oasis-open.org/docbook">site officiel de
  DocBook</ulink> présente une bonne documentation d'introduction et
  de référence ainsi qu'un livre complet de chez O'Reilly disponible en ligne
  pour votre plaisir. Le <ulink
  url="http://www.freebsd.org/docproj/docproj.html">projet de
  documentation FreeBSD</ulink> utilise également DocBook et fournit
  également de bonnes informations, incluant un certain nombre de
  lignes directrices qu'il peut être bon de prendre en
  considération.
  </para>
 </sect1>


 <sect1 id="docguide-toolsets">
  <title>Ensemble d'outils</title>

  <para>
  Les outils suivants sont utilisés pour générer la documentation.
  Certains sont optionnels (comme mentionné).

   <variablelist>
    <varlistentry>
     <term><ulink url="http://www.oasis-open.org/docbook/sgml/">DTD DocBook</ulink></term>
     <listitem>
      <para>
      Il s'agit de la définition de DocBook elle-même. Nous
      utilisons actuellement la version 3.1. Vous ne pouvez pas
      utiliser des versions plus récentes ou plus anciennes. Notez
      qu'il existe également une version <acronym>XML</acronym> de
      DocBook -- ne l'utilisez pas&nbsp;!
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><ulink
     url="http://www.oasis-open.org/cover/ISOEnts.zip">Les entités
     de caractère ISO 8879</ulink></term>
     <listitem>
      <para>
      Celles-ci sont nécessaires à DocBook mais sont distribués à part
      car elles sont maintenues par l'ISO.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><ulink url="http://openjade.sourceforge.net">OpenJade</ulink></term>
     <listitem>
      <para>
      C'est le paquetage de base pour le traitement de
      <acronym>SGML</acronym>. Il contient un analyseur
      <acronym>SGML</acronym>, un processeur
      <acronym>DSSSL</acronym> (qui est un programme permettant la
      conversion de documents <acronym>SGML</acronym> en d'autres
      formats en utilisant des feuilles de styles
      <acronym>DSSSL</acronym>), ainsi qu'un certain nombre d'autres
      outils. <productname>Jade</productname> est actuellement
      maintenu par le groupe OpenJade et non plus par James Clark.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><ulink
     url="http://docbook.sourceforge.net/projects/dsssl/index.html">Feuilles
     de styles DocBook DSSSL</ulink></term>
     <listitem>
      <para>
      Celles-ci contiennent les instructions permettant la
      conversion des sources DocBook en d'autres formats tels que le
      <acronym>HTML</acronym>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><ulink url="http://docbook2x.sourceforge.net">Les outils DocBook2X</ulink></term>
     <listitem>
      <para>
      Ce paquetage est utilisé pour créer les pages de manuel. Un
      certain nombre d'autres paquetages sont nécessaires pour le
      faire fonctionner. Pour plus d'informations, vérifiez sur le
      site web.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><ulink url="http://jadetex.sourceforge.net">JadeTeX</ulink></term>
     <listitem>
      <para>
       Si vous le souhaitez, vous pouvez installer
       <productname>JadeTeX</productname> qui s'appuie sur
       <productname>TeX</productname> en tant qu'outil de formatage
       pour <productname>Jade</productname>.
       <application>JadeTeX</application> est capable de créer des
       fichiers au formats Postscript ou
       <acronym>PDF</acronym> (pour ce dernier, il implante les
       signets).
      </para>

      <para>
      Cependant, une sortie <application>JadeTeX</application> est
      de qualité moindre par rapport à ce que vous pouvez obtenir
      d'une sortie <acronym>RTF</acronym>.
      Les principaux problèmes que l'on peut rencontrer se situent
      autour des tables et des éléments de placements verticaux et
      horizontaux. Il est à noter qu'il n'y a aucun recours de
      correction afin de corriger manuellement ces problèmes.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

  <para>
  Nous avons pris le soin de documenter, ci-aprés, plusieurs types de méthodes
  d'installation pour les différents outils nécessaires au
  traitement de la documentation. Il peut exister d'autres types de
  distributions empaquetées de ces outils. Veuillez notifier tout
  changement de paquetage auprés de la liste de discussion de la
  documentation, nous tâcherons d'inclure ces informations ici-même.
  </para>

  <sect2>
   <title>Installation <acronym>RPM</acronym>
   <productname>Linux</productname></title>

   <para>
   La plupart des fabriquants de distributions mettent à disposition
   des utilisateurs un ensemble complet de
   paquetages RPM pour le traitement de DocBook au sein de leur
   distribution. Lors de l'installation, recherchez une option
   <quote>SGML</quote> ou les paquetages suivants&nbsp;:
   <filename>sgml-common</filename>, <filename>docbook</filename>,
   <filename>stylesheets</filename>, <filename>openjade</filename>.
   Vous aurez probablement besoin de
   <filename>sgml-tools</filename>. Si le fournisseur de la
   distribution ne permet pas de disposer de ceux-ci, vous devriez
   être capable d'utiliser des paquetages issus d'une autre
   distribution compatible.
   </para>
  </sect2>

  <sect2>
   <title>Installation pour FreeBSD</title>

   <para>
   Le projet de documentation FreeBSD (FreeBSD Documentation
   Projetc) est lui-même un utilisateur intensif de DocBook, et
   c'est sans surprise que l'on retrouve en son sein un ensemble
   complet de <quote>portages</quote> des outils de documentation
   sur FreeBSD. Les portages suivants devront être installés afin de
   produire la documentation sur FreeBSD.
    <itemizedlist>
     <listitem>
      <para><filename>textproc/sp</filename></para>
     </listitem>
     <listitem>
      <para><filename>textproc/openjade</filename></para>
     </listitem>
     <listitem>
      <para><filename>textproc/docbook-310</filename></para>
     </listitem>
     <listitem>
      <para><filename>textproc/iso8879</filename></para>
     </listitem>
     <listitem>
      <para><filename>textproc/dsssl-docbook-modular</filename></para>
     </listitem>
    </itemizedlist>
    Vous pourrez également porter un intérêt particulier aux
    différents éléments de <filename>/usr/ports/print</filename>
    (<filename>tex</filename> ou <filename>jadetex</filename>).
   </para>

   <para>
    Il est probable que les portages ne mettent pas à jour le
    fichier de catalogue général dans
    <filename>/usr/local/share/sgml/catalog</filename>. Assurez-vous
    que la ligne suivante y figure bien&nbsp;:
<programlisting>
CATALOG "/usr/local/share/sgml/docbook/3.1/catalog"
</programlisting>
    Si vous ne voulez pas éditer ce fichier, vous pouvez également
    modifier la variable d'environnement
    <envar>SGML_CATALOG_FILES</envar> en y mettant une liste de
    fichiers catalogues séparés par des caractères <quote>deux
    points</quote>.
   </para>

   <para>
   Vous pourrez trouver plus d'informations sur les outils dédiés à
   la documentation de FreeBSD dans les <ulink
   url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html">
   instructions du projet de documentation de FreeBSD</ulink>.
   </para>
  </sect2>

  <sect2>
   <title>Paquetages Debian</title>

   <para>
   Un ensemble complet de paquetages d'outils de documentation sont
   disponibles pour <productname>Debian GNU/Linux</productname>.
   Pour l'installer, utilisez simplement&nbsp;:
<programlisting>
apt-get install jade
apt-get install docbook
apt-get install docbook-stylesheets
</programlisting>
   </para>
  </sect2>

  <sect2>
   <title>Installation manuelle à partir des sources</title>

   <para>
    L'installation manuelle des outils DocBook est quelque peu
    complexe. Il est donc préférable que vous utilisiez des
    paquetages pré-compilés. Nous ne décrivons ici que la mise en
    &oelig;uvre standard utilisant des répertoires d'installation
    standards et sans fonctionnalités particulières. Pour entrer
    dans les détails, nous vous recommandons d'étudier la
    documentation respective de chaque paquetage et de lire les
    document d'introduction à <acronym>SGML</acronym>.
   </para>

   <sect3>
    <title>Installer OpenJade</title>

    <procedure>
      <step>
       <para>
        L'installation d'OpenJade se fait par l'intermédiaire des
        outils de construction <literal>./configure;make;make
        install</literal> classique de GNU. Vous pourrez trouver des
        informations détaillées dans la distribution des sources
        d'OpenJade. En quelques mots&nbsp;:
<synopsis>
./configure --enable-default-catalog=/usr/local/share/sgml/catalog
make
make install
</synopsis>
        Assurez-vous de bien vous souvenir de l'endroit où vous
        placez le <quote>catalogue par défaut</quote>&nbsp;; vous en aurez
        besoin par la suite. Vous pouvez également vous passer de
        renseigner cette option. Dans ce cas, vous devrez définir la
        variable d'environnement <envar>SGML_CATALOG_FILES</envar>
        afin qu'elle pointe vers le bon fichier à chaque fois que
        vous lancerez <application>jade</application>. (Cette
        méthode est également possible si OpenJade est déjà installé
        et que vous souhaitez installer le reste de l'environnement
        de publication localement.)
        </para>
      </step>

      <step id="doc-openjade-install">
       <para>
        Par ailleurs, vous devez installer les fichiers 
        <filename>dsssl.dtd</filename>, <filename>fot.dtd</filename>,
        <filename>style-sheet.dtd</filename> et
        <filename>catalog</filename> du répertoire
        <filename>dsssl</filename> quelque part, par exemple dans 
        <filename>/usr/local/share/sgml/dsssl</filename>.  Il vous
        sera certainement plus facile de copier le répertoire entier.
<synopsis>
cp -R dsssl /usr/local/share/sgml
</synopsis>
       </para>
      </step>

      <step>
       <para>
       Enfin, créez le fichier
        <filename>/usr/local/share/sgml/catalog</filename> et
        ajoutez-y la ligne suivante&nbsp;:
<programlisting>
CATALOG "dsssl/catalog"
</programlisting>
        (Il s'agit d'un chemin relatif référençant le fichier
        installé dans l'<xref linkend="doc-openjade-install">.
        Assurez-vous de bien avoir renseigné ce chemin si vous avez
        utilisé un répertoire d'installation différent.)
       </para>
      </step>
     </procedure>
   </sect3>

   <sect3>
    <title>Installation du kit <acronym>DTD</acronym> de
     <productname>DocBook</productname></title>

    <procedure>
     <step>
      <para>
       Récupérez la distribution <ulink
       url="http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip">DocBook
       V3.1</ulink>.
      </para>
     </step>

     <step>
      <para>
       Créez le répertoire
       <filename>/usr/local/share/sgml/docbook31</filename> et
       placez-y vous. (L'emplacement importe peu en fait mais
       celle-ci a le bénéfice d'être cohérente avec le schéma
       d'installation que nous vous proposons ici.)
<screen>
<prompt>$ </prompt><userinput>mkdir /usr/local/share/sgml/docbook31</userinput>
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook31</userinput>
</screen>
      </para>
     </step>

     <step>
      <para>
       Décompressez l'archive.
<screen>
<prompt>$ </prompt><userinput>unzip -a ...../docbk31.zip</userinput>
</screen>
       (L'archive décompressera ses fichier dans le répertoire
       courant.)
      </para>
     </step>

     <step>
      <para>
       Éditez le fichier
       <filename>/usr/local/share/sgml/catalog</filename> (ou ce que
       vous aurez dit à jade lors de l'installation) et placez-y une
       ligne similaire à celle-ci&nbsp;:
<programlisting>
CATALOG "docbook31/docbook.cat"
</programlisting>
      </para>
     </step>

     <step>
      <para>
       Éventuellement, vous pouvez éditer le fichier
       <filename>docbook.cat</filename> et commenter ou supprimer la
       ligne contenant <literal>DTDDECL</literal>. Si vous ne le faites pas,
       <application>jade</application> générera des avertissements
       qui ne seront pas réellement un obstacle pour le but que nous
       nous sommes fixés.
      </para>
     </step>

     <step>
      <para>
       Téléchargez l'archive contenant les <ulink
       url="http://www.oasis-open.org/cover/ISOEnts.zip">entités de
       caractères ISO 8879</ulink>, décompressez-la et placez les
       fichiers dans le même répertoire que celui des fichiers de
       DocBook.
<screen>
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook31</userinput>
<prompt>$ </prompt><userinput>unzip ...../ISOEnts.zip</userinput>
</screen>
      </para>
     </step>

     <step>
      <para>
      Lancez la commande suivante dans le répertoire contenant les
      fichiers DocBook et ISO&nbsp;:
<programlisting>
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
</programlisting>
       (Cette opération permet de corriger les mélanges entre le
       fichier de catalogue de DocBook et les noms réels des
       fichiers contenant les entités de caractères ISO.)
      </para>
     </step>
    </procedure>
   </sect3>

   <sect3>
    <title>Installation des feuilles de style <acronym>DSSSL</acronym> DocBook</title>

    <para>
     Pour installer les feuilles de style, décompressez et déballez la
     distribution et déplacez-la à un endroit convenable de votre
     aborescence comme, par exemple, 
     <filename>/usr/local/share/sgml</filename>. (L'archive créera
     automatiquement un sous-répertoire.)
<screen>
<prompt>$</prompt> <userinput>gunzip docbook-dsssl-1.<replaceable>xx</>.tar.gz</userinput>
<prompt>$</prompt> <userinput>tar -C /usr/local/share/sgml -xf docbook-dsssl-1.<replaceable>xx</>.tar</userinput>
</screen>
    </para>

    <para>
     L'entrée de catalogue communément admise  dans
     <filename>/usr/local/share/sgml/catalog</filename> peut
     également être réalisée&nbsp;:
<programlisting>
CATALOG "docbook-dsssl--1.<replaceable>xx</>/catalog
</programlisting>
     Comme les feuilles de styles changent assez souvent et qu'il est
     parfois avantageux d'essayer des versions alternatives,
     <productname>PostgreSQL</productname> n'utilise pas cette
     entrée dans le catalogue. Regardez dans la <xref
     linkend="docguide-toolsets-configure"> pour tout renseignement
     sur la manière de sélectionner une feuille de style.
    </para>
   </sect3>

   <sect3>
    <title>Intallation de <productname>JadeTeX</productname></title>

    <para>
     Pour installer et utiliser <productname>JadeTeX</productname>,
     vous devez disposer d'une installation fonctionnelle de 
     <productname>TeX</productname> et de 
     <productname>LaTeX2e</productname>, incluant également les
     paquetages 
     <productname>d'outils</productname> de support, la bibliothèque 
     <productname>graphics</productname>,
     <productname>Babel</productname>,
     <productname>les polices <acronym>AMS</acronym></productname>
     et
     <productname>AMS-LaTeX</productname>, l'extension
     <productname><acronym>PSNFSS</acronym></productname>
     et le kit d'accompagnement de <quote>35 polices</quote>, le
     programme 
     <productname>dvips</productname> permettant de générer du
     <productname>PostScript</productname>, le paquetage de macros
     <productname>fancyhdr</productname>,
     <productname>hyperref</productname>,
     <productname>minitoc</productname>,
     <productname>url</productname> et enfin 
     <productname>ot2enc</productname>.  Tous ceux-ci peuvent être
     trouvé sur le site web de <ulink
     url="http://www.ctan.org"><acronym>CTAN</acronym></ulink> .
     L'installation de base pour le système
     <application>TeX</application> va au-delà des buts visés par
     cette introduction. Des paquetages binaires devraient être
     disponibles pour tout système pouvant exécuter 
     <application>TeX</application>.
    </para>

    <para>
     Avant que vous soyez en mesure d'utiliser
     <application>JadeTeX</application> avec les sources de la
     documentation de <productname>PostgreSQL</productname>, vous devrez
     augmenter la taille des structures de données internes de 
     <application>TeX</application>. Des explications plus détaillées sur
     <application>JadeTeX</application>
     pourront être trouvées sur les instructions d'installation de ce produit.
    </para>

    <para>
     Une fois ceci terminé, vous pouvez installer
     <application>JadeTeX</application>&nbsp;:
<screen>
<prompt>$</prompt> <userinput>gunzip jadetex-<replaceable>xxx</replaceable>.tar.gz</userinput>
<prompt>$</prompt> <userinput>tar xf jadetex-<replaceable>xxx</replaceable>.tar</userinput>
<prompt>$</prompt> <userinput>cd jadetex</userinput>
<prompt>$</prompt> <userinput>make install</userinput>
<prompt>$</prompt> <userinput>mktexlsr</userinput>
</screen>
     Les deux dernières commandes doivent être exécutées en temps que <systemitem>root</systemitem>.
    </para>

   </sect3>

  </sect2>

  <sect2 id="docguide-toolsets-configure">
   <title>Détection par <command>configure</command></title>

  <para>
   Avant de pouvoir générer la documentation, vous devrez lancer le script
   <filename>configure</filename> comme vous le feriez lors de la génération des
   programmes <productname>PostgreSQL</productname> eux-même. Vérifiez la sortie
   de l'exécution de ce script vers la fin, vous trouverez quelque chose de
   similaire à ce qui suit&nbsp;:
<screen>
<computeroutput>
checking for onsgmls... onsgmls
checking for openjade... openjade
checking for DocBook V3.1... yes
checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular
checking for sgmlspl... sgmlspl
</computeroutput>
</screen>
   Si ni <filename>onsgmls</filename> ni <filename>nsgmls</filename> n'ont été
   trouvés, vous ne verrez pas les quatre dernières lignes.
   <filename>onsgmls</filename> fait partie du paquetage Jade. Si <quote>DocBook
   V3.1</quote> n'a pas été trouvé, cela signifie que le kit de DTD DocBook n'a
   pas été placé à l'endroit où jade peut le trouver ou que vous n'avez pas
   configuré les fichiers de catalogue correctement. Regardez les indications
   d'installation ci-dessus. Les feuilles de style DocBook sont recherchées dans
   un certain nombre d'endroits relativement standardisés, mais si vous les avez
   placées ailleurs, vous devrez modifier la variable d'environnement
   <envar>DOCBOOKSTYLE</envar> à cet emplacement et relancer
   <filename>configure</filename> juste aprés.
  </para>

  </sect2>
 </sect1>

 <sect1 id="docguide-build">
  <title>Génération de la documentation</title>

  <para>
   Une fois que tout est en place, placez-vous dans le répertoire
   <filename>doc/src/sgml</filename> et lancez une des commandes décrites dans
   les sections suivantes afin de générer la documentation. (Souvenez-vous bien
   d'utiliser la version GNU de make.) 
  </para>

  <sect2>
   <title>HTML</title>

   <para>
    Pour générer la version <acronym>HTML</acronym> de la
    documentation, effectuez ce qui suit&nbsp;:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake html</userinput>
</screen>
    Il s'agit également de la cible par défaut.
   </para>

   <para>
    Lorsque la documentation HTML est générée, le processus
    produit également des informations de liaison pour les entrées
    de l'index. Ainsi, si vous souhaitez disposer d'un index des concepts
    à la fin de votre documentation, vous devrez produire une
    première fois la documentation HTML, puis relancer la production de la documentation 
    avec le format que vous souhaitez obtenir.
   </para>

   <para>
    Pour un côté plus pratique lors de la manipulation de la distribution
    finale de la documentation, l'ensemble des fichiers y compris la
    documentation HTML est stockée dans une archive tar qui est
    décompressée lors de l'installation. Pour créer le
    paquetage <acronym>HTML</acronym>, utilisez les commandes&nbsp;:
<programlisting>
cd doc/src
gmake postgres.tar.gz
</programlisting>
    Dans la distribution de PostgreSQL, cette archive se trouve dans le
    répertoire <filename>doc</filename> et peut être installée grace à
    <command>gmake install</command>.
  </para>
 </sect2>

 <sect2>
  <title>Pages man (de manuels)</title>

  <para>
   Afin de convertir les pages de références de la documentation
   <productname>DocBook</productname> en pages man nous utilisons
   <application>docbook2man</application> pour les convertir dans un format
   compatible avec *roff. Les pages man sont également distribuées
   sous la forme d'une archive tar, à l'instar de la version
   <acronym>HTML</acronym>. Pour créer le paquetage de pages man,
   utilisez les commandes&nbsp;:
<programlisting>
cd doc/src
gmake man.tar.gz
</programlisting>
   qui résulteront en un fichier tar généré dans le
   répertoire <filename>doc/src</filename>.
  </para>

  <para>
   Afin de générer des pages man de qualité, il sera
   peut-être nécessaire d'utiliser une version modifiée de
   l'utilitaire de conversion ou de faire des modification manuelles en
   post-production. Toutes les pages man doivent être manuellement
   vérifiées avant toute distribution.
  </para>
 </sect2>

  <sect2>
   <title>Sortie pour l'impression via
<application>JadeTex</application></title>

   <para>
    Si vous souhaitez utiliser <application>JadeTex</application> pour produire
    une documentation à destination de l'impression, vous pouvez utiliser une
    des commandes suivantes&nbsp;:
    <itemizedlist>
     <listitem>
      <para>
       Pour créer une version <acronym>DVI</acronym>&nbsp;:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.dvi</userinput>
</screen>
      </para>
     </listitem>

     <listitem>
      <para>
       Pour générer un fichier Postscript à partir du
       <acronym>DVI</acronym>&nbsp;:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.ps</userinput>
</screen>
      </para>
     </listitem>
  
     <listitem>
      <para>
       Pour créer un <acronym>PDF</acronym>&nbsp;:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.pdf</userinput>
</screen>
       (Bien entendu, vous pouvez également créer une version
       <acronym>PDF</acronym> à partir d'un document Postscript, mais si vous le
       générez directement, votre <acronym>PDF</acronym> bénéficiera des
       liens actifs et de fonctionnalités supérieures.)
      </para>
     </listitem>
    </itemizedlist>
   </para>
  </sect2>

  <sect2>
   <title>Version imprimable via <acronym>RTF</acronym></title>

   <para>
    Vous pouvez aussi créer une version imprimable de la documentation de
    <productname>PostgreSQL</productname> en la convertissant en RTF et en y
    appliquant des corrections de formatage en utilisant une suite de logiciels
    de bureau. En fonction des capacité de cette dernière, vous pourrez
    convertir la documentation aux formats Postscript ou
    <acronym>PDF</acronym>. La procédure ci-dessous décrit une telle procédure
    en utilisant <productname>Applixware</productname>.
   </para>

   <note>
    <para>
     Il apparaît que la version actuelle de la documentation de
     <productname>PostgreSQL</productname> génère quelques bogues au niveau
     d'OpenJade, dépassant notamment la taille maximale de traitement. Si le
     processus de génération de la version <acronym>RTF</acronym> reste
     suspendu un long moment et que la sortie garde une taille de 0, c'est que
     vous devez vous trouver face à ce problème. (Considérez cependant qu'une
     génération normale doit prendre 5 à 10 minutes, n'abandonnez donc pas trop
     tôt.)
    </para>
   </note>

   <procedure>
    <title>Nettoyage du <acronym>RTF</acronym> pour
     <productname>Applixware</productname></title>

    <para>
     <application>OpenJade</application> oublie de spécifier un style par
     défaut pour le corps du texte. Dans le passé, ce problème non diagnostiqué
     a amené un processus très long pour la génération du sommaire. Néanmoins,
     avec un grande aide des gens de <productname>Applixware</productname>, le
     symptôme a été diagnostiqué et un contournement est disponible.
    </para>

    <step performance="required">
     <para>
      Produisez la version <acronym>RTF</acronym> en saisissant&nbsp;:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.rtf</userinput>
</screen>
     </para>
    </step>

    <step performance="required">
     <para>
      Réparez le fichier RTF afin de spécifier correctement tous les
      styles et en particulier le style par défaut (default). Si le document
      contient des sections <sgmltag>refentry</sgmltag>, vous devrez également
      supprimer les éléments de formatage qui relient le paragraphe précédent au
      paragraphe courant. À la place, il faudra relier le paragraphe précédent
      au paragraphe courant. Un utilitaire, <command>fixrtf</command>, est
      disponible dans <filename>doc/src/sgml</filename> afin de permettre ces
      corrections&nbsp;:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>./fixrtf --refentry postgres.rtf</userinput>
</screen>
     </para>

     <para>
      Le script ajoute <literal>{\s0 Normal;}</literal> en temps que style de
      rang zéro dans le document. D'après <productname>Applixware</productname>,
      le standard RTF prohibe l'utilisation implicite d'un style de rang 0 alors
      que Microsoft Word est capable de gérer cette éventualité. Afin de réparer
      les sections <sgmltag>refentry</sgmltag>, le script remplace les balises
      <literal>\keepn</literal> par <literal>\keep</literal>.
     </para>
    </step>

    <step performance="required">
     <para>
      Ouvrez un nouveau document dans <productname>Applixware
      Words</productname> puis importez le fichier <acronym>RTF</acronym>.
     </para>
    </step>

    <step performance="required">
     <para>
      Générez une nouvelle table des matières en utilisant
      <productname>Applixware</productname>.
     </para>

     <substeps>
      <step>
       <para>
        Sélectionnez les lignes existantes de la table des matières, du premier
        caractère de la table au dernier caractère de la dernière ligne.
       </para>
      </step>

      <step>
       <para>
        Construisez une nouvelle table des matières en allant dans le menu
        <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
        Building</guisubmenu><guimenuitem>Create Table of
        Contents</guimenuitem></menuchoice>. Sélectionnez les trois premiers
        niveaux de titres pour l'inclusion dans la table des matières. Cela
        remplacera les lignes existantes importées du RTF en une table des
        matières issue d'<productname>Applixware</productname>.
       </para>
      </step>

      <step>
       <para>
        Ajustez le formatage de la table des matières en utilisant le menu
        <menuchoice><guimenu>Format</guimenu><guimenuitem>Style</guimenuitem></menuchoice>,
        en sélectionnant chacun des trois styles de la table des matières et en
        ajustant les indentations pour <literal>First</literal> et
        <literal>Left</literal>. En utilisant les valeurs suivantes&nbsp;:
        <informaltable>
         <tgroup cols="3">
          <thead>
           <row>
            <entry>Style</entry>
            <entry>Indentation de First (pouces)</entry>
            <entry>Indentation de Left (pouces)</entry>
           </row>
          </thead>

          <tbody>
           <row>
            <entry><literal>TOC-Heading 1</literal></entry>
            <entry><literal>0.4</literal></entry>
            <entry><literal>0.4</literal></entry>
           </row>

           <row>
            <entry><literal>TOC-Heading 2</literal></entry>
            <entry><literal>0.8</literal></entry>
            <entry><literal>0.8</literal></entry>
           </row>

           <row>
            <entry><literal>TOC-Heading 3</literal></entry>
            <entry><literal>1.2</literal></entry>
            <entry><literal>1.2</literal></entry>
           </row>
          </tbody>
         </tgroup>
        </informaltable>
       </para>
      </step>
     </substeps>
    </step>

    <step performance="required">
     <para>
      Travaillez la totalité du document en&nbsp;:

      <itemizedlist>
       <listitem>
        <para>
         Ajustant les sauts de page.
        </para>
       </listitem>

       <listitem>
        <para>
         Ajustant la largeur des colonnes des tables.
        </para>
       </listitem>
      </itemizedlist>
     </para>
    </step>

    <step performance="required">
     <para>
      Remplacez les numéros de pages justifiés à droite dans les portions
      d'exemple et de figures de la table des matières avec les bonnes valeurs.
      Cela ne prend que quelques minutes.
      </para>
    </step>

    <step performance="optional">
     <para>
       Supprimez la section d'index du document si elle est vide.
     </para>
    </step>

    <step performance="required">
     <para>
       Régénérez et ajustez la table des matières.
     </para>

      <substeps>
       <step>
        <para>
         Sélectionnez un champ de la table des matières.
        </para>
       </step>

       <step>
        <para>
         Sélectionnez le menu <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
         Building</guisubmenu><guimenuitem>Create Table of
         Contents</guimenuitem></menuchoice>.
        </para>
       </step>

       <step>
        <para>
         Déliez la table des matières en sélectionnant le menu
         <menuchoice><guimenu>Tools</guimenu><guisubmenu>Field
         Editing</guisubmenu><guimenuitem>Unprotect</guimenuitem></menuchoice>.
        </para>
       </step>

       <step>
        <para>
         Supprimez la première ligne de la table des matières, qui est un des
         champs de la table elle-même.
        </para>
       </step>
      </substeps>
    </step>
    <step performance="required">
     <para>
      Sauvegardez le document au format natif de <productname>Applixware
      Words</productname> afin de pouvoir faire des modifications facilement
      dans le futur.
     </para>
    </step>

    <step performance="required">
     <para>
      <quote>Imprimez</quote> le document dans un fichier au format Postscript.
     </para>
    </step>
   </procedure>
  </sect2>

  <sect2>
   <title>Fichiers texte</title>

   <para>
    Plusieurs fichiers textes sont distribués comme fichiers pour la lecture
    durant le processus d'installation. Le fichier <filename>INSTALL</filename>
    correspond au <xref linkend="installation">, avec quelques changements
    mineurs à mettre sur le compte d'un contexte différent. Pour recréer le
    fichier, placez-vous dans le répertoire <filename>doc/src/sgml</filename> et
    entrez la commande suivante <userinput>gmake INSTALL</userinput>. Ceci
créera
    un fichier <filename>INSTALL.html</filename> que vous pourrez sauvegarder au
    format texte avec <productname>Netscape Navigator</productname> et remplacer
    le fichier existant. <productname>Netscape</productname> semble fournir la
    meilleure qualité pour la conversion du <acronym>HTML</acronym> en texte
    (comparé à <application>lynx</application> et à
    <application>w3m</application>).
   </para>

   <para>
    Le fichier <filename>HISTORY</filename> peut être créé de manière similaire
    en utilisant la commande <userinput>gmake HISTORY</userinput>. Pour le
    fichier <filename>src/test/regress/README</filename>, la commande est
    <userinput>gmake regress_README</userinput>.
   </para>
  </sect2>

  <sect2>
   <title>Vérification syntaxique</title>

   <para>
    Fabriquer la documentation peut prendre beaucoup de temps. Il existe
    cependant une méthode ne prenant que quelques secondes et permettant juste
    de vérifier que la syntaxe est correcte dans les fichiers de
    documentation&nbsp;:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake check</userinput>
</screen>
   </para>
  </sect2>
 </sect1>


 <sect1 id="docguide-authoring">
  <title>Écriture de la documentation</title>

   <para>
    <acronym>SGML</acronym> et <productname>DocBook</productname> ne souffrent
    pas du foisonnement d'outils d'édition open-source. Le plus commun
    d'entre eux est l'éditeur
    <productname>Emacs</productname>/<productname>XEmacs</productname> qui
    dispose d'un mode d'édition approprié. Sur certains systèmes, ces outils
    sont fournis sous la forme d'une installation complète (un même paquetage ou
    ensemble).
   </para>

   <sect2>
    <title>Emacs/PSGML</title>

    <para>
     <productname>PSGML</productname> est le mode d'édition de documents
     <acronym>SGML</acronym> le plus répandu et le plus puissant. S'il est
     correctement configuré, il vous permettra d'utiliser
     <application>Emacs</application> pour insérer de balises et en vérifier la
     consistance. Vous pouvez également l'utiliser pour le
     <acronym>HTML</acronym>. Visitez le <ulink
     url="http://www.lysator.liu.se/projects/about_psgml.html">site web de
     PSGML</ulink> pour le télécharger, avoir des informations sur
     l'installation et pour disposer d'une documentation détaillée.
    </para>

    <para>
     Un point important à noter avec <productname>PSGML</productname>&nbsp;: son
     auteur suppose que votre répertoire
     principal pour la <acronym>DTD</acronym> <acronym>SGML</acronym> est
     <filename>/usr/local/lib/sgml</filename>.  Si, comme c'est le cas dans les
     exemples de ce chapitre, vous utilisez le répertoire
     <filename>/usr/local/share/sgml</filename>, vous devrez modifier la
     variable d'environnement 
     <envar>SGML_CATALOG_FILES</envar> ou vous pouvez personnaliser votre
     installation de <productname>PSGML</productname> (son manuel vous
     renseignant sur la manière de le faire).
    </para>

    <para>
     Ajoutez les lignes suivantes dans votre fichier d'environnement
     <filename>~/.emacs</filename> (en ajustant les noms des répertoires pour
     qu'il convienne à votre système de fichiers)&nbsp;:

<programlisting>
; ********** pour le mode SGML (psgml)

(setq sgml-omittag t)
(setq sgml-shorttag t)
(setq sgml-minimize-attributes nil)
(setq sgml-always-quote-attributes t)
(setq sgml-indent-step 1)
(setq sgml-indent-data t)
(setq sgml-parent-document nil)
(setq sgml-default-dtd-file "./reference.ced")
(setq sgml-exposed-tags nil)
(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
(setq sgml-ecat-files nil)

(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
</programlisting>

     et dans le même fichier ajoutez l'entrée pour le <acronym>SGML</acronym> 
     dans la définition (existante) pour
     <varname>auto-mode-alist</varname>&nbsp;:
<programlisting>
(setq
  auto-mode-alist
  '(("\\.sgml$" . sgml-mode)
   ))
</programlisting>
    </para>

    <para>
     Actuellement, chaque fichier source <acronym>SGML</acronym> contient le
     bloc suivant à la fin du fichier&nbsp;:

<programlisting>
&lt;!-- Conservez ce commentaire à la fin du fichier
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
--&gt;
</programlisting>
     Ce bloc vous permet de définir un certain nombre de paramètres du mode
     d'édition même si vous n'avez pas configuré votre fichier
     <filename>~/.emacs</filename>, mais il est un peu malheureux car, si vous
     avez suivi les instructions d'installation ci-dessus, le chemin de
     catalogue ne correspond pas à l'endroit où vous l'aurez mis. Si c'est le
     cas, vous drevrez faire en sorte de ne pas prendre en compte les variables
     locales&nbsp;:
    <programlisting>
(setq inhibit-local-variables t)
</programlisting>
    </para>

    <para>
     La distribution <productname>PostgreSQL</productname>  inclut un fichier
     DTD pré-traité contenant des défintions appelé
     <filename>reference.ced</filename>. Vous trouverez certainement plus
     confortable d'insérer une déclaration <literal>DOCTYPE</literal> lorsque
     vous éditerez un fichier avec PSGML. Si par exemple vous travaillez sur ce
     fichier source qui est un chapitre annexe, vous pourrez spécifier que le
     document est une instance <quote>appendix</quote> d'un document DocBook en
     ajoutant en première ligne ceci&nbsp;:

<programlisting>
&lt;!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V3.1//EN"&gt;
</programlisting>

     Ceci signifie que, quelque soit l'outil lisant le 
     <acronym>SGML</acronym>, il le fera correctement et que je peux vérifier la
     validité du document avec 
     <command>nsgmls -s docguide.sgml</command>. (Cependant, vous devrez
     supprimer la ligne avant de fabriquer le document complet à partir des
     différents fichiers.)