  Introduction au Projet de Documentation de FreeBSD pour les nouveaux
                              participants

  Nik Clayton

   <nik@FreeBSD.ORG>

   Copyright (c) 1998, 1999 Nik Clayton

   Merci de votre participation au Projet de Documentation de
   FreeBSD. Votre contribution est tres utile.

   Cette introduction decrit tout ce que vous devez savoir pour
   commencer `a participer au projet de documentation de FreeBSD, des
   outils et logiciels que vous utiliserez (indispensables et
   facultatifs) `a la philosophie sous-jacente au Projet de
   Documentation.

   Ce document est en cours de redaction et n'est pas termine. Les
   sections inachevees sont indiquees par un asterisque - * - qui
   precede leur nom.

   Version franc,aise de Frederic Haby
   <frederic.haby@mail.dotcom.fr>.

   La redistribution et l'utilisation du code source (SGML), et
   compile (HTML, PostScript, etc.), modifies ou non, sont soumises
   aux conditions suivantes :

    1. Le code source (SGML DocBook) distribue doit conserver le
       copyright ci-dessus, la presente liste de conditions et
       l'avertissement qui la suit, sans modifications, en tete de ce
       fichier.

    2. Le code source distribue sous forme compile (transformation
       vers d'autres DTDs, conversion en PDF, PostScript, RTF et
       autres formats) doit faire apparaitre dans la documentation
       et/ou les autres composants distribues, le copyright
       ci-dessus, la presente liste de conditions et l'avertissement
       qui la suit.

     Important : CE DOCUMENT EST FOURNI PAR NIK CLAYTON ``TEL QUEL''
     ET AUCUNE GARANTIE EXPRESSE OU IMPLICITE, Y COMPRIS, MAIS NON
     LIMITEE, GARANTIES IMPLICITES DE COMMERCIABILITE ET D'ADEQUATION
     A UN BUT PARTICULIER N'EST DONNEE. EN AUCUN CAS NIK CLAYTON NE
     SAURAIT ETRE TENU RESPONSABLE DES DOMMAGES DIRECTS, INDIRECTS,
     ACCIDENTELS, SPECIAUX, EXEMPLAIRES OU CONSEQUENTS (Y COMPRIS,
     MAIS SANS LIMITATION, LA FOURNITURE DE BIENS ET SERVICES
     ANNEXES  DEFAUT D'UTILISABILITE, PERTE DE DONNEES OU DE
     PROFITS ; OU INTERRUPTION DE TRAVAIL) QUELLE QU'EN SOIT LA CAUSE
     ET SELON TOUTE DEFINITION DE RESPONSABILITE, SOIT PAR CONTRAT,
     RESPONSABILITE STRICTE, OU PREJUDICE (Y COMPRIS NEGLIGENCE OU
     AUTRES) IMPUTABLES D'UNE FAC,ON OU D'UNE AUTRE A L'UTILISATION
     DE CE DOCUMENT, MEME APRES AVOIR ETE AVISE DE LA POSSIBILITE DE
     TELS DOMMAGES.

     --------------------------------------------------------------

   Table des matieres

   Preface

                Invites de l'interpreteur de commandes

                Conventions Typographiques

                Notes, avertissements et exemples

                Remerciements

   1. Introduction

                1.1. Le jeu de documentations de FreeBSD

                1.2. Avant de commencer

   2. Outils

                2.1. Outils indispensables

                             2.1.1. Logiciels

                             2.1.2. DTDs et Entites

                             2.1.3. Feuilles de style

                2.2. Outils facultatifs

                             2.2.1. Logiciels

   3. Introduction `a SGML

                3.1. Introduction

                3.2. Elements, marques et attributs

                             3.2.1. A faire...

                3.3. La declaration DOCTYPE

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

                             3.3.2. Alternatives aux FPIs

                3.4. Revenir au SGML

                3.5. Commentaires

                             3.5.1. A faire...

                3.6. Entites

                             3.6.1. Entites Generales

                             3.6.2. Entites parametres

                             3.6.3. A faire...

                3.7. Utiliser les entites pour inclure des fichiers

                             3.7.1. Utiliser les entites generales
                             pour inclure des fichiers

                             3.7.2. Utiliser les entites parametres
                             pour inclure des fichiers

                             3.7.3. A faire...

                3.8. Sections marquees

                             3.8.1. Mots-cles pour les sections
                             marquees

                             3.8.2. A faire...

                3.9. Conclusion

   4. Marques SGML

                4.1. HTML

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

                             4.1.2. Sections

                             4.1.3. Elements de blocs

                             4.1.4. Elements

                             4.1.5. Liens

                4.2. DocBook

                             4.2.1. Extensions FreeBSD

                             4.2.2. Identifiant Public
                             Formel - Formal Public Indentifier,
                             (FPI)

                             4.2.3. Structure des documents

                             4.2.4. Elements de blocs

                             4.2.5. Elements en ligne

                             4.2.6. Liens

                4.3. * LinuxDoc

   5. * Feuilles de style

                5.1. * DSSSL

                5.2. * CSS

   6. * La Foire Aux Questions

   7. * Le Manuel de Reference

                7.1. Organisation logique

                7.2. Organisation physique

                             7.2.1. Makefile

                             7.2.2. handbook.sgml

                             7.2.3. repertoire/chapter.sgml

                7.3. Guide de style

                             7.3.1. Majuscules et minuscules

                             7.3.2. Indentation

                             7.3.3. Modifications de presentation des
                             sources

                7.4. * Conversion du Manuel dans d'autres formats

   8. * Le site Web

   9. Traductions

   10. Style

   11. Utiliser sgml-mode avec Emacs

   12. A consulter

                12.1. Projet de Documentation de FreeBSD

                12.2. SGML

                12.3. HTML

                12.4. DocBook

                12.5. Le Projet de Documentation de Linux

   Liste des exemples

   1. Un exemple d'exemple

   3-1. Utiliser un element (marques de debut et de fin)

   3-2. Utiliser un element (marque de debut uniquement)

   3-3. Elements dans des elements ; <em>

   3-4. Utiliser un element avec un attribut

   3-5. Simples quotes dans un attribut

   3-6. .profile, pour les utilisateurs de sh(1) et bash(1)

   3-7. .login, pour les utilisateurs de csh(1) et tcsh(1)

   3-8. Commentaire SGML generique

   3-9. Commentaires SGML erronnes

   3-10. Definition d'entites generales

   3-11. Definition d'entites parametres

   3-12. Utiliser les entites generales pour inclure des fichiers

   3-13. Utiliser les entites parametres pour inclure des fichiers

   3-14. Structure d'une section marquee

   3-15. Utiliser une section marquee CDATA

   3-16. Utiliser INCLUDE et IGNORE dans les sections marquees

   3-17. Utiliser une entite parametre pour controler une section
   marquee

   4-1. Structure habituelle d'un document HTML

   4-2. <h1>, <h2>, etc.

   4-3. Mauvais ordonnancement des elements <hn>

   4-4. <p>

   4-5. <blockquote>

   4-6. <ul> et <ol>

   4-7. Listes de definition avec <dl>

   4-8. <pre>

   4-9. Emploi simple de <table>

   4-10. Emploi de rowspan

   4-11. Emploi de colspan

   4-12. Emploi de rowspan et colspan ensemble

   4-13. <em> et <strong>

   4-14. <b> et <i>

   4-15. <tt>

   4-16. <big>, <small> et <font>

   4-17. Emploi de <a href="...">

   4-18. Emploi de <a name="...">

   4-19. Lien sur une partie nommee d'un autre document

   4-20. Lien sur une partie nommee du meme document

   4-21. Boilerplate??? <book> avec <bookinfo>

   4-22. Boilerplate??? <article> avec <artheader>

   4-23. Un chapitre

   4-24. Chapitres vides

   4-25. Sections dans les chapitres

   4-26. <para>

   4-27. <blockquote>

   4-28. <warning>

   4-29. <itemizedlist>, <orderedlist> et <procedure>

   4-30. <programlisting>

   4-31. <informaltable>

   4-32. Tableaux avec frame="none"

   4-33. <screen>, <prompt> et <userinput>

   4-34. <emphasis>

   4-35. Applications, commandes et options.

   4-36. <filename>

   4-37. <devicename>

   4-38. <hostid> et roles

   4-39. <username>

   4-40. <maketarget> et <makevar>

   4-41. <literal>

   4-42. <replaceable>

   4-43. id de chapitres et de section

   4-44. <anchor>

   4-45. Se servir de <xref>

   4-46. Utiliser <link>

   4-47. <ulink>

     --------------------------------------------------------------

                                Preface

Invites de l'interpreteur de commandes

   La table ci-dessous donne les invites par defaut du systeme pour
   un utilisateur normal et pour le super-utilisateur. Elles sont
   utilisees dans les exemples pour indiquer quel utilisateur doit
   appliquer l'exemple.

      Utilisateur     Invite 
   Utilisateur normal %      
   root               #      

     --------------------------------------------------------------

Conventions Typographiques

   La table ci-dessous decrit les conventions typographiques
   utilisees dans le present ouvrage.

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

     --------------------------------------------------------------

Notes, avertissements et exemples

   Dans le cours du texte, il peut y avoir des notes, des
   avertissements et des exemples.

     Note : Les notes apparaissent comme ceci, et contiennent des
     informations que vous devriez prendre en consideration, parce
     qu'elles peuvent avoir une incidence sur ce que vous faites.

     Avertissement : Les avertissements apparaissent comme ceci, et
     vous previennent de problemes potentiels si vous n'appliquez pas
     ces instructions. Des degats peuvent etre causes `a votre
     materiel, ou ne pas etre physiques, suppression inopinee de
     fichiers importants par exemple.

   Exemple 1. Un exemple d'exemple

   Les exemples apparaissent comme ceci, et sont generalement des
   exemples que vous devriez tester ou qui vous montrent quels
   doivent etre les resultats d'une operation donnee.

     --------------------------------------------------------------

Remerciements

   Mes remerciements `a Sue Blake, Patrick Durusau, Jon Hamilton,
   Peter Flynn et Christopher Maden, qui ont pris le temps de lire
   les premieres versions de ce document et ont apporte de nombreux
   commentaires et critiques utiles.

     --------------------------------------------------------------

                        Chapitre 1. Introduction

   Bienvenue au Projet de Documentation de FreeBSD. Une documentation
   de bonne qualite est un facteur important de succes pour FreeBSD,
   et le Projet de Documentation de FreeBSD - ``The FreeBSD
   Documentation Project'' -  est la source d'une grande part de
   cette documentation. Votre participation est importante.

   L'objectif principal de ce document est d'expliquer clairement
   comment est organise le FDP, comment ecrire et soumettre de la
   documentation au FDP et comment utiliser les outils disponibles
   pour produire de la documentation.

   La participation de chacun au FDP est bienvenue. Il n'y a pas de
   cotisation minimum, pas de quota de documentation `a produire par
   mois. Il vous suffit de vous inscrire sur la liste de diffusion du
   groupe de documentation de FreeBSD.

   Apres avoir lu ce document, vous :

     * Saurez quelles sont les documentations maintenues par le FDP.

     * Serez capable de lire et comprendre le code SGML source des
       documentations maintenues par le FDP.

     * Serez capable de modifier la documentation.

     * Saurez comment soumettre vos modifications pour qu'elles
       soient revues et incorporees `a la documentation de FreeBSD.

     --------------------------------------------------------------

1.1. Le jeu de documentations de FreeBSD

   Le FDP a la responsabilite de quatre categories de documents.

   Les pages de manuel

           Les pages de manuel systeme en anglais ne sont pas
           redigees par le FDP, puisqu'elles font partie du systeme
           de base. Le FDP, neanmoins, peut (et a) recrit des pages
           de manuel existantes pour les clarifier ou corriger des
           inexactitudes.

           Les equipes de traductions sont responsables de la
           traduction des pages de manuel dans les differentes
           langues. Ces traductions sont archivees par le FDP.

   FAQ

           L'objectif de la FAQ est de repondre (sous forme de
           courtes questions/reponses) aux questions qui sont posees,
           ou devraient etre posees, sur les differentes listes de
           diffusion et forums de discussion consacrees `a FreeBSD.
           Son format n'autorise pas de reponses longues et
           exhaustives.

   Manuel de reference - ``Handbook''

           Le Manuel cherche `a etre la ressource en ligne exhaustive
           et de reference pour les utilisateurs de FreeBSD.

   Le site Web

           C'est le point de presence central de FreeBSD sur le World
           Wide Web, dont le site principal est
           http://www.freebsd.org/ et qui a de nombreux sites miroirs
           dans le monde. Pour beaucoup de gens, ce site est leur
           premiere rencontre avec FreeBSD.

   Ces quatres categories de documentation sont disponibles dans les
   archives CVS de FreeBSD. Ce qui signifie que les modifications et
   les notifications sont accessibles `a tous, et que chacun peut
   utiliser un programme comme CVSup ou CTM pour maintenir `a jour
   son propre exemplaire local.

   En plus de ces documents, de nombreuses personnes ont ecrit des
   guides ou realise des sites Web se rapportant `a FreeBSD. Certains
   sont aussi archives dans l'arborescence CVS (quand l'auteur a
   donne son accord). Dans d'autre cas, l'auteur a choisi de
   conserver ses documentations en dehors des archives FreeBSD. Le
   FDP essaie de donner le maximum de liens possible sur ces
   documents.

     --------------------------------------------------------------

1.2. Avant de commencer

   Ce document fait l'hypothese que vous savez dej`a :

     * Vous procurer et tenir `a jour une copie locale de la
       documentation. Soit en maintenant une copie locale des
       archives CVS de FreeBSD (avec CVS, CVSup ou CTM), ou en vous
       servant de CVSup pour ne telecharger que la version
       extraite - courante.

     * Comment telecharger et installer de nouveaux logiciels en vous
       servant soit du catalogue des logiciels de FreeBSD soit de
       pkg_add(1).

     --------------------------------------------------------------

                           Chapitre 2. Outils

   Le FDP utilise un certain nombre de logiciels pour faciliter la
   gestion de la documentation de FreeBSD, la convertir en differents
   formats, et ainsi de suite. Vous devrez vous-meme vous servir de
   ces outils, si vous travaillez `a la documentation de FreeBSD.

   Tous ces outils existent sous forme de logiciels portes ou
   pre-compiles pour FreeBSD, ce qui vous simplifie beaucoup la tache
   de leur installation.

   Vous devrez les installer avant de mettre en pratique les exemples
   donnes dans les chapitres suivants. Ces chapitres vous expliquent
   comment vous servir de ces outils.

     Utilisez textproc/docproj si possible : Vous pouvez gagner
     beaucoup de temps si vous les installez avec textproc/docproj.
     C'est un meta-port qui ne contient pas lui-meme de logiciels. Au
     lieu de cela, il depend de l'installation correcte de divers
     autres logiciels portes. Son installation devrait telecharger et
     installer automatiquement tous les paquetages listes dans ce
     chapitre dont vous aurez besoin, s'ils n'existent pas dej`a sur
     votre systeme.

     L'un des paquetages dont vous aurez peut-etre besoin est le jeu
     de macro-instructions JadeTeX. Celui-ci, `a son tour, a besoin
     que TeX soit installe. TeX est un paquetage volumineux, dont
     vous n'aurez besoin que si vous voulez generer les versions
     PostScript et PDF.

     Pour economiser du temps et de l'espace disque, vous pouvez
     preciser si vous voulez ou non installer JadeTeX (et donc TeX).
     Faites soit :

 # make JADETEX=yes install

     ou :

 # make JADETEX=no install

     selon le cas.

     --------------------------------------------------------------

2.1. Outils indispensables

  2.1.1. Logiciels

   Vous aurez besoin de ces programmes avant de pouvoir utilement
   travailler sur la documentation de FreeBSD. Ils font tous partie
   de textproc/docproj.

   SP (textproc/sp)

           Une serie d'applications, dont un analyseur syntaxique
           SGML et un outil de normalisation du source SGML.

   Jade (textproc/jade)

           Une implementation des DSSSL. Cela sert `a convertir des
           documents marques vers d'autres formats, dont HTML et TeX.

   Tidy (www/tidy)

           Un formateur HTML, qui sert `a remettre en forme le code
           HTML genere automatiquement pour qu'il soit plus lisible.

   Lynx (www/lynx-current)

           Navigateur WWW en mode texte, lynx(1) peut aussi convertir
           des fichiers HTML en fichiers texte.

     --------------------------------------------------------------

  2.1.2. DTDs et Entites

   Ce sont les DTDs et jeux d'entites utilises par le FDP. Il faut
   les installer avant de pouvoir travailler `a la documentation.

   DTD HTML (textproc/html)

           HTML est le langage principal du World Wide Web, il est
           utilise constamment par le site Web de FreeBSD.

   DTD LinuxDoc (textproc/linuxdoc)

           Une partie de la documentation de FreeBSD est marquee avec
           LinuxDoc. Le FDP migre activement de LinuxDoc `a DocBook.

   DTD DocBook (textproc/docbook)

           DocBook est conc,u pour le marquage de documentation
           technique et le FDP est en cours de migration de LinuxDoc
           `a DocBook. A la date de redaction de cette documentation,
           celle-ci et le Manuel de Reference de FreeBSD sont au
           format DocBook.

   Entites ISO 8879 (textproc/iso8879)

           19 de jeux de caracteres ISO 8879:1986 utilises par de
           nombreuses DTDs. Cela comprend des symboles mathematiques
           nommes, les caracteres ``latins'' supplementaires
           (accents, signes diacritiques et ainsi de suite) et les
           lettres grecques.

     --------------------------------------------------------------

  2.1.3. Feuilles de style

   Les feuilles de style sont utilisees pour convertir et formater la
   documentation pour l'affichage `a l'ecran, l'impression, et ainsi
   de suite.

   Les Modular DocBook Stylesheets (textproc/dsssl-docbook-modular)

           Les Modular DocBook Stylesheets sont utilisees pour
           convertir la documentation marque en DocBook aux autres
           formats, comme HTML ou RTF.

     --------------------------------------------------------------

