
HOWTO-HOWTO

Mark F. Komarinski

   v1.4 12 Juin 2000
   _R_e_v_i_s_i_o_n_ _H_i_s_t_o_r_y
   Revision 1.4 12 Juin 2000 Revised by: mfk
   Documentation sur vim et sgedit. Correction de l'orthographe et
   modifications issues des listes du LDP. Ajout galement de conseils du
   LDP dans les conseils de style.

   Ce document dcrit les outils et procdures, et donne des conseils aux
   auteurs de HOWTO. (Adaptation franaise par Nicolas Duboc)
     _________________________________________________________________

   _T_a_b_l_e_ _o_f_ _C_o_n_t_e_n_t_s
   1. AA  pprrooppooss  ddee  ccee  HHOOWWTTOO

        1.1. OObbjjeeccttiiff  //  CCoonntteennuu  ddee  ccee  HHOOWWTTOO
        1.2. AA  pprrooppooss  dduu  LLDDPP
        1.3. RReettoouurr  ddee  ccoommmmeennttaaiirreess
        1.4. CCooppyyrriigghhttss
        1.5. CCoonnttrriibbuuttiioonnss  eett  rreemmeerrcciieemmeennttss
        1.6. CCoonnvveennttiioonnss

   2. IInnffoorrmmaattiioonnss  ggnnrraalleess  ssuurr  llee  LLDDPP  eett  SSGGMMLL

        2.1. LLee  LLDDPP
        2.2. SSGGMMLL
        2.3. PPoouurrqquuooii  SSGGMMLL  pplluutttt  qquuee  HHTTMMLL  oouu  dd''aauuttrreess  ffoorrmmaattss  ??
        2.4. PPoouurr  lleess  nnoouuvveeaauuxx  aauutteeuurrss
        2.5. LLeess  lliisstteess  ddee  ddiissccuussssiioonn

   3. LLeess  oouuttiillss

        3.1. DDSSSSSSLL
        3.2. LLaa  DDTTDD  DDooccBBooookk  ((vveerrssiioonn  33..11))
        3.3. JJaaddee
        3.4. IInntteerrffaacceess  ((""FFrroonntt--eennddss""))  ppoouurr  JJaaddee
        3.5. EEddiitteeuurrss
        3.6. AAuuttrreess  oouuttiillss  //  RRffrreenncceess

   4. DDmmaarrrreerr  aavveecc  DDooccBBooookk

        4.1. TTllcchhaarrggeerr  eett  iinnssttaalllleerr  lleess  oouuttiillss
        4.2. EEccrriirree  dduu  SSGGMMLL    llaa  mmaaiinn
        4.3. EEccrriirree  dduu  SSGGMMLL  eenn  uuttiilliissaanntt  LLyyXX
        4.4. EEccrriirree  dduu  SSGGMMLL  eenn  uuttiilliissaanntt  PPSSGGMMLL

   5. CCoonnvveennttiioonnss  ddee  ssttyyllee

        5.1. FFoorrmmaatt  ddeess  ddaatteess
        5.2. UUttiilliissaattiioonn  ddeess  iimmaaggeess
        5.3. VVeerrssiioonnss  ddee  DDooccBBooookk
        5.4. BBaalliisseess  oobbssoolltteess
        5.5. RRdduuccttiioonn  ddeess  bbaalliisseess
        5.6. CCoonnvveennttiioonnss

   6. TTrruuccss  eett  aassttuucceess  ppoouurr  DDooccBBooookk

        6.1. IInncclluurree  ddeess  iimmaaggeess
        6.2. NNoomm  ddeess  ffiicchhiieerrss  HHTTMMLL  ssppaarrss
        6.3. UUttiilliisseerr  llddpp..ddssll

   7. CCVVSS

        7.1. OObbtteenniirr  uunn  ccoommppttee  CCVVSS
        7.2. AAuuttrreess  iinnffoorrmmaattiioonnss  ssuurr  CCVVSS
        7.3. CCVVSS  eett  llaa  mmiissee    jjoouurr  ddeess  ffiicchhiieerrss

   8. DDiissttrriibbuueerr  vvoottrree  ddooccuummeennttaattiioonn

        8.1. AAvvaanntt  llaa  ddiissttrriibbuuttiioonn
        8.2. PPrroobbllmmeess  ddee  ccooppyyrriigghhtt  eett  ddee  lliicceennccee
        8.3. SSoouummiissssiioonn  aauu  LLDDPP
        8.4. MMaaiinntteennaannccee  ddeess  HHOOWWTTOO

   9. FFAAQQ    pprrooppooss  dduu  LLDDPP

        9.1. JJee  ddssiirree  aaiiddeerr  llee  LLDDPP..  CCoommmmeenntt  ppuuiiss--jjee  llee  ffaaiirree  ??
        9.2. JJee  vvoouuddrraaiiss  ppuubblliieerr  uunn  eennsseemmbbllee  ddee  ddooccuummeennttss  dduu  LLDDPP  ddaannss  uunn
                lliivvrree..  CCoommmmeenntt  llee  ccoonntteennuu  dduu  LLDDPP  eesstt--iill  pprroottgg  ??

        9.3. JJ''aaii  ttrroouuvv  uunnee  eerrrreeuurr  ddaannss  uunn  ddooccuummeenntt  dduu  LLDDPP..  PPuuiiss--jjee  llaa
                ccoorrrriiggeerr  ??

        9.4. MMaaiiss  jjee  nnee  ccoonnnnaaiiss  ppaass  SSGGMMLL  //  JJee  nn''aarrrriivvee  ppaass    ffaaiirree
                mmaarrcchheerr  lleess  oouuttiillss  //  JJee  nn''aaiimmee  ppaass  SSGGMMLL..

1. A propos de ce HOWTO

1.1. Objectif / Contenu de ce HOWTO

   Ce document a t commenc le 26 Aot 1999 par Mark F. Komarinski
   aprs deux jours de frustration  essayer de faire marcher les outils.
   Ne se trouverait-il qu'un auteur du LDP (NdT : "Linux Documentation
   Project", Projet de Documentation Linux) pour trouver de l'aide dans
   ce document, j'aurais atteint mon objectif.

   La version la plus rcente de ce document peut tre trouve sur ma
   page personnelle hhttttpp::////wwwwww..ccggiippcc..ccoomm//~~mmaarrkkkk// au format SGML. D'autres
   versions peuvent tre trouves dans diffrents formats sur le site du
   LDP hhttttpp::////wwwwww..lliinnuuxxddoocc..oorrgg//.

   Il existe de nombreuses manires de contribuer au mouvement Linux sans
   rellement crire de code. Une des plus importantes est d'crire de la
   documentation, permettant  chaque personne de partager ses
   connaissances avec des milliers d'autres autour du monde. Ce HOWTO a
   t cr pour vous familiariser avec les rouages du LDP, et avec les
   outils dont vous aurez besoin pour crire votre propre HOWTO.
     _________________________________________________________________

