Introduction au Projet de Documentation de FreeBSD pour les nouveaux participants

Version française de Frédéric Haby `<frederic.haby@mail.dotcom.fr>`.

Vous avez reçu du courrier.
% su
Password:
# make JADETEX=yes install
# make JADETEX=no install
% rm /tmp/foo
<para>Pour effacer <filename>/tmp/foo</filename>, utilisez
 &man.rm.1;.</para>

<para><command>rm /tmp/foo</command></para>
C'est un paragraphe. Il commence avec la marque de début pour
 l'élément 'p', et se terminera avec la marque de fin pour
 l'élément 'p'

C'est un autre paragraphe. Mais il est beaucoup plus
 court.
C'est un paragraphe.

<hr>

C'est un autre paragraphe. Une ligne horizontale le sépare
 du précédent.
C'est un paragraphe simple où certains
 mots ont été mis en valeur.
L'attribut align est superflus pour ce paragraphe,
 puisque 'left' est la valeur par défaut.

<p align="center">Ce paragraphe sera peut-être centré.</p>
<p align='right'>Je suis &agrave; droite&nbsp;!</p>
SGML_ROOT=/usr/local/share/xml
SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES
export SGML_CATALOG_FILES
setenv SGML_ROOT /usr/local/share/xml
setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0
  Transitional//EN">

<html>
  <head>
    <title>Exemple de fichier HTML</title>
  </head>

  <body>
    <p>C'est un paragraphe avec du texte.</p>

    <p>C'est encore un paragraphe avec du texte.</p>

    <p align="right">Ce paragraphe sera peut-être justifié &agrave;
      droite.</p>
  </body>
</html>
% nsgmls -s example.xml
% nsgmls -s example.xml
nsgmls:example.xml:5:4:E: character data is not allowed here
nsgmls:example.xml:6:8:E: end tag for "HEAD" which is not finished
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">
"Propriétaire//Mot-Clé Description//Langue"
PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"
<!DOCTYPE html SYSTEM "/path/to/file.dtd">

<!-- C'est le texte du commentaire -->

<!-- C'est un autre commentaire -->

<!-- Voici une façon de mettre un commentaire
     sur plusieurs lignes -->

<!-- Voici une autre façon --
  -- de le faire -->
>!-- C'est en commentaire --

     CE N'EST PAS EN COMMENTAIRE!

  -- retour au commentaire -->
<!CE N'EST PAS EN COMMENTAIRE>
<!----- C'est un très mauvaise idée ----->
<!--===================================================-->
<para>La version courante de notre produit est la
  &version.courante;.</para>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY version.courante    "3.0-RELEASE">
<!ENTITY derniere.version  "2.2.7-RELEASE">
]>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % param.du "du">
<!ENTITY % param.texte "text">
<!ENTITY % param.encore  "encore %param.du more %param.texte">
]>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY version "1.1">
]>

<html>
  <head>
    <title>Exemple de fichier HTML</title>
  </head>

  <body>
    <p>C'est un paragraphe avec du texte.</p>

    <p>C'est encore un paragraphe avec du texte.</p>

    <p align="right">Ce paragraphe sera peut-être justifié &agrave;
      droite</p>

    <p>La version courante de ce document est : &version;</p>
  </body>
</html>
% sgmlnorm exemple.xml > exemple.html
% sgmlnorm -d exemple.xml > exemple.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY chapitre.1 SYSTEM "chapitre1.xml">
<!ENTITY chapitre.2 SYSTEM "chapitre2.xml">
<!ENTITY chapitre.3 SYSTEM "chapitre3.xml">
]>

<html>
  &chapitre.1;
  &chapitre.2;
  &chapitre.3;
</html>
<!ENTITY chapitre.1 SYSTEM "chapitre1.xml">
<!ENTITY chapitre.2 SYSTEM "chapitre2.xml">
<!ENTITY chapitre.3 SYSTEM "chapitre3.xml">
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % chapitres SYSTEM "chapitres.ent">
%chapitres;
]>

<html>
  &chapitre.1;
  &chapitre.2;
  &chapitre.3;
</html>
<p>C'est le premier paragraphe.</p>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.xml">
<!ENTITY para2 SYSTEM "para2.xml">
<!ENTITY para3 SYSTEM "para3.xml">
]>

<html>
  <head>
    <title>Exemple de fichier HTML</title>
  </head>

  <body>
    <p>La version courante de ce document est : &version;</p>

    &para1;
    &para2;
    &para3;
  </body>
</html>
% sgmlnorm -d exemple.xml > exemple.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % entites SYSTEM "entites.xml"> %entites;
]>

<html>
  <head>
    <title>Exemple de fichier HTML</title>
  </head>

  <body>
    <p>La version courant de ce document est : &version;</p>

    &para1;
    &para2;
    &para3;
  </body>
</html>
<!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.xml">
<!ENTITY para2 SYSTEM "para2.xml">
<!ENTITY para3 SYSTEM "para3.xml">
% sgmlnorm -d exemple.xml > exemple.html
<![ MOT-CLE [
  Contenu de la section marquée
]]>
<para>Voici un exemple de la façon dont vous pourriez inclure
  un texte comportant de nombreux &lt; et &amp;. L'exemple
  lui-même est en HTML. Le texte qui l'encadre (<para> et
  <programlisting>) est du DocBook.</para>

