      Introduction au Projet de Documentation de FreeBSD pour les nouveaux
                                  participants

  Nik Clayton

   <nik@FreeBSD.ORG>

   Version: 43184

   Copyright (c) 1998-1999 Nik Clayton

   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.

   Resume

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

   [ Multiples pages HTML / Page HTML unique ]

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

   Table des matieres

   Preface

                1. Invites de l'interpreteur de commandes

                2. Conventions Typographiques

                3. Notes, avertissements et exemples

                4. Remerciements

   1. Introduction

                1.1. Le jeu de documentations de FreeBSD

                1.2. Avant de commencer

   2. Outils

                2.1. Outils indispensables

                2.2. Outils facultatifs

   3. Introduction `a SGML

                3.1. Introduction

                3.2. Elements, marques et attributs

                3.3. La declaration DOCTYPE

                3.4. Revenir au SGML

                3.5. Commentaires

                3.6. Entites

                3.7. Utiliser les entites pour inclure des fichiers

                3.8. Sections marquees

                3.9. Conclusion

   4. Marques SGML

                4.1. HTML

                4.2. DocBook

                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.3. Guide de style

                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

   Index

   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

   Table des matieres

   1. Invites de l'interpreteur de commandes

   2. Conventions Typographiques

   3. Notes, avertissements et exemples

   4. Remerciements

1. 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               #      

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

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

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

   Table des matieres

   1.1. Le jeu de documentations de FreeBSD

   1.2. Avant de commencer

   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

   Table des matieres

   2.1. Outils indispensables

   2.2. Outils facultatifs

   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

   Table des matieres

   3.1. Introduction

   3.2. Elements, marques et attributs

   3.3. La declaration DOCTYPE

   3.4. Revenir au SGML

   3.5. Commentaires

   3.6. Entites

   3.7. Utiliser les entites pour inclure des fichiers

   3.8. Sections marquees

   3.9. Conclusion

   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 debut pour
   l'element 'p', et se terminera avec la marque de fin pour
   l'element '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 separe
   du precedent.</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 ou certains
   <em>mots</em> ont ete <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 defaut.</p>

 <p align="center">Ce paragraphe sera peut-etre centre.</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/xml
 SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
 SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES
 export SGML_CATALOG_FILES

       Exemple 3.7. .login, pour les utilisateurs de csh(1) et tcsh(1)

 setenv SGML_ROOT /usr/local/share/xml
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES

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

    3. Creez un fichier exemple.xml, 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-etre justifie &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.xml

       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.xml
 nsgmls:example.xml:5:4:E: character data is not allowed here
 nsgmls:example.xml:6:8:E: end tag for "HEAD" which is not finished

       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.    
       5       (Ce n'est cependant pas 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/xml/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/xml/docbook/catalog

     * /usr/local/share/xml/html/catalog

     * /usr/local/share/xml/iso8879/catalog

     * /usr/local/share/xml/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, << Revenir au SGML >> 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 fac,on de mettre un commentaire
      sur plusieurs lignes -->

 <!-- Voici une autre fac,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 tres mauvaise idee ----->

   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.xml et validez vos modifications
       avec nsgmls(1)

    2. Ajoutez des commentaires incorrects `a exemple.xml, 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">
 ]>

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

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

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

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

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

     <p align="right">Ce paragraphe sera peut-etre justifie &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.xml 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.xml > 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.xml > 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.xml, chapitre2.xml,
   et ainsi de suite, et que le fichier livre.xml 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.xml">
 <!ENTITY chapitre.2 SYSTEM "chapitre2.xml">
 <!ENTITY chapitre.3 SYSTEM "chapitre3.xml">
 ]>

 <html>
   &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.xml, chapitre2.xml, 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.xml">
 <!ENTITY chapitre.2 SYSTEM "chapitre2.xml">
 <!ENTITY chapitre.3 SYSTEM "chapitre3.xml">

   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" [
 <!ENTITY % chapitres SYSTEM "chapitres.ent">
 %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.xml, para2.xml et para3.xml.

       Mettez-y quelque chose qui ressemble `a ceci :

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

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

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

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

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

     &para1;
     &para2;
     &para3;
   </body>
 </html>

    3. Generez exemple.html en normalisant exemple.xml.

 % sgmlnorm -d exemple.xml > exemple.html

    4. Affichez exemple.html avec votre navigateur Web et verifiez que les
       fichiers paran.xml 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.xml :

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % entites SYSTEM "entites.xml"> %entites;
 ]>

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

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

     &para1;
     &para2;
     &para3;
   </body>
 </html>

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

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

    3. Generez exemple.html en normalisant exemple.xml.

 % sgmlnorm -d exemple.xml > exemple.html

    4. Affichez exemple.html avec votre navigateur Web et verifiez que les
       fichiers paran.xml 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 elements de HTML. Comme les
       caracteres < et > y sont si frequemment utilises, il est plus
       facile de marquer tout l'exemple comme CDATA plutot que de se
       servir des entites &agrave; la place de ces caracteres dans tout le
       texte.</p>

     <ul>
       <li>C'est un element de liste</li>
       <li>C'est un second element de liste</li>
       <li>C'est un troisieme element 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.xml, 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.

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

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

                            Chapitre 4. Marques SGML

   Table des matieres

   4.1. HTML

   4.2. DocBook

   4.3. * LinuxDoc

   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
   lequel 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>Premiere section</h1>

 <!-- Introduction du document -->

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

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

 <h3>C'est le titre de la premiere sous-section</h3>

 <!-- Contenu de la premiere sous-section -->

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

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

   Une page HTML doit normalement 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>Premiere section</h1>

 <!-- Introduction du document -->

 <h3>Sous-section</h3>

 <!-- Ce n'est pas bon, <h2> a ete oublie -->

    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 element.</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'etablir la Justice, d'assurer
   la Tranquilite domestique, de defendre chacun, de promouvoir
   le Bien-etre general, et de garantir les Benedictions de
   la Liberte &agrave; nous-memes et &agrave; notre Posterite, decidons et
   etablissons cette Constitution des Etats-Unis d'Amerique.</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 ordonnee. Les elements de la liste seront
   probablement precedes par des puces.</p>

 <ul>
   <li>Premier element</li>

   <li>Second element</li>

   <li>Troisieme element</li>
 </ul>

 <p>Une liste ordonnee, dont les elements comportent plusieurs paragraphes.
   Chaque element (note : et non chaque paragraphe) sera numerote.</p>

 <ol>
   <li><p>C'est le premier element. Il n'a qu'un paragraphe..</p></li>

   <li><p>C'est le premier paragraphe du second element.</p>

     <p>C'est le second paragraphe du second element.</p>

   <li><p>C'est le premier et seul paragraphe du troisieme element.</p></li>
 </ol>

   Exemple 4.7. Listes de definition avec dl

   Utilisez :

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

   <dd><p>Paragraphe 1 de la definition 1.</p></dd>

     <p>Paragraphe 2 de la definition 1.</p></dd>

   <dt>Terme 2</dt>

   <dd><p>Paragraphe 1 de la definition 2.</p></dd>

   <dt>Terme 3</dt>

   <dd>Paragraphe 1 de la definition 3. Remarquez que l'element <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 souhaites.

   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 s'etend sur deux
   lignes et deux colonnes. Les autres cellules sont normales.</p>

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

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

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

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

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

     <td>Cellule en bas &agrave; droite</td>
   </tr>
 </table>

  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 accentue, 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 etre contacte par courrier
   electronique &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 lesquels 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 etre reference
   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/xml/freebsd.dtd.

  4.2.2. Identifiant Public Formel - Formal Public Identifier, (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 en chapters. C'est une obligation. Il peut y avoir
   des parts entre le livre et le chapitre si 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>

     &hellip;
   </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>

         &hellip;
       </sect3>
     </sect2>

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

       &hellip;
     </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 parts

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

 <part>
   <title>Introduction</title>

   <chapter>
     <title>Resume</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 paras vous suffiront. Les formalparas ont un
   title, et avec les simparas, certains elements sont interdits `a
   l'interieur du paragraphe. Tenez-vous en aux paras.

   Exemple 4.26. para

   Utilisez :

 <para>C'est un paragraphe. Il peut contenir
   presque n'importe quel autre element.</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>Preambule &agrave; la Constitution des Etats-Unis</title>

   <attribution>Copie d'un site Web quelque part</attribution>

   <para>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 &agrave;
     nous-memes et &agrave; notre Posterite les bienfaits de la
     Liberte, proclamons et etablissons cette Constitution des
     Etats-Unis d'Amerique.</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 steps, qui `a
   leur tour sont composes de steps ou substeps. Chaque step contient des
   elements de blocs.

   Exemple 4.29. itemizedlist, orderedlist et procedure

   Utilisez :

 <itemizedlist>
   <listitem>
     <para>C'est le premier element de la liste.</para>
   </listitem>

   <listitem>
     <para>C'est le second element de la liste.</para>
   </listitem>
 </itemizedlist>

 <orderedlist>
   <listitem>
     <para>C'est le premier element de la liste
       ordonnee.</para>
   </listitem>

   <listitem>
     <para>C'est le second element de la liste ordonnee.</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 systeme
   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/xml/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 electronique le plus employe 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 parametres de la ligne de commande de
   <citerefentry><refentrytitle>sendmail</refentrytitle>
     <manvolnum>8</manvolnum></citerefentry>,
     <option>-bp</option>, affiche l'etat des messages
     dans la file d'attente. Verifiez-le en executant
     <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 Reference en Anglais dans
   <filename>/usr/doc/en/handbook/</filename>. Le
   fichier principal, dans ce repertoire, s'appelle
   <filename>handbook.xml</filename>. Il doit aussi
   y avoir un <filename>Makefile</filename> et un
   certain nombre de fichiers avec l'extension
   <filename>.ent</filename>.</para>

   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.xml. 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 series.
   <devicename>sio</devicename> correspond
   &agrave; un certain nombre d'entrees dans
   <filename>/dev</filename>, dont
   <filename>/dev/ttyd0</filename> et
   <filename>/dev/cuaa0</filename>.</para>

 <para>A l'inverse, les peripheriques reseaux, 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
           hexadecimales sur deux positions separees par des deux-points.

   Exemple 4.38. hostid et roles

   Utilisez :

 <para>La machine locale peut toujours
   etre designee 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-reseau
   <hostid role="netmask">255.255.255.255</hostid>
   (qui peut aussi s'ecrire
   <hostid role="netmask">0xffffffff)</hostid>.</para>

 <para>L'adresse MAC identifie de fac,on unique
   chaque carte reseau 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
   taches d'administration systeme,
   vous aurez besoin d'etre
   <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>Generalement, invoquer <maketarget>all</maketarget>
   reconstruit l'application, et invoquer
   <maketarget>clean</maketarget> supprime les
   fichiers temporaires (<filename>.o</filename>
   par exemple) crees lors de la reconstruction.</para>

 <para><maketarget>clean</maketarget> peut etre
   controlee 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 determine la table de nombreuses
   tables systeme et definit approximativement le nombre de
   connexions simultanees qu'acceptera le systeme.</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'utilisateur 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 determine la table de nombreuses
   tables systeme et definit approximativement le nombre
   de connexions simultanees qu'acceptera le systeme.</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'apparait
   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 detaillees 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 detaillees 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 sur 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.

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

   [3] Il y a d'autres types de listes dans DocBook, mais ils ne nous
   concernent pas pour le moment.

                        Chapitre 5. * Feuilles de style

   Table des matieres

   5.1. * DSSSL

   5.2. * CSS

   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

   Table des matieres

   7.1. Organisation logique

   7.2. Organisation physique

   7.3. Guide de style

   7.4. * Conversion du Manuel dans d'autres formats

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
   parts, qui contiennent elles-memes plusieurs chapters. Les chapters 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, << * Conversion
   du Manuel dans d'autres formats >>.

  7.2.2. handbook.xml

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

   handbook.xml 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.xml

   Chaque chapitre du manuel est compose d'un fichier chapter.xml 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.xml 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.xml, 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.xml dont basics/chapter.xml, introduction/chapter.xml
   et printing/chapter.xml.

  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.xml 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 indente &agrave; partir de la colonne 0,
         <emphasis>quel que soit</emphasis> le niveau d'indentation dans le
         fichier ou il est inclus.</para>

       <para>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.</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                                            
                          *.xml                                               
                                                                              
         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, 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 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/xml/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                               
                                                                              
              $Id: chapter.xml,v 1.11 1999/06/20 21:18:57 billf Exp $         
         -->                                                                  
                                                                              
         La forme exacte peut changer, mais elles comporteront toujours la    
         ligne "Id" et la phrase The FreeBSD Documentation Project.           
                                                                              
         Vos traductions doivent comporter leur propre ligne "Id" et FreeBSD  
         Documentation Project doit 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                       
                                                                              
              $Id: chapter.xml,v 1.3 1999/06/24 19:12:32 jesusr Exp $         
              Original revision: 1.11                                         
         -->                                                                  

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

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

                              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.

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

   [5] N.d.T.: Ceci s'applique bien sur aux textes rediges en anglais.

                  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 .xml,
   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

   Table des matieres

   12.1. Projet de Documentation de FreeBSD

   12.2. SGML

   12.3. HTML

   12.4. DocBook

   12.5. Le Projet de Documentation de Linux

   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.

                                     Index
