root/traduc/trunk/postgresql/docguide.xml

<?xml version="1.0" encoding="ISO-8859-15"?>
<!-- Dernière modification
     le       $Date$
     par      $Author$
     révision $Revision$ -->

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

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

  <itemizedlist>
   <listitem>
    <para>
     le 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> peuvent
  être trouvés à divers endroits de l'arbre des sources de
  <productname>PostgreSQL</productname>. Ils renseignent
  l'utilisateur sur différents points d'implantation.
 </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 téléchargement.
 </para>

 <sect1 id="docguide-docbook">
  <title>DocBook</title>
  <para>
   Les sources de la documentation sont écrites en
   <firstterm>DocBook</firstterm>, langage assez semblable au
   <acronym>HTML</acronym>. Ces deux langages sont
   des applications du <firstterm>Standard Generalized Markup
   Language</firstterm>, <acronym>SGML</acronym>, qui est
   essentiellement un langage de description d'autres langages. Dans ce
   qui suit, les termes DocBook et <acronym>SGML</acronym> sont tous deux utilisés,
   mais ils ne sont 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
  à se soucier du détail de la présentation. Un style de
  document définit le rendu du contenu 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 à la
  lecture en ligne. Le <ulink
  url="http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html">guide
  DocBook des nouveaux venus</ulink> est très utile pour les débutants. 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 qui suivent sont utilisés pour produire 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. C'est actuellement la
      version 4.2 qui est utilisée&nbsp;; il n'est pas posiible d'en utiliser
      une autre (plus récente ou plus ancienne). Il existe également une version
      <acronym>XML</acronym> de DocBook &mdash; elle ne doit pas être
      utilisée.
      </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ées à part
      car 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> (programme qui permet la
      conversion de documents <acronym>SGML</acronym> en d'autres
      formats à l'aide de 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 de
      conversion des sources DocBook en d'autres formats, tel 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érifier sur le site web.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><ulink url="http://jadetex.sourceforge.net">JadeTeX</ulink></term>
     <listitem>
      <para>
       <productname>JadeTeX</productname> peut être installé pour utiliser
       <productname>TeX</productname> comme outil de formatage
       pour <productname>Jade</productname>.
       <application>JadeTeX</application> est capable de créer des
       fichiers au formats PostScript ou
       <acronym>PDF</acronym> (ce dernier avec les signets).
      </para>

      <para>
      Cependant, une sortie <application>JadeTeX</application> est
      de moindre qualité qu'une sortie <acronym>RTF</acronym>.
      Les principaux problèmes que l'on peut rencontrer concernent
      les tables et les éléments de placements verticaux et
      horizontaux. Il n'y a aucune possibilité de corriger manuellement le
      résultat.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

  <para>
  Différentes méthodes d'installation sont détaillées ci-après pour
  les divers outils nécessaires au
  traitement de la documentation. Il peut exister d'autres types de
  distributions empaquetées de ces outils. Tout
  changement du statut d'un paquetage peut être rapportée auprés de
  la liste de discussion de la
  documentation, afin d'inclure ces informations ici-même.
  </para>

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

   <para>
   La plupart des revendeurs mettent à disposition
   des utilisateurs un ensemble complet de
   paquetages RPM pour le traitement de DocBook au sein de leur
   distribution. Lors de l'installation, il faut recherche une option
   <quote>SGML</quote> ou les paquetages suivants&nbsp;:
   <filename>sgml-common</filename>, <filename>docbook</filename>,
   <filename>stylesheets</filename>, <filename>openjade</filename>.
   <filename>sgml-tools</filename> est probablement requis. Si le fournisseur de la
   distribution ne les fournit pas, il doit être possible 
   d'utiliser des paquetages issus d'une distribution compatible.
   </para>
  </sect2>

  <sect2>
   <title>Installation sous FreeBSD</title>

   <para>
   Le projet de documentation FreeBSD (FreeBSD Documentation
   Project) 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 doivent être installés afin de
   produire la documentation sur FreeBSD&nbsp;:
    <itemizedlist>
     <listitem>
      <para><filename>textproc/sp</filename>&nbsp;;</para>
     </listitem>
     <listitem>
      <para><filename>textproc/openjade</filename>&nbsp;;</para>
     </listitem>
     <listitem>
      <para><filename>textproc/iso8879</filename>&nbsp;;</para>
     </listitem>
     <listitem>
      <para><filename>textproc/dsssl-docbook-modular</filename>.</para>
     </listitem>
     <listitem>
      <para><filename>textproc/docbook-420</filename></para>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    Un intérêt particulier peut également être porté aux
    différents éléments de <filename>/usr/ports/print</filename>
    (<filename>tex</filename>, <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.ports</filename> ou que l'ordre ne
    soit pas le bon. Les lignes suivantes doivent figurent au début&nbsp;:
<programlisting>CATALOG "openjade/catalog"
CATALOG "iso8879/catalog"
CATALOG "docbook/dsssl/modular/catalog"
CATALOG "docbook/4.2/catalog"</programlisting>
    Pour ne pas éditer ce fichier, il est possible de positionner
    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>
   De plus amples informations sur les outils dédiés à
   la documentation de FreeBSD se trouvent 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 est
   disponible pour <productname>Debian GNU/Linux</productname>.
   Pour l'installer, il suffit de taper&nbsp;:
<programlisting>apt-get install openjade1.3
apt-get install docbook
apt-get install docbook-dsssl
</programlisting>
    (Le package <literal>openjade</literal> installe
    OpenJade 1.4 qui semble ne pas fonctionner.)
   </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 d'utiliser des
    paquetages pré-compilés. Seule une procédure de mise en
    &oelig;uvre standard, qui utilise des répertoires d'installation
    standard et sans fonctionnalités particulières, est ici décrite. Pour
    les détails, on peut étudier la
    documentation respective de chaque paquetage et lire les
    documents 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> classiques de GNU. Les
        détails sont 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>
        L'emplacement du <quote>catalogue par défaut</quote> a son
        importance&nbsp;; il est utilisé par la suite. Il est possible de ne
        pas s'en souvenir, mais dans ce cas, la
        variable d'environnement <envar>SGML_CATALOG_FILES</envar> doit être
        définie de façon à pointer vers le bon fichier à chaque fois que
        <application>jade</application> est exécuté. (Cette
        méthode est également possible si OpenJade est déjà installé
        et que le reste de l'environnement de publication est installé localement.)
        </para>
      </step>

      <step id="doc-openjade-install">
       <para>
        De même, 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> doivent être installés quelque part, dans 
        <filename>/usr/local/share/sgml/dsssl</filename>, par exemple. Il
        est certainement plus facile de copier le répertoire entier.
<synopsis>cp -R dsssl /usr/local/share/sgml
</synopsis>
       </para>
      </step>

      <step>
       <para>
        Enfin, le fichier
        <filename>/usr/local/share/sgml/catalog</filename> doit être créé pour
        y ajouter 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"/>.
        Ce chemin doit être correctement renseigné si
        un répertoire d'installation différent est utilisé.)
       </para>
      </step>
     </procedure>
   </sect3>

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

    <procedure>
     <step>
      <para>
       Récupérer la distribution <ulink
       url="http://www.docbook.org/sgml/4.2/docbook-4.2.zip">DocBook
       V4.2</ulink>.
      </para>
     </step>

     <step>
      <para>
       Créer le répertoire
       <filename>/usr/local/share/sgml/docbook-4.2</filename> et
       s'y placer. (L'emplacement exact importe peu mais
       celui-ci a le bénéfice d'être cohérent avec le schéma
       d'installation proposé ici.)
<screen><prompt>$ </prompt><userinput>mkdir /usr/local/share/sgml/docbook-4.2</userinput>
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput></screen>
      </para>
     </step>

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

     <step>
      <para>
       Éditer le fichier
       <filename>/usr/local/share/sgml/catalog</filename> (ou celui précisé
       à jade lors de l'installation) et y placer une
       ligne similaire à celle-ci&nbsp;:
<programlisting>CATALOG "docbook-4.2/docbook.cat"
</programlisting>
      </para>
     </step>

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

     <step>
      <para>
      Lancer 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écompresser et dépaqueter la
     distribution, la déplacer à un endroit convenable de l'aborescence comme, par exemple, 
     <filename>/usr/local/share/sgml</filename>. (L'archive crée
     automatiquement un sous-répertoire.)
<screen><prompt>$</prompt> <userinput>gunzip docbook-dsssl-1.<replaceable>xx</replaceable>.tar.gz</userinput>
<prompt>$</prompt> <userinput>tar -C /usr/local/share/sgml -xf docbook-dsssl-1.<replaceable>xx</replaceable>.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</replaceable>/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 du catalogue. Regarder 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>,
     il faut une installation fonctionnelle de 
     <productname>TeX</productname> et de 
     <productname>LaTeX2e</productname>, incluant également les
     paquetages 
     <productname>tools</productname> et 
     <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> pour la production de
     <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 peuvent être
     trouvés sur le 
     <ulink url="http://www.ctan.org">site web du <acronym>CTAN</acronym></ulink>.
     L'installation du système <application>TeX</application> de base est en
     dehors du périmètre de cette introduction. Des paquetages binaires sont
     probablement disponibles pour tout système pouvant exécuter 
     <application>TeX</application>.
    </para>

    <para>
     Avant de pouvoir utiliser
     <application>JadeTeX</application> avec les sources de la
     documentation de <productname>PostgreSQL</productname>, il va falloir
     augmenter la taille des structures de données internes de
     <application>TeX</application>. Des explications plus détaillées sont
     fournies dans les instructions d'installation de
     <application>JadeTeX</application>.
    </para>

    <para>
     Lorsque tout cela est réalisé, <application>JadeTeX</application> peut
     être installé&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 <systemitem>root</systemitem>.
    </para>

   </sect3>

  </sect2>

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

  <para>
   Avant de pouvoir engendrer la documentation, le script
   <filename>configure</filename> doit être lancé, comme cela se fait pour la génération des
   programmes <productname>PostgreSQL</productname> eux-mêmes. La fin de
   l'affichage de l'exécution de ce script doit ressembler à&nbsp;:
<screen><computeroutput>checking for onsgmls... onsgmls
checking for openjade... openjade
checking for DocBook V4.2... 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, les quatre dernières lignes ne sont pas affichées.
   <filename>onsgmls</filename> fait partie du paquetage Jade. Les variables
   d'environnement <envar>JADE</envar> et
   <envar>NSGMLS</envar> peuvent être renseignées pour indiquer les
   emplacements des programmes s'ils ne sont pas
   trouvés automatiquement. Si <quote>DocBook V4.2</quote> n'a pas été trouvé,
   c'est que le kit de la DTD DocBook n'est pas installé à un endroit où
   Jade peut le trouver ou que les fichiers
   catalogues ne sont pas correctement configurés. Il convient, dans ce cas,
   de se reporter aux conseils donnés plus haut.
   Les feuilles de style DocBook sont recherchées dans
   un certain nombre d'endroits standard, mais si elles sont placées en un
   autre endroit, il faut configurer la variable d'environnement
   <envar>DOCBOOKSTYLE</envar> avec cet emplacement et relancer
   <filename>configure</filename>.
  </para>

  </sect2>
 </sect1>

 <sect1 id="docguide-build">
  <title>Construire la documentation</title>

  <para>
   Lorsque tout est en place, se placer dans le répertoire
   <filename>doc/src/sgml</filename> et lancer une des commandes décrites dans
   les sections suivantes afin de produire la documentation. (Il est impératif
   d'utiliser la version GNU de make.) 
  </para>

  <sect2>
   <title>HTML</title>

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

   <para>
    Pour créer un bon index, la construction doit se faire en plusieurs étapes
    identiques. Si l'index n'est pas utile et qu'il s'agit simplement de
    vérifier le résultat, on peut utiliser <literal>draft</literal>&nbsp;:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake draft</userinput>
</screen>
   </para>

   <para>
    Pour simplifier la manipulation de la distribution
    finale de la documentation, l'ensemble des fichiers, dont la
    documentation HTML, peut être stocké dans une archive tar
    décompressée à l'installation. Pour créer le
    paquetage <acronym>HTML</acronym>, on utilise les commandes&nbsp;:
<programlisting>cd doc/src
gmake postgres.tar.gz
</programlisting>
    Dans la distribution de PostgreSQL, cette archive, qui se trouve dans le
    répertoire <filename>doc</filename>, est installée par
    <command>gmake install</command>.
  </para>
 </sect2>

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

  <para>
   <application>docbook2man</application> est utilisé pour convertir les pages
   de références <productname>DocBook</productname> dans un format
   *roff compatible avec les pages man. 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,
   utiliser les commandes&nbsp;:
<programlisting>cd doc/src
gmake man.tar.gz
</programlisting>
   qui produisent un fichier tar placé dans le
   répertoire <filename>doc/src</filename>.
  </para>

  <para>
   Afin de produire des pages man de qualité, il peut
   être nécessaire d'utiliser une version modifiée de
   l'utilitaire de conversion ou de faire des modifications manuelles
   post-production. L'ensemble des pages man doit être manuellement
   vérifié avant toute distribution.
  </para>
 </sect2>

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

   <para>
    Si <application>JadeTex</application> est utilisé pour produire
    une documentation pour impression, une des commandes suivantes peut être
    utilisée&nbsp;:
    <itemizedlist>
     <listitem>
      <para>
       pour produire un fichier PostScript à partir du
       <acronym>DVI</acronym> au format A4&nbsp;:
<screen><prompt>doc/src/sgml$ </prompt><userinput>gmake postgres-A4.ps</userinput></screen>
       Au format letter&nbsp;:
<screen><prompt>doc/src/sgml$ </prompt><userinput>gmake postgres-US.ps</userinput></screen>
      </para>
     </listitem>
  
     <listitem>
      <para>
       pour créer un <acronym>PDF</acronym>&nbsp;:
<screen><prompt>doc/src/sgml$ </prompt><userinput>gmake postgres-A4.pdf</userinput></screen>
       ou
<screen><prompt>doc/src/sgml$ </prompt><userinput>gmake postgres-US.pdf</userinput></screen>
       (Bien entendu, la version <acronym>PDF</acronym> peut être obtenue 
       à partir d'un document PostScript, mais la génération directe permet de
       bénéficier des liens et autres fonctionnalités avancées dans le
       <acronym>PDF</acronym>.)
      </para>
     </listitem>
    </itemizedlist>
   </para>
   
   <para>
    Lors de l'utilisation de JadeTeX pour la construction de la documentation
    PostgreSQL, il est probablement nécessaire d'augmenter la valeur de certains
    paramètres internes de TeX. Ils sont configurables dans le fichier
    <filename>texmf.cnf</filename>. Les paramètres suivants ont fonctionné
    quand ce texte a été écrit&nbsp;:
<programlisting>
hash_extra.jadetex  = 200000
hash_extra.pdfjadetex  = 200000
pool_size.jadetex = 2000000
pool_size.pdfjadetex = 2000000
string_vacancies.jadetex = 150000
string_vacancies.pdfjadetex = 150000
max_strings.jadetex = 300000
max_strings.pdfjadetex = 300000
save_size.jadetex = 15000
save_size.pdfjadetex = 15000
</programlisting>
   </para>
  </sect2>

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

   <para>
    Une version imprimable de la documentation de
    <productname>PostgreSQL</productname> peut être obtenue en la convertissant en RTF et en y
    appliquant des corrections de formatage mineures à l'aide d'une suite de logiciels
    de bureau. En fonction des capacités de cette dernière, la documentation
    peut ensuite être convertie dans les formats PostScript et/ou
    <acronym>PDF</acronym>. La procédure ci-dessous décrit cette procédure
    pour <productname>Applixware</productname>.
   </para>

   <note>
    <para>
     Il apparaît que la version actuelle de la documentation de
     <productname>PostgreSQL</productname> produit 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 le fichier de sortie reste vide, c'est que
     ce problème est survenu. (Une génération normale doit prendre 5 à 10
     minutes, ne pas s'avouer vaincu trop vite.)
    </para>
   </note>

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

    <para>
     <application>OpenJade</application> ne précise pas de style par
     défaut pour le corps du texte. Dans le passé, ce problème non diagnostiqué
     engendrait un long processus de génération du sommaire. 
     Grâce à la grande aide des gens d'<productname>Applixware</productname>, le
     symptôme a été diagnostiqué et un contournement est disponible.
    </para>

    <step performance="required">
     <para>
      Produire 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éparer le fichier RTF afin de préciser correctement tous les
      styles et en particulier le style par défaut (default). Si le document
      contient des sections <sgmltag>refentry</sgmltag>, il faut remplacer les
      éléments de formatage qui relient le paragraphe précédent au
      paragraphe courant par un lien entre le paragraphe courant
      et le paragraphe suivant. 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> comme 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 ce cas. 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>
      Ouvrir un nouveau document dans <productname>Applixware
      Words</productname> et y importer le fichier <acronym>RTF</acronym>.
     </para>
    </step>

    <step performance="required">
     <para>
      Produire une nouvelle table des matières avec
      <productname>Applixware</productname>.
     </para>

     <substeps>
      <step>
       <para>
        sélectionner 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&nbsp;;
       </para>
      </step>

      <step>
       <para>
        construire 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électionner les trois premiers
        niveaux de titres pour l'inclusion dans la table des matières. Cela
        remplace les lignes existantes importées du RTF en une table des
        matières issue d'<productname>Applixware</productname>&nbsp;;
       </para>
      </step>

      <step>
       <para>
        Ajuster le formatage de la table des matières à l'aide de 
        <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>. Utiliser 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>
      Sur l'ensemble du document&nbsp;:

      <itemizedlist>
       <listitem>
        <para>
         ajuster les sauts de page&nbsp;;
        </para>
       </listitem>

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

    <step performance="required">
     <para>
      Remplacer 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>
       Supprimer la section d'index du document si elle est vide.
     </para>
    </step>

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

      <substeps>
       <step>
        <para>
         sélectionner un champ de la table des matières&nbsp;;
        </para>
       </step>

       <step>
        <para>
         sélectionner le menu <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
         Building</guisubmenu><guimenuitem>Create Table of
         Contents</guimenuitem></menuchoice>&nbsp;;
        </para>
       </step>

       <step>
        <para>
         délier la table des matières en sélectionnant le menu
         <menuchoice><guimenu>Tools</guimenu><guisubmenu>Field
         Editing</guisubmenu><guimenuitem>Unprotect</guimenuitem></menuchoice>&nbsp;;
        </para>
       </step>

       <step>
        <para>
         supprimer 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>
      Sauvegarder le document au format natif <productname>Applixware
      Words</productname> pour que les modifications de dernière minute soient
      plus faciles par la suite.
     </para>
    </step>

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

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

   <para>
    Plusieurs fichiers sont distribués comme fichiers texte pour être lus lors
    de la phase d'installation. Le fichier <filename>INSTALL</filename>
    correspond au <xref linkend="installation"/>, avec quelques changements
    mineurs pour tenir compte de contextes différents. Pour recréer le
    fichier, se placer dans le répertoire <filename>doc/src/sgml</filename> et
    entrer la commande <userinput>gmake INSTALL</userinput>. Ceci crée
    un fichier <filename>INSTALL.html</filename> qui peut être enregistré au
    format texte avec <productname>Netscape Navigator</productname> pour 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, qui ne prend que quelques secondes, 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 OpenSource. 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 permet d'utiliser
     <application>Emacs</application> pour insérer des balises et en vérifier la
     cohérence. Il peut aussi être utilisé pour le
     <acronym>HTML</acronym>. Visiter 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>
     L'auteur de <productname>PSGML</productname> suppose que le 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, le répertoire
     <filename>/usr/local/share/sgml</filename>est utilisé, il faut modifier la
     variable d'environnement <envar>SGML_CATALOG_FILES</envar> ou
     personnaliser l'installation de <productname>PSGML</productname> (son manuel
     indique la procédure).
    </para>

    <para>
     Ajouter les lignes suivantes dans le fichier d'environnement
     <filename>~/.emacs</filename> (en ajustant les noms des répertoires pour
     qu'il convienne au 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 ajouter 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
  '(("\\.xml$" . sgml-mode)
   ))
</programlisting>
    </para>

    <para>
     La distribution <productname>PostgreSQL</productname>  inclut un fichier
     DTD pré-traité contenant des définitions appelé
     <filename>reference.ced</filename>. Il peut s'évérer plus
     confortable pour gérer des fichiers séparés d'insérer une déclaration
     <literal>DOCTYPE</literal> propre lors de l'édition d'un fichier avec
     <productname>PSGML</productname>. Si l'on considère le fichier source de
     cette annexe, par exemple, il est possible de préciser 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 V4.2//EN"&gt;
</programlisting>

     Ceci signifie que, quelque soit l'outil lisant le 
     <acronym>SGML</acronym>, il le fait correctement et que la
     validité du document peut être vérifiée avec 
     <command>nsgmls -s docguide.xml</command>. (Cependant, il faut 
     supprimer la ligne avant de fabriquer le document complet à partir des
     différents fichiers.)
    </para>
   </sect2>

   <sect2>
    <title>Autres modes pour Emacs</title>
    <para>
     <productname>GNU Emacs</productname> dispose d'un mode
     <acronym>SGML</acronym> natif différent qui n'est pas aussi puissant que
     <productname>PSGML</productname>, mais qui a le bénéfice d'être plus simple
     et léger. Il offre la coloration syntaxique (en mode font lock), ce qui
     peut être utile.
    </para>

    <para>
     Norm Walsh propose <ulink
     url="http://nwalsh.com/emacs/docbookide/index.html">un mode majeur
     spécifique à DocBook</ulink> qui dispose également de la coloration
     syntaxique et d'un certain nombre de fonctions permettant de réduire le
     temps de saisie.
    </para>
   </sect2>

 </sect1>

 <sect1 id="docguide-style">
  <title>Guide des styles</title>

  <sect2>
   <title>Pages de références</title>

   <para>
    Les pages de références obéissent à des règles de standardisation.
    De cette façon, les utilisateurs retrouvent plus rapidement l'information
    souhaitée, et cela encourage également les rédacteurs à documenter tous
    les aspects relatifs à une commande. Cette cohérence n'est pas uniquement
    souhaitée pour les pages de références
    <productname>PostgreSQL</productname>, mais également pour les pages de
    références fournies par le système d'exploitation et les autres paquetages.
    C'est pour cela que les règles suivantes ont été développées. Elles sont, pour la
    plupart, cohérentes avec les règles similaires établies pour
    différents systèmes d'exploitation.
   </para>

   <para>
    Les pages de référence qui décrivent des commandes exécutables doivent
    contenir les sections qui suivent dans l'ordre indiqué. Les sections qui ne sont pas
    applicables peuvent être omise