<programlisting>
  <![CDATA[
    <p>Cet exemple vous montre quelques éléments de HTML. Comme les
      caractères < et > y sont si fréquemment utilisés, il est plus
      facile de marquer tout l'exemple comme CDATA plutôt que de se
      servir des entités &agrave; la place de ces caractères dans tout le
      texte.</p>

    <ul>
      <li>C'est un élément de liste</li>
      <li>C'est un second élément de liste</li>
      <li>C'est un troisième élément de liste</li>
    </ul>

    <p>C'est la fin de l'exemple.</p>
  ]]>
</programlisting>
<![ INCLUDE [
  Ce texte sera traité et inclus.
]]>

<![ IGNORE [
  Ce texte ne sera pas traité ou inclus.
]]>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % version.electronique "INCLUDE">
]]>

...

<![ %version.electronique [
 Ce texte ne doit apparaître que dans
 la version électronique du document.
]]>
<!ENTiTY % version.electronique "IGNORE">
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % text.output "INCLUDE">
]>

<html>
  <head>
    <title>Exemple d'utilisation des sections marquées</title>
  </head>

  <body>
    <p>Ce paragraphe <![CDATA[contient de nombreux
      caractères < (< < < < <) il est donc
      plus facile de l'inclure dans une section marquée
      CDATA ]]></p>

    <![IGNORE[
    <p>Ce paragraphe n'apparaîtra jamais dans les
      sorties.</p>
    ]]>

    <![ %sortie.texte [
    <p>Ce paragraphe apparaîtra peut-être dans les
      sorties.</p>

    <p>Cela dépend de l'entité paramètre
      %sortie.texte.</p>
    ]]>
  </body>
</html>
PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
<html>
  <head>
	  <title>Le titre du document</title>
  </head>

  <body>

    …

  </body>
</html>
<h1>Première section</h1>

<!-- Introduction du document -->

<h2>C'est le titre de la première section</h2>

<!-- Contenu de la première section -->

<h3>C'est le titre de la première sous-section</h3>

<!-- Contenu de la première sous-section -->

<h2>C'est le titre de la seconde section</h2>

<!-- Contenu de la seconde section -->
<h1>Première section</h1>

<!-- Introduction du document -->

<h3>Sous-section</h3>

C'est un paragraphe. Il peut contenir pratiquement
 n'importe quel élément.
Un court extrait de la Constitution des Etats-Unis&nbsp;:

<blockquote>Nous le Peuple des Etats-Unis, dans le But de former
 une Union plus parfaite, d'établir la Justice, d'assurer
 la Tranquilité domestique, de défendre chacun, de promouvoir
 le Bien-être général, et de garantir les Bénédictions de
 la Liberté &agrave; nous-mêmes et &agrave; notre Postérité, décidons et
 établissons cette Constitution des Etats-Unis d'Amérique.</blockquote>
Une liste non ordonnée. Les éléments de la liste seront
 probablement précédés par des puces.

<ul>
  <li>Premier élément</li>

  <li>Second élément</li>

  <li>Troisième élément</li>
</ul>

Une liste ordonnée, dont les éléments comportent plusieurs paragraphes.
 Chaque élément (note : et non chaque paragraphe) sera numéroté.

<ol>
 <li>C'est le premier élément. Il n'a qu'un paragraphe..</li>

  <li><p>C'est le premier paragraphe du second élément.</p>

    <p>C'est le second paragraphe du second élément.</p>

  <li><p>C'est le premier et seul paragraphe du troisième élément.</p></li>
</ol>
<dl>
  <dt>Terme 1</dt>

  <dd><p>Paragraphe 1 de la définition 1.</p></dd>

    <p>Paragraphe 2 de la définition 1.</p></dd>

  <dt>Terme 2</dt>

  <dd><p>Paragraphe 1 de la définition 2.</p></dd>

  <dt>Terme 3</dt>

  <dd>Paragraphe 1 de la définition 3. Remarquez que l'élément <p> n'est
    pas obligatoire dans le cas d'un paragraphe unique.</dd>
</dl>
<pre>
  From: nik@freebsd.org
  To: freebsd-doc@freebsd.org
  Subject: Nouvelle documentation disponible

  Une nouvelle version de mon introduction pour les nouveaux
  participants au Projet de Documentation de FreeBSD est
  disponible &agrave; l'adresse suivante :

    <URL:http://www.freebsd.org/~nik/primer/index.html>

  Commentaires souhaités.

  N
</pre>
<p>C'est une table 2x2 simple.</p>

<table>
  <tr>
    <td>Cellule en haut &agrave; gauche</td>

    <td>Cellule en haut &agrave; droite</td>
  </tr>

  <tr>
    <td>Cellule en bas &agrave; gauche</td>

    <td>Cellule en bas &agrave; droite</td>
  </tr>
</table>
<p>Une grande cellule &agrave; gauche, deux petites cellule &agrave; droite.</p>