1.2. A propos du LDP

   Ce qui suit est un extrait du Manifeste du LDP
   (hhttttpp::////wwwwww..lliinnuuxxddoocc..oorrgg//mmaanniiffeessttoo..hhttmmll)

   Le Projet de Documentation Linux (LDP) travaille sur le dveloppement
   libre et de haute qualit d'une documentation pour le systme
   d'exploitation GNU/Linux. Le but premier du LDP est de collaborer dans
   tous les thmes de documentation pour Linux. Cela inclut la cration
   de "HOWTOs" et de "Guides". Nous esprons tablir un systme de
   documentation pour Linux simple d'utilisation et facilitant les
   recherches. Ce systme implique l'intgration des pages de manuel, des
   docs infos, des HOWTOs, et d'autres documents.

   Vous pouvez trouver plus d'informations  propos du Projet de
   Documentation Linux  l'adresse hhttttpp::////wwwwww..lliinnuuxxddoocc..oorrgg//
     _________________________________________________________________

1.3. Retour de commentaires

   Les commentaires sur ce HOWTO peuvent tre envoys  l'auteur
   (<mmaarrkkkk@@lliinnuuxxddoocc..oorrgg>). (NdT : quant aux commentaires sur la
   traduction : <dduubboocc@@eessssii..ffrr>)
     _________________________________________________________________

1.4. Copyrights

   (c) 1999-2000 Mark F. Komarinski

   Ce manuel peut tre reproduit en totalit ou en partie, sans frais,
   sous rserve des restrictions suivantes :

     * Cette note de copyright et de permission doit tre prserve dans
       toutes copies partielles ou totales.
     * Toutes traductions ou travaux drivs doivent tre approuvs par
       l'auteur en le prvenant avant leur distribution.
     * Si vous distribuez une partie de ce travail, les instructions pour
       obtenir la version complte devront galement tre fournies.
     * De courts extraits peuvent tre reproduits, sans ces notes de
       permission, dans le cadre d'exposs et de citations si les
       rfrences sont correctement cites.

   Des exceptions  ces rgles peuvent tre tolres pour un but
   ducatif : contactez l'auteur et demandez-lui. Ces restrictions sont
   l pour nous protger en tant qu'auteurs, et non pour vous restreindre
   en tant que lecteurs ou enseignants. Tous les codes sources
   apparaissant dans ce document sont protgs par la Licence Publique
   Gnrale GNU, disponible par FTP anonyme depuis les archives GNU.
     _________________________________________________________________

1.5. Contributions et remerciements

   Merci  tous ceux qui ont donn leurs commentaires lorsque j'crivais
   ceci. Cela inclut David Lawyer, Deb Richardson, Daniel Barlow, Greg
   Ferguson, Mark Craig et les autres membres de la liste de diffusion
   <llddpp--ddiissccuussss@@lliissttss..lliinnuuxxddoocc..oorrgg>. J'ai tir quelques sections du HHOOWWTTOO
   IInnddeexx (disponible sur tous les sites du LDP) et de la documentation de
   sgmltools. Les sections sur l'accs rseau  CVS ont t partiellement
   crites par Serek (<sseerr@@sseerreekk..aarrcchh..ppwwrr..wwrroocc..ppll>). Les sections sur
   DocBook ont t crites par Jorge Godoy (<ggooddooyy@@ccoonneeccttiivvaa..ccoomm..bbrr>). Un
   grand merci  tous les deux pour leur aide.
     _________________________________________________________________

1.6. Conventions

   Les commandes qui sont listes ont le format suivant. Les commandes
   sont prcdes par le nom du shell utilis. Suit un $ pour les
   commandes qui devraient tre lances par un utilisateur normal (pas le
   super-utilisateur). Si le nom du shell est suivi par un #, cela
   signifie que la commande doit tre lance par le super-utilisateur.
     _________________________________________________________________

2. Informations gnrales sur le LDP et SGML

2.1. Le LDP

   Le Projet de Documentation de Linux (LDP) a t cr pour fournir aux
   nouveaux utilisateurs un moyen d'obtenir rapidement des informations
   sur un sujet particulier. Il contient non seulement une liste de
   livres sur l'administration systme, le rseau ou la programmation,
   mais galement un grand nombre de petits travaux sur des sujets plus
   particuliers, crits par ceux qui les ont utiliss. Si vous cherchez
   des informations sur les impressions, vous trouverez le
   PPrriinnttiinngg--HHOOWWTTOO. Si vous dsirez savoir si votre carte Ethernet
   fonctionne sous Linux, rcuprez le EEtthheerrnneett--HHOOWWTTOO, etc.

   Au dpart, la plupart de ces documents taient au format texte ou
   HTML. Avec le temps, il fallait trouver un meilleur moyen de grer ces
   travaux. Celui-ci permettrait de les lire depuis une page Web, depuis
   un fichier texte sur un CD-ROM, ou encore depuis votre organiseur de
   poche. La solution s'est avre tre SGML.
     _________________________________________________________________

2.2. SGML

   Le "Standard Generalized Markup Language" (SGML) est un langage qui
   est bas sur le balisage du texte (de ce point de vue, il est
   similaire  HTML, mais les similitudes s'arrtent l). La force de
   SGML est que contrairement  la philosophie WYSIWYG (What You See Is
   What You Get, NdT : Ce que vous voyez est ce que vous obtenez), vous
   ne dfinissez pas la couleur, la taille de la police, ou d'autres
   paramtres de formatage. Au lieu de cela, vous dfinissez des lments
   (paragraphes, sections, listes numrotes) et laissez l'interprte
   SGML et le programme final s'occuper du placement, des couleurs, des
   polices, et de tout le reste. HTML fait la mme chose, puisqu'il est
   en fait une subdivision de SGML. SGML est en ralit constitu de
   trois parties. La premire est la Structure, qui est appele la DTD,
   ou encore Dfinition du Type du Document. La DTD dfinit les relations
   entre chacun des lments d'un texte. La DTD DocBook, utilise pour
   crer le prsent document, en est un exemple. La DTD liste les rgles
   que le contenu doit respecter. La seconde partie est DSSSL ou encore
   "Document Style Semantics and Specification Language" (NdT :
   Smantique de Prsentation de Documents et Langage de Spcifications).
   DSSSL indique au programme charg du rendu final comment convertir le
   code SGML en quelque chose de lisible par Monsieur-tout-le-monde. Il
   demande par exemple, de convertir une balise <table> en une fonte
   grasse 14 points si le format de destination est RTF, ou en une balise
   <h1> si on veut du HTML. Enfin, la troisime partie est le Contenu,
   qui est trait par l'interprteur SGML et qui est finalement visualis
   par l'utilisateur. Le prsent paragraphe est un contenu, comme
   pourrait l'tre une image, une table, une liste numrote ou autre
   chose. Le contenu est entour de balises pour sparer les diffrents
   lments.
     _________________________________________________________________

2.3. Pourquoi SGML plutt que HTML ou d'autres formats ?

   SGML permet plus qu'une simple mise en forme. Vous pouvez crer
   automatiquement des index, des tables des matires ou des liens
   internes ou externes. Les paquetages Jade et OpenJade vous permettent
   aussi d'exporter (j'appellerai cela gnrer  partir de maintenant)
   vos documents SGML vers LaTeX, info, du texte, HTML ou RTF. Vous
   pouvez alors crer,  partir de ces formats de base, des fichiers
   d'autres types comme MS Word, PostScript, PDF, etc. Des programmes
   comme LyX vous permettent d'crire au format TeX, d'exporter au format
   SGML et de gnrer ce que vous voulez depuis SGML. En fin de compte,
   SGML s'intresse plus au rle des lments dans le document plutt
   qu' leur apparence. Une diffrence de taille, en tout cas qui vous
   permettra d'crire plus vite, puisque vous n'avez plus  vous soucier
   de la justification des paragraphes, des types et tailles des polices,
   etc.
     _________________________________________________________________

2.4. Pour les nouveaux auteurs

   Si vous tes un nouvel auteur au sein du LDP, et que vous voulez
   prendre en main un HOWTO (ou un Mini-HOWTO) non maintenu ou en crire
   un vous-mme, contactez le coordinateur du LDP  l'adresse
   <llddpp--ssuubbmmiitt@@lliissttss..lliinnuuxxddoocc..oorrgg>. Cela lui permet de savoir qui
   travaille sur quel document.

   Une fois cela effectu, vous pouvez crire votre documentation dans le
   format que vous voulez et soumettre un brouillon 
   <llddpp--ssuubbmmiitt@@lliissttss..lliinnuuxxddoocc..oorrgg> pour qu'il soit relu par un volontaire
   du LDP. Quelques jours plus tard vous recevrez les corrections et
   commentaires du relecteur. Aprs avoir appliqu les modifications
   suggres, vous pouvez envoyer cette version  la liste ldp-submit une
   nouvelle fois pour la soumission finale au LDP.

   A partir de l, un autre volontaire du LDP traduira votre document en
   DocBook et vous renverra cette version finale. Maintenant, toutes les
   soumissions au LDP doivent tre au format DocBook. Si vous avez des
   questions sur les balises, vous pouvez toujours demander aux
   volontaires qui vous ont aid, ou directement  la liste DocBook du
   LDP.
     _________________________________________________________________

2.5. Les listes de discussion

   Il y a quelques listes de discussion auxquelles vous pouvez vous
   abonner pour prendre part au fonctionnement du LDP. La premire est
   <llddpp--ddiissccuussss@@lliissttss..lliinnuuxxddoocc..oorrgg>, qui est le principal lieu de
   discussion du LDP. Pour s'abonner, il suffit d'envoyer un message avec
   "subscribe" comme sujet  l'adresse
   <llddpp--ddiissccuussss--rreeqquueesstt@@lliissttss..lliinnuuxxddoocc..oorrgg>. Pour se dsabonner, mme
   adresse avec "unsubscribe" comme sujet du message.

   Une autre liste est la liste <llddpp--ddooccbbooookk@@lliissttss..lliinnuuxxddoocc..oorrgg>, qui est
   prvue pour les questions sur DocBook. Si vous rencontrez des
   problmes avec une balise particulire, vous pouvez y envoyer une
   question. Vous pouvez vous abonner  la liste DocBook en envoyant un
   message "subscribe"  <llddpp--ddooccbbooookk--rreeqquueesstt@@lliissttss..lliinnuuxxddoocc..oorrgg>.
     _________________________________________________________________

3. Les outils

   Dans cette section, nous allons survoler les outils dont vous aurez
   besoin ou que vous voudrez utiliser pour crer votre propre
   documentation LDP. Nous allons les dcrire ici, et mieux les explorer
   plus tard, en mme temps qu'expliquer leur procdure d'installation.
   Si vous utilisez d'autres outils pour crire des manuels du LDP,
   faites-le moi savoir, j'ajouterai un descriptif ici.
     _________________________________________________________________

3.1. DSSSL

   La version de Norman Walsh est ncessaire, la version du LDP est
   optionnelle.
     _________________________________________________________________

3.1.1. DSSSL de Norman Walsh

   hhttttpp::////nnwwaallsshh..ccoomm//ddooccbbooookk//ddssssssll//ddbb115522..zziipp

   NdT : ce site de Norman Walsh sur DDooccBBooookk est une mine d'informations.
   On y trouve maintenant une version de DSSSL plus rcente que celle
   propose par l'auteur.

   La Smantique et le Langage de Spcification de Style (DSSSL) indique
    Jade comment gnrer un document imprimable ou visualisable en ligne
    partir d'une version SGML. DSSSL est ce qui convertit une balise de
   titre en une balise <H1> en HTML, ou en une police Times Roman gras 14
   points pour RTF par exemple. La documentation sur DSSSL se situe 
   l'adresse hhttttpp::////nnwwaallsshh..ccoomm//ddooccbbooookk//ddssssssll//ddbb115522dd..zziipp. Notez que
   modifier le DSSSL ne modifie en rien DocBook lui-mme. Cela ne change
   que la manire dont sera rendu le texte. Le LDP lui-mme utilise un
   DSSSL modifi qui ajoute une table des matires.
     _________________________________________________________________

3.1.2. LDP DSSSL

   hhttttpp::////mmeettaallaabb..uunncc..eedduu//ggffeerrgg//llddpp//llddpp..ddssll

   Le DSSSL du LDP require la version de Norman Walsh (voir plus haut)
   mais est en fait une version du DSSSL lgrement modifie pour fournir
   quelques fonctionnalits supplmentaires telles qu'une table des
   matires.
     _________________________________________________________________

3.2. La DTD DocBook (version 3.1)

   Ncessaire - hhttttpp::////wwwwww..ooaassiiss--ooppeenn..oorrgg//ddooccbbooookk//ssggmmll//33..11//ddooccbbkk3311..zziipp

   La DTD DocBook dfinit les balises et les structures du document SGML
   DocBook. Modifier la DTD, par exemple ajouter des balises, donne une
   DTD qui n'est plus DocBook.
     _________________________________________________________________

3.3. Jade

   Jade et OpenJade sont deux programmes qui ralisent le travail de
   conversion et de validation du code en utilisant la DTD et DSSSL. Un
   de ces deux programmes est ncessaire et doit tre install aprs la
   DTD et DSSSL.
     _________________________________________________________________

3.3.1. Jade

   ffttpp::////ffttpp..jjccllaarrkk..ccoomm//ppuubb//jjaaddee//jjaaddee--11..22..11..ttaarr..ggzz

   Jade est le programme qui se charge du traitement du document SGML.
   Jade utilise DSSSL et la DTD DocBook pour effectuer la vrification du
   texte SGML et sa conversion vers le format choisi.
     _________________________________________________________________

3.3.2. OpenJade

   hhttttpp::////ooppeennjjaaddee..ssoouurrcceeffoorrggee..nneett//

   Une volution de Jade crite par la communaut DSSSL. Certaines
   applications exigent Jade, mais elles sont/seront mises  jour pour
   accepter les deux logiciels.
     _________________________________________________________________

3.4. Interfaces ("Front-ends") pour Jade

   Ces outils sont optionnels et peuvent tre installs aprs Jade, DSSSL
   et la DTD.
     _________________________________________________________________

3.4.1. sgmltools-lite

   hhttttpp::////ssggmmllttoooollss--lliittee..ssoouurrcceeffoorrggee..nneett//

   C'est le successeur du projet sgmltools, qui a officiellement t
   arrt il y a  peu prs un an. Depuis, Cees de Groot a cr un projet
   lgrement diffrent qui consiste en une interface utilisateur qui
   enveloppe Jade. Il cache la plupart des lourdeurs de syntaxe de Jade.
   L'auteur du prsent HOWTO a russi  installer l'ancien paquetage
   sgmltools suivi de sgmltools-lite et a pu formater ce document assez
   facilement. Il y a une page de manuel expliquant la syntaxe de
   sgmltools.
     _________________________________________________________________

3.4.2. Les outils DocBook de Cygnus

   Peut-tre spcifique  RedHat - hhttttpp::////wwwwww..rreeddhhaatt..ccoomm//

   RedHat distribue trois paquetages, depuis la version 6.2, qui offrent
   un support pour DocBook et fournissent plusieurs outils. Ces derniers
   s'installent facilement, vous permettant ainsi de vous concentrer sur
   votre document plutt que vous battre avec les procdures
   d'installation. Il faut au pralable avoir install TeTeX, Jade et
   JadeTeX. Ces trois paquetages sont disponibles sur le CD.
     _________________________________________________________________

3.5. Editeurs

   Les outils suivants peuvent tre utiliss pour crer, diter et
   valider votre HOWTO.
     _________________________________________________________________

3.5.1. LyX

   hhttttpp::////wwwwww..llyyxx..oorrgg//

   LyX vous permet d'crire du SGML avec la facilit d'un traitement de
   texte standard. Ce n'est pas un programme WYSIWYG (NdT : Ce que vous
   voyez est ce que vous obtenez), mais plutt WYSIWYM (NdT :Ce que vous
   voyez est ce que vous voulez dire), puisque ce que vous voyez 
   l'cran n'est pas forcment ce que vous obtiendrez une fois que le
   processeur SGML aura fait son travail. L'affichage que fournit LyX est
   proche, mais n'est pas exactement ce que Jade vous donnera en sortie.
   Nanmoins, cela est suffisant pour se rendre compte de la structure du
   document. Les sections et sous-sections sont numrotes et mises en
   caractres gras, et des polices diffrentes sont utilises pour
   reprsenter les balises comme <code> ou <URL>. La plupart des balises
   vous sont caches pendant que vous ditez votre texte, puisque LyX
   gnre des documents en TeX, avant de les convertir en SGML.

   _F_i_g_u_r_e_ _1_._ _C_a_p_t_u_r_e_ _d_'__c_r_a_n_ _d_e_ _L_y_X

   [lyx_screenshot.jpg]
     _________________________________________________________________

