path: root/fr_FR.ISO8859-1/books/fdp-primer/the-handbook/chapter.sgml

<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.

     Redistribution and use in source (SGML DocBook) and 'compiled' forms
     (SGML HTML, PDF, PostScript, RTF and so forth) with or without
     modification, are permitted provided that the following conditions
     are met:

      1. Redistributions of source code (SGML DocBook) must retain the above
         copyright notice, this list of conditions and the following
         disclaimer as the first lines of this file unmodified.

      2. Redistributions in compiled form (transformed to other DTDs,
         converted to PDF, PostScript, RTF and other formats) must reproduce
         the above copyright notice, this list of conditions and the
         following disclaimer in the documentation and/or other materials
         provided with the distribution.

     THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
     INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
     SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
     STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
     ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
     POSSIBILITY OF SUCH DAMAGE.

     $FreeBSD$
-->

<chapter id="the-handbook">
  <title>* Le Manuel de Référence</title>

  <sect1>
    <title>Organisation logique</title>

    <para>Le Manuel de Référence est rédigé en conformité avec la DTD DocBook
      étendue de FreeBSD.</para>

    <para>Le Manuel de Référence est un <sgmltag>book</sgmltag> DocBook. Il
      est ensuite divisé en <sgmltag>part</sgmltag>s, qui contiennent
      elles-mêmes plusieurs <sgmltag>chapter</sgmltag>s. Les
      <sgmltag>chapter</sgmltag>s sont eux-mêmes composés de sections
      (<sgmltag>sect1</sgmltag>) et sous-sections
      (<sgmltag>sect2</sgmltag>, <sgmltag>sect3</sgmltag>) et ainsi de
      suite.</para>
  </sect1>

  <sect1>
    <title>Organisation physique</title>

    <para>Le Manuel de Référence (et ses traductions) sont dans le
      sous-répertoire
      <filename>doc/<replaceable>langue</replaceable>/handbook</filename>
      des archives CVS principales. <replaceable>langue</replaceable> est le
      code ISO pour la langue, <literal>en</literal>, pour l'Anglais,
      <literal>ja</literal> pour le Japonais, et ainsi de suite.</para>

    <para>Il y a un certain nombre de fichiers et répertoires dans le
      répertoire <filename>handbook</filename>.</para>

    <note>
      <para>L'organisation du Manuel de Référence sera peut-être modifiée avec
        le temps, et le présent document peut ne pas être en phase avec ces
        changements. Si vous avez des questions sur la façon dont le Manuel de
        Référence est organisé, contactez s'il vous plaît le Projet de
        Documentation de FreeBSD, <email>doc@FreeBSD.ORG</email>.</para>
    </note>

    <sect2>
      <title><filename>Makefile</filename></title>

      <para>Le <filename>Makefile</filename> décrit les règles utilisées pour
        convertir le Manuel de Référence &agrave; partir du source (DocBook) dans
        plusieurs formats cibles (dont HTML, PostScript, et texte).</para>

      <para>Le <filename>Makefile</filename> est décrit plus en détail &agrave; la
	<xref linkend="the-handbook-converting"/>.</para>
    </sect2>

    <sect2>
      <title><filename>handbook.sgml</filename></title>

      <para>C'est la racine du Manuel de Référence. Il contient la
	<link linkend="sgml-primer-doctype-declaration">déclaration
          DOCTYPE</link> du Manuel, ainsi que les éléments qui décrivent sa
          structure.</para>

      <para><filename>handbook.sgml</filename> utilise des <link
	  linkend="sgml-primer-parameter-entities">entités paramètres</link>
        pour charger les fichiers d'extensions <filename>.ent</filename>. Ces
        fichiers (décrits plus loin) définissent &agrave; leur tour des
	<link linkend="sgml-primer-general-entities">entités générales</link>
        qui sont elles-mêmes employées dans le reste du Manuel.</para>
    </sect2>

    <sect2>
      <title><filename><replaceable>répertoire</replaceable>/chapter.sgml</filename></title>

      <para>Chaque chapitre du manuel est composé d'un fichier
	<filename>chapter.sgml</filename> dans un sous-répertoire séparé pour
        chaque chapitre. Chaque répertoire prend le nom de l'attribut
	<literal>id</literal> de l'élément <sgmltag>chapter</sgmltag>.</para>

      <para>Si par exemple, un des chapitres contient&nbsp;:</para>

    <programlisting><![ CDATA [
<chapter id="kernelconfiguration">
...
</chapter>]]></programlisting>

      <para>il s'appelera alors <filename>chapter.sgml</filename> dans le
	répertoire <filename>kernelconfiguration</filename>. Habituellement,
        il y aura un seul fichier pour tout le chapitre.</para>

      <para>A la génération de la version HTML du Manuel, on obtiendra un
	<filename>kernelconfiguration.html</filename>. C'est dû &agrave; la valeur
        du <literal>id</literal>, et non au nom du répertoire.</para>

      <para>Dans les versions précédentes du Manuel, ces fichiers étaient dans
        le même répertoire que <filename>handbook.sgml</filename>, avec le
        même nom que l'attribut <literal>id</literal> de l'élément
	<sgmltag>chapter</sgmltag> du fichier. Ils ont été déplacés dans des
        répertoires séparés en prévision des évolutions &agrave; venir du Manuel. Il
        sera en particulier bientôt possible d'inclure des images dans chaque
        chapitre. Il est donc plus logique que celles-ci soient rangées dans
        un répertoire où se trouve aussi le texte du chapitre plutôt que de
        mettre le texte de chaque chapitre, et donc toutes les images dans un
        même répertoire. Il y aurait fatalement des conflits de nom, alors
        qu'il est plus facile de travailler avec plusieurs répertoires
        contenant quelques fichiers qu'avec un seul répertoire dans lequel il
        y a beaucoup de fichiers.</para>

      <para>Un bref coup d'oeil montre qu'il y a de nombreux répertoires avec
        chacun un fichier <filename>chapter.sgml</filename> dont
	<filename>basics/chapter.sgml</filename>,
	<filename>introduction/chapter.sgml</filename> et
	<filename>printing/chapter.sgml</filename>.</para>

      <important>
	<para>Les noms des chapitres et/ou répertoires ne doivent pas faire
          réference &agrave; leur place dans le Manuel. Cet ordre peut changer quand
          le contenu du Manuel est réorganisé&nbsp;; ce type de réorganisation
          ne devrait (normalement) pas entraîner de modification des noms des
          fichiers (&agrave; moins que des chapitres entiers ne changent de niveau
          dans la hiérarchie).</para>
      </important>

      <para>Chaque fichier <filename>chapter.sgml</filename> n'est pas un
        document SGML intégral. Ils n'ont en particulier pas de déclaration
        DOCTYPE en tête du fichier.</para>

      <para>C'est dommage pour deux raisons&nbsp;:</para>

      <itemizedlist>
	<listitem>
	  <para>Il n'est pas possible de les traiter comme des fichiers SGML
            et de les convertir en HTML, RTF, PS et autres formats de la même
            manière que le Manuel. Cela vous <emphasis>oblige</emphasis> &agrave;
            recompiler tout le Manuel chaque fois que vous voulez vérifier les
            effets d'une modification d'un seul chapitre.</para>
	</listitem>

	<listitem>
	  <para>Le <literal>sgml-mode</literal> d'Emacs ne peut pas s'en
            servir pour déterminer quelle DTD utiliser, ce qui fait perdre les
            bénéfices de fonctionnalités utiles du
            <literal>sgml-mode</literal> (complétion des éléments, validation
	    automatique, et ainsi de suite).</para>
	</listitem>
      </itemizedlist>
    </sect2>
  </sect1>

  <sect1>
    <title>Guide de style</title>

    <para>Respectez s'il vous plaît les conventions de style ci-dessous pour
      garder aux sources du Manuel une consistance malgré les nombreuses
      personnes qui interviennent dessus.</para>

    <sect2>
      <title>Majuscules et minuscules</title>

      <para>Les marques doivent être en minuscules
        <literal>&lt;para&gt;</literal> et <emphasis>non</emphasis>
        <literal>&lt;PARA&gt;</literal>.</para>

      <para>Le texte dans les contextes SGML est normalement en majuscules,
	<literal>&lt!ENTITY&hellip;&gt;</literal> ou
	<literal>&lt;!DOCTYPE&hellip;&gt;</literal> et
        <emphasis>non</emphasis> <literal>&lt;!entity&hellip;&gt;</literal>
        ou <literal>&lt;!doctype&hellip;&gt;</literal>.</para>
    </sect2>

    <sect2>
      <title>Indentation</title>

      <para>Chaque fichier est indenté &agrave; partir de la colonne 0,
	<emphasis>quel que soit</emphasis> le niveau d'indentation dans le
        fichier où il est inclus.</para>

      <para>Chaque marque de début augmente l'indentation de 2 blancs et
        chaque marque de fin la décrémente d'autant. Le contenu des éléments
        doit être indenté de 2 blancs s'il court sur plusieurs lignes.</para>

      <para>A titre d'exemple, voici &agrave; quoi ressemble le source de cette
        section&nbsp;:</para>

      <programlisting>