<table>
  <tr>
    <td rowspan="2">Grande et mince</td>
  </tr>

  <tr>
    <td>Cellule du haut</td>

    <td>Cellule du bas</td>
  </tr>
</table>
<p>Une grande cellule en haut, deux petites cellules en dessous.</p>

<table>
  <tr>
    <td colspan="2">Cellule du haut</td>
  </tr>

  <tr>
    <td>Cellule du bas &agrave; gauche</td>

    <td>Cellule du bas &agrave; droite</td>
  </tr>
</table>
<p>Sur une grille 3x3, la cellule en haut &agrave; gauche s'étend sur deux
  lignes et deux colonnes. Les autres cellules sont normales.</p>

<table>
  <tr>
    <td colspan="2" rowspan="2">Grande cellule en haut &agrave; gauche</td>

    <td>Cellule en haut &agrave; droite</td>
  </tr>

  <tr>
    <td>Cellule du milieu &agrave; droite</td>
  </tr>

  <tr>
    <td>Cellule en bas &agrave; gauche</td>

    <td>Cellule en bas au milieu</td>

    <td>Cellule en bas &agrave; droite</td>
  </tr>
</table>
<p><em>Ceci</em> est accentué, et
  <strong>cela</strong> l'est encore plus.</p>
<p><b>Ceci</b> est en gras, tandis que <i>cela</i> est
  en italiques.</p>
<p>L'auteur original de ce document est
  Nik Clayton, qui peut être contacté par courrier
  électronique &agrave; l'adresse : <tt>nik@freebsd.org</tt>.</p>
<p>Ce texte est <small>un peu plus petit</small>.
  Mais celui-l&agrave; <big>est un peu plus gros</big>.</p>

Ce texte est un peu plus petit.
 Mais celui-l&agrave; est un peu plus gros.

<p>Ce texte est <font size="2">un peu plus petit</font>.
  Mais celui-l&agrave; <font size="4">est un peu plus gros</font>.</p>
<p>Vous trouverez plus d'informations sur le
  <a href="http://www.freebsd.org/">site Web de FreeBSD</a>.</p>
<p><a name="para1">Ce</a> paragraphe peut être référencé
  par d'autres liens via le nom <tt>para1</tt>.</p>
<p>Vous trouverez plus d'informations au
  <a href="foo.html#para1">premier paragraphe</a> de
  <tt>foo.html</tt>.</p>
<p>Vous trouverez plus d'informations au
  <a href="#para1">premier paragraphe</a> de
  ce document.</p>
PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"
<book>
  <bookinfo>
    <title>Mettez le titre ici</title>

    <author>
      <firstname>Votre prénom</firstname>
      <surname>Votre nom de famille</surname>
      <affiliation>
        <address><email>Votre adresse de courrier
              électronique</email></address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:Votre adresse de courrier
            électronique">Votre nom</holder>
    </copyright>

    <pubdate role="rcs">$Date$</pubdate>

    <releaseinfo>$Id$</releaseinfo>

    <abstract>
      <para>Résumez ici le contenu du
            livre.</para>
    </abstract>
  </bookinfo>

  …

</book>
<article>
  <artheader>
    <title>Mettez le titre ici</title>

    <author>
      <firstname>Votre prénom</firstname>
      <surname>Votre nom de famille</surname>
      <affiliation>
        <address><email>Votre adresse de courrier
              électronique</email></address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:Votre adresse de courrier
            électronique">Votre nom</holder>
    </copyright>

    <pubdate role="rcs">$Date$</pubdate>

    <releaseinfo>$Id$</releaseinfo>

    <abstract>
      <para>Résumez ici le contenu de l'article.</para>
    </abstract>
  </artheader>

  …

</article>
<chapter>
  <title>Le titre du chapitre</title>

...
</chapter>
<chapter>
 <title>C'est un chapitre vide</title>

  <para></para>
</chapter>
<chapter>
  <title>Exemple de chapitre</title>

  <para>Du texte dans le chapitre.</para>

  <sect1>
    <title>Première section (1.1)</title>

    &hellip;
  </sect1>

  <sect1>
    <title>Seconde section (1.2)</title>

    <sect2>
      <title>Première sous-section (1.2.1)</title>

      <sect3>
        <title>Première sous-sous-section (1.2.1.1)</title>

        &hellip;
      </sect3>
    </sect2>

    <sect2>
      <title>Seconde sous-section (1.2.2)</title>

      &hellip;
    </sect2>
  </sect1>
</chapter>
<part>
  <title>Introduction</title>

  <chapter>
    <title>Resumé</title>

    ...
  </chapter>

  <chapter>
    <title>Qu'est-ce que FreeBSD&nbsp;?</title>

    ...
  </chapter>

  <chapter>
    <title>Historique</title>

    ...
  </chapter>
</part>
<para>C'est un paragraphe. Il peut contenir
  presque n'importe quel autre élément.</para> 
<para>Un court extrait de la constitution des Etats-Unis&nbsp;:</para>