3.5.2. Emacs (PSGML)

   Optionnel - hhttttpp::////wwwwww..llyyssaattoorr..lliiuu..ssee//~~lleennsstt//aabboouutt__ppssggmmll//

   Emacs dispose d'un mode d'dition SGML appel psgml qui est un mode
   majeur utilis pour les documents SGML et XML. Il permet une
   coloration syntaxique et un affichage agrable qui font ressortir les
   balises SGML. Il fournit un moyen d'insrer les balises sans avoir 
   les taper  la main, et est capable de valider la syntaxe de votre
   document lors de sa rdaction.

   Pour les utilisateurs d'Emacs, c'est un excellent outil, et beaucoup
   pensent qu'il permet une plus grande polyvalence que tout autre
   diteur de code SGML. Il fonctionne aussi bien avec DocBook et
   LinuxDoc que d'autres DTD.
     _________________________________________________________________

3.5.3. VIM

   hhttttpp::////wwwwww..vviimm..oorrgg

   On ne peut pas parler d'Emacs sans parler de vi. L'diteur VIM (Vi
   IMproved) dispose de toutes les fonctions du vi classique, mais aussi
   d'un mode SGML qui utilise la coloration syntaxique pour faire
   ressortir les balises.
     _________________________________________________________________

3.5.4. WordPerfect 9 (Corel Office 2000)

   hhttttpp::////wwwwww..ccoorreell..ccoomm//

   WordPerfect 9 pour Windows supporte SGML et DocBook 3.0. WordPerfect 9
   pour Linux n'a pas ces fonctions SGML.

   C'est la moins chre des applications commerciales qui supportent
   SGML.
     _________________________________________________________________