<![ CDATA [+--- C'est la colonne 0

<chapter>
  <title>...</title>

  <sect1>
    <title>...</title>

    <sect2>
      <title>Indentation</title>

      <para>Chaque fichier est indenté &agrave; partir de la colonne 0,
	<emphasis>quel que soit</emphasis> le niveau d'indentation dans le
        fichier où il est inclus.</para>

      <para>Chaque marque de début augmente l'indentation de 2 blancs et
        chaque marque de fin la décrémente d'autant. Le contenu des éléments
        doit être indenté de 2 blancs s'il court sur plusieurs lignes.</para>

      ...
    </sect2>
  </sect1>
</chapter>]]></programlisting>

      <para>Si vous vous servez d'<application>Emacs</application> ou
	<application>Xemacs</application> pour éditer les fichiers, le
	<literal>sgml-mode</literal> doit être chargé automatiquement, et les
        variables Emacs locales en fin de chaque fichier doivent mettre ces
        indentations en pratique.</para>
    </sect2>

    <sect2>
      <title>Modifications de présentation des sources</title>

      <para>Quand vous intégrez des modifications, <emphasis>ne faites pas en
        même temps de modification de contenu et de présentation des
        sources</emphasis>.</para>

      <para>Cela pour que les équipes de traductions du Manuel puissent
        rapidement voir les modifications de contenu que vous avez intégrées,
        sans avoir &agrave; se demander si une ligne a changé de contenu ou
        simplement de présentation.</para>

      <para>Si vous avez par exemple ajouté deux phrases &agrave; un paragraphe, de
        sorte que les lignes du paragraphe débordent maintenant des 80
        colonnes, intégrez d'abord la modification avec les lignes trop
        longues. Puis corrigez ensuite ce problème, en précisant qu'il ne
        s'agit que d'une modification de présentation, dont les équipes de
        traduction n'ont pas &agrave; se soucier.</para>
    </sect2>
  </sect1>

  <sect1 id="the-handbook-converting">
    <title>* Conversion du Manuel dans d'autres formats</title>

    <para></para>
  </sect1>
</chapter>