<blockquote>
  <title>Préambule &agrave; la Constitution des Etats-Unis</title>

  <attribution>Copié d'un site Web quelque part</attribution>

  <para>Nous le Peuple des Etats-Unis, dans le but de former
    une Union plus parfaite, d'établir la Justice, de garantir
    la Tranquilité domestique, assurer la défense collective,
    promouvoir notre Bien-être général, et conserver &agrave;
    nous-mêmes et &agrave; notre Postérité les bienfaits de la
    Liberté, proclamons et établissons cette Constitution des
    Etats-Unis d'Amérique.</para>
</blockquote>
<warning>
  <para>Installer FreeBSD peut vous donner envie de supprimer
    Windows de votre disque dur.</para>
</warning>
<itemizedlist>
  <listitem>
    <para>C'est le premier élément de la liste.</para>
  </listitem>

  <listitem>
    <para>C'est le second élément de la liste.</para>
  </listitem>
</itemizedlist>

<orderedlist>
  <listitem>
    <para>C'est le premier élément de la liste
      ordonnée.</para>
  </listitem>

  <listitem>
    <para>C'est le second élément de la liste ordonnée.</para>
  </listitem>
</orderedlist>

<procedure>
  <step>
    <para>Faites ceci.</para>
  </step>

  <step>
    <para>Puis cela.</para>
  </step>

  <step>
    <para>Et maintenant cela.</para>
  </step>
</procedure>
<para>Quand vous aurez fini, votre programme
 ressemblera &agrave; cela :</para>

<programlisting>#include &lt;stdio.h&gt;

int
main(void)
{
    printf("bonjour, le monde\n");
}</programlisting>
#include <stdio.h>

int
main(void)
{
    printf("bonjour, le monde\n");
}
<informaltable>
  <tgroup cols="2">
    <thead>
      <row>
        <entry>C'est le titre de la colonne 1</entry>
        <entry>C'est le titre de la colonne 2</entry>
      </row>
    </thead>

    <tbody>
      <row>
        <entry>Ligne 1, colonne 1</entry>
        <entry>Ligne 1, colonne 2</entry>
      </row>

      <row>
        <entry>Ligne 2, colonne 1</entry>
        <entry>Ligne 2, colonne 2</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>
<screen>&prompt.user; <userinput>ls -1</userinput>
foo1
foo2
foo3
&prompt.user; <userinput>ls -1 | grep foo2</userinput>
foo2
&prompt.user; <userinput>su</userinput>
<prompt>Password: </prompt>
&prompt.root; <userinput>cat foo2</userinput>
C'est le fichier 'foo2'</screen>
% ls -1
foo1
foo2
foo3
% ls -1 | grep foo2
foo2
% su
Password: 
# cat foo2
C'est le fichier 'foo2'
<para>FreeBSD est sans aucun doute
  <emphasis>le</emphasis> premier système
  d'exploitation de type Unix pour
  architecture Intel.</para>
PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"
<!DOCTYPE book PUBLIC
  "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [

<!ENTITY % man PUBLIC
  "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;

…

]>
<para><application>Sendmail</application> est le logiciel de
  courrier électronique le plus employé sous Unix.</para>

<para><application>Sendmail</application> comporte les
  programmes <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry> et &man.newaliases.8;.</para>

<para>L'un des paramètres de la ligne de commande de
  <citerefentry><refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum></citerefentry>,
    <option>-bp</option>, affiche l'état des messages
    dans la file d'attente. Vérifiez-le en exécutant
    <command>sendmail -bp</command>.</para>
<para>Vous trouverez le source SGML du Manuel
  de Référence en Anglais dans
  <filename>/usr/doc/en/handbook/</filename>. Le
  fichier principal, dans ce répertoire, s'appelle
  <filename>handbook.xml</filename>. Il doit aussi
  y avoir un <filename>Makefile</filename> et un
  certain nombre de fichiers avec l'extension
  <filename>.ent</filename>.</para>
<para><devicename>sio</devicename> sert
  sous FreeBSD aux communications séries.
  <devicename>sio</devicename> correspond
  &agrave; un certain nombre d'entrées dans
  <filename>/dev</filename>, dont
  <filename>/dev/ttyd0</filename> et
  <filename>/dev/cuaa0</filename>.</para>

<para>A l'inverse, les périphériques réseaux, tel que
  <devicename>ed0</devicename> n'apparaissent pas dans
  <filename>/dev</filename>.</para>

<para>Sous MS-DOS, le premier lecteur de disquette s'appelle
 <devicename>a:</devicename>. Sous FreeBSD, c'est
 <filename>/dev/fd0</filename>.</para>
<para>La machine locale peut toujours
 être désignée par <hostid>localhost</hostid>,
 et aura l'adresse IP
 <hostid role="ipaddr">127.0.0.1</hostid>.</para>

<para>Le domaine
  <hostid role="domainname">FreeBSD.org</hostid>
  inclut un certain nombre de machine, dont
  <hostid role="fqdn">freefall.FreeBSD.org</hostid> et
  <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>

<para>Quand vous ajoutez un alias IP &agrave; une interface (avec
  <command>ifconfig</command>), utilisez
  <emphasis>toujours</emphasis> le masque de sous-réseau
  <hostid role="netmask">255.255.255.255</hostid>
  (qui peut aussi s'écrire
  <hostid role="netmask">0xffffffff)</hostid>.</para>