2.2. Outils facultatifs

   Il n'est pas obligatoire d'installer les outils qui suivent. Si
   vous le faites cependant, vous trouverez peut-etre plus facile de
   travailler `a la documentation et ils vous donneront plus de
   possibilite de choix du format de sortie.

     --------------------------------------------------------------

  2.2.1. Logiciels

   JadeTeX et teTeX (print/jadetex et print/teTeX)

           Jade et teTeX servent `a convertir les documents DocBook
           en DVI, Postscript et PDF. Il faut pour cela les
           macro-instructions JadeTeX.

           Si vous n'avez pas l'intention de convertir votre
           documentation `a l'un de ces formats (i.e., HTML, texte et
           RTF vous suffisent), il n'est pas necessaire d'installer
           JadeTeX et teTeX. Cela vous fera gagner du temps et de
           l'espace disque, teTeX, en effet occupe plus de 30 Mo.

             Important : Si vous choisissez d'installer JadeTeX et
             teTeX, vous devrez configurer teTeX apres avoir installe
             JadeTeX. print/jadetex/pkg-message vous donnera des
             instructions detaillees sur la fac,on de proceder.

   Emacs ou xemacs (editors/emacs ou editors/xemacs)

           Ces deux editeurs ont un mode specialise pour travailler
           sur des documents marques conformement `a une DTD SGML.
           Cela vous permet d'avoir moins de choses `a saisir et
           limite la possibilite d'erreurs.

           Vous n'etes pas oblige de les utiliser, n'importe quel
           editeur peut servir avec des documents marques. Mais vous
           trouverez peut-etre qu'ils vous permettent d'etre plus
           efficace.

   Si quelqu'un a d'autres outils utiles pour manipuler des documents
   SGML, merci de transmettre l'information `a Nik Clayton
   (nik@freebsd.org), de fac,on `a ce qu'il les ajoute `a cette
   liste.

     --------------------------------------------------------------

                    Chapitre 3. Introduction `a SGML

   La majorite des documentations du FDP utilisent SGML. Ce chapitre
   vous explique ce que cela signifie exactement, comment lire et
   comprendre le source de la documentation et decrit la fac,on
   d'utiliser le SGML que vous recontrerez dans la documentation.

   Des parties de cette section se sont inspirees du livre de Mark
   Galassi, ``Get Going With DocBook''.

     --------------------------------------------------------------

3.1. Introduction

   Il etait autrefois facile de travailler sur des documents
   electroniques. Vous n'aviez normalement `a connaitre que le jeu de
   caracteres utilise (ASCII, EBCDIC, ou l'un des nombreux autres) et
   c'etait `a peu pres tout. Le texte etait du texte, et vous voyiez
   vraiment ce que vous obteniez. Pas de sophistication, pas de
   formatage, pas d'intelligence.

   Cela devint inevitablement insuffisant. Une fois que vous avez du
   texte qu'une machine peut lire, vous vous attendez `a ce que la
   machine puisse l'utiliser et le manipuler intelligemment. Vous
   aimeriez pouvoir preciser que certaines phrases sont accentuees, y
   ajouter un glossaire ou des hyper-liens. Vous voulez que les noms
   de fichiers apparaissent en police ``machine `a ecrire'' `a
   l'ecran et en italique `a l'impression, et tout un tas d'autres
   options de presentation encore.

   Il fut un temps ou l'on pensait que l'Intelligence Artificielle
   (IA) rendrait cela facile. Votre ordinateur pourrait lire le
   document et identifier les phrases cles, les noms de fichiers, le
   texte que l'utilisateur devait taper, et d'autres encore.
   Malheureusement, la realite est un peu differente, et il faut
   aider nos ordinateurs `a manipuler intelligemment notre texte.

   Plus precisement, il faut les aider `a indentifier ce qui est
   quoi. Vous et moi, `a la vue de :

     Pour effacer /tmp/foo, utilisez rm(1) :

 % rm /tmp/foo

   distinguons facilement ce qui est nom de fichier, commande `a
   taper, reference aux pages de manuel, et ainsi de suite. Mais
   l'ordinateur lui ne le peut pas. Pour cela, Nous avons besoin des
   marques.

   Le ``marquage'' est communement qualifie de ``valeur ajoutee'' ou
   ``cout augmente''. Le terme prend ces deux sens quand il
   s'applique au texte. La marquage est du texte en supplement dans
   le document, distinct par un moyen ou un autre du contenu du
   document, de fac,on `a ce que les programmes qui traitent le
   document puisse le lire et l'utiliser pour prendre des decisions.
   Les editeurs peuvent masquer le marquage `a l'utilisateur, de
   fac,on `a ce qu'il ne soit pas perturbe par ces marques.

   L'information supplementaire donnee avec les marques ajoute de la
   valeur au document. Le marquage doit habituellement etre
   manuel - apres tout, si les ordinateurs pouvait analyser
   suffisamment le texte pour ajouter les marques, il n'y en aurait
   alors en fait pas besoin. Cela augment le cout du document.

   L'exemple precedent est code comme suit dans le present document :

 <para>Pour effacer <filename>/tmp/foo</filename>, utilisez
   &man.rm.1;.</para>

 <para><command>rm /tmp/foo</command></para>

   Comme vous pouvez le constater, le marquage est clairement separe
   du contenu.

   Bien evidemment, si vous devez utiliser des marques, vous devrez
   definir ce que les marques veulent dire et comment elles doivent
   etre traitees. Il vous faudra un language de marquage auquel vous
   referer pour marquer vos documents.

   Un seul language de marquage peut bien sur ne pas suffire. Les
   besoins de marquage d'une documentation technique different
   enormement de ceux de recettes de cuisines. ces derniers seront `a
   leur tour differents de ceux d'un language de marquage pour de la
   poesie. Vous avez en fait besoin d'un language qui vous permette
   de definir ces autres languages de marquage. Un meta-language de
   marquage.

   C'est exactement ce qu'est Standard Generalised Markup Language
   (SGML) - Language de Marquage Standard Generalise. De nombreux
   languages de marquage sont ecrits en SGML, dont les deux languages
   les plus utilises par le FDP, HTML et DocBook.

   Chaque definition d'un language s'appelle plus exactement une
   Document Type Definition (DTD) - Definition de Type de Document.
   La DTD definit les noms des elements utilisables, leur ordre
   d'apparition (et leur hierarchie) et les informations qui s'y
   rapportent. Une DTD est parfois designee comme une application de
   SGML.

   Une DTD est une specification complete de tous les elements
   autorises, de l'ordre dans lequel ils doivent etre utilises, quels
   sont ceux qui sont obligatoires, quels sont ceux qui sont
   facultatifs, et ainsi de suite. Il est alors possible d'ecrire un
   analyseur qui lise et la DTD et le document qui pretend s'y
   conformer. L'analyseur peut alors verifier si tous les elements
   requis sont bien presents dans l'ordre voulu dans le document et
   s'il y a des erreurs dans le marquage. On appelle habituellement
   cela "valider le document".

     Note : Ce traitement ne valide uniquement que le choix des
     elements, leur ordre, et ainsi de suite, se conforme `a ce que
     definit la DTD. Il ne verifie pas que vous avez utilise les
     marques appropriees au document. Si vous marquez tous les noms
     de fichiers de votre document comme des noms de fonctions,
     l'analyseur ne le signalera pas comme une erreur (en supposant,
     bien sur, que votre DTD definisse des elements pour les noms de
     fichiers et de fonctions et qu'ils aient le droit d'apparaitre
     aux memes endroits).

   Il est probable que vos contributions au Projet de Documentation
   consiste en documents marques soit en HTML soit en DocBook, plutot
   qu'en modifications aux DTDs. Pour cette raison, cet ouvrage
   n'abordera pas la fac,on d'ecrire une DTD.

     --------------------------------------------------------------

3.2. Elements, marques et attributs

   Toutes les DTDs ecrites en HTML ont des caracteristiques communes.
   Ce n'est guere surprenant comme le montre inevitablement la
   philosophie qui sous-tend SGML. Une des manifestations les plus
   visibles de cette philosophie est la caracterisation en contenu et
   elements.

   Votre documentation (que ce soit une seule page Web ou un ouvrage
   volumineux) est vue comme etant un contenu. Ce contenu est alors
   divise (et ensuite subdivise) en elements. L'objectif de l'ajout
   de marques est de nommer et de definir le debut et la fin de ces
   elements pour traitement ulterieur.

   Considerez par exemple un livre type. Au plus haut niveau, ce
   livre lui-meme est un element. Cet element ``livre'' contient
   evidemment des chapitres, qui peuvent aussi etre legitimement
   consideres comme des elements. Chaque chapitre contiendra `a son
   tour des elements, tels que des paragraphes, des citations et de
   notes de bas de page. Chaque paragraphe peut lui-meme contenir
   encore des elements, pour identifier le texte parle par exemple,
   ou les noms des personnages de l'histoire.

   Vous pouvez si vous le voulez voir cela comme un ``morcelement''
   du contenu. A la racine, vous avez un morceau, le livre. Un niveau
   en dessous, vous avez plus de morceaux, les chapitres individuels.
   Ils sont `a leur tour morceles en pargraphes, notes de bas de
   page, noms des personnages, et ainsi de suite.

   Remarquez que vous pouvez differencier les elements sans utiliser
   la terminologie SGML. C'est vraiment immediat. Vous pouvez le
   faire avec un surligneur et un livre imprime, en utilisant des
   couleurs differentes pour chaque type d'element.

   Nous n'avons bien sur pas de surligneur electronique, il nous faut
   donc un autre moyen d'indiquer `a quel element appartient chaque
   morceau du contenu. Dans les languages ecrits avec SGML ,(HTML,
   DocBook, et al.), cela se fait avec des marques.

   Une marque sert `a dire ou commence et ou finit un element. La
   marque ne fait pas partie de l'element lui-meme. Comme chaque DTD
   est habituellement ecrite pour marquer des types d'informations
   specifiques, chacune reconnaitra des elements differents, et aura
   donc des noms differents pour les marques.

   Pour un element appele nom-de-l'element, la marque de debut sera
   normalement <nom-de-l'element>. La marque de fin correspondante
   sera </nom-de-l'element>.

   Exemple 3-1. Utiliser un element (marques de debut et de fin)

   HTML dispose d'un element pour indiquer que le contenu inclus est
   un paragraphe, appele p. Cet element a une marque de debut et une
   de fin.

 <p>C'est un paragraphe. Il commence avec la marque de d&eacute;but pour
   l'&eacute;l&eacute;ment 'p', et se terminera avec la marque de fin pour
   l'&eacute;l&eacute;ment 'p'</p>

 <p>C'est un autre paragraphe. Mais il est beaucoup plus
   court.</p>

   Tous les elements n'ont pas besoin d'une marque de fin. Certains
   n'ont pas de contenu. En HTML, par exemple, vous pouvez indiquer
   que vous voulez avoir une ligne horizontal dans votre document.
   Cette ligne n'a bien sur aucun contenu, vous n'avez donc besoin
   que de la marque de debut pour cet element.

   Exemple 3-2. Utiliser un element (marque de debut uniquement)

   HTML dispose d'un element pour inclure une ligne horizontale,
   appele hr. C'est un element sans contenu, il n'a donc qu'une
   marque de debut.

 <p>C'est un paragraphe.</p>

 <hr>

 <p>C'est un autre paragraphe. Une ligne horizontale le s&eacute;pare
   du pr&eacute;c&eacute;dent.</p>

   Si ce n'etait pas encore clair, les elements peuvent contenir
   d'autres elements. Dans l'exemple du livre plus haut, ce livre
   contenait tous les chapitres, qui `a leur tour contenaient tous
   les paragraphes, et ainsi de suite.

   Exemple 3-3. Elements dans des elements ; <em>

 <p>C'est un <em>paragraphe</em> simple o&ugrave; certains
   <em>mots</em> ont &eacute;t&eacute; <em>mis en valeur</em>.</p>

   La DTD definira les regles qui disent quels elements peuvent etre
   inclus dans quels autres elements, et ce qu'ils peuvent
   precisement contenir.

     Important : Les gens confondent souvent marques et elements
     comme si c'etaient des termes interchangeables. Ce n'est pas le
     cas.

     Un element est une partie de la structure d'un document. Un
     element a un debut et une fin. Les marques definissent ou
     commence et ou finit le document.

     Quand le present document (ou quelqu'un d'autre qui connait le
     SGML) parle de la marque ``the <p> tag'', cela se rapporte au
     texte compose des trois caracteres <, p et >. Mais la phrase
     ``l'element <p>'' designe tout l'element.

     Cette distinction est tres subtile. Mais gardez la `a l'esprit.

   Les elements peuvent avoir des attributs. Un attribut a un nom et
   une valeur, et sert `a donner des informations supplementaires
   concernant l'element. Ce peuvent etre des informations qui
   precisent comment l'element doit etre formate, ou un identifiant
   unique pour cette occurrence de l'element, ou autre chose encore.

   Les attributs d'un element sont donnes dans la marque de debut de
   l'element et ont la forme
   nom-de-l'attribut="valeur-de-l'attribut".

   Dans les versions recentes d'HTML, l'element <p> a un attribut
   appele align, qui suggere un alignement (justification) du
   paragraphe au programme affichant l'HTML.

   L'attribut align peut prendre l'une des quatre valeurs
   predefinies, left, center, right et justify. Si l'attribut n'est
   pas precise, la valeur par defaut est left.

   Exemple 3-4. Utiliser un element avec un attribut

 <p align="left">L'attribut align est superflus pour ce paragraphe,
   puisque 'left' est la valeur par d&eacute;faut.</p>

 <p align="center">Ce paragraphe sera peut-&ecirc;tre centr&eacute;.</p>

   Certains attributs ne prennent que des valeurs predefinies, comme
   left ou justify. D'autres peuvent prendre les valeurs que vous
   voulez. Si vous avez besoin de quotes (") dans un attribut, mettez
   la valeur de l'attribut entre simples quotes.

   Exemple 3-5. Simples quotes dans un attribut

 <p align='right'>Je suis &agrave; droite&nbsp;!</p>

   Vous n'avez pas toujours besoin de mettre la valeur de l'attribut
   entre simples quotes. Les regles `a ce sujet sont cependant
   subtiles, et il est beaucoup plus simple de toujours mettre entre
   simples quotes les valeurs des attributs.

     --------------------------------------------------------------

  3.2.1. A faire...

   Pour tester les exemples donnes dans ce document, vous devrez
   installer des logiciels sur votre systeme et verifiez qu'une
   variable d'environnement est correctement definie.

    1. Telechargez et installez textproc/docproj du catalogue des
       logiciels portes de FreeBSD. C'est un meta-port qui doit
       telecharger et installer tous les programmes et fichiers
       utilises par le Projet de Documentation.

    2. Ajoutez les lignes pour definir SGML_CATALOG_FILES `a vos
       procedures d'initialisation de l'interpreteur de commandes.

       Exemple 3-6. .profile, pour les utilisateurs de sh(1) et
       bash(1)

 SGML_ROOT=/usr/local/share/sgml    
 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

       Exemple 3-7. .login, pour les utilisateurs de csh(1) et
       tcsh(1)

 setenv SGML_ROOT /usr/local/share/sgml
 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

       Deconnectez-vous et reconnectez-vous ensuite, ou executez ces
       commandes pour definir la variable d'environnement.

    3. Creez un fichier exemple.sgml, ou vous mettrez :

 <!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-&ecirc;tre justifi&eacute; &agrave;
       droite.</p>
   </body>          
 </html>

    4. Essayez de le valider avec un analyseur syntaxique SGML.

       L'analyseur syntaxique nsgmls(1) fait partie de
       textproc/docproj. nsgmls(1) lit normalement un document marque
       en utilisant une DTD SGML et genere l'Element Structure
       Information Set (ESIS) - Informations sur la Structuration en
       Elements - mais cela ne nous concerne pas pour le moment.

       Neanmoins, avec le parametre -s, nsgmls(1) ne genere rien mais
       affiche simplement les messages d'erreurs eventuels. C'est
       utile pour verifier si votre document est correct ou non.

       Utilisez nsgmls(1) pour verifier si votre document est
       valide :

 % nsgmls -s example.sgml

       Vous constaterez que nsgmls(1) n'affiche rien. Cela signifie
       qu'il a valide votre document.

    5. Voyez ce qui ce passe si vous oubliez un element requis.
       Supprimez les marques <title> et </title> et relancer la
       validation.

 % nsgmls -s example.sgml
 nsgmls:example.sgml:5:4:E: character data is not allowed here
 nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished

       Les messages d'erreur de nsgmls(1) sont structures en colonnes
       separes par des deux-points ou des points-virgules.

       Colonne                     Signification                      
       1       Nom du programme qui a genere l'erreur. Ce sera        
               toujours nsgmls.                                       
       2       Nom du fichier ou se trouve l'erreur.                  
       3       Numero de la ligne ou se trouve l'erreur.              
       4       Numero de la colonne ou se trouve l'erreur.            
               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 references croisees. (Ce n'est cependant pas       
       5       toujours la cinquieme colonne. nsgmls -sv affiche      
               nsgmls:I: SP version "1.3" - selon la version          
               installee. 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.                          

       Vous aurez plus d'informations sur les erreurs de nsgmls(1)
       dans la Unofficial 'Kindler, Gentler HTML Validator' FAQ.

       Ne pas mettre les marques <title> a genere 2 erreurs
       differentes.

       La premiere erreur indique que l'analyseur SGML a rencontre un
       contenu (ici, des caracteres, au lieu d'une marque de debut
       d'element) alors qu'il attendait autre chose. Dans le cas
       present, l'analyseur attendait une marque de debut pour un
       element valide `a l'interieur de <head> (<title> par exemple).

       La deuxieme erreur est due au fait que les elements <head>
       doivent contenir un element <title>. nsgmls(1) considere alors
       que l'element n'est pas complet. La marque de fin indique donc
       que l'element se termine alors qu'il n'est pas correctement
       renseigne.

    6. Remettez l'element title en place.

     --------------------------------------------------------------

3.3. La declaration DOCTYPE

   Au debut de chaque document que vous redigez, vous devez preciser
   le nom de la DTD `a laquelle le document se conforme. Cela pour
   que les analyseurs syntaxiques SGML la connaissent et puissent
   valider le document.

   Cette information est habituellement donnee sur une seule ligne,
   dans la declaration DOCTYPE.

   Voici une declaration typique pour un document conforme `a la
   version 4.0 de la DTD HTML :

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">

   Cette ligne a plusieurs composants distincts :

   <!

           C'est l'indicateur qui dit que c'est une declaration SGML.
           Cette ligne definit le type de document.

   DOCTYPE

           Precise que c'est la declaration SGML du type de document.

   html

           Definit le premier element qui apparaitra dans le
           document.

   PUBLIC "-//W3C//DTD HTML 4.0//EN"

           Donne le Formal Public Identifier (FPI) - Identifiant
           Public Officiel - de la DTD `a laquelle le document se
           conforme.

           PUBLIC n'appartient pas au FPI, mais indique au processeur
           SGML comment trouver la DTD referencee par le FPI. Les
           autres fac,ons de dire `a l'analyseur SGML comment trouver
           la DTD sont donnees plus loin.

   >

           Retour au document.

     --------------------------------------------------------------

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

     Note : Vous n'avez pas besoin de connaitre ce qui suit, mais ce
     n'est n'est pas inutile, et cela peut vous aider `a resoudre des
     problemes, si votre processeur SGML ne trouve pas la DTD que
     vous utilisez.

   Les FPIs doivent respecter une syntaxe precise. La voici :

 "Proprietaire//Mot-Cle Description//Langue"

   Proprietaire

           Indique qui detient le FPI.

           Si la chaine de caracteres commence par ``ISO'', c'est un
           FPI ISO. Par exemple, le FPI "ISO 8879:1986//ENTITIES
           Greek Symbols//EN" donne ISO 8879:1986 comme proprietaire
           du jeu d'entites pour les lettres grecques. ISO 8879:1986
           est le numero ISO du standard SGML.

           Sinon, cette chaine sera de la forme -//Proprietaire ou
           +//Proprietaire (remarquez que la seule difference est le
           + ou - du debut).

           Si la chaine commence par un -, c'est que le proprietaire
           n'est pas enregistre, il l'est si elle commence par un +.

           L'ISO 9070:1991 definit comment sont generes les noms
           enregistres ; ils peuvent deriver du numero d'une
           publication ISO, d'un code ISBN ou d'un code
           d'organisation affecte selon l'ISO 6523. De plus, il
           pourrait y avoir une autorite d'enregistrement pour
           l'affectation de ces noms. Le conseil ISO a delegue cela
           `a l'American National Standards Institute
           (ANSI) - Institut National Americain des Standards.

           Comme le Projet FreeBSD n'est pas enregistre, la chaine
           utilisee est -//FreeBSD. Comme vous pouvez vous en rendre
           compte, le W3C n'est pas non plus un proprietaire
           enregistre.

   Mot-Cle

           Il y a plusieurs mots-cles qui definissent le type
           d'information dans le fichier. Les mots-cles les plus
           courants sont : DTD, ELEMENT, ENTITIES et TEXT. DTD ne
           sert que pour les DTD, ELEMENT sert habituellement pour
           les extraits de DTD qui ne contiennent que des entites ou
           des declarations d'elements. TEXT sert pour le contenu
           SGML (texte et marques).

   Description

           La description que vous souhaitez donner du contenu du
           fichier. Cela peut inclure des numeros de version et
           n'importe quel texte court qui ait un sens et soit unique
           au systeme SGML.

   Langue

           C'est une code ISO de deux caracteres qui identifie la
           langue utilisee dans le fichier. Pour l'anglais, c'est EN.

     --------------------------------------------------------------

    3.3.1.1. Fichiers catalog

   Si vous avez utilise la syntaxe decrite plus haut et essaye
   d'utiliser un processeur SGML pour traiter votre document, il aura
   besoin de convertir le FPI en un nom de fichier sur votre
   ordinateur qui decrive la DTD.

   Vous pouvez pour cela vous servir d'un fichier catalogue
   (habituellement appele catalog). Il contient des lignes qui
   donnent les correspondances entre FPIs et noms de fichiers. Par
   exemple, s'il y a la ligne :

 PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"

   le processeur SGML cherchera la DTD dans le fichier strict.dtd du
   sous-repertoire 4.0 ou se trouve le fichier catalog qui comporte
   cette ligne.

   Jettez un oeil au fichier /usr/local/share/sgml/html/catalog.
   C'est le fichier catalogue pour les DTDs HTML qui ont ete
   installees par le logiciel porte textproc/docproj.

     --------------------------------------------------------------

    3.3.1.2. SGML_CATALOG_FILES

   Pour trouver un fichier catalog, votre processeur SGML doit savoir
   ou chercher. La plupart d'entre eux ont des parametres de leur
   ligne de commande pour donner le chemin d'acces `a un ou plusieurs
   catalogues.

   Vous pouvez par ailleurs definir SGML_CATALOG_FILES pour designer
   ces fichiers. Cette variable d'environnement doit contenir une
   liste de fichiers catalogues (donnes par leurs chemins d'acces
   complets) separes par des points-virgules.

   Habituellement, vous incluerez les fichiers suivants :

     * /usr/local/share/sgml/docbook/catalog

     * /usr/local/share/sgml/html/catalog

     * /usr/local/share/sgml/iso8879/catalog

     * /usr/local/share/sgml/jade/catalog

     --------------------------------------------------------------

  3.3.2. Alternatives aux FPIs

   Au lieu d'utiliser un FPI pour preciser la DTD utilisee (et donc
   le fichier qui contient la DTD), il est possible de donner
   explicitement le nom du fichier.

   La syntaxe pour le faire est legerement differente :

 <!DOCTYPE html SYSTEM "/path/to/file.dtd">

   Le mot-cle SYSTEM indique que le processeur SGML doit localiser le
   fichier d'une fac,on qui depend du systeme. Cela signifie
   habituellement (mais pas toujours) que la DTD sera definie par un
   nom de fichier.

   Il est preferable d'utiliser des FPIs pour des raisons de
   portabilite. Vous ne voulez pas livrer un exemplaire de la DTD
   avec votre document, et si vous avez utilise l'identifiant SYSTEM,
   il faudra que chacun ait ses DTDs aux memes endroits.

     --------------------------------------------------------------

3.4. Revenir au SGML

   On a dit plus haut dans cette introduction que le SGML n'etait
   utilise que pour ecrire les DTDs. Ce n'est pas tout `a fait vrai.
   Il y a des elements de la syntaxe SGML que vous voudrez pouvoir
   utiliser dans vos documents. Par exemple, vous pouvez y inclure
   des commentaires, qui seront ignores par les analyseurs. Les
   commentaires sont inclus en utilisant une syntaxe SGML. D'autres
   utilisations du SGML dans les documents seront mentionnees plus
   loin.

   Il vous faut evidemment un moyen d'indiquer au processeur SGML que
   ce qui va suivre n'est pas constitue d'elements du document, mais
   est du SGML que le processeur doit prendre en compte.

   Ces sections sont marques avec <! ... > dans votre document. Tout
   ce qui se trouve entre ces delimiteurs est du code SGML comme on
   en trouve dans les DTDs.

   Comme vous venez peut-etre de vous en rendre compte, la
   declaration DOCTYPE est un exemple de syntaxe SGML que vous devez
   inclure dans votre document...

     --------------------------------------------------------------

3.5. Commentaires

   *** A Traduire ***

   Les commentaires suivent une syntaxe SGML et ne sont normalement
   autorises que dans une DTD. Cependant comme la Section 3.4 le
   montre, il est possible d'inclure du SGML dans vos documents.

   Les delimiteurs pour les commentaires SGML sont constitues de la
   chaine de caracteres ``--''. Une premiere occurence ouvre le
   commentaire, et la seconde le ferme.

   Exemple 3-8. Commentaire SGML generique

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

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

 <!-- Voici une fa&ccedil;on de mettre un commentaire
      sur plusieurs lignes -->

 <!-- Voici une autre fa&ccedil;on --
   -- de le faire -->

   Si vous avez dej`a utilise HTML auparavant, on vous a peut-etre
   donne des regles differentes pour les commentaires. En
   particulier, vous pensez peut-etre qu'ils commencent par <!-- et
   ne se terminent qu'avec -->.

   Ce n'est pas le cas. Les analyseurs syntaxiques de nombreux
   navigateurs sont defectueux et acceptent cette syntaxe. Ceux
   qu'utilisent le Projet de Documentation sont plus rigoureux et
   rejetteront les documents qui comportent cette erreur.

   Exemple 3-9. Commentaires SGML erronnes

 <!-- C'est en commentaire --

      CE N'EST PAS EN COMMENTAIRE!

   -- retour au commentaire -->

   L'analyseur SGML traitera cela comme s'il trouvait :

 <!CE N'EST PAS EN COMMENTAIRE>

   Ce qui n'est pas du SGML valide et donnera des messages d'erreur
   source de confusion.

 <!--------------- C'est un tr&egrave;s mauvaise id&eacute;e --------------->

   Comme l'exemple le suggere, ne mettez pas de commentaires de ce
   type.

 <!--===================================================-->

   C'est une (legerement) meilleure idee, mais c'est toute de meme
   une source de confusion potentielle pour les debutants en SGML.

     --------------------------------------------------------------

  3.5.1. A faire...

    1. Ajoutez des commentaires `a exemple.sgml et validez vos
       modifications avec nsgmls(1)

    2. Ajoutez des commentaires incorrects `a exemple.sgml, pour voir
       quels messages d'erreur produit alors nsgmls(1).

     --------------------------------------------------------------

3.6. Entites

   Les entites fournissent un mecanisme pour designer des parties
   d'un contenu. Lorsque l'analyseur SGML traite votre document, il
   remplace les entites qu'il rencontre par le contenu de ces
   entites.

   C'est un bon moyen pour avoir du texte reutilisable et facile `a
   modifier. C'est aussi le seul moyen d'inclure, en utilisant SGML,
   un fichier marque dans un autre.

   Il y a deux sortes d'entites SGML qui s'utilisent dans des
   situations differentes : les entites generales et les entites
   parametres.

     --------------------------------------------------------------

  3.6.1. Entites Generales

   Vous ne pouvez pas employer les entites generales dans un contexte
   SGML (bien que ce soit l`a que vous les definissiez). Elles ne
   peuvent etre utilisees que dans votre document. Comparez cela au
   cas des entites parametres.

   Chaque entite generale a un nom. Quand vous voulez y faire
   reference (et donc inclure le texte qu'elle contient dans votre
   document), vous mettez &nom-de-l'entite;. Supposons par exemple
   que vous ayez une entite appelee version.courante qui contienne le
   numero de version courante de votre produit. Vous pourriez
   ecrire :

 <para>La version courante de notre produit est la
   &version.courante;.</para>

   Quand le numero de version change, il vous suffit de modifier la
   definition de l'entite generale et de recompiler votre document.

   Vous pouvez aussi vous servir d'entites generales pour representer
   des caracteres que vous ne pouvez pas inclure autrement dans un
   document SGML. < et &, par exemple, ne doivent normalement pas
   apparaitre dans un document SGML. Quand l'analyseur SGML rencontre
   un symbole <, il suppose qu'il precede une marque (de debut ou de
   fin), et quand il rencontre un symbole &, il suppose que le texte
   qui le suit est le nom d'une entite.

   Heureusement, il y a deux entites generales, &lt; et &amp; pour le
   cas ou vous auriez besoin d'inclure l'un ou l'autre de ces
   symboles.

   Une entite generale ne peut etre definie que dans un contexte
   SGML. On le fait habituellement immediatement apres la declaration
   DOCTYPE.

   Exemple 3-10. Definition d'entites generales

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY version.courante    "3.0-RELEASE">
 <!ENTITY derniere.version  "2.2.7-RELEASE">
 ]>

   Remarquez que la declaration DOCTYPE est suivie d'un crochet
   ouvrant `a la fin de la premiere ligne. Les deux entites sont
   definies aux deux lignes suivantes, avant le crochet fermant. La
   declaration DOCTYPE se termine ensuite.

   Les crochets sont necessaires pour dire que nous ajoutons un
   complement `a la DTD mentionnee par la declaration DOCTYPE.

     --------------------------------------------------------------

  3.6.2. Entites parametres

   Comme les entites generales, les entites parametres servent `a
   nommer des parties reutilisables du texte. Cependant, alors que
   les entites generales peuvent etre utilisees dans le corps du
   document, les entites parametres ne peuvent etre employees que
   dans un contexte SGML.

   Les entites parametres sont definies de la meme maniere que les
   entites generales. Sinon qu'au lieu de vous servir de
   &inomd-de-l'entite; pour y faire reference, vous utiliserez
   %nom-de-l'entite;[1]. Leur definition comporte aussi un % entre le
   mot-cle ENTITY et le nom de l'entite.

   Exemple 3-11. Definition d'entites parametres

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

 <!-- %param.encore contient maintenant "encore du texte" -->
 ]>

   Cela ne parait peut etre pas tres utile. On verra pourtant que c,a
   l'est.

     --------------------------------------------------------------

  3.6.3. A faire...

    1. Definissez un entite generale dans exemple.sgml.

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
 <!ENTITY version "1.1">
 ]>   

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

   <!-- Vous pourriez aussi mettre des commentaires ici -->
          
   <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-&ecirc;tre justifi&eacute; &agrave;
       droite</p>

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

    2. Validez le document avec nsgmls(1)

    3. Chargez exemple.sgml avec votre navigateur (vous devrez
       peut-etre le recopier dans exemple.html pour que votre
       navigateur le reconnaisse comme un document HTML).

       A moins que votre navigateur ne soit tres evolue, il ne
       remplacera pas la reference &version; `a l'entite par le
       numero de version. Les analyseurs de la plupart des
       navigateurs sont elementaires et ne gerent pas correctement le
       SGML[2].

    4. La solution est de normaliser votre document avec un outil de
       normalisation du SGML. Ce type d'outil lit un document SGML
       valide et le transforme en un autre document SGML tout aussi
       valide. En particulier, il y remplace les references aux
       entites par leur contenu.

       Vous pouvez le faire avec sgmlnorm(1).

 % sgmlnorm exemple.sgml > exemple.html

       exemple.html doit maintenant contenir une version normalisee
       (i.e., ou les references aux entites ont ete remplacees par
       leur contenu) de votre document, prete `a etre affichee par
       votre navigateur.

    5. Si vous jetez un oeil au resultat de sgmlnorm(1), vous verrez
       qu'il ne comporte pas de declaration DOCTYPE au debut. Pour
       qu'elle y soit, utilisez l'option -d :

 % sgmlnorm -d exemple.sgml > exemple.html

     --------------------------------------------------------------

3.7. Utiliser les entites pour inclure des fichiers

   Les entites (generales et parametres) sont particulierement utiles
   pour inclure un fichier dans un autre.

     --------------------------------------------------------------

  3.7.1. Utiliser les entites generales pour inclure des fichiers

   Supposons que le contenu d'un livre SGML soit decoupe en fichiers,
   `a raison d'un fichier par chapitre, appeles chaptitre1.sgml,
   chapitre2.sgml, et ainsi de suite, et que le fichier livre.sgml
   inclue ces chapitres.

   Pour que vos entites aient pour valeur le contenu de ces fichiers,
   vous les declarerez avec le mot-cle SYSTEM. Cela indique `a
   l'analyseur SGML qu'il doit utiliser le contenu du fichier
   mentionne comme valeur de l'entite.

   Exemple 3-12. Utiliser les entites generales pour inclure des
   fichiers

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY chapitre.1 SYSTEM "chapitre1.sgml">
 <!ENTITY chapitre.2 SYSTEM "chapitre2.sgml">
 <!ENTITY chapitre.3 SYSTEM "chapitre3.sgml">
 <!-- Et ainsi de suite -->
 ]>

 <html>
   <!-- Utilisation des entit&eacute;s pour inclure les chapitres -->

   &chapitre.1;
   &chapitre.2;
   &chapitre.3;
 </html>

     Avertissement : Quand vous vous servez d'entites generales pour
     inclure d'autres fichiers dans un document, les fichiers inclus
     (chapitre1.sgml, chapitre2.sgml, et ainsi de suite) ne doivent
     pas commencer par une declaration DOCTYPE. Ce serait une erreur
     de syntaxe.

     --------------------------------------------------------------

  3.7.2. Utiliser les entites parametres pour inclure des fichiers

   Rappelez-vous que les entites parametres ne peuvent etre utilisees
   que dans un contexte SGML. Quand aurez-vous besoin d'inclure un
   fichier dans un contexte SGML ?

   Vous pouvez vous en servir pour etre sur de pouvoir reutiliser vos
   entites generales.

   Supposons que votre document comporte de nombreux chapitres, et
   que vous reutilisiez ces chapitres dans deux livres differents,
   chacun organisant ces chapitres de fac,on differente.

   Vous pourriez donner la liste des entites en tete de chaque livre,
   mais cela pourrait rapidement devenit fastidieux `a gerer.

   Mettez, au lieu de cela, les definitions des entites generales
   dans un fichier, et utilisez une entite parametre pour inclure ce
   fichier dans votre document.

   Exemple 3-13. Utiliser les entites parametres pour inclure des
   fichiers

   Mettez d'abord les definitions de vos entites dans un fichier
   separe, appele chapitres.ent. Voici ce qu'il contiendra :

 <!ENTITY chapitre.1 SYSTEM "chapitre1.sgml">
 <!ENTITY chapitre.2 SYSTEM "chapitre2.sgml">
 <!ENTITY chapitre.3 SYSTEM "chapitre3.sgml">

   Creez maintenant une entite parametre qui fasse reference au
   contenu de ce fichier. Utilisez ensuite cette entite pour inclure
   le fichier dans votre document, vous pourrez alors y utiliser les
   entites generales. Ce que vous faites de la meme fac,on que
   precedemment :

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!--
      D&eacute;finissez une entit&eacute; param&egrave;tre pour inclure le fichier
      des entit&eacute;s g&eacute;n&eacute;rales pour les chapitres
 -->
 <!ENTITY % chapitres SYSTEM "chapitres.ent">

 <!-- Utilisez maintenant l'entit&eacute; g&eacute;n&eacute;rale pour inclure ce fichier -->
 %chapitres;
 ]>

 <html>
   &chapitre.1;
   &chapitre.2;
   &chapitre.3;
 </html>

     --------------------------------------------------------------

  3.7.3. A faire...

    3.7.3.1. Utiliser les entites generales pour inclure des fichiers

    1. Creez trois fichiers, para1.sgml, para2.sgml et para3.sgml.

       Mettez-y quelque chose qui ressemble `a ceci :

 <p>C'est le premier paragraphe.</p>

    2. Modifiez exemple.sgml de la fac,on suivante :

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY version "1.1">
 <!ENTITY para1 SYSTEM "para1.sgml">
 <!ENTITY para2 SYSTEM "para2.sgml">
 <!ENTITY para3 SYSTEM "para3.sgml">
 ]>

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

    3. Generez exemple.html en normalisant exemple.sgml.

 % sgmlnorm -d exemple.sgml > exemple.html

    4. Affichez exemple.html avec votre navigateur Web et verifiez
       que les fichiers paran.sgml ont bien ete inclus dans
       exemple.html.

     --------------------------------------------------------------

    3.7.3.2. Utiliser les entites parametres pour inclure des fichiers

     Note : Vous devez d'abord avoir mis en pratique l'exemple
     precedent.

    1. Modifiez comme ceci exemple.sgml :

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % entites SYSTEM "entites.sgml"> %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>

    2. Creez un nouveau fichier, entites.sgml, qui contienne :

 <!ENTITY version "1.1">
 <!ENTITY para1 SYSTEM "para1.sgml">
 <!ENTITY para2 SYSTEM "para2.sgml">
 <!ENTITY para3 SYSTEM "para3.sgml">

    3. Generez exemple.html en normalisant exemple.sgml.

 % sgmlnorm -d exemple.sgml > exemple.html

    4. Affichez exemple.html avec votre navigateur Web et verifiez
       que les fichiers paran.sgml ont bien ete inclus dans
       example.html.

     --------------------------------------------------------------

