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

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

     $Id: chapter.sgml,v 1.1 2000-06-12 15:46:54 gioria Exp $
-->

<chapter id="the-handbook">
  <title>* Le Manuel de R&eacute;f&eacute;rence</title>
 
  <sect1>
    <title>Organisation logique</title>

    <para>Le Manuel de R&eacute;f&eacute;rence est r&eacute;dig&eacute; en conformit&eacute; avec la DTD DocBook
      &eacute;tendue de FreeBSD.</para>
    
    <para>Le Manuel de R&eacute;f&eacute;rence est un <sgmltag>book</sgmltag> DocBook. Il
      est ensuite divis&eacute; en <sgmltag>part</sgmltag>s, qui contiennent
      elles-m&ecirc;mes plusieurs <sgmltag>chapter</sgmltag>s. Les
      <sgmltag>chapter</sgmltag>s sont eux-m&ecirc;mes compos&eacute;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&eacute;f&eacute;rence (et ses traductions) sont dans le
      sous-r&eacute;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&eacute;pertoires dans le 
      r&eacute;pertoire <filename>handbook</filename>.</para>

    <note>
      <para>L'organisation du Manuel de R&eacute;f&eacute;rence sera peut-&ecirc;tre modifi&eacute;e avec
        le temps, et le pr&eacute;sent document peut ne pas &ecirc;tre en phase avec ces
        changements. Si vous avez des questions sur la fa&ccedil;on dont le Manuel de
        R&eacute;f&eacute;rence est organis&eacute;, contactez s'il vous pla&icirc;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&eacute;crit les r&egrave;gles utilis&eacute;es pour
        convertir le Manuel de R&eacute;f&eacute;rence &agrave; partir du source (DocBook) dans
        plusieurs formats cibles (dont HTML, PostScript, et texte).</para>

      <para>Le <filename>Makefile</filename> est d&eacute;crit plus en d&eacute;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&eacute;f&eacute;rence. Il contient la
	<link linkend="sgml-primer-doctype-declaration">d&eacute;claration 
          DOCTYPE</link> du Manuel, ainsi que les &eacute;l&eacute;ments qui d&eacute;crivent sa
          structure.</para>

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

    <sect2>
      <title><filename><replaceable>r&eacute;pertoire</replaceable>/chapter.sgml</filename></title>

      <para>Chaque chapitre du manuel est compos&eacute; d'un fichier
	<filename>chapter.sgml</filename> dans un sous-r&eacute;pertoire s&eacute;par&eacute; pour
        chaque chapitre. Chaque r&eacute;pertoire prend le nom de l'attribut
	<literal>id</literal> de l'&eacute;l&eacute;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&eacute;pertoire <filename>kernelconfiguration</filename>. Habituellement,
        il y aura un seul fichier pour tout le chapitre.</para>
      
      <para>A la g&eacute;n&eacute;ration de la version HTML du Manuel, on obtiendra un
	<filename>kernelconfiguration.html</filename>. C'est d&ucirc; &agrave; la valeur
        du <literal>id</literal>, et non au nom du r&eacute;pertoire.</para>

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

      <para>Un bref coup d'oeil montre qu'il y a de nombreux r&eacute;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&eacute;pertoires ne doivent pas faire
          r&eacute;ference &agrave; leur place dans le Manuel. Cet ordre peut changer quand
          le contenu du Manuel est r&eacute;organis&eacute;&nbsp;; ce type de r&eacute;organisation
          ne devrait (normalement) pas entra&icirc;ner de modification des noms des
          fichiers (&agrave; moins que des chapitres entiers ne changent de niveau
          dans la hi&eacute;rarchie).</para>
      </important>
    
      <para>Chaque fichier <filename>chapter.sgml</filename> n'est pas un
        document SGML int&eacute;gral. Ils n'ont en particulier pas de d&eacute;claration
        DOCTYPE en t&ecirc;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&ecirc;me
            mani&egrave;re que le Manuel. Cela vous <emphasis>oblige</emphasis> &agrave;
            recompiler tout le Manuel chaque fois que vous voulez v&eacute;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&eacute;terminer quelle DTD utiliser, ce qui fait perdre les
            b&eacute;n&eacute;fices de fonctionnalit&eacute;s utiles du
            <literal>sgml-mode</literal> (compl&eacute;tion des &eacute;l&eacute;ments, validation
	    automatique, et ainsi de suite).</para>
	</listitem>
      </itemizedlist>
    </sect2>
  </sect1>

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

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

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

      <para>Les marques doivent &ecirc;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&eacute; &agrave; partir de la colonne 0,
	<emphasis>quel que soit</emphasis> le niveau d'indentation dans le
        fichier o&ugrave; il est inclus.</para>

      <para>Chaque marque de d&eacute;but augmente l'indentation de 2 blancs et
        chaque marque de fin la d&eacute;cr&eacute;mente d'autant. Le contenu des &eacute;l&eacute;ments
        doit &ecirc;tre indent&eacute; 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&eacute; &agrave; partir de la colonne 0,
	<emphasis>quel que soit</emphasis> le niveau d'indentation dans le
        fichier o&ugrave; il est inclus.</para>

      <para>Chaque marque de d&eacute;but augmente l'indentation de 2 blancs et
        chaque marque de fin la d&eacute;cr&eacute;mente d'autant. Le contenu des &eacute;l&eacute;ments
        doit &ecirc;tre indent&eacute; 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 &eacute;diter les fichiers, le
	<literal>sgml-mode</literal> doit &ecirc;tre charg&eacute; automatiquement, et les
        variables Emacs locales en fin de chaque fichier doivent mettre ces
        indentations en pratique.</para>
    </sect2>

    <sect2>
      <title>Modifications de pr&eacute;sentation des sources</title>

      <para>Quand vous int&eacute;grez des modifications, <emphasis>ne faites pas en
        m&ecirc;me temps de modification de contenu et de pr&eacute;sentation des
        sources</emphasis>.</para>
      
      <para>Cela pour que les &eacute;quipes de traductions du Manuel puissent 
        rapidement voir les modifications de contenu que vous avez int&eacute;gr&eacute;es,
        sans avoir &agrave; se demander si une ligne a chang&eacute; de contenu ou
        simplement de pr&eacute;sentation.</para>

      <para>Si vous avez par exemple ajout&eacute; deux phrases &agrave; un paragraphe, de
        sorte que les lignes du paragraphe d&eacute;bordent maintenant des 80
        colonnes, int&eacute;grez d'abord la modification avec les lignes trop
        longues. Puis corrigez ensuite ce probl&egrave;me, en pr&eacute;cisant qu'il ne
        s'agit que d'une modification de pr&eacute;sentation, dont les &eacute;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>

<!--
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../book.sgml" "part" "chapter")
     End:
-->