<para>L'adresse MAC identifie de façon unique
  chaque carte réseau existante.  Une adresse MAC
  ressemble typiquement &agrave; <hostid
    role="mac">08:00:20:87:ef:d0</hostid>.</para>
<para>Pour effectuer la plupart des
  tâches d'administration système,
  vous aurez besoin d'être
  <username>root</username>.</para>
<para>Il y a deux cibles courantes dans les
  <filename>Makefile</filename>&nbsp;:
  <maketarget>all</maketarget> et
  <maketarget>clean</maketarget>.</para>

<para>Généralement, invoquer <maketarget>all</maketarget>
  reconstruit l'application, et invoquer
  <maketarget>clean</maketarget> supprime les
  fichiers temporaires (<filename>.o</filename>
  par exemple) créés lors de la reconstruction.</para>

<para><maketarget>clean</maketarget> peut être
  contrôlée par un certain nombre
  de variables, dont <makevar>CLOBBER</makevar> et
  <makevar>RECURSE</makevar>.</para>
<para>La ligne <literal>maxusers 10</literal> du fichier
  de configuration du noyau détermine la table de nombreuses
  tables système et définit approximativement le nombre de
  connexions simultanées qu'acceptera le système.</para>
<informalexample>
  <screen>&prompt.user; <userinput>man
  <replaceable>command</replaceable></userinput></screen>
</informalexample>
% man command
<para>La ligne <literal>maxusers 10</literal> du fichier
  de configuration du noyau détermine la table de nombreuses
  tables système et définit approximativement le nombre
  de connexions simultanées qu'acceptera le système.</para>

<para><literal>32</literal> est un valeur correcte de
  <replaceable>n</replaceable> pour une station
  de travail.</para>
<chapter id="chapitre1">
  <title>Introduction</title>

  <para>C'est l'introduction. Elle comporte une sous-section,
    qui a aussi un identifiant.</para>

  <sect1 id="chapter1-sect1">
    <title>Sous-section 1</title>

    <para>C'est la sous-section.</para>
  </sect1>
</chapter>
<para>Ce paragraphe inclut un
  <anchor id="para1">lien interne. Il n'apparaît
  pas dans le document.</para>
<para>Vous trouverez plus d'information
  au <xref linkend="chapter1">.</para>

<para>Vous trouverez des informations plus détaillées dans
  <xref linkend="chapter1-sect1">.</para>
<para>Vous trouverez plus d'information
  au <link linkend="chapter1">premier chapitre</link>.</para>

<para>Vous trouverez des informations plus détaillées dans
  <link linkend="chapter1-sect1">cette</link>
  section.</para>
<para>Vous pouvez bien sûr cessez de lire
  ce document, et aller au lieu de cela sur la <ulink
    url="http://www.FreeBSD.org/"> page Web de FreeBSD</ulink>.</para>
<chapter id="kernelconfiguration">
...
</chapter>
+--- 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>
      doc/
          sv/
	     Makefile
	     FAQ/
	         Makefile
		 *.xml
% cd doc
% tar cf swedish-docs.tar sv
% gzip -9 swedish-docs.tar
<!--
     The FreeBSD Documentation Project

     $Id: chapter.xml,v 1.11 1999/06/20 21:18:57 billf Exp $
-->
<--
     The FreeBSD Spanish Documentation Project

     $Id: chapter.xml,v 1.3 1999/06/24 19:12:32 jesusr Exp $
     Original revision: 1.11
-->

Utilisateur	Invite
Utilisateur normal	`%`
`root`	`#`

Signification	Exemples
Noms de commandes, fichiers et répertoires. Affichage à l'écran de l'ordinateur.	Modifiez votre fichier `.login`. Utilisez `ls -a` pour avoir la liste de tous les fichiers. Vous avez reçu du courrier.
Ce que vous tapez, par opposition à ce que l'ordinateur affiche.	`%` `su` Password:
Références aux pages de manuel	Utilisez su(1) pour changer de nom d'utilisateur.
Noms d'utilisateurs et de groupes	Seul `root` peut le faire.
Mise en valeur	Vous devez le faire.
Variables sur la ligne de commande ; à remplacer par le nom ou la valeur effectif.	Pour supprimer un fichier, tapez `rm nom_du_fichier`.
Variables d'environnement	`$HOME` est votre répertoire utilisateur.