3.8. Sections marquees

   SGML fournit un mecanisme pour definir quelles parties d'un
   document doivent etre traitees de fac,on particuliere. On appelle
   cela des ``sections marquees''.

   Exemple 3-14. Structure d'une section marquee

 <![ MOT-CLE [
   Contenu de la section marquee
 ]]>

   Comme vous pouviez vous y attendre, une section marquee est une
   fonctionnalite SGML et commence donc par <!.

   Le premier crochet ouvrant delimite la section marquee.

   Le MOT-CLE definit comment cette section marquee doit etre traitee
   par l'analyseur.

   Le second crochet ouvrant indique que le contenu de la section
   marquee commence l`a.

   La section marquee se termine par deux crochets fermants, puis un
   > pour indiquer que l'on quitte le contexte SGML et que l'on
   revient au document.

     --------------------------------------------------------------

  3.8.1. Mots-cles pour les sections marquees

    3.8.1.1. CDATA, RCDATA

   Ces deux mots-cles definissent des sections marquees comme modele
   de contenu et vous permettent de modifier sa valeur par defaut.

   Quand un analyseur SGML traite un docuemnt, il memorise ce que
   l'on appelle le ``modele de contenu''.

   En bref, le modele de contenu decrit ce que l'analyseur doit
   s'attendre `a trouver comme contenu, et ce qu'il doit en faire
   quand il le rencontre.

   Les deux modeles de contenu que vous trouverez certainement les
   plus utiles sont CDATA et RCDATA.

   CDATA signifie ``Character Data'' - donnees caracteres. Si
   l'analyseur est `a l'interieur de ce modele de contenu, il
   s'attend `a trouver des caracteres, et uniquement des caracteres.
   Les symboles < et & perdent alors leur signification particuliere
   et sont traites comme de simples caracteres.

   RCDATA signifie ``References `a des entites et donnees
   caracteres''. Si l'analyseur est `a l'interieur de ce modele de
   contenu, il s'attend `a trouver des caracteres et des entites. <
   perd sa signification particuliere, mais & est toujours compris
   comme le debut d'une entite generale.

   C'est particulierement utile si vous incluez du texte qui contient
   de nombreux caracteres < et &. Vous pourriez bien sur controler
   que dans votre texte tous les < sont ecrits &lt; et tous les &
   &amp;, il peut etre plus facile de marquer la section comme ne
   contenant que des ``CDATA''. Quand SGML rencontre l'instruction
   correspondante, il ignorera les symboles < et & qui apparaitront
   dans le contenu.

   Exemple 3-15. Utiliser une section marquee CDATA

 <para>Voici un exemple de la fac,on dont vous pourriez inclure
   un texte comportant de nombreux &lt; et &amp;. L'exemple
   lui-meme est en HTML. Le texte qui l'encadre (<para> et
   <programlisting>) est du DocBook.</para>

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

     <ul>
       <li>C'est un &eacute;l&eacute;ment de liste</li>
       <li>C'est un second &eacute;l&eacute;ment de liste</li>
       <li>C'est un troisi&egrave;me &eacute;l&eacute;ment de liste</li>
     </ul>

     <p>C'est la fin de l'exemple.</p>
   ]]>
 </programlisting>

   Si vous consultez le source de ce document, vous verrez qu'il
   utilise constamment cette technique.

     --------------------------------------------------------------

    3.8.1.2. INCLUDE et IGNORE

   Si le mot-cle est INCLUDE, alors le contenu de la section marquee
   sera pris en compte. Si le mot-cle est IGNORE, alors la section
   marquee sera ignoree. Il n'apparaitra pas dans les sorties.

   Exemple 3-16. Utiliser INCLUDE et IGNORE dans les sections
   marquees

 <![ INCLUDE [
   Ce texte sera traite et inclus.
 ]]>

 <![ IGNORE [
   Ce texte ne sera pas traite ou inclus.
 ]]>

   En soi, cela ne sert pas `a grand-chose. Si vous vouliez supprimer
   du texte de votre document, vous auriez pu l'enlever ou le mettre
   en commentaires.

   Cela devient plus utile quand vous comprenez que vous pouvez vous
   servir des entites parametres pour controler ces sections.
   Rappelez-vous que les entites parametres ne peuvent etre utilisees
   que dans un contexte SGML, et une section marquee est un contexte
   SGML.

   Si par exemple, vous generez une version imprimee et une version
   electronique de votre document, vous pourriez vouloir inclure dans
   la version electronique un contenu supplementaire qui ne devra pas
   apparaitre dans la version imprimee.

   Creez une entite parametre et donnez lui comme contenu INCLUDE.
   Redigez votre document en utilisant des sections marquees pour
   delimiter le contenu qui ne doit apparaitre que dans la version
   electronique. Dans ces sections marquees, servez-vous de l'entite
   parametre au lieu du mot-cle.

   Lorsque vous voulez generer la version electronique, changez la
   valeur de l'entite parametre en IGNORE et retraitez le document.

   Exemple 3-17. Utiliser une entite parametre pour controler une
   section marquee

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % version.electronique "INCLUDE">           
 ]]>

 ...

 <![ %version.electronique [
   Ce texte ne doit apparaitre que dans
   la version electronique du document.
 ]]>

   Pour generer la version imprimee, changez la definition de
   l'entite en :

 <!ENTiTY % version.electronique "IGNORE">

   A la seconde passe sur le document, les sections marquees qui
   utilisent %version.electronique comme mot-cle seront ignorees.

     --------------------------------------------------------------

  3.8.2. A faire...

    1. Creez un nouveau fichier, section.sgml, qui contienne :

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % text.output "INCLUDE">
 ]>

 <html>
   <head>
     <title>Exemple d'utilisation des sections marquees</title>
   </head>

   <body>    
     <p>Ce paragraphe <![ CDATA [contient de nombreux
       caracteres < (< < < < <) il est donc
       plus facile de l'inclure dans une section marquee
       CDATA ]]></p>

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

     <![ %sortie.texte [
     <p>Ce paragraphe apparaitra peut-etre dans les
       sorties.</p>

     <p>Cela depend de l'entite parametre
       %sortie.texte.</p>    
     ]]>
   </body>
 </html>

    2. Normalisez le fichier avec sgmlnorm(1) et examinez le
       resultat. Notez quels paragraphes ont ete conserves et quels
       paragraphes ont ete supprimes, et ce qu'est devenu le contenu
       des sections marquees CDATA.

    3. Modifiez la definition de l'entite sortie.texte de INCLUDE en
       IGNORE. Normalisez de nouveau le fichier et regardez ce qui a
       change dans le resultat.

     --------------------------------------------------------------

3.9. Conclusion

   Ici se termine cette introduction `a SGML. Pour des raisons de
   place et de complexite, de nombreux points ont ete survoles (voire
   omis). Les sections qui precedent decrivent neanmoins suffisamment
   d'elements du SGML pour vous permettre de comprendre comment est
   organisee la documentation du FDP.

     --------------------------------------------------------------

                        Chapitre 4. Marques SGML

   Ce chapitre decrit les trois langages de marquage que vous
   rencontrerez si vous contribuez au Projet de Documentation de
   FreeBSD. Chaque section decrit le langage et detaille les marques
   que vous serez probablement amenes `a utiliser, ou qui sont dej`a
   utilisees.

   Ces langages sont riches en elements et il est parfois difficile
   de savoir lequels employer dans un contexte particulier. Cette
   section decrit ceux dont vous aurez probablement besoin et donne
   des exemples de la maniere de s'en servir.

   Ce n'est pas une liste exhaustive d'elements, cela ne ferait que
   reprendre le contenu de la documentation de chacun de ces
   langages. L'objectif de cette section est de lister les elements
   qui ont le plus de chance de vous etre utiles. Si vous avez des
   questions sur le type de marque `a employer dans un contexte
   particulier, posez-les s'il vous plait `a la liste de diffusion du
   Projet de Documentation de FreeBSD, <freebsd-doc@freebsd.org>.

     En ligne vs. de bloc : Dans la suite de ce document, quand on
     decrira des elements, en ligne signifie que l'element peut
     apparaitre `a l'interieur d'un bloc et ne genere pas de passage
     `a la ligne. A l'inverse un element de bloc provoque un passage
     `a la ligne (et d'autres operations) lorsqu'on le rencontre.

     --------------------------------------------------------------

4.1. HTML

   HTML, l'HyperText Markup Language - Langage de Marquage de
   l'Hypertexte - est le langage de predilection du World Wide Web.
   Vous trouverez plus d'informations sur <URL:http://www.w3.org/>.

   HTML est utilise pour marquer les pages du site Web de FreeBSD. Il
   ne devrait (habituellement) pas servir pour d'autre type de
   documentation, parce que DocBook offre un jeu de marques beaucoup
   plus riche. Vous ne devriez donc rencontrez des pages HTML que si
   vous ecrivez pour le site Web.

   Il y a eu plusieurs versions de HTML, 1, 2, 3.0, 3.2, et il existe
   deux variantes de la derniere version, 4.0 (disponible `a la fois
   en version stricte et relachee).

   Les DTDs HTML existent au catalogue des logiciels portes dans
   textproc/html. Elles sont automatiquement installees par le
   meta-port textproc/docproj.

     --------------------------------------------------------------

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

   Il y a un certain nombre de FPIs HTML, selon la version (qu'on
   appelle aussi le niveau) de HTML avec laquelle vous voulez que
   votre document soit compatible.

   La plupart des documents HTML du site Web de FreeBSD respectent
   strictement la version relachee de HTML 4.0 :

 PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"

     --------------------------------------------------------------

  4.1.2. Sections

   Un document HTML est habituellement compose de deux sections. La
   premiere section, appelee head - en-tete, contient des
   informations sur le document, comme son titre, le nom de son
   auteur, le document dans lequel il est inclus, et ainsi de suite.
   La seconde section, le body - corps, contient ce qui sera affiche.

   Ces sections sont denotees par les elements <head> et <body>
   respectivement. Ces elements appartiennent `a l'element de premier
   niveau <html>.

   Exemple 4-1. Structure habituelle d'un document HTML

 <html>
   <head>
           <title>Le titre du document</title>
   </head>

   <body>

     ...

   </body>
 </html>

     --------------------------------------------------------------

  4.1.3. Elements de blocs

    4.1.3.1. Titres

   HTML vous permet d'avoir jusqu'`a six niveaux de titres differents
   dans votre document.

   Le titre le plus gros et le plus visible est <h1>, puis <h2>,
   jusqu'`a <h6>.

   Le contenu de l'element est le texte du titre.

   Exemple 4-2. <h1>, <h2>, etc.

   Utilisez :

 <h1>Premi&egrave;re section</h1>

 <!-- Introduction du document -->

 <h2>C'est le titre de la premi&egrave;re section</h2>

 <!-- Contenu de la premi&egrave;re section -->

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

 <!-- Contenu de la premi&egrave;re sous-section -->

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

 <!-- Contenu de la seconde section -->

   Un page HTML doit normalementi avoir un titre de premier niveau
   (<h1>). Il peut contenir plusieurs titres de second niveau (<h2>),
   et `a leur tour, de nombreux titres de troisieme niveau. Chaque
   element <hn> doit appartenir `a un meme element de niveau
   superieur. Il faut eviter de sauter d'un cran dans la
   numerotation.

   Exemple 4-3. Mauvais ordonnancement des elements <hn>

   Use:

 <h1>Premi&egrave;re section</h1>

 <!-- Introduction du document -->

 <h3>Sous-section</h3>

 <!-- Ce n'est pas bon, <h2> a &eacute;t&eacute; oubli&eacute; -->

     --------------------------------------------------------------

    4.1.3.2. Paragraphes

   HTML n'a qu'un seul element paragraphe, <p>.

   Exemple 4-4. <p>

   Utilisez :

 <p>C'est un paragraphe. Il peut contenir pratiquement
   n'importe quel &eacute;l&eacute;ment.</p>

     --------------------------------------------------------------

    4.1.3.3. Citations

   Une citation d'un long extrait d'un autre document, qui ne doit
   pas apparaitre dans le paragraphe en cours, mais est mise dans un
   bloc de citation.

   Exemple 4-5. <blockquote>

   Utilisez :

 <p>Un court extrait de la Constitution des Etats-Unis&nbsp;:</p>

 <blockquote>Nous le Peuple des Etats-Unis, dans le But de former
   une Union plus parfaite, d'&eacute;tablir la Justice, d'assurer
   la Tranquilit&eacute; domestique, de d&eacute;fendre chacun, de promouvoir
   le Bien-&ecirc;tre g&eacute;n&eacute;ral, et de garantir les B&eacute;n&eacute;dictions de
   la Libert&eacute; &agrave; nous-m&ecirc;mes et &agrave; notre Post&eacute;rit&eacute;, d&eacute;cidons et
   &eacute;tablissons cette Constitution des Etats-Unis d'Am&eacute;rique.</blockquote>

     --------------------------------------------------------------

    4.1.3.4. Listes

   Il y a trois types de listes que vous pouvez afficher : ordonnee,
   non ordonnee et de definition.

   Typiquement, chaque entree d'une liste ordonnee sera numerotee,
   alors que chaque entree d'une liste non ordonnee sera precedee
   d'une puce. Les listes de definition ont deux sections pour chaque
   entree. La premiere est le terme que l'on definit et la seconde sa
   definition.

   Les listes ordonnees sont denotees par l'element <ol>, les listes
   non ordonnees par l'element <ul> et les listes de definition par
   l'element <dl> element.

   Les listes ordonnees et non ordonnees contiennent des elements de
   liste, notes avec l'element <li>. Un element de liste peut
   contenir du texte, ou etre decompose en plusieurs elements <p>.

   Les listes de definition contiennent des termes `a definir (<dt>)
   et leurs definitions (<dd>). Le terme `a definir n'est compose que
   de texte. La definition peut comporter d'autres elements de blocs.

   Exemple 4-6. <ul> et <ol>

   Utilisez :

 <p>Une liste non ordonn&eacute;e. Les &eacute;l&eacute;ments de la liste seront
   probablement pr&eacute;c&eacute;d&eacute;s par des puces.</p>

 <ul>
   <li>Premier &eacute;l&eacute;ment</li>

   <li>Second &eacute;l&eacute;ment</li>

   <li>Troisi&egrave;me &eacute;l&eacute;ment</li>
 </ul>

 <p>Une liste ordonn&eacute;e, dont les &eacute;l&eacute;ments comportent plusieurs paragraphes.
   Chaque &eacute;l&eacute;ment (note : et non chaque paragraphe) sera num&eacute;rot&eacute;.</p>

 <ol>
   <li><p>C'est le premier &eacute;l&eacute;ment. Il n'a qu'un paragraphe..</p></li>

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

     <p>C'est le second paragraphe du second &eacute;l&eacute;ment.</p>

   <li><p>C'est le premier et seul paragraphe du troisi&egrave;me &eacute;l&eacute;ment.</p></li>
 </ol>

   Exemple 4-7. Listes de definition avec <dl>

   Utilisez :

 <dl>
   <dt>Terme 1</dt>

   <dd><p>Paragraphe 1 de la d&eacute;finition 1.</p></dd>

     <p>Paragraphe 2 de la d&eacute;finition 1.</p></dd>

   <dt>Terme 2</dt>

   <dd><p>Paragraphe 1 de la d&eacute;finition 2.</p></dd>

   <dt>Terme 3</dt>

   <dd>Paragraphe 1 de la d&eacute;finition 3. Remarquez que l'&eacute;l&eacute;ment <p> n'est
     pas obligatoire dans le cas d'un paragraphe unique.</dd>
 </dl>

     --------------------------------------------------------------

    4.1.3.5. Texte pre-formate

   Vous pouvez preciser que du texte doit apparaitre exactement comme
   il est presente dans le fichier. Cela signifie habituellement que
   le texte est affiche en police fixe, que les blancs successifs
   sont conserves et que les passages `a la ligne dans le texte sont
   significatifs.

   Pour cela, il faut mettre ce texte dans un element <pre>.

   Exemple 4-8. <pre>

   Vous pouvez utiliser <pre> pour marquer le texte d'un courrier
   electronique :

 <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&eacute;s.

   N
 </pre>

     --------------------------------------------------------------

    4.1.3.6. Tables

     Note : La plupart des navigateurs en mode texte (comme Lynx)
     n'affichent pas tres bien les tables. Si vous utilisez ce type
     de presentation en tableaux, vous devriez envisager d'utiliser
     d'autres marques pour eviter la confusion.

   Marquez les tableaux avec l'element <table>. Un tableau est
   compose d'une ou plusieurs lignes (<tr>), chacune contenant une ou
   plusieurs cellules (<td>). Chaque cellule peut contenir d'autres
   elements de bloc, des paragraphes ou des listes par exemple. Elle
   peut aussi contenir d'autres tables (cet emboitement peut se
   repeter indefiniment). Si la cellule ne contient qu'un seul
   paragraphe, l'element <p> n'est pas obligatoire.

   Exemple 4-9. Emploi simple de <table>

   Utilisez :

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

   Une cellule peut occuper plusieurs lignes ou colonnes. Pour le
   preciser, ajoutez les attributs rowspan et/ou colspan, dont les
   valeurs donnent le nombre de lignes et de colonnes occupees.

   Exemple 4-10. Emploi de rowspan

   Utilisez :

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

   Exemple 4-11. Emploi de colspan

   Utilisez :

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

   Exemple 4-12. Emploi de rowspan et colspan ensemble

   Use:

 <p>Sur une grille 3x3, la cellule en haut &agrave; gauche d'&eacute;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>
     <!-- Comme la grande cellule se prolonge
          sur cette colonne, la premi&egrave;re cellule
          marqu&eacute;e par <td> se trouvera &agrave; sa droite -->
            
     <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>

     --------------------------------------------------------------

  4.1.4. Elements

    4.1.4.1. Information d'accentuation

   Il y a deux niveaux d'accentuation disponibles en HTML, <em> et
   <strong>. <em> marque une accentuation normale et <strong> une
   accentuation plus prononcee.

   <em> est generalement rendu en italiques et <strong> en gras. Ce
   n'est malgre tout pas toujours le cas, et il ne faut pas se baser
   l`a-dessus.

   Exemple 4-13. <em> et <strong>

   Utilisez :

 <p><em>Ceci</em> est accentu&eacute;, et
   <strong>cela</strong> l'est encore plus.</p>

     --------------------------------------------------------------

    4.1.4.2. Gras et italiques

   HTML comporte des marques pour la presentation, vous pouvez donc
   aussi preciser qu'un contenu donne doit apparaitre en gras ou en
   italiques. Les elements pour cela sont respectivement <b> et <i>.

   Exemple 4-14. <b> et <i>

 <p><b>Ceci</b> est en gras, tandis que <i>cela</i> est
   en italiques.</p>

     --------------------------------------------------------------

    4.1.4.3. Texte en police fixe

   S'il y a du texte qui doit etre affiche en police fixe (machine `a
   ecrire), servez-vous de <tt> ( pour ``teletype'').

   Exemple 4-15. <tt>

   Utilisez :

 <p>L'auteur original de ce document est
   Nik Clayton, qui peut &ecirc;tre contact&eacute; par courrier
   &eacute;lectronique &agrave; l'adresse : <tt>nik@freebsd.org</tt>.</p>

     --------------------------------------------------------------

    4.1.4.4. Taille de police

   Vous pouvez preciser qu'un contenu doit etre affiche en police
   plus grande ou plus petite. Il y a trois fac,ons de le faire.

    1. Utilisez <big> et <small> pour encadrer le texte dont vous
       voulez modifier la taille. Ces marques peuvent etre
       imbriquees, il est donc possible d'avoir : <big><big>C'est
       bien plus gros</big></big>.

    2. Servez-vous de <font> avec l'attribut size prenant
       respectivement les valeurs +1 ou -1. C'est la meme chose que
       d'utiliser <big> ou <small>. Mais cette fac,on de faire est
       obsolete.

    3. Utilisez <font> avec l'attribut size prenant une valeur de 1
       `a 7. La taille de police par defaut est 3. Cette fac,on de
       faire est aussi obsolete.

   Exemple 4-16. <big>, <small> et <font>

   Les trois extraits suivants ont le meme resultat :

 <p>Ce texte est <small>un peu plus petit</small>.
   Mais celui-l&agrave; <big>est un peu plus gros</big>.</p>

 <p>Ce texte est <font size="-1">un peu plus petit</font>.
   Mais celui-l&agrave; <font size="+1">est un peu plus gros</font>.</p>

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

     --------------------------------------------------------------

  4.1.5. Liens

     Note : Les liens font aussi partie du contenu du document.

     --------------------------------------------------------------

    4.1.5.1. Liens vers d'autres documents sur le WWW

   Pour mettre un lien sur un autre document sur le WWW, il faut que
   vous connaissiez l'URL de ce document.

   Ce lien est note avec <a> et l'attribut href contient l'URL du
   document cible. Le lien est le contenu de l'element, il est
   habituellement presente d'une fac,on ou d'une autre `a
   l'utilisateur (souligne, couleur differente, curseur de forme
   differente quand on passe dessus, et ainsi de suite).

   Exemple 4-17. Emploi de <a href="...">

   Utilisez :

 <p>Vous trouverez plus d'informations sur le
   <a href="http://www.freebsd.org/">site Web de FreeBSD</a>.</p>

   Ces liens ameneront l'utilisateur au debut du document
   selectionne.

     --------------------------------------------------------------

    4.1.5.2. Liens sur d'autres parties des documents

   Pour mettre un lien sur un endroit precis d'un autre (ou du meme)
   document, il faut que l'auteur de ce document y ait mis des points
   d'ancrage sur lequels vous pouvez pointer.

   Les points d'ancrage sont notes avec <a> et l'attribut name au
   lieu de href.

   Exemple 4-18. Emploi de <a name="...">

   Utilisez :

 <p><a name="para1">Ce</a> paragraphe peut &ecirc;tre r&eacute;f&eacute;renc&eacute;
   par d'autres liens via le nom <tt>para1</tt>.</p>

   Pour mettre un lien sur une partie nommee d'un document, utilisez
   un lien ordinaire, mais ajoutez-y le nom du point d'ancrage
   precede d'un symbole #.

   Exemple 4-19. Lien sur une partie nommee d'un autre document

   Supposons que l'exemple para1 se trouve dans un document appele
   foo.html.

 <p>Vous trouverez plus d'informations au
   <a href="foo.html#para1">premier paragraphe</a> de
   <tt>foo.html</tt>.</p>

   Si le lien pointe sur un point d'ancrage nomme du meme document,
   vous pouvez ommettre son URL et ne mettre que le nom du point
   d'ancrage (precede de #).

   Exemple 4-20. Lien sur une partie nommee du meme document

   Supposons que l'exemple para1 fasse partie de ce document.

 <p>Vous trouverez plus d'informations au
   <a href="#para1">premier paragraphe</a> de
   ce document.</p>

     --------------------------------------------------------------