3.5.5. sgedit

   hhttttpp::////wwwwww..ttkkssggmmll..ddee//

   Le programme sgedit vous permet d'diter visuellement vos fichiers
   SGML. Vous n'avez pas besoin de connatre Emacs ou vi pour l'utiliser.
   De plus, il fonctionne sous diverses plate-formes, dont Windows et
   Linux. C'est une application commerciale, mais le prix n'a pas encore
   t fix. Il y aura des licences gratuites pour une utilisation prive
   ou dans un cadre ducatif.

   En plus d'une dition visuelle, sgedit peut vrifier la syntaxe de
   votre document lors du chargement ainsi qu' la demande avec la
   commande Document->Validate.

   [sgeditscreenshot.jpg]
     _________________________________________________________________

3.6. Autres outils / Rfrences

   Les lments de cette section sont des livres de rfrence ou d'autres
   utilitaires qui sont difficilement classables (pour l'instant).
     _________________________________________________________________

3.6.1. DocBook: The Definitive Guide

   hhttttpp::////wwwwww..ddooccbbooookk..oorrgg//

   Ce livre est publi par O'Reilly depuis Octobre 1999. C'est une trs
   bonne rfrence sur DocBook. Je n'ai pas trouv qu'il soit vraiment
   pratique, de plus il est trs orient vers XML, mais les balises
   DocBook 3.1 sont toutes listes dans un format commode. Vous pourrez
   le trouver chez votre libraire favori. Une version en ligne est
   galement disponible (aux formats HTML et SGML)  l'adresse
   prcdente.
     _________________________________________________________________

3.6.2. Aspell

   Optionnel - hhttttpp::////aassppeellll..ssoouurrcceeffoorrggee..nneett//

   C'est un correcteur d'orthographe qui sait reconnatre les balises
   SGML et qui ne vrifie que le contenu du document. Les correcteurs
   standards comme ispell essaieraient de corriger les balises,
   provoquant une erreur  chacune de celles-ci.
     _________________________________________________________________

4. Dmarrer avec DocBook

   Cette section couvre les nouvelles mthodes pour crire de la
   documentation pour le LDP, en utilisant la DTD DocBook 3.1. Nous
   verrons comment rcuprer, installer et utiliser les outils, ainsi
   qu'une introduction aux balises DocBook. Etant donn qu'il y a prs de
   300 balises DocBook, nous ne les verrons pas toutes ici. Les lecteurs
   vraiment intresss pourront se tourner vers hhttttpp::////wwwwww..ddooccbbooookk..oorrgg
   pour plus d'informations.
     _________________________________________________________________

4.1. Tlcharger et installer les outils

4.1.1. Mthode manuelle pour Jade/OpenJade

   Ceci est la mthode rapide mais pas trs propre ("quick and dirty")
   qui devrait marcher pour toutes les distributions.

    1. Crer un rpertoire de base o installer tous les outils, par
       exemple /usr/local/sgml/. Dans la suite nous l'appellerons
       $_toolroot.
    2. Installer Jade, la DTD DocBook et DSSSL dans le rpertoire
       $_toolroot (en y crant les sous-rpertoires
       $_toolroot/jade-1.2.1, $_toolroot/dtd, $_toolroot/dsssl).
    3. Vous aurez besoin de dfinir la variable d'environnement
       SGML_CATALOG_FILES pour indiquer les catalogues dont vous disposez
       dans $_toolroot. Vous pouvez le faire avec la commande _b_a_s_h_$
       _e_x_p_o_r_t_ _S_G_M_L___C_A_T_A_L_O_G___F_I_L_E_S_ _=
       _$___t_o_o_l_r_o_o_t_/_d_t_d_/_d_o_c_b_o_o_k_._c_a_t_:_$___t_o_o_l_r_o_o_t_/_d_s_s_s_l_/_d_o_c_b_o_o_k_/_c_a_t_a_l_o_g_:_$___t_o_o_l
       _r_o_o_t_/_j_a_d_e_-_1_._2_._1_/_d_s_s_s_l_/_c_a_t_a_l_o_g
    4. Maintenant vous pouvez utiliser Jade. Pour crer des fichiers HTML
       spars :
       _$___t_o_o_l_r_o_o_t_/_j_a_d_e_-_1_._2_._1_/_j_a_d_e_/_j_a_d_e_ _-_t_ _s_g_m_l_ _-_i_ _h_t_m_l_ _-_d
       _$___t_o_o_l_r_o_o_t_/_d_s_s_s_l_/_d_o_c_b_o_o_k_/_h_t_m_l_/_d_o_c_b_o_o_k_._d_s_l_ _h_o_w_t_o_._s_g_m_l
    5. Pour crer un unique document HTML, ajoutez _-_V_ _n_o_c_h_u_n_k_s  la liste
       des paramtres passs  Jade.
     _________________________________________________________________

4.1.2. sgmltools

   Contrairement  LinuxDoc, vous aurez besoin d'une version 2.x de
   sgmltools pour utiliser DocBook. Puisque la plupart des distributions
   ne contiennent qu'une version 1.x, vous devrez supprimer le paquetage
   sgmltools 1.x et installer une version 2.x ou une version CVS. Pour
   rcuprer les sources de la dernire version CVS vous pouvez utiliser
   les commandes suivantes :
bash$ CVSROOT=:pserver:cvs@cvs.sgmltools.org:/home/cvs
bash$ export CVSROOT
bash$ cvs login
bash$ cvs -z6 get sgmltools

   Le mot de passe CVS est 'cvs'. Une fois le tlchargement termin,
   vous pouvez utiliser
bash$ ./compile
bash$ make
bash# make install

   pour installer sgmltools. Pour les systmes RedHat (utilisant RPM)
   vous pouvez utiliser la commande rpmfind pour rcuprer la dernire
   version. Le programme rpmfind est disponible  l'adresse
   hhttttpp::////wwwwww..rrppmmffiinndd..nneett//. Vrifiez que vous rcuprez bien sgmltools et
   non sgml-tools, car ce dernier paquetage est en fait une version 1.0.9
   qui ne marche que pour les documents utilisant LinuxDoc. Pour les
   systmes Debian, version 2.2 "Potato" ou plus, apt-get rcuprera le
   bon paquetage pour vous :
   bash# apt-get install sgmltools-2

   Comme pour les systmes RedHat, le paquetage sgml-tools est obsolte.
   Assurez-vous de rcuprer sgmltools-2.
     _________________________________________________________________

4.1.3. Les outils DocBook de Cygnus

   Ces outils sont fournis avec la Red Hat 6.2. Vrifiez que les
   paquetages suivants sont installs :

     * sgml-common
     * docbook
     * stylesheets

   Vous trouverez la dernire version sur le site de Red Hat :
   hhttttpp::////wwwwww..rreeddhhaatt..ccoomm//ssuuppppoorrtt//eerrrraattaa//RRHHBBAA--22000000002222--0011..hhttmmll.

   Tlchargez/rcuprez les fichiers RPM sur votre machine et
   installez-les de la manire habituelle (en tant que
   super-utilisateur : _r_p_m_ _-_U_v_h_ _n_o_m_d_u_f_i_c_h_i_e_r). Une fois les RPMs
   installs, vous pouvez utiliser les commandes suivantes pour convertir
   les fichiers DocBook :
   bash$ db2html _n_o_m_d_u_f_i_c_h_i_e_r

   pour convertir du DocBook en HTML. Un sous-rpertoire de mme nom que
   le fichier (sans l'extension .sgml) est cr et les fichiers HTML y
   sont placs.
   bash$ db2pdf _n_o_m_d_u_f_i_c_h_i_e_r

   pour convertir un fichier DocBook en un fichier PDF.
     _________________________________________________________________

4.2. Ecrire du SGML  la main

   Tout est expliqu dans le document de Jorge Godoy intitul Using
   DocBook (NdT : malheureusement uniquement en anglais). Les personnes
   intresses peuvent le lire en ligne  l'adresse
   hhttttpp::////mmeettaallaabb..uunncc..eedduu//ggooddooyy//uussiinngg--ddooccbbooookk//uussiinngg--ddooccbbooookk..hhttmmll

   Note _S_i_ _v_o_u_s_ __c_r_i_v_e_z_ _d_u_ _S_G_M_L_ __ _l_a_ _m_a_i_n


   SGML dispose de plus de 300 balises, et les utilise bien plus
   massivement que HTML. Il est recommand de prendre un HOWTO existant
   comme modle pour voir comment les autres auteurs utilisent ces
   balises. Il est galement conseill d'utiliser un diteur de texte
   convivial comme Emacs-PSGML ou WordPerfect pour Windows, qui listent
   une grande partie des balises utilisables.
     _________________________________________________________________

4.3. Ecrire du SGML en utilisant LyX

4.3.1. Nouveaux documents

   Vous pouvez facilement commencer un nouvel HOWTO en utilisant LyX. La
   commande de menu Fichier->Nouveau depuis modle... vous permet de
   choisir un modle de document. Cliquez sur _M_o_d__l_e_s sur la droite de la
   bote de dialogue puis slectionnez _d_o_c_b_o_o_k___t_e_m_p_l_a_t_e_._l_y_x dans la liste
   des fichiers. Cliquez sur OK et vous aurez alors un document vierge.
   Remplissez les champs proposs tels que le titre, le rsum, le nom de
   l'auteur, puis commencez la rdaction.

   _F_i_g_u_r_e_ _2_._ _S__l_e_c_t_i_o_n_ _d_u_ _m_o_d__l_e_ _D_o_c_B_o_o_k_ _d_a_n_s_ _L_y_X

   [docbook_template.jpg]
     _________________________________________________________________

4.3.2. Documents existants

   Si vous disposez d'un document LyX, TeX ou texte, vous pouvez
   l'importer dans LyX grce  la commande Fichier->importer. Une fois le
   fichier import, utilisez la commande Mise en Page->Document...
   Choisissez l'entre _S_G_M_L_ _(_D_o_c_B_o_o_k_ _A_r_t_i_c_l_e_) dans le menu Type. Il vous
   sera demand si vous voulez convertir tout le texte ; dites Oui. Vous
   devrez rappliquer les balises, mais cela consiste juste 
   slectionner du texte et  choisir un style. La plupart des fonctions
   LyX disposent d'un raccourci clavier.

   _F_i_g_u_r_e_ _3_._ _E_c_r_a_n_ _d_e_ _m_i_s_e_ _e_n_ _p_a_g_e_ _d_u_ _d_o_c_u_m_e_n_t

   [document_layout.jpg]
     _________________________________________________________________

4.3.3. Exporter vers SGML

   Pour commencer, sauvegardez votre document au format LyX. Cela vous
   permettra d'diter les futures versions plus facilement. Utilisez
   ensuite la commande Fichier->Exporter->DocBook... pour exporter votre
   fichier au format DocBook.
     _________________________________________________________________

4.4. Ecrire du SGML en utilisant PSGML

4.4.1. Introduction

   Si vous disposez d'une distribution rcente, PSGML est certainement
   dj install avec Emacs. Pour vrifier, lancez Emacs et cherchez la
   documentation sur PSGML (_C-_h _i _m _p_s_g_m_l).

   A partir de maintenant nous supposerons que PSGML est install
   correctement au sein d'une version rcente de GNU Emacs. Si tout cela
   va trop vite pour vous, consultez le chapitre librement disponible du
   livre de Bob Ducharme : hhttttpp::////wwwwww..ssnneeee..ccoomm//bboobb//ssggmmllffrreeee//.
     _________________________________________________________________

4.4.2. Mise  jour du fichier .emacs pour PSGML

   Si vous voulez que GNU Emacs utilise automatiquement le mode PSGML
   quand vous ouvrez un fichier _._s_g_m_l, vrifier que PSGML saura o
   trouver la DTD DocBook. Si PSGML tait dj install sur votre
   systme, vous n'aurez certainement rien  faire. Sinon, vous devrez
   dfinir une variable d'environnement qui indiquera o trouver le
   catalogue SGML (la liste des DTD).

   Par exemple :
   bash$ export SGML_CATALOG_FILES=/usr/lib/sgml/catalog

   Ensuite ajouter les lignes suivantes  votre fichier .emacs
;; *******************************************************************
;; set up psgml mode...
;; use psgml-mode instead of emacs native sgml-mode ;;

(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
(setq auto-mode-alist (append (list '("\\.sgm$" . sgml-mode)
'("\\.sgml$" . sgml-mode) ) auto-mode-alist))

;; set some psgml variables

(setq sgml-auto-activate-dtd t) (setq sgml-omittag-transparent t)
(setq sgml-balanced-tag-edit t) (setq
sgml-auto-insert-required-elements t) (setq
sgml-live-element-indicator t) (setq sgml-indent-step nil)

;; create faces to assign to markup categories

(make-face 'sgml-comment-face) (make-face 'sgml-start-tag-face)
(make-face 'sgml-end-tag-face) (make-face 'sgml-entity-face)
(make-face 'sgml-doctype-face) ; DOCTYPE data
(make-face 'sgml-ignored-face) ; data ignored by PSGML
(make-face 'sgml-ms-start-face) ; marked sections start
(make-face 'sgml-ms-end-face) ; end of marked section
(make-face 'sgml-pi-face) ; processing instructions
(make-face 'sgml-sgml-face) ; the SGML declaration
(make-face 'sgml-shortref-face) ; short references

;; view a list of available colors with the emacs-lisp command: ;; ;;
list-colors-display ;; ;; please assign your own groovy colors,
;; because these are pretty bad
(set-face-foreground 'sgml-comment-face "coral"
;(set-face-background 'sgml-comment-face "cornflowerblue")
(set-face-foreground 'sgml-start-tag-face "slateblue")
;(set-face-background 'sgml-start-tag-face "cornflowerblue")
(set-face-foreground 'sgml-end-tag-face "slateblue")
;(set-face-background 'sgml-end-tag-face "cornflowerblue")
(set-face-foreground 'sgml-entity-face "lavender")
;(set-face-background 'sgml-entity-face "cornflowerblue")
(set-face-foreground 'sgml-doctype-face "lavender")
;(set-face-background 'sgml-doctype-face "cornflowerblue")
(set-face-foreground 'sgml-ignored-face "cornflowerblue")
;(set-face-background 'sgml-ignored-face "cornflowerblue")
(set-face-foreground 'sgml-ms-start-face "coral")
;(set-face-background 'sgml-ms-start-face "cornflowerblue")
(set-face-foreground 'sgml-ms-end-face "coral")
;(set-face-background 'sgml-ms-end-face "cornflowerblue")
(set-face-foreground 'sgml-pi-face "coral")
;(set-face-background 'sgml-pi-face "cornflowerblue")
(set-face-foreground 'sgml-sgml-face "coral")
;(set-face-background 'sgml-sgml-face "cornflowerblue")
(set-face-foreground 'sgml-shortref-face "coral")
;(set-face-background 'sgml-shortref-face "cornflowerblue")

;; assign faces to markup categories

(setq sgml-markup-faces ' ( (comment . sgml-comment-face) (start-tag
  . sgml-start-tag-face) (end-tag . sgml-end-tag-face) (entity
  . sgml-entity-face) (doctype . sgml-doctype-face) (ignored
  . sgml-ignored-face) (ms-start . sgml-ms-start-face) (ms-end
  . sgml-ms-end-face) (pi . sgml-pi-face) (sgml . sgml-sgml-face)
  (shortref . sgml-shortref-face) ))

;; tell PSGML to pay attention to face settings ;;
(setq sgml-set-face t)
;; ...done setting up psgml-mode.  ;;
*******************************************************************

   Puis relancer Emacs.
     _________________________________________________________________

4.4.3. SGML "Smoke Test"

   Essayez le test suivant. Crez un nouveau document, _/_t_m_p_/_t_e_s_t_._s_g_m_l par
   exemple, et insrez le texte suivant :
   <!DOCTYPE test [ <!ELEMENT test - - (#PCDATA)> ]>

   Tapez _C-_c _C-_p. Si Emacs parvient  accder  votre DTD, vous verrez le
   message _P_a_r_s_i_n_g_ _p_r_o_l_o_g_._._._d_o_n_e dans le minibuffer. Essayez ensuite _C_-_c
   _C_-_e_ _E_N_T_R_E_E pour insrer un lment _<_t_e_s_t_>. Si tout s'est bien pass,
   vous devriez voir ceci :
<!DOCTYPE test [ <!ELEMENT test - - (#PCDATA)> ]>
<test></test>
     _________________________________________________________________

4.4.4. Ecrire un nouveau HOWTO avec DocBook

   Dmarrez un nouveau fichier pour le HOWTO avec le texte suivant :
   <!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

   Tapez _C-_c_C-_p et retenez votre souffle. Si tout se passe comme prvu,
   Emacs va tourner pendant quelques secondes puis afficher le message
   _P_a_r_s_i_n_g_ _p_r_o_l_o_g_._._._d_o_n_e dans le minibuffer.

   A partir de l, utilisez _C-_c_C-_e_R_E_T_U_R_N pour insrer une balise
   _<_a_r_t_i_c_l_e_> et commencer  taper votre texte.
     _________________________________________________________________

4.4.5. Rfrence non-exhaustive sur PSGML pour Emacs

   Voir le document d'introduction de Nik Clayton, dans la documentation
   FreeBSD :
   hhttttpp::////wwwwww..ffrreeeebbssdd..oorrgg//ttuuttoorriiaallss//ddooccpprroojj--pprriimmeerr//ppssggmmll--mmooddee..hhttmmll
     _________________________________________________________________

5. Conventions de style

   Cette section fournit des informations sur les conventions adoptes
   par le LDP dans le but de donner le mme style  tous ses documents.
   Gardez ces conseils en mmoire lors de la rdaction de votre document.
     _________________________________________________________________

5.1. Format des dates

   La balise <pubdate>, dans l'en-tte, doit encadrer un texte de la
   forme suivante :
   v1.0, 21 Avril 2000
     _________________________________________________________________

5.2. Utilisation des images

   Si vous devez envoyer des images avec votre document, envoyez pour
   chaque image une version au format EPS et une autre au format GIF ou
   JPEG. Bien qu'il donne de meilleurs rsultats que le format JPEG,
   faites attention au problme des brevets sur le format GIF.
     _________________________________________________________________

5.3. Versions de DocBook

   Seule la version 3.1 de DocBook est supporte par le LDP pour le
   moment. Le LDP envisage l'utilisation future de la version 4.0. La
   plupart des documents en version 3.1 peuvent tre facilement convertis
   en 4.0 en vitant d'utiliser les balises obsoltes.

   L'en-tte DocBook de votre document devrait ressembler  ceci :
<!doctype article public "-//OASIS//DTD
DocBook V3.1//EN">
     _________________________________________________________________

5.4. Balises obsoltes

   Le LDP encourage  ne pas utiliser les balises indiques comme
   obsoltes dans le livre _D_o_c_B_o_o_k_:_ _T_h_e_ _D_e_f_i_n_i_t_i_v_e_ _G_u_i_d_e. La manire
   d'utiliser les nouvelles balises est indique dans la section Trucs et
   Astuces.
     _________________________________________________________________

5.5. Rduction des balises

   La rduction des balises consiste  utiliser </>  la place de la
   forme complte de fin de balise (comme </para>). Puisque cette
   pratique rend le document plus confus pour les futurs auteurs et les
   membres du LDP, et qu'elle n'est pas permise en DocBook XML, il est
   demand de l'viter.
     _________________________________________________________________

5.6. Conventions

   Les conventions sur les diffrents types de texte sont les suivantes :

   Si vous voulez montrer l'utilisation d'une commande, mettez-la sous la
   forme d'une vraie ligne de commande sous shell. L'invite de
   l'interprteur de commande doit contenir le nom du shell (bash, tcsh,
   zsh, etc.) suivi de $ pour les commandes d'un utilisateur normal ou #
   pour les commandes du super-utilisateur (root).

   Ainsi une commande devrait ressembler  ceci :
bash$ command "en tant qu'utilisateur normal"
bash# command "en tant que root"
tcsh# setenv DISPLAY :0.0
     _________________________________________________________________

6. Trucs et astuces pour DocBook

   Cette section contient d'autres informations dont vous pourrez avoir
   besoin pour crire vos documents.
     _________________________________________________________________

6.1. Inclure des images

   Contrairement  LinuxDoc, DocBook permet d'inclure des images dans
   votre HOWTO. Voici un exemple :
<figure> <title>LyX screen shot</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="lyx_screenshot.eps" format="eps">
    </imageobject>
    <imageobject>
      <imagedata fileref="lyx_screenshot.jpg" format="jpg">
    </imageobject>
    <textobject>
      <phrase> Screen shot of the LyX document
                     processing program
      </phrase>
    </textobject>
  </mediaobject>
</figure>

   Il est prfrable d'utiliser cette technique plutt que la balise
   <graphic> pour deux raisons. Premirement, la balise <graphic> ne sera
   plus disponible avec DocBook 5.0. Il faudra utiliser <mediaobject>.
   Donc, autant utiliser ds maintenant la bonne mthode. Deuximement,
   <mediaobject> permet de dfinir plusieurs types d'objets suivant le
   format dans lequel sera converti le document. Dans cet exemple, le
   premier <imageobject> est un fichier PostScript encapsul (EPS) 
   utiliser pour les sorties bases sur TeX, comme DVI, PS et PDF. Le
   second <imageobject> est une image JPEG principalement utilise pour
   HTML. La balise <textobject> ne sera utilise que si le format ne
   supporte pas les images (TXT). On peut comparer ce dernier cas  la
   balise <alt> de HTML.
     _________________________________________________________________

6.2. Nom des fichiers HTML spars

   Par dfaut, quand les fichiers HTML sont gnrs, le processeur SGML
   donne des noms arbitraires aux diffrents fichiers. Cela peut tre
   gnant pour les personnes voulant indexer une des pages pour pouvoir
   facilement en voir les changements, ou mme pour vous, pour savoir ce
   que contient chaque fichier. Quelque soit votre raison, voici comment
   indiquer les noms  utiliser :

   Dans votre premire balise <article> (qui devrait tre la seule),
   ajoutez un paramtre id et appelez-le index. Cela devrait vous donner
   ceci :
   <article id="index">

   Ne modifiez pas la premire balise <sect1> puisqu'elle correspond
   gnralement  une introduction et que vous voulez certainement
   qu'elle apparaisse sur la premire page. Pour les autres balises
   <sect>, ajoutez un paramtre id avec comme valeur le nom voulu. Ces
   noms ne doivent contenir que des caractres alphanumriques et tre
   suffisamment courts pour tre comprhensibles.
   <sect1 id="tips">
     _________________________________________________________________

6.3. Utiliser ldp.dsl

   Le LDP utilise son propre fichier DSSSL, qui ajoute quelques fonctions
   dont un fond de page blanc et la table des matires que vous voyez au
   dbut des HOWTO. Vous trouverez la version la plus rcente de ce
   fichier  l'adresse hhttttpp::////mmeettaallaabb..uunncc..eedduu//ggffeerrgg//llddpp//llddpp..ddssll.

   Une fois que vous disposez du fichier, vous devrez en diter les
   premires lignes pour modifier le chemin vers les fichiers DSSSL
   DocBook. Mon exemple utilise les outils Cygnus.

   Placez le fichier ldp.dsl dans /usr/lib/sgml/stylesheets et ouvrez-le
   avec l'diteur de texte de votre choix. Vous devriez voir quelque
   chose comme ceci :

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style
Sheet//EN" [ <!ENTITY % html "IGNORE"> <![%html;[ <!ENTITY %
print "IGNORE"> <!ENTITY docbook.dsl SYSTEM "docbook.dsl (1) " CDATA dsssl> ]]>
 <!ENTITY % print "INCLUDE">
<![%print;[ <!ENTITY docbook.dsl SYSTEM "docbook.dsl (2) " CDATA dsssl> ]]> ]>

   ((11))  
          Changez le premier "docbook.dsl" en
          /usr/lib/sgml/stylesheets/nwalsh-modular/html/docbook.dsl
   ((22))  
          Changez le second "docbook.dsl" en
          /usr/lib/sgml/stylesheets/nwalsh-modular/print/docbook.dsl

   Si vous utilisez un autre DSSSL, changez les chemins pour les faire
   correspondre avec les rpertoires html et print de votre DSSSL.

   Une fois cela effectu, vous pouvez gnrer des fichiers HTML :
bash$ mkdir HOWTO-HOWTO ; cd HOWTO-HOWTO
bash$ jade -t sgml -ihtml -d \
  /usr/lib/sgml/stylesheets/ldp.dsl\#html \
  ../HOWTO-HOWTO.sgml

   La premire commande cre un nouveau rpertoire o placer les
   fichiers. La seconde (l'appel  Jade) gnre un fichier HTML pour
   chaque section de votre document. Si vous prfrez gnrer des
   fichiers RTF, vous pouvez utiliser cette commande :
bash$ jade -t rtf -d /usr/lib/sgml/stylesheets/ldp.dsl \
../HOWTO-HOWTO.sgml
     _________________________________________________________________

7. CVS

   Le LDP est en train de mettre un place un accs CVS pour les auteurs.
   Il y a en effet de bonnes raisons d'utiliser CVS :

    1. CVS gre une sauvegarde des documents. Si vous passez un document
        un autre auteur, ce dernier peut rcuprer le document depuis
       CVS et continuer  travailler dessus. Si vous avez besoin de
       revenir  une ancienne version, vous pouvez galement la
       rcuprer.
    2. CVS est trs apprciable si plusieurs auteurs travaillent sur le
       mme document. Vous pouvez lui demander de vous indiquer quelles
       modifications ont t faites pendant que vous travailliez sur le
       document, et directement intgrer ces changements.
    3. CVS garde un historique des modifications du document. Cet
       historique peut tre plac automatiquement dans le document si
       vous utilisez certaines balises qui seront excutes avant
       l'interprteur SGML.
    4. CVS peut permettre, grce  un programme, la mise  jour
       automatique du site Web du LDP, et ce ds qu'un document est
       termin et soumis  CVS. Cela n'est pas encore en place, mais est
       envisag. Pour l'instant, les mises  jour par CVS signalent au
       coordinateur des HOWTO qu'une mise  jour du site Web est
       ncessaire. Si vous utilisez CVS, vous n'avez donc plus besoin
       d'envoyer votre document SGML par courrier lectronique.

   Si CVS est quelque chose de nouveau pour vous, voici quelques pages
   Web qui pourront vous aider :

     * hhttttpp::////wwwwww..ssoouurrcceeggeeaarr..ccoomm//CCVVSS//DDooccss//bbllaannddyy
     * hhttttppss::////wwrrooccllaaww..aarrtt..ppll//~~sseerr//ddooccss//ccvvss..hhttmmll
     _________________________________________________________________

7.1. Obtenir un compte CVS

   D'abord, il vous faudra obtenir un compte dans le "repository" CVS du
   LDP (NdT : lieu de stockage et de dpt des documents pour CVS). Il
   s'agit souvent du rpertoire racine utilis par CVS, o chaque projet
   (HOWTO, Mini-HOWTO, ...) dispose d'un sous-rpertoire.

   Vous devrez crer un mot de passe crypt et un identifiant
   d'utilisateur pour votre compte. Crypter votre mot de passe vous
   permet de l'envoyer au groupe CVS sans qu'on ait besoin de le voir en
   clair. Vous pouvez le faire par les commandes suivantes, depuis un
   shell bash (ou sh) :
bash$ echo your_password | perl -e "print crypt(<>,\ join
'',('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]),\"\n\""

   Envoyez la sortie de cette commande avec l'identifiant d'utilisateur 
   <ccvvssaaddmmiinn@@ccvvsslliisstt..lliinnuuxxddoocc..oorrgg>. Votre propre rpertoire CVSROOT sera
   cr et vous recevrez un e-mail avec une rponse. Quand vous aurez
   obtenu la rponse, connectez-vous sur votre CVSROOT et vrifiez que
   tout est configur correctement :
bash$ export CVSROOT=:pserver:_y_o_u_r___u_s_e_r_i_d@cvs.linuxdoc.org:/cvsroot
bash$ cvs -d $CVSROOT login

   (Remplacez _y_o_u_r___u_s_e_r_i_d par ce qui vous a t indiqu dans la rponse.)

   On vous demandera de saisir votre mot de passe,  la suite de quoi
   vous aurez accs au repository CVS en lecture-criture. Aprs avoir
   utilis _c_v_s_ _l_o_g_i_n une fois et obtenu l'accs au systme, votre mot de
   passe sera stock dans .cvsroot et vous n'aurez plus besoin d'utiliser
   _c_v_s_ _l_o_g_i_n. Positionnez CVSROOT correctement et c'est parti. Vous
   pouvez rcuprer le repository linuxdoc en entier avec cette
   commande :
   bash$ cvs get LDP

   Ou vous pouvez obtenir le fichier source SGML de votre propre document
   par :
bash$ cvs get howto/YOUR-HOWTO.sgml
bash$ cvs get minihowto/YOURDOC.sgml
     _________________________________________________________________

7.2. Autres informations sur CVS

7.2.1. Accs CVS anonyme

   Un accs CVS anonyme est disponible pour ceux qui n'ont pas besoin de
   compte (tels ceux dsirant juste rcuprer les documents du LDP). Ce
   repository est en lecture seule :
bash$ cvs -d \
:pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login

   Utilisez "cvs" comme mot de passe. Vous pouvez alors accder aux
   modules linuxdoc comme dcrit ci-dessus. Notez que les changements
   apparaissent sur le CVS anonyme une demi-heure environ aprs le site
   principal.
     _________________________________________________________________

7.2.2. Accs CVS par le Web

   Vous pouvez accder au repository CVS par le Web  l'adresse
   hhttttpp::////ccvvsswweebb..lliinnuuxxddoocc..oorrgg//iinnddeexx..ccggii//lliinnuuxxddoocc.
     _________________________________________________________________

7.2.3. Accs graphique  CVS

   Il existe des interfaces graphiques pour CVS, et vous en trouverez une
   liste sur le site hhttttpp::////ffrreesshhmmeeaatt..nneett//aappppiinnddeexx. Lancez-y une
   recherche sur: "CVS".
     _________________________________________________________________

7.3. CVS et la mise  jour des fichiers

   CVS reconnat une balise spciale, _$_I_d, que vous pouvez utiliser pour
   insrer automatiquement la date et le numro de version dans votre
   document. Lors de la mise  jour, CVS remplace cette balise par
   quelque chose comme _$_I_d_:_ _H_O_W_T_O_-_H_O_W_T_O_._s_g_m_l_,_v_ _1_._5_ _2_0_0_0_/_0_6_/_1_2_ _2_1_:_4_5_:_5_1
   _g_f_e_r_g_ _E_x_p_ _$. En plaant cette balise dans votre document, elle sera
   modifie  chaque changement du document, permettant une
   incrmentation automatique du numro de version.

   Quand vous voulez copier votre fichier modifi sur le serveur CVS,
   utilisez la commande _c_v_s_ _c_i_ _-_m_ _"_c_o_m_m_e_n_t_a_i_r_e_s_"_ _V_O_T_R_E_-_H_O_W_T_O_._s_g_m_l. Le
   paramtre -m "commentaires" n'est pas obligatoire, mais si vous ne le
   mettez pas, votre diteur de texte sera lanc (en gnral vi, ou du
   moins l'diteur indiqu par la variable d'environnement EDITOR) et
   vous pourrez taper un commentaire  propos des changements.

   Vous pouvez suivre toutes les discussions  propos de CVS sur la liste
   ldp-discuss. Pour l'instant, les soumissions LDP doivent toujours tre
   envoyes  <llddpp--ssuubbmmiitt@@lliissttss..lliinnuuxxddoocc..oorrgg>.
     _________________________________________________________________

8. Distribuer votre documentation

8.1. Avant la distribution

   Avant de distribuer votre prose  des millions de lecteurs potentiels,
   il y a quelques petites choses  faire.

   D'abord, vrifiez le bon franais de votre texte. La plupart des
   outils que vous utiliserez pour crire en SGML disposent de modules de
   vrification d'orthographe. Si ce n'est pas le cas, il y a toujours
   ASPELL.

   Deuximement, faites relire votre document par quelqu'un d'autre que
   vous pour obtenir des commentaires et d'ventuelles corrections. La
   documentation publie par le LDP a besoin d'tre la plus correcte
   possible, car des millions d'utilisateurs de Linux peuvent avoir
   besoin de la lire. Si vous faites partie d'une liste de discussion
   parlant du sujet trait, demandez aux autres intervenants de vous
   aider.

   Troisimement, crez un site Web o vous pourrez distribuer vos
   ralisations. Ce n'est pas indispensable, mais trs utile aux autres
   pour retrouver l'origine du document.
     _________________________________________________________________

8.1.1. Valider votre code SGML

   En utilisant Jade ou nsgmls, vous pouvez valider votre code SGML par
   rapport  la DTD pour tre sr qu'il ne comporte pas d'erreurs.
   bash$ nsgmls -s HOWTO-HOWTO.sgml

   S'il n'y a pas de problme, aucun message ne sera affich.
     _________________________________________________________________

8.2. Problmes de copyright et de licence

   Pour qu'un document soit accept par le LDP, il doit utiliser une
   licence qui soit en accord avec la section "LICENSE REQUIREMENTS" du
   Manifeste du LDP disponible  l'adresse
   hhttttpp::////wwwwww..lliinnuuxxddoocc..oorrgg//mmaanniiffeessttoo..hhttmmll. En tant qu'auteur, vous
   pourrez conserver le copyright et ajouter d'autres restrictions (par
   exemple, que vous deviez approuver toutes traductions ou travaux
   drivs). Un exemple de licence est disponible  l'adresse
   hhttttpp::////wwwwww..lliinnuuxxddoocc..oorrgg//CCOOPPYYRRIIGGHHTT..hhttmmll. Si vous choisissez d'utiliser
   ce copyright, copiez-le dans votre code source dans une section
   intitule "Copyright et licence" ou quelque chose de similaire.
   Incluez galement une clause de proprit (puisque vous serez le
   propritaire du document). Si vous tes le nouveau responsable d'un
   HOWTO qui existait dj, vous devez inclure les clauses de copyright
   des anciens auteurs et indiquer les priodes o ils ont maintenu le
   document.

   Vous remarquerez que la licence du HOWTO-HOWTO requiert une
   notification  l'auteur de tous travaux drivs ou traductions. En
   outre, tous les codes sources inclus sont protgs par la GPL. Si
   votre document inclut des sources, et dsirez que d'autres puissent
   les utiliser, faites-en de mme.
     _________________________________________________________________

8.3. Soumission au LDP

   Une fois que votre document a t soigneusement relu, vous pouvez le
   soumettre au LDP. Envoyez un e-mail  <llddpp--ssuubbmmiitt@@lliissttss..lliinnuuxxddoocc..oorrgg>
   avec votre fichier source (que vous pouvez gzipper si vous le dsirez)
   en attachement .

   Indiquez le nom de votre HOWTO dans le sujet du mail, et utilisez le
   corps du message pour rendre compte des principaux changements
   effectus. Cela permet aux coordinateurs de faire leur travail plus
   rapidement, et de ne pas avoir  trop attendre avant que votre HOWTO
   ne soit disponible sur le site Web du LDP. Si vous n'avez pas de
   rponse dans les sept jours suivants, renvoyez un mail pour savoir si
   votre HOWTO est toujours bien en cours de traitement.

   Si votre HOWTO contient des extras, comme des images ou un catalogue
   particulier, placez-les tous ainsi que votre fichier source SGML dans
   une archive tar.gz et envoyez cette dernire en attachement avec votre
   mail  la liste ldp-submit.
     _________________________________________________________________

8.4. Maintenance des HOWTO

   Maintenant que vous tes un auteur de HOWTO, vous devriez maintenir
   votre document et le mettre  jour au fil des nouvelles versions de
   logiciels. Vous devriez galement rpondre aux commentaires et
   questions raisonnables de vos lecteurs. Vous n'avez pas  tous les
   aider, surtout si les rponses sont dj dans votre HOWTO. Nanmoins,
   un des objectifs du LDP est d'aider au maximum les utilisateurs. C'est
   galement un bon moyen d'accrotre la popularit de Linux.
     _________________________________________________________________

9. FAQ  propos du LDP

9.1. Je dsire aider le LDP. Comment puis-je le faire ?

   La faon la plus simple, c'est de trouver un sujet et d'en faire un
   document. Regardez galement la liste des HOWTO non maintenus et voyez
   s'il n'y en a pas un que vous pourriez continuer.
     _________________________________________________________________

9.2. Je voudrais publier un ensemble de documents du LDP dans un livre.
Comment le contenu du LDP est-il protg ?

   Rfrez-vous  la page hhttttpp::////wwwwww..lliinnuuxxddoocc..oorrgg//CCOOPPYYRRIIGGHHTT..hhttmmll. Notez
   que cela n'est qu'un exemple destin aux auteurs. Nanmoins, la
   licence utilise ne peut pas tre plus restrictive que celle donne 
   cette URL.
     _________________________________________________________________

9.3. J'ai trouv une erreur dans un document du LDP. Puis-je la corriger ?

   Contactez l'auteur du document, ou le coordinateur du LDP sur la liste
   <llddpp--ssuubbmmiitt@@lliissttss..lliinnuuxxddoocc..oorrgg> et informez-le du problme en lui
   donnant une ventuelle correction.
     _________________________________________________________________

9.4. Mais je ne connais pas SGML / Je n'arrive pas  faire marcher les
outils / Je n'aime pas SGML.

   Pas de problme. Vous avez la possibilit d'crire un brouillon de
   votre HOWTO dans le format que vous voulez puis de le soumettre au
   LDP. Un volontaire se chargera de le relire et de le convertir en
   DocBook pour vous. Il vous sera alors plus facile de le maintenir 
   jour. Si vous avez des questions vous pouvez toujours faire appel aux
   volontaires de la liste DocBook du LDP  l'adresse
   <llddpp--ddooccbbooookk@@lliissttss..lliinnuuxxddoocc..oorrgg>.