Colonne	Signification
1	Nom du programme qui a généré l'erreur. Ce sera toujours `nsgmls`.
2	Nom du fichier où se trouve l'erreur.
3	Numéro de la ligne où se trouve l'erreur.
4	Numéro de la colonne où se trouve l'erreur.
5	Une lettre donnant le type de message d'erreur. `I` pour un message d'information, `W` pour un message d'avertissement, `E` pour un message d'erreur et `X` pour les références croisées. (Ce n'est cependant pas toujours la cinquième colonne. `nsgmls -sv` affiche `nsgmls:I: SP version "1.3"` - selon la version installée. Comme vous pouvez le constater, c'est un message d'information.) Vous voyez donc que nous avons dans notre exemple des messages d'erreurs.
6	Le texte du message d'erreur.

9.1.	Pourquoi une FAQ ?
	De plus en plus de gens s'adressent à la liste de diffusion du groupe de documentation de FreeBSD et se proposent de traduire en d'autres langues la documentation de FreeBSD. Le but de cette FAQ est de répondre à leurs questions de façon à ce qu'ils puissent commencer le plus rapidement possible à traduire la documentation.
9.2.	Que signfient i18n et l10n ?
	i18n veut dire internationalisation et l10n localisation. Ce ne sont que des abréviations commodes. i18n se lit “i” suivi de 18 lettres, suivies d'un “n”. De la même façon, l10n se lit “l” suivi de 10 lettres, suivies d'un “n”.
9.3.	Y-a-t-il une liste de diffusion pour les traducteurs ?
	Oui, `<freebsd-translate@ngo.org.uk>`. Inscrivez-vous en envoyant un message à `<freebsd-translate-request@ngo.org.uk>` avec le mot `subscribe` dans le texte du message. Vous recevrez une réponse vous demandant de confirmer votre inscription (de la même façon que pour les listes de FreeBSD sur `FreeBSD.org`). La langue de base sur la liste est l'Anglais, mais les messages en d'autres langues sont acceptés. La liste n'est pas modérée, mais vous devez vous y être inscrit avant d'y adresser des messages. La liste est archivée, mais il n'est pas actuellement possible d'y faire des recherches. Vous aurez en retour des explications sur la façon d'accéder aux archives en envoyant le message `help` à `<majordomo@ngo.org.uk>`. Il est prévue que la liste de diffusion soit transférée sur `FreeBSD.org` et devienne donc officielle dans un avenir proche.
9.4.	A-t-on besoin de nouveaux traducteurs ?
	Oui. Plus il y a de gens qui travaillent aux traductions, plus vite elles sont réalisées, et synchronisées avec les modifications de la version anglaise. Il n'est pas nécessaire que vous soyez traducteur professionnel pour pouvoir contribuer.
9.5.	Quelle langue faut-il que je connaisse ?
	Dans l'idéal, il faudrait que vous ayez une bonne connaissance de l'anglais écrit et bien sûr, il faut que vous pratiquiez couramment la langue dans laquelle vous traduisez. L'anglais n'est pas strictement indispensable. Vous pourriez par exemple effectuez une traduction en Hongrois, à partir de la traduction espagnole de la FAQ.
9.6.	Quels logiciels faut-il que je connaisse ?
	Il est fortement recommandé que vous teniez à jour une copie locale des archives CVS de FreeBSD (au moins de la documentation), soit à l'aide de CTM, soit en utilisant CVSup. Le chapitre “Se synchroniser avec la version `-current` de FreeBSD” du Manuel de Référence vous explique comment utiliser ces logiciels. Il faudra que vous soyiez à l'aise avec CVS. Cela vous permettra de suivre les modifications apportées entre les différentes versions des fichiers qui constituent la documentation. [A Faire -- écrire un mode d'emploi qui explique comment utiliser CVSup pour ne récupérer que la documentation, et voir ce qui a évolué entre deux versions données]
9.7.	Comment savoir qui d'autre traduit la documentation dans la même langue ?
	La page des traductions du Projet de Documentation liste les traductions en cours déjà connues. S'il y a déjà d'autres personnes qui travaillent à la traduction de documentation dans votre langue, s'il vous plaît, ne faites pas le même travail qu'eux en double. Au lieu de cela, prenez contact avec eux, pour savoir comment vous pouvez les aider. S'il la page n'indique personne qui travaille dans votre langue, envoyez un message à la liste de diffusion du groupe de documentation de FreeBSD au cas où quelqu'un aurait déjà envisagé de commencer une traduction, mais que ne ce soit pas encore signalé.
9.8.	Il n'y a personne d'autre qui traduise dans ma langue. Que faire ?
	Félicitations, vous venez juste de lancer le “Projet de Documentation `dans-votre-langue` de FreeBSD. Bien venu à bord. Commencez par vous assurer que vous avez bien du temps disponible. Comme vous êtes pour le moment le seul volontaire pour la traduction dans votre langue, il sera de votre responsabilité de publier votre travail et de coordonner celui d'autres personnes qui voudraient y collaborer. Envoyez un courrier électronique à la liste de diffusion du groupe de documentation de FreeBSD pour annoncer que vous allez traduire la documentation de façon à ce que la pages des traductions du Projet de Documentation puisse être tenue à jour. Il faudra vous inscrire à la liste de diffusion `<freebsd-translate@ngo.org.uk>` (comme expliqué plus haut). S'il y a déjà dans votre pays quelqu'un qui maintienne un site miroir de FreeBSD, vous devriez le contacter et voir s'il peut vous fournir un hébergement pour votre projet et, si possible, une adresse de courrier électronique et la possibilité de mettre en place une liste de diffusion. Choisissez ensuite une documentation et commencez la traduction. Il vaut mieux commencer par quelque chose de pas trop volumineux—soit la FAQ, soit l'un des guides.
9.9.	J'ai traduit une documentation, à qui dois-je l'envoyer ?
	Cela dépend. Si vous travaillez déjà au sein d'une équipe de traduction (comme l'équipe Japonaise ou l'équipe Allemande), elle aura ses propres procédures pour gérer la documentation soumise, qui seront décrites dans ses pages Web. Si vous êtes la seule personne à travailler dans une langue donnée (ou si vous êtes responsable d'un projet de traduction et voulez soumettre votre travail au Projet FreeBSD), vous devez alors l'envoyer au Projet FreeBSD (voir la question suivante).
9.10.	Je suis la seule personne à traduire dans cette langue, comment soumettre mes traductions ? ou Nous sommes une équipe de traduction et voulons soumettre les traductions de nos membres ?
	Commencez par vérifier que vos traductions sont correctement structurées. C'est-à-dire qu'elles doivent s'intégrer à l'arborescence des documentations existantes et compiler sans problèmes. La documentation de FreeBSD est actuellement archivée dans les répertoires en dessous de `doc/`. Les sous-répertoires de celui-ci prennent le nom codifiant la langue dans laquelle les documentations sont écrites, selon la norme ISO639 (`/usr/share/misc/iso639`, pour les versions de FreeBSD postérieures au 20 Janvier 1999). S'il ya a différentes codifications pour votre langue (le Chinois,par exemple), il y aura au niveau en-dessous plusieurs sous-répertoires, un pour chacun des formats de codage que vous aurez fournis. Vous aurez enfin des sous-répertoires pour chaque document. Une éventuelle traduction en Suédois ressemblerait par exemple à ce qui suit : doc/ sv/ Makefile FAQ/ Makefile .xml `sv` est le code ISO639 pour le Suédois. Remarquez les deux `Makefile`s, qui servent à compiler la documentation. Il n'y a qu'une seule façon de coder le Suédois, il n'y a donc pas de niveau intermédiaire entre les répertoires `sv` et `FAQ`^[4]. Utilisez tar(1) et gzip(1) pour compresser votre documentation, et envoyez-la au projet. `%` `cd doc`* `%` `tar cf swedish-docs.tar sv` `%` `gzip -9 swedish-docs.tar` Mettez `swedish-docs.tar.gz` quelque part. Si vous ne disposez pas d'espace sur le Web (votre fournisseur d'accès n'en met peut-être pas à votre disposition), vous pouvez envoyer un courrier électronique à Nik Clayton, pour vous mettre d'accord sur une date pour les lui envoyer par courrier. De quelque façon que vous procédiez, il faudra que vous utilisez send-pr(1) pour envoyer un rapport signalant que vous avez soumis de la documentation. Il serait très utile que d'autres puissent relire votre traduction d'abord, parce qu'il y a peu de chances que la personne qui l'intégrera connaisse bien votre langue. Quelqu'un (probablement le Responsbale du Projet de Documentation, Nik Clayton actuellement), récupérera votre traduction et s'assurera qu'elle compile. En particulier, les points suivants seront examinés : Tous vos fichiers utilisent-ils de chaînes RCS (comme “ID”). `make all` fonctionne-t-il correctement dans le répertoire `sv`. `make install` fonctionne-t-il correctement. S'il y a des problèmes, la personne qui examine votre soumission vous en fera part pour que vous essayiez de les régler. S'il n'y a pas de problèmes, votre traduction sera intégrée aussi vite que possible.
9.11.	Puis-je inclure dans mon texte des considérations propres à la langue ou au pays ?
	Nous préférerions que vous ne le fassiez pas. Supposons par exemple que vous traduisiez le Manuel de Référence en Coréen et que vous vouliez inclure une section sur les revendeurs en Corée dans votre Manuel. Il n'y a pas vraiment de raison pour que cette information ne soit pas aussi présente dans la version anglaise (ou allemande, espagnole, …). Il se peut qu'un anglophone ait besoin d'un exemplaire de FreeBSD alors qu'il se trouve en Corée. Cela permet aussi de mettre en avant la pénétration de FreeBSD dans le monde entier, ce qui n'est pas une mauvaise chose. Si vous avez des informations propres à un pays donné, soumettez-les d'abord sous forme de modifications à la version anglaise du Manuel de Référence (avec send-pr(1)) et traduisez-les ensuite dans votre langue dans le Manuel de Référence dans cette langue. Merci.
9.12.	Comment faut-il coder les caractères propres à une langue ? Dans les documentations, les caractères Non-ASCII doivent apparaître sous forme d'entités SGML. Brièvement, celles-ci sont constituées d'une perluette (&), du nom de l'entité, et d'un point-virgule (;). Les noms des entités sont définis par la norme ISO8879, que vous trouverez dans le catalogue des logiciels portés, sous `textproc/iso8879`. Voici quelques examples : Entité: é L'apparence: é Définition: “e” accent aigu minuscule Entité: É L'apparence: É Définition: “e” accent aigu majuscule Entité: ü L'apparence: ü Définition: “u” tréma minuscule Après installation du logiciel porté “iso8879”, le fichier `/usr/local/share/xml/iso8879` en donne la liste complète.
9.13.	Comment doit-on s'adresser au lecteur ?
	Dans les documents anglais, le “you” est employé, il n'y a qu'une seule forme, à l'inverse d'autres langues. Si vous traduisez dans une langue qui dispose de plusieurs formes, utilisez celle que l'on emploie habituellement dans les documentations techniques. En cas de doute, servez-vous d'une forme de politesse courante.
9.14.	Y'a-t-il des informations supplémentaires à inclure dans les traductions ?
	Oui. Les en-têtes de la version anglaise du document ressembleront à ceci : <!-- The FreeBSD Documentation Project $Id: chapter.xml,v 1.11 1999/06/20 21:18:57 billf Exp $ --> La forme exacte peut changer, mais elles comporteront toujours la ligne “Id” et la phrase `The FreeBSD Documentation Project`. Vos traductions doivent comporter leur propre ligne “Id” et `FreeBSD Documentation Project` doit être remplacé par `The FreeBSD Langue Documentation Project`. Vous devrez aussi ajouter une troisième ligne qui donne la version anglaise d'origine sur laquelle est basée la traduction. Donc, la version espagnole du présent fichier commencerait par : <-- The FreeBSD Spanish Documentation Project $Id: chapter.xml,v 1.3 1999/06/24 19:12:32 jesusr Exp $ Original revision: 1.11 -->

	Préambule à la Constitution des Etats-Unis Nous le Peuple des Etats-Unis, dans le but de former une Union plus parfaite, d'établir la Justice, de garantir la Tranquilité domestique, assurer la défense collective, promouvoir notre Bien-être général, et conserver à nous-mêmes et à notre Postérité les bienfaits de la Liberté, proclamons et établissons cette Constitution des Etats-Unis d'Amérique.
	--Copié d'un site Web quelque part

C'est le titre de la colonne 1	C'est le titre de la colonne 2
Ligne 1, colonne 1	Ligne 1, colonne 2
Ligne 2, colonne 1	Ligne 2, colonne 2

Introduction au Projet de Documentation de FreeBSD pour les nouveaux participants

Nik Clayton

Important:

Préface

1. Invites de l'interpréteur de commandes

2. Conventions Typographiques

3. Notes, avertissements et exemples

Note:

Avertissement:

4. Remerciements

Chapitre 1. Introduction

1.1. Le jeu de documentations de FreeBSD

1.2. Avant de commencer

Chapitre 2. Outils

Utilisez textproc/docproj si possible:

2.1. Outils indispensables

2.1.1. Logiciels

2.1.2. DTDs et Entités

2.1.3. Feuilles de style

2.2. Outils facultatifs

2.2.1. Logiciels

Important:

Chapitre 3. Introduction à SGML

3.1. Introduction

Note:

3.2. Eléments, marques et attributs

Important:

3.2.1. A faire…

3.3. La déclaration DOCTYPE

3.3.1. Formal Public Identifiers (FPIs) - Identifiants Publics Officiels

Note:

3.3.1.1. Fichiers catalog

3.3.1.2. SGML_CATALOG_FILES

3.3.2. Alternatives aux FPIs

3.4. Revenir au SGML

3.5. Commentaires

3.5.1. A faire…

3.6. Entités

3.6.1. Entités Générales

3.6.2. Entités paramètres

3.6.3. A faire…

3.7. Utiliser les entités pour inclure des fichiers

3.7.1. Utiliser les entités générales pour inclure des fichiers

Avertissement:

3.7.2. Utiliser les entités paramètres pour inclure des fichiers

3.7.3. A faire…

3.7.3.1. Utiliser les entités générales pour inclure des fichiers

3.7.3.2. Utiliser les entités paramètres pour inclure des fichiers

Note:

3.8. Sections marquées

3.8.1. Mots-clés pour les sections marquées

3.8.1.1. CDATA, RCDATA

3.8.1.2. INCLUDE et IGNORE

3.8.2. A faire…

3.9. Conclusion

Chapitre 4. Marques SGML

En ligne vs. de bloc:

4.1. HTML

4.1.1. Formal Public Identifier (FPI) - Identifiant Public Formel

4.1.2. Sections

4.1.3. Eléments de blocs

4.1.3.1. Titres

4.1.3.2. Paragraphes

4.1.3.3. Citations

4.1.3.4. Listes

4.1.3.5. Texte pré-formaté

4.1.3.6. Tables

Note:

4.1.4. Eléments

4.1.4.1. Information d'accentuation

4.1.4.2. Gras et italiques

4.1.4.3. Texte en police fixe

4.1.4.4. Taille de police

4.1.5. Liens

Note:

4.1.5.1. Liens vers d'autres documents sur le WWW

4.1.5.2. Liens sur d'autres parties des documents

4.2. DocBook

formel vs. informel:

4.2.1. Extensions FreeBSD

Utilisez `textproc/docproj` si possible:

3.3.1.1. Fichiers `catalog`

3.3.1.2. `SGML_CATALOG_FILES`

3.8.1.1. `CDATA`, `RCDATA`

3.8.1.2. `INCLUDE` et `IGNORE`

`formel` vs. `informel`:

4.2.3.5. Subdivision en `part`s

4.2.5.7. Décrire les `Makefile`s

7.2.1. `Makefile`

7.2.2. `handbook.xml`

7.2.3. `répertoire/chapter.xml`

Chapitre 11. Utiliser `sgml-mode` avec Emacs