4.2. DocBook

   DocBook est une DTD creee par le Davenport Group pour la redaction
   de documentation technique. De sorte que, et au contraire de
   LinuxDoc ou HTML, les marques DocBook sont plus conc,ues pour
   decrire ce qu'est quelque chose que comment il faut le presenter.

     formel vs. informel : Certains elements ont deux
     versions - formelle et informelle. Habituellement, la version
     formelle de l'element comporte une titre. La version informelle
     n'en a pas.

   La DTD DocBook est disponible au catalogue des logiciels portes
   avec le ``meta-logiciel porte'' textproc/docbook. Elle est
   automatiquement installee par ce dernier.

     --------------------------------------------------------------

  4.2.1. Extensions FreeBSD

   Le Projet de Documentation de FreeBSD a ajoute quelques nouveaux
   elements `a la DTD DocBook. Ces elements permettent un marquage
   plus precis.

   Dans la suite, quand il sera question d'un element propre `a
   FreeBSD, ce sera clairement indique.

   Le terme ``DocBook'' designe dans ce qui suit la DTD DocBook avec
   les extensions FreeBSD.

     Note : Il n'y a rien dans ces extensions qui soit propre `a
     FreeBSD, on a juste pense que ce seraient des ajouts utiles pour
     ce projet precis. Si d'autres contributeurs aux autres projets
     ``*nix'' (NetBSD, OpenBSD, Linux, ...) sont interesses `a
     participer `a la mise au point d'un jeu d'extensions DocBook
     standard, merci de contacter Nik Clayton <nik@FreeBSD.org>.

   Les extensions FreeBSD ne font pas (actuellement) partie du
   catalogue des logiciels portes. Elles sont inclues dans les
   sources du Projet de Documentation et se trouvent dans
   doc/share/sgml/freebsd.dtd.

     --------------------------------------------------------------

  4.2.2. Identifiant Public Formel - Formal Public Indentifier, (FPI)

   En conformite avec les conventions DocBook concernant les FPIs
   pour les personnalisations de DocBook, le FPI pour la DTD DocBook
   avec les extensions FreeBSD est :

 PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"

     --------------------------------------------------------------

  4.2.3. Structure des documents

   DocBook vous permet de structurer votre documentation de
   differentes fac,ons. Le Projet de Documentation de FreeBSD utilise
   deux types de documents de base, le livre et l'article.

   Un livre est organise <chapter>s. C'est une obligation. Il peut y
   avoir des <part>s entre le livre et le chapitre s'il l'on veut un
   niveau supplementaire dans le decoupage.

   Un chapitre peut avoir (ou non) une ou plusieurs sections. Elles
   sont designees par l'element <sect1>. Si une section inclue une
   autre section, utilisez l'element <sect2>, et ainsi de suite,
   jusqu'`a <sect5>.

   Le contenu du livre est lui-meme dans les chapitres et sections.

   Un article est plus simple qu'un livre, et n'a pas de chapitres.
   Au lieu de cela, le contenu d'un article est organise en une ou
   plusieurs sections, `a l'aide des memes elements <sect1> (<sect2>
   et ainsi de suite) dont on se sert pour les livres.

   Il vous faudra manifestement choisir le type de document `a
   utiliser selon la nature du document que vous redigez. Les
   articles sont bien adaptes pour des documents qui n'ont pas besoin
   d'etre decomposes en chapitres, et qui sont, relativement parlant,
   assez court - jusqu'`a 20-25 pages. Les livres eux conviennent aux
   documents qui peuvent etre decoupes en plusieurs chapitres, avec
   eventuellement des annexes, et autres composants.

   Les guides FreeBSD sont tous des articles, tandis que ce document,
   la FAQ FreeBSD, et le Manuel de Reference FreeBSD sont des livres.

     --------------------------------------------------------------

    4.2.3.1. Commencer un livre

   Le contenu d'un livre est un inclus dans l'element <book>. Tout
   autant que des marques organisant le contenu, cet element peut
   contenir des elements qui donnent des informations supplementaires
   sur le livre. Ce sont soit des meta-informations, utilisees pour y
   faire reference, soit un contenu supplementaire servant `a generer
   la page de titre.

   Ces informations supplementaires doivent etre inclues dans
   l'element <bookinfo>.

   Exemple 4-21. Boilerplate??? <book> avec <bookinfo>

 <book>
   <bookinfo>
     <title>Mettez le titre ici</title>
    
     <author>
       <firstname>Votre prenom</firstname>
       <surname>Votre nom de famille</surname>
       <affiliation>
         <address><email>Votre adresse de courrier
               electronique</email></address>
       </affiliation>
     </author>

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

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

     <releaseinfo>$Id$</releaseinfo>

     <abstract>
       <para>Resumez ici le contenu du
             livre.</para>
     </abstract>
   </bookinfo>

   ...

 </book>

     --------------------------------------------------------------

    4.2.3.2. Commencer un article

   Le contenu d'un article est un inclus dans l'element <article>.
   Tout autant que des marques organisant le contenu, cet element
   peut contenir des elements qui donnent des informations
   supplementaires sur l'article. Ce sont soit des meta-informations,
   utilisees pour y faire reference, soit un contenu supplementaire
   servant `a generer la page de titre.

   Ces informations supplementaires doivent etre inclues dans
   l'element <artheader>.

   Exemple 4-22. Boilerplate??? <article> avec <artheader>

 <article>
   <artheader>
     <title>Mettez le titre ici</title>
    
     <author>
       <firstname>Votre prenom</firstname>
       <surname>Votre nom de famille</surname>
       <affiliation>
         <address><email>Votre adresse de courrier
               electronique</email></address>
       </affiliation>
     </author>

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

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

     <releaseinfo>$Id$</releaseinfo>

     <abstract>
       <para>Resumez ici le contenu de l'article.</para>
     </abstract>
   </artheader>

   ...

 </article>

     --------------------------------------------------------------

    4.2.3.3. Separer les chapitres

   Utilisez <chapter> pour marquer vos chapitres. Chaque chapitre a
   obligatoirement un <title>. Les articles n'ont pas de chapitre,
   ils sont reserves aux livres.

   Exemple 4-23. Un chapitre

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

   ...
 </chapter>

   Un chapitre ne peut pas etre vide, il doit contenir des elements
   en plus du <title>. Si vous voulez inclure un chapitre vide,
   ajoutez lui simplement un paragraphe vide.

   Exemple 4-24. Chapitres vides

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

   <para></para>
 </chapter>

     --------------------------------------------------------------

    4.2.3.4. Sections dans les chapitres

   Dans les livres, les chapitres peuvent (mais ce n'est pas
   obligatoire) etre decomposes en sections, sous-sections, et ainsi
   de suite. Dans les articles, les sections sont les principaux
   elements d'organisation et chaque article doit contenir au moins
   une section. Utilisez l'element <sectn>. Le n est le type de
   section, qui indique son niveau de profondeur.

   La premiere <sectn> est <sect1>. Vous pouvez en avoir plus d'une
   dans un chapitre. Elles peuvent inclure un ou plusieurs elements
   <sect2>, et ainsi de suite, jusqu'`a <sect5>.

   Exemple 4-25. Sections dans les chapitres

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

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

   <sect1>
     <title>Premiere section (1.1)</title>

     ...
   </sect1>

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

     <sect2>
       <title>Premiere sous-section (1.2.1)</title>

       <sect3>
         <title>Premiere sous-sous-section (1.2.1.1)</title>

         ...
       </sect3>
     </sect2>

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

       ...
     </sect2>
   </sect1>
 </chapter>

     Note : Cet exemple donne les numeros des sections dans leurs
     titres. Vous ne devez pas le faire. Les feuilles de style s'en
     chargent (voir plus bas pour plus de details), et vous n'avez
     pas `a vous en preoccupez.

     --------------------------------------------------------------

    4.2.3.5. Subdivision en <part>s

   Vous pouvez avoir un niveau d'organisation supplementaire entre le
   <book> et le <chapter> en definissant une ou plusieurs <part>s. Ce
   n'est pas possible dans un <article>.

 <part>
   <title>Introduction</title>

   <chapter>
     <title>Resum&eacute;</title>

     ...
   </chapter>

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

     ...
   </chapter>

   <chapter>
     <title>Historique</title>

     ...
   </chapter>
 </part>

     --------------------------------------------------------------

  4.2.4. Elements de blocs

    4.2.4.1. Paragraphes

   DocBook connait trois types de paragraphes : <formalpara>, <para>
   et <simpara>.

   La plupart du temps, des <para>s vous suffiront. Les <formalpara>s
   ont un <title>, et avec les <simpara>s, certains elements sont
   interdits `a l'interieur du paragraphe. Tenez-vous en aux <para>s.

   Exemple 4-26. <para>

   Utilisez :

 <para>C'est un paragraphe. Il peut contenir
   presque n'importe quel autre &eacute;l&eacute;ment.</para>

   Apparence :

   C'est un paragraphe. Il peut contenir presque n'importe quel autre
   element.

     --------------------------------------------------------------

    4.2.4.2. Citations en bloc

   Une citation en bloc est un long extrait d'un autre document qui
   ne doit pas faire partie du paragraphe courant. Vous n'en aurez
   probablement pas besoin souvent.

   Les citations en blocs peuvent facultativement avoir un titre et
   une attribution (ou n'avoir ni titre ni attribution).

   Exemple 4-27. <blockquote>

   Utilisez :

 <para>Un court extrait de la constitution des Etats-Unis&nbsp;:</para>
              
 <blockquote>
   <title>Pr&eacute;ambule &agrave; la Constitution des Etats-Unis</title>

   <attribution>Copi&eacute; d'un site Web quelque part</attribution>
            
   <para>Nous le Peuple des Etats-Unis, dans le but de former
     une Union plus parfaite, d'&eacute;tablir la Justice, de garantir
     la Tranquilit&eacute; domestique, assurer la d&eacute;fense collective,
     promouvoir notre Bien-&ecirc;tre g&eacute;n&eacute;ral, et conserver &agrave;
     nous-m&ecirc;mes et &agrave; notre Post&eacute;rit&eacute; les bienfaits de la
     Libert&eacute;, proclamons et &eacute;tablissons cette Constitution des
     Etats-Unis d'Am&eacute;rique.</para>
 </blockquote>

   Apparence :

   Un court extrait de la constitution des Etats-Unis :

     Preambule `a la Constitution des Etats-Unis                      
                                                                    
     Nous le Peuple des Etats-Unis, dans le but de former une Union 
     plus parfaite, d'etablir la Justice, de garantir la            
     Tranquilite domestique, assurer la defense collective,         
     promouvoir notre Bien-etre general, et conserver `a nous-memes 
     et `a notre Posterite les bienfaits de la Liberte, proclamons  
     et etablissons cette Constitution des Etats-Unis d'Amerique.   
                                 --Copie d'un site Web quelque part   

     --------------------------------------------------------------

    4.2.4.3. Indications, notes, avertissements, mises en garde,
    informations importantes et barres verticales.

   Vous devrez peut-etre ajouter des informations distinctes du texte
   lui-meme. Ce sont habituellement des ``meta-informations'' que
   l'utilisateur doit connaitre.

   Selon la nature de l'information, vous utiliserez l'un des
   elements <tip>, <note>, <warning>, <caution> ou <important>. Ou
   bien, si l'information est en rapport avec le texte, mais ne
   correspond `a aucun des cas precedents, servez-vous de <sidebar>.

   Les cas ou il faut choisir l'un ou l'autre de ces elements ne sont
   pas clairement explicites. Voici ce que suggere la documentation
   DocBook :

     * Une Note est une information destinee `a tous les lecteurs.

     * Un element Important est une variante de la Note.

     * Une Caution est une information relative `a la perte de
       donnees ou degats logiciels eventuels.

     * Un Warning est une information relative aux degats materiels
       ou risques corporels.

   Exemple 4-28. <warning>

   Utilisez :

 <warning>
   <para>Installer FreeBSD peut vous donner envie de supprimer
     Windows de votre disque dur.</para>
 </warning>

     Avertissement : Installer FreeBSD peut vous donner envie de
     supprimer Windows de votre disque dur.

     --------------------------------------------------------------

    4.2.4.4. Listes and procedures

   Vous aurez souvent besoin de lister des informations ou d'indiquer
   `a l'utilisateur les differentes etapes necessaires pour effectuer
   une tache donnee.

   Pour cela, servez-vous de <itemizedlist>, <orderedlist> ou
   <procedure>[3]

   <itemizedlist> et <orderedlist> sont semblables `a leurs
   contreparties <ul> et <ol> en HTML. Chacune comporte un ou
   plusieurs elements <listitem>, et chaque <listitem> contient un ou
   plusieurs elements de blocs. Les elements <listitem> sont
   analogues aux marques <li> du HTML. Neanmoins, au contraire du
   HTML, ils sont ici obligatoires.

   Une <procedure> est legerement differente. Elle consiste en
   <step>s, qui `a leur tour sont composes de <step>s ou <substep>s.
   Chaque <step> contient des elements de blocs.

   Exemple 4-29. <itemizedlist>, <orderedlist> et <procedure>

   Utilisez :

 <itemizedlist>
   <listitem>
     <para>C'est le premier &eacute;l&eacute;ment de la liste.</para>
   </listitem>

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

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

   <listitem>
     <para>C'est le second &eacute;l&eacute;ment de la liste ordonn&eacute;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>

   Apparence :

     * C'est le premier element de la liste.

     * C'est le second element de la liste.

    1. C'est le premier element de la liste ordonnee.

    2. C'est le second element de la liste ordonnee.

    1. Faites ceci.

    2. Puis cela.

    3. Et maintenant cela.

     --------------------------------------------------------------

    4.2.4.5. Extraits de fichiers

   Si vous voulez incorporer un extrait de fichier (ou eventuellement
   une fichier entier), mettez-le dans un element <programlisting>.

   Les blancs et sauts de ligne `a l'interieur de <programlisting>
   sont significatifs. Cela signifie en particulier que la marque de
   debut doit etre sur la meme ligne que la premiere ligne du listing
   et que la marque de fin doit etre sur la meme ligne que la
   derniere ligne du listing, sans quoi il y aurait des lignes
   blanches en trop.

   Exemple 4-30. <programlisting>

   Utilisez :

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

   Notez qu'il faut utiliser les entites correspondantes et non les
   signes ``superieur'' et ``inferieur'' `a la ligne #include.

   Apparence :

   Quand vous aurez fini votre programme, ressemblera `a cela :

 #include <stdio.h>

 int
 main(void)
 {
     printf("bonjour, le monde\n");
 }

     Note : DocBook dispose d'un mecanisme pour faire reference `a
     des sections d'un <programlisting> inclus auparavant, appele
     ``rappels'' (voir <programlistingco> pour plus d'information).
     Je ne le comprend pas tout `a fait (i.e., je ne l'ai jamais
     employe), je ne peux donc pas le decrire. En attendant, vous
     pouvez numeroter les lignes et y faire reference ensuite. Cela
     changera des que je trouverais le temps de comprendre et
     documenter les ``rappels''.

     --------------------------------------------------------------

    4.2.4.6. Tables

   Au contraire d'HTML, vous n'avez pas besoin d'utiliser les tables
   pour des questions de presentation, puisque les feuilles de style
   s'en chargent. Les tables servent uniquement pour les donnees en
   tableaux.

   Brievement (voyez la documentation de DocBook pour plus de
   details), une table (qui peut-etre formelle ou informelle) est
   constituee d'un element <table>. Il contient au moins un element
   <tgroup>, dont l'attribut donne le nombre de colonnes dans ce
   sous-tableau. Dans le sous-tableau, vous pouvez ensuite avoir un
   element <thead>, qui contient les elements correspondant aux
   en-tetes des colonnes, et un <tbody> qui contient le corps du
   tableau.

   Les <thead> et <tbody> contiennent des elements <row> - lignes,
   qui contiennent `a leur tour des elements <entry>. Chaque element
   <entry> correspond `a une cellule du tableau.

   Exemple 4-31. <informaltable>

   Utilisez :

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

   Apparence :

   +----------------------------------------------------------------+
   | 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            |
   +----------------------------------------------------------------+

   Si vous ne voulez pas de bordures autour du tableau, vous pouvez
   ajouter `a l'element <informaltable> l'attribut frame avec la
   valeur none (i.e., <informaltable frame="none">).

   Exemple 4-32. Tableaux avec frame="none"

   Apparence :

   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             

     --------------------------------------------------------------

    4.2.4.7. Exemples que l'utilisateur doit suivre

   Vous aurez souvent `a donner des exemples que l'utilisateur puisse
   suivre. Ce seront habituellement des dialogues avec la machine :
   l'utilisateur tape une commande, il rec,oit une reponse, il tape
   une autre commande, et ainsi de suite.

   Il y a l`a un certain nombre d'entites et d'elements qui entrent
   en jeu.

   <screen>

           Tout ce que l'utilisateur voit dans cet exemple est
           affiche sur l'ecran de l'ordinateur, l'element suivant est
           donc <screen>.

           A l'interieur de <screen>, les blancs sont significatifs.

   <prompt>, &prompt.root; et &prompt.user;

           Parmi ce que l'utilisateur verra `a l'ecran, il y a les
           invites (du systeme, de l'interpreteur de commandes ou des
           applications). Ils doivent etre marques avec <prompt>.

           Le cas particulier des deux invites de l'interpreteur de
           commandes, pour un utilisateur ordinaire et pour le
           super-utilisateur, est traite avec des entites. Chaque
           fois que vous voulez montrer que l'utilisateur est sous
           l'interpreteur de commande, servez-vous de &prompt.root;
           ou &prompt.user; selon le cas. Il n'y a pas besoin
           qu'elles soient `a l'interieur de <prompt>.

             Note : &prompt.root; et &prompt.user; sont des
             extensions FreeBSD `a DocBook, et ne font pas partie de
             la DTD originale.

   <userinput>

           Quant il s'agit de texte que l'utilisateur doit taper,
           mettez-le dans un element <userinput>. Il sera normalement
           affiche differement.

   Exemple 4-33. <screen>, <prompt> et <userinput>

   Utilisez :

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

   Apparence:

 % ls -1
 foo1
 foo2
 foo3
 % ls -1 | grep foo2
 foo2
 % su
 Password:
 # cat foo2
 C'est le fichier 'foo2'

     Note : Bien que nous montrions le contenu du fichier foo2, nous
     n'utilisons pas la marque <programlisting>. Reservez
     <programlisting> pour les extraits de fichiers hors du dialogue
     homme/machine.

     --------------------------------------------------------------

  4.2.5. Elements en ligne

    4.2.5.1. Mettre de l'information en valeur

   Si vous voulez mettre en valeur un mot ou une phrase, servez-vous
   de <emphasis>. La presentation en sera peut-etre en italiques, ou
   gras, ou bien ce sera prononce differement par un logiciel de
   synthese vocale.

   Il n'y a aucun moyen de changer la presentation du texte mis en
   valeur dans votre document, pas d'equivalent des <b> et <i>. Si
   l'information que vous donnez est importante, envisagez d'utiliser
   <important> plutot que <emphasis>.

   Exemple 4-34. <emphasis>

   Utilisez :

 <para>FreeBSD est sans aucun doute
   <emphasis>le</emphasis> premier syst&egrave;me
   d'exploitation de type Unix pour
   architecture Intel.</para>

   Apparence :

   FreeBSD est sans aucun doute le premier systeme d'exploitation de
   type Unix pour architecture Intel.

     --------------------------------------------------------------

    4.2.5.2. Applications, commandes, options et references

   Il vous arrivera souvent de designer des applications ou des
   commandes quand vous redigerez quelque chose pour le Manuel de
   Reference. Distinguer les unes des autres est simple : une
   application est un ensemble de (ou eventuellement un seul)
   programmes dedies `a une tache particuliere. Une commande est le
   nom d'un programme que l'utilisateur peut executer.

   Vous aurez aussi de temps `a autre `a lister une ou plusieurs des
   options d'une commande.

   Pour finir, il arrivera souvent que vous vouliez indiquer en meme
   temps que la commande, son numero de section dans les pages de
   manuel, au format ``commande(numero)'' habituel dans les
   documentations Unix.

   Designez les noms d'applications avec <application>.

   Si vous voulez lister une commande avec son numero de section dans
   le manuel (ce qui sera la plupart du temps le cas), l'element
   DocBook pour cela est <citerefentry>. Il contiendra deux autres
   elements, <refentrytitle> et <manvolnum>. Le contenu de
   <refentrytitle> est le nom de la commande, et celui de <manvolnum>
   est son numero de section dans le manuel.

   Ce peut etre fastidieux `a taper, aussi a-t-on defini une series
   d'entites generales pour faciliter ces references. Chacune de ces
   entites est de la forme &man.page-de-manuel.section-du-manuel;.

   Ces entites sont dans le fichier doc/share/sgml/man-refs.ent, qui
   peut-etre reference par le FPI :

 PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"

   L'introduction de votre documentation ressemblera donc probalement
   `a  :

 <!DOCTYPE book PUBLIC
   "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [

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

 ...

 ]>

   Servez-vous de <command> quand vous voulez mettre le nom d'une
   commande dans le texte en le presentant comme quelque chose que
   l'utilisateur doit taper.

   Utilisez <option> pour designer les options d'une commande.

   Ce peut etre confus, et le bon choix n'est pas toujours evident.
   Esperons que les exemples qui suivent eclaircirons les choses.

   Exemple 4-35. Applications, commandes et options.

   Utilisez :

 <para><application>Sendmail</application> est le logiciel de
   courrier &eacute;lectronique le plus employ&eacute; 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&egrave;tres de la ligne de commande de
   <citerefentry><refentrytitle>sendmail</refentrytitle>
     <manvolnum>8</manvolnum></citerefentry>,
     <option>-bp</option>, affiche l'&eacute;tat des messages
     dans la file d'attente. V&eacute;rifiez-le en ex&eacute;cutant
     <command>sendmail -bp</command>.</para>

   Apparence :

   Sendmail est le logiciel de courrier electronique le plus employe
   sous Unix.

   Sendmail comporte les programmes sendmail(8) et newaliases(8).

   L'un des parametres de la ligne de commande de sendmail(8), -bp,
   affiche l'etat des messages dans la file d'attente. Verifiez-le en
   executant sendmail -bp.

     Note : Remarquez comme il est plus facile d'utiliser la notation
     &man.commande.section;.

     --------------------------------------------------------------

    4.2.5.3. Fichiers, repertoires, extensions

   Chaque fois que vous voulez donner le nom d'un fichier, d'un
   repertoire ou de l'extension d'un fichier, servez-vous de
   <filename>.

   Exemple 4-36. <filename>

   Utilisez :

 <para>Vous trouverez le source SGML du Manuel
   de R&eacute;f&eacute;rence en Anglais dans
   <filename>/usr/doc/en/handbook/</filename>. Le
   fichier principal, dans ce r&eacute;pertoire, s'appelle
   <filename>handbook.sgml</filename>. Il doit aussi
   y avoir un <filename>Makefile</filename> et un
   certain nombre de fichiers avec l'extension
   <filename>.ent</filename>.</para>

   Apparence :

   Vous trouverez le source SGML du Manuel de Reference en Anglais
   dans /usr/doc/en/handbook/. Le fichier principal, dans ce
   repertoire, s'appelle handbook.sgml. Il doit aussi y avoir un
   Makefile et un certain nombre de fichiers avec l'extension .ent.

     --------------------------------------------------------------

    4.2.5.4. Fichiers speciaux de peripheriques

     extension FreeBSD : Ces elements font partie des extensions
     FreeBSD `a DocBook et n'existent pas dans la DTD DocBook
     d'origine.

   Pour faire reference `a des fichiers speciaux de peripheriques,
   vous avez deux solutions. Soit utiliser le nom du fichier special
   dans /dev, soit le nom sous lequel il est designe dans le noyau.
   Dans ce dernier cas, servez-vous de <devicename>.

   Il y a des cas ou vous n'aurez pas le choix. Pour certains
   peripheriques, les cartes reseaux par exemple, il n'y a pas
   d'entrees dans /dev, ou bien celles-ci sont tres differentes des
   noms utilises dans le noyau.

   Exemple 4-37. <devicename>

   Utilisez :

 <para><devicename>sio</devicename> sert
   sous FreeBSD aux communications s&eacute;ries.
   <devicename>sio</devicename> correspond
   &agrave; un certain nombre d'entr&eacute;es dans
   <filename>/dev</filename>, dont
   <filename>/dev/ttyd0</filename> et
   <filename>/dev/cuaa0</filename>.</para>

 <para>A l'inverse, les p&eacute;riph&eacute;riques r&eacute;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>

   Apparence :

   sio sert sous FreeBSD aux communications series. sio correspond `a
   un certain nombre d'entrees dans /dev, dont /dev/ttyd0 et
   /dev/cuaa0.

   A l'inverse, les peripheriques reseaux, tel que ed0 n'apparaissent
   pas dans /dev.

   Sous MS-DOS, le premier lecteur de disquette s'appelle a:. Sous
   FreeBSD, c'est /dev/fd0.

     --------------------------------------------------------------

    4.2.5.5. Machines, domaines, adresses IP, et ainsi de suite

     extension FreeBSD : Ces elements font partie des extensions
     FreeBSD `a DocBook et n'existent pas dans la DTD DocBook
     d'origine.

   Il y a differentes fac,ons de denoter les informations
   d'identification des machines en reseau, selon le type
   d'information. Elles utilisent toutes <hostid> comme element,
   l'attribut role servant `a qualifier le type d'information.

   Pas de valeur de l'attribut, ou role="hostname"

           Sans valeur de l'attribut (i.e., <hostid>...<hostid>),
           l'information donnee est le seul nom de la machine,
           freefall ou wcarchive, par exemple. Vous pouvez
           l'expliciter avec role="hostname".

   role="domainname"

           C'est ici un nom de domaine, comme FreeBSD.org ou
           ngo.org.uk. Il n'y a pas de nom de machine.

   role="fqdn"

           C'est le nom complet de la machine - Fully Qualified
           Domain Name, compose du nom de la machine et du nom de
           domaine.

   role="ipaddr"

           On donne alors l'adresse IP, probablement sous forme de
           quatre nombres separes par des points.

   role="netmask"

           C'est un masque de sous-reseau, qui peut etre donne comme
           quatre nombres separes par des points, un chaine en
           hexadecimal ou un / suivi d'un nombre.

   role="mac"

           C'est une adresse Ethernet MAC, exprimee par un series de
           valeurs hexadeciamales sur deux positions separees par des
           deux-points.

   Exemple 4-38. <hostid> et roles

   Utilisez :

 <para>La machine locale peut toujours
   &ecirc;tre d&eacute;sign&eacute;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&eacute;seau
   <hostid role="netmask">255.255.255.255</hostid>
   (qui peut aussi s'&eacute;crire
   <hostid role="netmask">0xffffffff)</hostid>.</para>

 <para>L'adresse MAC identifie de fa&ccedil;on unique
   chaque carte r&eacute;seau existante.  Une adresse MAC
   ressemble typiquement &agrave; <hostid
     role="mac">08:00:20:87:ef:d0</hostid>.</para>

   Apparence :

   La machine locale peut toujours etre designee par localhost, et
   aura l'adresse IP 127.0.0.1.

   Le domaine FreeBSD.org inclut un certain nombre de machine, dont
   freefall.FreeBSD.org et bento.FreeBSD.org.

   Quand vous ajoutez un alias IP `a une interface (avec ifconfig),
   utilisez toujours le masque de sous-reseau 255.255.255.255 (qui
   peut aussi s'ecrire 0xffffffff).

   L'adresse MAC identifie de fac,on unique chaque carte reseau
   existante. Une adresse MAC ressemble typiquement `a
   08:00:20:87:ef:d0.

     --------------------------------------------------------------

    4.2.5.6. Noms d'utilisateurs

     extension FreeBSD : Ces elements font partie des extensions
     FreeBSD `a DocBook et n'existent pas dans la DTD DocBook
     d'origine.

   Si vous avez besoin de faire reference `a un nom d'utilisateur,
   comme root ou bin, servez-vous de <username>.

   Exemple 4-39. <username>

   Utilisez :

 <para>Pour effectuer la plupart des
   t&acirc;ches d'administration syst&egrave;me,
   vous aurez besoin d'&ecirc;tre
   <username>root</username>.</para>

   Apparence :

   Pour effectuer la plupart des taches d'administration systeme,
   vous aurez besoin d'etre root.

     --------------------------------------------------------------

    4.2.5.7. Decrire les Makefiles

     extension FreeBSD : Ces elements font partie des extensions
     FreeBSD `a DocBook et n'existent pas dans la DTD DocBook
     d'origine.

   Il y a des elements pour decrire les composantes d'un Makefiles,
   <maketarget> et <makevar>.

   <maketarget> designe une cible definie dans un Makefile qui peut
   etre utilisee en parametre de make. <makevar> designe une variable
   qui peut etre definie (dans l'environnement, sur la ligne de
   commande de make ou dans le Makefile) et affecte le processus .

   Exemple 4-40. <maketarget> et <makevar>

   Utilisez :

 <para>Il y a deux cibles courantes dans les
   <filename>Makefile</filename>&nbsp;:
   <maketarget>all</maketarget> et
   <maketarget>clean</maketarget>.</para>

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

 <para><maketarget>clean</maketarget> peut &ecirc;tre
   contr&ocirc;l&eacute;e par un certain nombre
   de variables, dont <makevar>CLOBBER</makevar> et
   <makevar>RECURSE</makevar>.</para>

   Apparence :

   Il y a deux cibles courantes dans les Makefile : all et clean.

   Generalement, invoquer all reconstruit l'application, et invoquer
   clean supprime les fichiers temporaires (.o par exemple) crees
   lors de la reconstruction.

   clean peut etre controlee par un certain nombre de variables, dont
   CLOBBER et RECURSE.

     --------------------------------------------------------------

    4.2.5.8. Literaux

   Vous aurez souvent besoin d'inclure ``literalement'' du texte dans
   le Manuel. Ce sont des extraits d'un fichier, que l'on doit
   pouvoir copier tel quel dans un autre fichier.

   Il vous suffira parfois de <programlisting> pour cela.
   <programlisting> n'est pas toujours approprie, en particulier
   quand vous voulez inclure un extrait de fichier au fil de l'eau,
   dans le corps meme du paragraphe.

   Servez-vous dans ces cas-l`a de <literal>.

   Exemple 4-41. <literal>

   Utilisez :

 <para>La ligne <literal>maxusers 10</literal> du fichier
   de configuration du noyau d&eacute;termine la table de nombreuses
   tables syst&egrave;me et d&eacute;finit approximativement le nombre de
   connexions simultan&eacute;es qu'acceptera le syst&egrave;me.</para>

   Apparence :

   La ligne maxusers 10 du fichier de configuration du noyau
   determine la table de nombreuses tables systeme et definit
   approximativement le nombre de connexions simultanees qu'acceptera
   le systeme.

     --------------------------------------------------------------

    4.2.5.9. Montrer ce que l'utilisateur doit renseigner

   Il arrivera souvent que vous vouliez montrer `a l'utilisateur ce
   qu'il doit faire, faire reference `a un fichier, `a une ligne de
   commande, ou autre, dans lesquels l'utitilisateur ne pourra pas
   purement et simplement copier les examples que vous lui donnez,
   mais devra y renseigner lui-meme certaines informations.

   <replaceable> est prevu pour ces cas-l`a. Servez-vous en `a
   l'interieur d'autres elements pour indiquer quels contenus
   l'utilisateur doit remplacer.

   Exemple 4-42. <replaceable>

   Utilisez :

 <informalexample>
   <screen>&prompt.user; <userinput>man
   <replaceable>command</replaceable></userinput></screen>
 </informalexample>

   Apparence :

 % man command

   <replaceable> peut servir dans de nombreux autres elements, dont
   <literal>. Cet exemple montre aussi qu'il ne faut mettre
   <replaceable> qu'autour du contenu que l'utilisateur doit fournir.
   Il faut laisser le reste tel quel.

   Utilisez :

 <para>La ligne <literal>maxusers 10</literal> du fichier
   de configuration du noyau d&eacute;termine la table de nombreuses
   tables syst&egrave;me et d&eacute;finit approximativement le nombre
   de connexions simultan&eacute;es qu'acceptera le syst&egrave;me.</para>

 <para><literal>32</literal> est un valeur correcte de
   <replaceable>n</replaceable> pour une station
   de travail.</para>

   Apparence :

   La ligne maxusers 10 du fichier de configuration du noyau
   determine la table de nombreuses tables systeme et definit
   approximativement le nombre de connexions simultanees qu'acceptera
   le systeme.

   32 est un valeur correcte de n pour une station de travail.

     --------------------------------------------------------------

  4.2.6. Liens

     Note : Les liens sont aussi des elements en ligne.

     --------------------------------------------------------------

    4.2.6.1. Mettre des liens vers d'autres parties du meme document

   Pour mettre de liens `a l'interieur meme du document, il faut que
   vous precisiez d'ou part le lien (i.e., le texte ou autre, sur
   lequel l'utilisateur clique) et ou il va.

   Chaque element DocBook possede un attribut id. Vous pouvez
   utiliser cet attribut pour donner un nom unique `a l'element.

   C'est cette valeur que vous utiliserez quand vous preciserez la
   destination du lien.

   Habituellement, vous mettrez des liens sur des chapitres ou des
   sections, vous ajouterez donc un attribut id `a ces elements.

   Exemple 4-43. id de chapitres et de section

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

   Vous devriez utiliser des valeurs plus explicites. Ces valeurs
   doivent etre uniques pour le document (i.e., pas uniquement dans
   le fichier, mais dans le document dans lequel le fichier peut
   eventuellement etre inclus aussi). Remarquez que l'id de la
   sous-section est construit en le prefixant de l'id du chapitre.
   Cela aide `a construire des identifiants uniques.

   Si vous voulez que l'utilisateur puisse aller `a un endroit precis
   du document (eventuellement au milieu du paragraphe), ou `a un
   exemple, servez-vous de <anchor>. Cet element n'a pas de contenu,
   mais il a un attribut id.

   Exemple 4-44. <anchor>

 <para>Ce paragraphe inclut un
   <anchor id="para1">lien interne. Il n'appara&icirc;t
   pas dans le document.</para>

   Si vous voulez fournir `a l'utilisateur un lien qu'il puisse
   activer (probablement en cliquant dessus) pour aller `a une
   section du document qui a un attribut id, vous pouvez vous servir
   de <xref> ou <link>.

   Ces deux elements ont un attribut linkend. La valeur de cette
   attribut doit etre celle que vous avez utilisee comme attribut id
   (peu importe si cette valeur n'a pas encore ete definie dans le
   document, les liens peuvent etre en avant ou en arriere).

   Si vous vous servez de <xref>, vous n'avez pas le controle du
   texte du lien. Il sera genere automatiquement.

   Exemple 4-45. Se servir de <xref>

   Supposons que ce fragment apparaisse quelque part dans un document
   qui contienne l'exemple que nous avons donne pour id :

 <para>Vous trouverez plus d'information
   au <xref linkend="chapter1">.</para>

 <para>Vous trouverez des informations plus d&eacute;taill&eacute;es dans
   <xref linkend="chapter1-sect1">.</para>

   Le texte du lien sera genere automatiquement, et cela ressemblera
   `a (le texte mis en valeur indique que c'est cela le lien) :

     Vous trouverez plus d'information au Chapitre Un.

     Vous trouverez des informations plus detaillees dans la section
     appellee Sous-section 1.

   Remarquez que le texte du lien est construit `a partir du titre de
   la section ou du numero du chapitre.

     Note : Cela veut dire que vous ne pouvez pas utiliser <xref>
     pour mettre un lien sur l'attribut id d'un element <anchor>.
     L'<anchor> n'a pas de contenu et <xref> ne pourrait donc pas
     generer le texte du lien.

   Si vous voulez avoir la maitrise du texte du lien, servez-vous
   alors de <link>. Cet element encadre un contenu qui sera utilise
   comme lien.

   Exemple 4-46. Utiliser <link>

   Supposons que ce fragment apparaisse quelque part dans un document
   qui contienne l'exemple que nous avons donne pour id :

 <para>Vous trouverez plus d'information
   au <link linkend="chapter1">premier chapitre</link>.</para>

 <para>Vous trouverez des informations plus d&eacute;taill&eacute;es dans
   <link linkend="chapter1-sect1">cette</link>
   section.</para>

   Ce qui generera (le texte mis en valeur indique que c'est cela le
   lien) :

     Vous trouverez plus d'information au premier chapitre.

     Vous trouverez des informations plus detaillees dans cette
     section.

     Note : Le dernier exemple n'est pas `a suivre. N'utilisez jamais
     ``ce'' ou ``ici'' comme origine du lien. Le lecteur devra
     detailler le contexte dans lequel c'est employe pour comprendre
     ou le lien va le mener.

     Note : Vous pouvez vous servir de <link> pour mettre un lien sur
     un id ou une <anchor>, puisque le contenu du <link> definit le
     texte qui sera utilise comme lien.

     --------------------------------------------------------------

    4.2.6.2. Liens vers d'autres documents sur le WWW

   Mettre des liens sur des documents externes est beaucoup plus
   facile, si tant est que vous connaissiez l'URL du document sur
   lequel vous voulez mettre un lien. Servez-vous de <ulink>.
   L'attribut url sera l'URL de la page ou pointera le lien, et le
   contenu du lien sera utilise pour que l'utilisateur puisse
   l'activer.

   Exemple 4-47. <ulink>

   Utilisez :

 <para>Vous pouvez bien s&ucirc;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>

   Apparence :

   Vous pouvez bien sur cessez de lire ce document, et aller au lieu
   de cela sur la page Web de FreeBSD.

     --------------------------------------------------------------

4.3. * LinuxDoc

   LinuxDoc est adapte de la DTD QWERTZ, et a ete d'abord utilise par
   le Projet de Documentation de Linux, puis adopte ensuite par celui
   de FreeBSD.

   La DTD LinuxDoc utilise des marques qui decrivent avant tout
   l'apparence du document et non son contenu (i.e., elle decrit `a
   quoi quelque chose ressemble, et non ce que c'est).

   Et le Projet de Documentation de FreeBSD et celui de Linux sont en
   train de migrer de la DTD LinuxDoc `a la DTD DocBook.

   La DTD LinuxDoc DTD est disponible au catalogue des logiciels
   portes, dans la categorie textproc/linuxdoc.

     --------------------------------------------------------------

                    Chapitre 5. * Feuilles de style

   SGML ne decrit pas comment un document doit etre affiche ou
   imprime. A cet effet, differents langages ont ete conc,us pour
   definir des feuilles de style, dont DynaText, Panorama, SPICE,
   JSSS, FOSI, CSS, et DSSSL.

   Pour DocBook, nous utilisons des feuilles de style ecrites en
   DSSSL. Pour le HTML, nous utilisons CSS.

     --------------------------------------------------------------

5.1. * DSSSL

   Le Projet de Documentation utilise une version un minimum
   personnalisee des feuilles de style DocBook modulaires de Norm
   Walsh.

   Vous les trouverez dans textproc/dsssl-docbook-modular.

     --------------------------------------------------------------

5.2. * CSS

     --------------------------------------------------------------

                  Chapitre 6. * La Foire Aux Questions

     --------------------------------------------------------------

                  Chapitre 7. * Le Manuel de Reference

7.1. Organisation logique

   Le Manuel de Reference est redige en conformite avec la DTD
   DocBook etendue de FreeBSD.

   Le Manuel de Reference est un <book> DocBook. Il est ensuite
   divise en <part>s, qui contiennent elles-memes plusieurs
   <chapter>s. Les <chapter>s sont eux-memes composes de sections
   (<sect1>) et sous-sections (<sect2>, <sect3>) et ainsi de suite.

     --------------------------------------------------------------

7.2. Organisation physique

   Le Manuel de Reference (et ses traductions) sont dans le
   sous-repertoire doc/langue/handbook des archives CVS principales.
   langue est le code ISO pour la langue, en, pour l'Anglais, ja pour
   le Japonais, et ainsi de suite.

   Il y a un certain nombre de fichiers et repertoires dans le
   repertoire handbook.

     Note : L'organisation du Manuel de Reference sera peut-etre
     modifiee avec le temps, et le present document peut ne pas etre
     en phase avec ces changements. Si vous avez des questions sur la
     fac,on dont le Manuel de Reference est organise, contactez s'il
     vous plait le Projet de Documentation de FreeBSD,
     <doc@FreeBSD.ORG>.

     --------------------------------------------------------------

  7.2.1. Makefile

   Le Makefile decrit les regles utilisees pour convertir le Manuel
   de Reference `a partir du source (DocBook) dans plusieurs formats
   cibles (dont HTML, PostScript, et texte).

   Le Makefile est decrit plus en detail `a la Section 7.4.

     --------------------------------------------------------------

  7.2.2. handbook.sgml

   C'est la racine du Manuel de Reference. Il contient la declaration
   DOCTYPE du Manuel, ainsi que les elements qui decrivent sa
   structure.

   handbook.sgml utilise des entites parametres pour charger les
   fichiers d'extensions .ent. Ces fichiers (decrits plus loin)
   definissent `a leur tour des entites generales qui sont
   elles-memes employees dans le reste du Manuel.

     --------------------------------------------------------------

  7.2.3. repertoire/chapter.sgml

   Chaque chapitre du manuel est compose d'un fichier chapter.sgml
   dans un sous-repertoire separe pour chaque chapitre. Chaque
   repertoire prend le nom de l'attribut id de l'element <chapter>.

   Si par exemple, un des chapitres contient :

 <chapter id="kernelconfiguration">
 ...
 </chapter>

   il s'appelera alors chapter.sgml dans le repertoire
   kernelconfiguration. Habituellement, il y aura un seul fichier
   pour tout le chapitre.

   A la generation de la version HTML du Manuel, on obtiendra un
   kernelconfiguration.html. C'est du `a la valeur du id, et non au
   nom du repertoire.

   Dans les versions precedentes du Manuel, ces fichiers etaient dans
   le meme repertoire que handbook.sgml, avec le meme nom que
   l'attribut id de l'element <chapter> du fichier. Ils ont ete
   deplaces dans des repertoires separes en prevision des evolutions
   `a venir du Manuel. Il sera en particulier bientot possible
   d'inclure des images dans chaque chapitre. Il est donc plus
   logique que celles-ci soient rangees dans un repertoire ou se
   trouve aussi le texte du chapitre plutot que de mettre le texte de
   chaque chapitre, et donc toutes les images dans un meme
   repertoire. Il y aurait fatalement des conflits de nom, alors
   qu'il est plus facile de travailler avec plusieurs repertoires
   contenant quelques fichiers qu'avec un seul repertoire dans lequel
   il y a beaucoup de fichiers.

   Un bref coup d'oeil montre qu'il y a de nombreux repertoires avec
   chacun un fichier chapter.sgml dont basics/chapter.sgml,
   introduction/chapter.sgml et printing/chapter.sgml.

     Important : Les noms des chapitres et/ou repertoires ne doivent
     pas faire reference `a leur place dans le Manuel. Cet ordre peut
     changer quand le contenu du Manuel est reorganise ; ce type de
     reorganisation ne devrait (normalement) pas entrainer de
     modification des noms des fichiers (`a moins que des chapitres
     entiers ne changent de niveau dans la hierarchie).

   Chaque fichier chapter.sgml n'est pas un document SGML integral.
   Ils n'ont en particulier pas de declaration DOCTYPE en tete du
   fichier.

   C'est dommage pour deux raisons :

     * 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
       meme maniere que le Manuel. Cela vous oblige `a recompiler
       tout le Manuel chaque fois que vous voulez verifier les effets
       d'une modification d'un seul chapitre.

     * Le sgml-mode d'Emacs ne peut pas s'en servir pour determiner
       quelle DTD utiliser, ce qui fait perdre les benefices de
       fonctionnalites utiles du sgml-mode (completion des elements,
       validation automatique, et ainsi de suite).

     --------------------------------------------------------------

7.3. Guide de style

   Respectez s'il vous plait les conventions de style ci-dessous pour
   garder aux sources du Manuel une consistance malgre les nombreuses
   personnes qui interviennent dessus.

     --------------------------------------------------------------

  7.3.1. Majuscules et minuscules

   Les marques doivent etre en minuscules <para> et non <PARA>.

   Le texte dans les contextes SGML est normalement en majuscules,
   <!ENTITY...> ou <!DOCTYPE...> et non <!entity...> ou
   <!doctype...>.

     --------------------------------------------------------------

  7.3.2. Indentation

   Chaque fichier est indente `a partir de la colonne 0, quel que
   soit le niveau d'indentation dans le fichier ou il est inclus.

   Chaque marque de debut augmente l'indentation de 2 blancs et
   chaque marque de fin la decremente d'autant. Le contenu des
   elements doit etre indente de 2 blancs s'il court sur plusieurs
   lignes.

   A titre d'exemple, voici `a quoi ressemble le source de cette
   section :

 +--- 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>

   Si vous vous servez d'Emacs ou Xemacs pour editer les fichiers, le
   sgml-mode doit etre charge automatiquement, et les variables Emacs
   locales en fin de chaque fichier doivent mettre ces indentations
   en pratique.

     --------------------------------------------------------------

  7.3.3. Modifications de presentation des sources

   Quand vous integrez des modifications, ne faites pas en meme temps
   de modification de contenu et de presentation des sources.

   Cela pour que les equipes de traductions du Manuel puissent
   rapidement voir les modifications de contenu que vous avez
   integrees, sans avoir `a se demander si une ligne a change de
   contenu ou simplement de presentation.

   Si vous avez par exemple ajoute deux phrases `a un paragraphe, de
   sorte que les lignes du paragraphe debordent maintenant des 80
   colonnes, integrez d'abord la modification avec les lignes trop
   longues. Puis corrigez ensuite ce probleme, en precisant qu'il ne
   s'agit que d'une modification de presentation, dont les equipes de
   traduction n'ont pas `a se soucier.

     --------------------------------------------------------------

7.4. * Conversion du Manuel dans d'autres formats

     --------------------------------------------------------------

                       Chapitre 8. * Le site Web

     --------------------------------------------------------------

                        Chapitre 9. Traductions

   Ceci est la Foire aux Questions pour les gens qui traduisent la
   documentation de FreeBSD (FAQ, Manuel de Reference, guides, pages
   de manuel et autres) en differentes langues.

   Elle est tres largement basee sur la FAQ du Projet Allemand de
   Documentation de FreeBSD, redigee `a l'origine par Frank Grnder
   <elwood@mc5sys.in-berlin.de> et traduite en Anglais par Bernd
   Warken <bwarken@mayn.de>.

   Nik Clayton <nik@FreeBSD.org> maintient cette FAQ.

   9.1. Pourquoi une FAQ ?

   9.2. Que signfient i18n et l10n ?

   9.3. Y-a-t-il une liste de diffusion pour les traducteurs ?

   9.4. A-t-on besoin de nouveaux traducteurs ?

   9.5. Quelle langue faut-il que je connaisse ?

   9.6. Quels logiciels faut-il que je connaisse ?

   9.7. Comment savoir qui d'autre traduit la documentation dans la
   meme langue ?

   9.8. Il n'y a personne d'autre qui traduise dans ma langue. Que
   faire ?

   9.9. J'ai traduit une documentation, `a qui dois-je l'envoyer ?

   9.10. Je suis la seule personne `a traduire dans cette langue,
   comment soumettre mes traductions ?

   9.11. Puis-je inclure dans mon texte des considerations propres `a
   la langue ou au pays ?

   9.12. Comment faut-il coder les caracteres propres `a une langue ?

   9.13. Comment doit-on s'adresser au lecteur ?

   9.14. Y'a-t-il des informations supplementaires `a inclure dans
   les traductions ?

   9.1. Pourquoi une FAQ ?

   De plus en plus de gens s'adressent `a 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 repondre `a leurs questions de fac,on `a ce qu'ils puissent
   commencer le plus rapidement possible `a traduire la
   documentation.

   9.2. Que signfient i18n et l10n ?

   i18n veut dire internationalisation et l10n localisation. Ce ne
   sont que des abreviations commodes.

   i18n se lit ``i'' suivi de 18 lettres, suivies d'un ``n''. De la
   meme fac,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 `a <freebsd-translate-request@ngo.org.uk> avec le mot
   subscribe dans le texte du message.

   Vous recevrez une reponse vous demandant de confirmer votre
   inscription (de la meme fac,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 acceptes. La liste n'est pas moderee, mais
   vous devez vous y etre inscrit avant d'y adresser des messages.

   La liste est archivee, mais il n'est pas actuellement possible d'y
   faire des recherches. Vous aurez en retour des explications sur la
   fac,on d'acceder aux archives en envoyant le message help `a
   <majordomo@ngo.org.uk>.

   Il est prevue que la liste de diffusion soit transferee 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 realisees, et synchronisees avec les modifications
   de la version anglaise.

   Il n'est pas necessaire que vous soyez traducteur professionnel
   pour pouvoir contribuer.

   9.5. Quelle langue faut-il que je connaisse ?

   Dans l'ideal, il faudrait que vous ayez une bonne connaissance de
   l'anglais ecrit et bien sur, 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, `a partir de la
   traduction espagnole de la FAQ.

   9.6. Quels logiciels faut-il que je connaisse ?

   Il est fortement recommande que vous teniez `a jour une copie
   locale des archives CVS de FreeBSD (au moins de la documentation),
   soit `a l'aide de CTM, soit en utilisant CVSup. Le chapitre ``Se
   synchroniser avec la version -current de FreeBSD'' du Manuel de
   Reference vous explique comment utiliser ces logiciels.

   Il faudra que vous soyiez `a l'aise avec CVS. Cela vous permettra
   de suivre les modifications apportees entre les differentes
   versions des fichiers qui constituent la documentation.

   [A Faire -- ecrire un mode d'emploi qui explique comment utiliser
   CVSup pour ne recuperer que la documentation, et voir ce qui a
   evolue entre deux versions donnees]

   9.7. Comment savoir qui d'autre traduit la documentation dans la
   meme langue ?

   La page des traductions du Projet de Documentation liste les
   traductions en cours dej`a connues. S'il y a dej`a d'autres
   personnes qui travaillent `a la traduction de documentation dans
   votre langue, s'il vous plait, ne faites pas le meme 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 `a la liste de diffusion du groupe de
   documentation de FreeBSD au cas ou quelqu'un aurait dej`a envisage
   de commencer une traduction, mais que ne ce soit pas encore
   signale.

   9.8. Il n'y a personne d'autre qui traduise dans ma langue. Que
   faire ?

   Felicitations, vous venez juste de lancer le ``Projet de
   Documentation dans-votre-langue de FreeBSD. Bien venu `a bord.

   Commencez par vous assurer que vous avez bien du temps disponible.
   Comme vous etes pour le moment le seul volontaire pour la
   traduction dans votre langue, il sera de votre responsabilite de
   publier votre travail et de coordonner celui d'autres personnes
   qui voudraient y collaborer.

   Envoyez un courrier electronique `a la liste de diffusion du
   groupe de documentation de FreeBSD pour annoncer que vous allez
   traduire la documentation de fac,on `a ce que la pages des
   traductions du Projet de Documentation puisse etre tenue `a jour.

   Il faudra vous inscrire `a la liste de diffusion
   <freebsd-translate@ngo.org.uk> (comme explique plus haut).

   S'il y a dej`a dans votre pays quelqu'un qui maintienne un site
   miroir de FreeBSD, vous devriez le contacter et voir s'il peut
   vous fournir un hebergement pour votre projet et, si possible, une
   adresse de courrier electronique et la possibilite 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, `a qui dois-je l'envoyer ?

   Cela depend. Si vous travaillez dej`a au sein d'une equipe de
   traduction (comme l'equipe Japonaise ou l'equipe Allemande), elle
   aura ses propres procedures pour gerer la documentation soumise,
   qui seront decrites dans ses pages Web.

   Si vous etes la seule personne `a travailler dans une langue
   donnee (ou si vous etes 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 `a traduire dans cette langue,
   comment soumettre mes traductions ?

   ou

   Nous sommes une equipe de traduction et voulons soumettre les
   traductions de nos membres ?

   Commencez par verifier que vos traductions sont correctement
   structurees. C'est-`a-dire qu'elles doivent s'integrer `a
   l'arborescence des documentations existantes et compiler sans
   problemes.

   La documentation de FreeBSD est actuellement archivee dans les
   repertoires en dessous de doc/. Les sous-repertoires de celui-ci
   prennent le nom codifiant la langue dans laquelle les
   documentations sont ecrites, selon la norme ISO639
   (/usr/share/misc/iso639, pour les versions de FreeBSD posterieures
   au 20 Janvier 1999).

   S'il ya a differentes codifications pour votre langue (le
   Chinois,par exemple), il y aura au niveau en-dessous plusieurs
   sous-repertoires, un pour chacun des formats de codage que vous
   aurez fournis.

   Vous aurez enfin des sous-repertoires pour chaque document.

   Une eventuelle traduction en Suedois ressemblerait par exemple `a
   ce qui suit :

       doc/
           sv/
              Makefile
              FAQ/
                  Makefile
                  *.sgml

   sv est le code ISO639 pour le Suedois. Remarquez les deux
   Makefiles, qui servent `a compiler la documentation. Il n'y a
   qu'une seule fac,on de coder le Suedois, il n'y a donc pas de
   niveau intermediaire entre les repertoires 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'acces n'en met peut-etre
   pas `a votre disposition), vous pouvez envoyer un courrier
   electronique `a Nik Clayton <nik@FreeBSD.org>, pour vous mettre
   d'accord sur une date pour les lui envoyer par courrier.

   De quelque fac,on que vous procediez, il faudra que vous utilisez
   send-pr(1) pour envoyer un rapport signalant que vous avez soumis
   de la documentation. Il serait tres utile que d'autres puissent
   relire votre traduction d'abord, parce qu'il y a peu de chances
   que la personne qui l'integrera connaisse bien votre langue.

   Quelqu'un (probablement le Responsbale du Projet de Documentation,
   Nik Clayton <nik@FreeBSD.org> actuellement), recuperera votre
   traduction et s'assurera qu'elle compile. En particulier, les
   points suivants seront examines :

    1. Tous vos fichiers utilisent-ils de chaines RCS (comme ``ID'').

    2. make all fonctionne-t-il correctement dans le repertoire sv.

    3. make install fonctionne-t-il correctement.

   S'il y a des problemes, la personne qui examine votre soumission
   vous en fera part pour que vous essayiez de les regler.

   S'il n'y a pas de problemes, votre traduction sera integree aussi
   vite que possible.

   9.11. Puis-je inclure dans mon texte des considerations propres `a
   la langue ou au pays ?

   Nous prefererions que vous ne le fassiez pas.

   Supposons par exemple que vous traduisiez le Manuel de Reference
   en Coreen et que vous vouliez inclure une section sur les
   revendeurs en Coree dans votre Manuel.

   Il n'y a pas vraiment de raison pour que cette information ne soit
   pas aussi presente 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 Coree. Cela permet
   aussi de mettre en avant la penetration de FreeBSD dans le monde
   entier, ce qui n'est pas une mauvaise chose.

   Si vous avez des informations propres `a un pays donne,
   soumettez-les d'abord sous forme de modifications `a la version
   anglaise du Manuel de Reference (avec send-pr(1)) et traduisez-les
   ensuite dans votre langue dans le Manuel de Reference dans cette
   langue.

   Merci.

   9.12. Comment faut-il coder les caracteres propres `a une langue ?

   Dans les documentations, les caracteres Non-ASCII doivent
   apparaitre sous forme d'entites SGML.

   Brievement, celles-ci sont constituees d'une perluette (&), du nom
   de l'entite, et d'un point-virgule (;).

   Les noms des entites sont definis par la norme ISO8879, que vous
   trouverez dans le catalogue des logiciels portes, sous
   textproc/iso8879.

   Voici quelques examples :

   Entite: &eacute;

   L'apparence: e

   Definition: ``e'' accent aigu minuscule

   Entite: &Eacute;

   L'apparence: E

   Definition: ``e'' accent aigu majuscule

   Entite: &uuml;

   L'apparence: u:

   Definition: ``u'' trema minuscule

   Apres installation du logiciel porte ``iso8879'', le fichier
   /usr/local/share/sgml/iso8879 en donne la liste complete.

   9.13. Comment doit-on s'adresser au lecteur ?

   Dans les documents anglais, le ``you'' est employe, il n'y a
   qu'une seule forme, `a 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 supplementaires `a inclure dans
   les traductions ?

   Oui.

   Les en-tetes de la version anglaise du document ressembleront `a
   ceci :

 <!--
      The FreeBSD Documentation Project

      &dollar;Id: chapter.sgml,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 etre remplace par The FreeBSD
   Langue Documentation Project.

   Vous devrez aussi ajouter une troisieme ligne qui donne la version
   anglaise d'origine sur laquelle est basee la traduction.

   Donc, la version espagnole du present fichier commencerait par :

 <!--
      The FreeBSD Spanish Documentation Project

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

     --------------------------------------------------------------

                           Chapitre 10. Style

   Pour conserver une certaine coherence entre le travail des
   nombreux redacteurs de la documentation de FreeBSD, on a defini
   quelques regles `a suivre.

   N'utilisez pas de formes contractees

           N'utilisez pas de formes contractees. Utilisez toujours
           les mots entiers. ``Don't use contractions'' n'est pas
           correct[5].

           Ne pas contracter donne au texte un ton plus formel, est
           plus precis, et facilite la tache des traducteurs.

   Utilisez la virgule dans les enumerations

           Dans une enumeration au sein d'un paragraphe, separez avec
           des virgules les elements les uns des autres. Mettez aussi
           un virgule et la conjonction ``et'' avant le dernier
           element.

           Examinez par exemple la phrase suivante :

             C'est une liste d'un, deux et trois elements.

           Est-ce une liste de trois elements, ``un'', ``deux'', et
           ``trois'', ou une liste de deux elements, ``un'' et ``deux
           et trois'' ?

           Il vaut mieux etre explicite et ajouter la derniere
           virgule :

             C'est une liste d'un, deux, et trois elements.

   Evitez les redondances

           Evitez les redondances. En particulier, ``la commande'',
           ``le fichier'', et ``man commande'' sont probablement
           redondants.

           Voici deux exemples pour ce qui concerne les commandes. Il
           est preferable d'utiliser le second.

           Utilisez la commande cvsup pour mettre `a jour vos
           sources.

           Utilisez cvsup pour mettre `a jour vos sources.

           Voici deux exemples pour ce qui concerne les noms de
           fichiers. Il est preferable d'utiliser le second.

           ... dans le fichier /etc/rc.local...

           ... dans /etc/rc.local...

           Voici enfin deux exemples pour les references aux pages de
           manuel. Il est preferable d'utiliser le second (il emploie
           <citerefentry>).

           Voyez man csh pour plus d'information.

           Voyez csh(1)

   Pour des details sur le style, consultez les Elements de Style, de
   William Strunk.

     --------------------------------------------------------------

               Chapitre 11. Utiliser sgml-mode avec Emacs

   Les versions recentes d'Emacs ou Xemacs (disponibles au catalogue
   des logiciels portes) incluent un paquetage tres utile appele
   PSGML. Il est automatiquement appele au chargement d'un fichier
   avec l'extension .sgml, ou lorsque l'on tape M-x sgml-mode. C'est
   un mode majeur pour traiter les fichiers SGML, les elements et les
   attributs.

   Connaitre certaines des commandes de ce mode peut rendre le
   travail sur des documents comme le Manuel de Reference beaucoup
   plus facile.

   C-c C-e

           Execute sgml-insert-element. On vous demandera le nom de
           l'element `a inserer l`a ou se trouve le curseur. Vous
           pouvez utiliser la touche Tab pour completer le nom de
           l'element. Seuls les elements syntaxiquement valides `a
           cet endroit seront acceptes.

           L'editeur inserera les marques de debut et de fin de
           l'element. S'il y a d'autres elements obligatoires qui
           doivent etre inclus dans cet element, ils seront aussi
           inclus.

   C-c =

           Execute sgml-change-element-name. Mettez-vous dans un
           element et utilisez cette commande. On vous demandera le
           nom de l'element par lequel il faut le remplacer. Les
           marques de debut et de fin de l'element seront remplacees.

   C-c C-r

           Execute sgml-tag-region. Selectionnez du texte
           (placez-vous au debut, C-espace, allez `a la fin du texte,
           C-espace) et lancez ensuite cette commande. On vous
           demandera quel element utiliser. Celui-ci sera insere
           immediatement avant et apres la region choisie.

   C-c -

           Execute sgml-untag-element. Mettez-vous sur la marque de
           debut ou de fin de l'element que vous voulez supprimer et
           lancez cette commande. Les marques de debut et de fin de
           l'element seront supprimees.

   C-c C-q

           Execute sgml-fill-element. ``Remplira'' (i.e.,
           reformatera) le contenu de l'element courant. Cela
           affectera aussi le contenu dont les blancs sont
           significatifs, comme celui des elements <programlisting>,
           utilisez donc cette commande avec precaution.

   C-c C-a

           Execute sgml-edit-attributes. Ouvre un deuxieme tampon
           donnant la liste des attributs de l'element qui inclut le
           contenu courant, avec leurs valeurs. La touche Tab vous
           permet de passer d'un attribut `a l'autre, C-k de modifier
           une valeur existante, et C-c de fermer le tampon et de
           revenir au document principal.

   C-c C-v

           Execute sgml-validate. Vous propose de sauvegarder le
           document en cours (si besoin est) et passe ensuite un
           programme de validation du SGML. Les resultats de cette
           validation sont affiches dans un nouveau tampon et vous
           pouvez ensuite naviguer d'une erreur `a l'autre, pour les
           corriger au fur et `a mesure.

   Il y a sans aucun doute d'autres fonctions utiles, mais j'ai
   decrit celles que j'utilise le plus souvent.

     --------------------------------------------------------------

                        Chapitre 12. A consulter

   Ce document ne decrit deliberement pas exhaustivement, ni le SGML,
   ni les DTDs citees, ni le Projet de Documentation de FreeBSD. Pour
   plus d'information sur ces sujets, il est recommande de consulter
   les sites Web ci-dessous.

     --------------------------------------------------------------

12.1. Projet de Documentation de FreeBSD

     * Les pages Web du Projet de Documentation de FreeBSD,

     * Le Manuel de Reference de FreeBSD.

     --------------------------------------------------------------

12.2. SGML

     * La page Web SGML/XML, un ressource SGML exhaustive,

     * L'Introduction en douceur au SGML.

     --------------------------------------------------------------

12.3. HTML

     * Le consortium World Wide Web,

     * Les specifications du HTML 4.0.

     --------------------------------------------------------------

12.4. DocBook

     * Le Davenport Group, qui maintient la DTD DocBook.

     --------------------------------------------------------------

12.5. Le Projet de Documentation de Linux

     * Les pages Web du Projet de Documentation de Linux.

  Notes

   [1] Les entites Parametres employent le symbole Pourcent.          
   [2] C'est tout `a fait dommage. Imaginez les problemes et          
       bricolages (comme les Server Side Includes) que cela           
       eviterait.                                                     
   [3] Il y a d'autres types de listes dans DocBook, mais ils ne nous 
       concernent pas pour le moment.                                 
   [4] Cette organisation va radicalement changer tres bientot.       
       Suivez ce qui ce dit sur la liste de diffusion du groupe de    
       documentation de FreeBSD pour plus d'information.              
   [5] N.d.T.: Ceci s'applique bien sur aux textes rediges en         
       anglais.                                                       

     --------------------------------------------------------------

        Ce document, ainsi que d'autres peut etre telecharge sur
                   ftp.FreeBSD.org/pub/FreeBSD/doc/.

Pour toutes questions `a propos de FreeBSD, lisez la documentation avant
                 de contacter <questions@FreeBSD.org>.
Pour les questions sur cette documentation, contactez <doc@FreeBSD.org>.
