Projet de documentation FreeBSD : SGML
Le Projet de Documentation FreeBSD utilise SGML comme format standard pour cr�er des documents.
SGML est le Standard Generalized Markup Language (Langage de Balisage Standard G�n�ralis�).
En un mot, avec toutes nos excuses pour oser choquer ainsi les puristes dans l'assistance, SGML est un langage con�u pour en �crire d'autres.
Vous avez probablement d�j� utilis� sans le savoir du SGML. HTML, le langage qui sert � la r�daction des pages web, est d�fini formellement. Sa d�finition est justement r�dig�e en SGML. Lorsque vous �crivez du HTML, vous n'�crivez pas du SGML tel quel, mais vous utilisez un langage qui est d�fini � partir de SGML.
Il existe de tr�s, tr�s nombreux langages de balisage d�finis � partir de SGML. HTML en est un. "DocBook" en est un autre. C'est un langage sp�cifiquement con�u pour la mise en forme de documentation technique et, en tant que tel, dispose de nombreux tags (les balises de la forme <tag�contenu>) pour d�crire les particularit�s des documents techniques avant un formatage. Le Projet de Documentation FreeBSD l'a adopt� et l'a enrichi de nouveaux �l�ments pour le rendre plus pr�cis.
Voici un exemple de ce � quoi peut ressembler un bref paragraphe �crit en HTML (ne vous souciez pas du contenu, mais seulement des tags) :
<p>Les mots de passe du syst�me sont stock�s dans <tt>/etc/passwd</tt>.
Pour modifier ce fichier, vous devez utiliser <b><tt>vipw</tt></b>.
Toutefois, si vous souhaitez simplement ajouter un nouvel utilisateur
vous pouvez utiliser <b><tt>adduser</tt></b>.</p>
Le m�me extrait, �crit en DocBook, ressemblerait � ceci :
<para>Les mots de passe du syst�me sont stock�s dans
<filename>/etc/passwd</filename>. Pour modifier ce fichier, vous devez utiliser
<command>vipw</command>. Toutefois, si vous souhaitez simplement ajouter un nouvel utilisateur
vous pouvez utiliser <command>adduser</command>.
</para>
Comme vous le voyez, DocBook est beaucoup plus "significatif" que HTML. Dans l'exemple HTML, le nom du fichier est marqu� comme devant �tre affich� en une police "machine � �crire". En DocBook, le nom du fichier est justement d�sign� par la balise "filename", son apparence finale n'�tant pas d�crite.
Il y a de nombreux avantages � cette forme plus significative de balisage :
Elle n'est ni ambigu� ni inconsistante.
Vous n'avez plus de temps � perdre � vous demander : "Mmh, c'est un nom de fichier, est-ce que j'utilise 'tt', 'b' ou 'em' ?"
Au lieu de cela, vous utilisez le bon tag au bon moment.
Le processus de conversion de DocBook en d'autres formats (HTML, Postscript�, etc.) s'assure que tous les �l�ments <filename> ont bien la m�me apparence.
Vous n'avez plus � vous soucier de l'apparence de votre document, et vous pouvez vous concentrer plut�t sur le contenu.
Parce que la documentation ne doit pas �tre li�e � un quelconque format de sortie, une seule et m�me source peut servir � produire de nombreux fichiers de types diff�rents—texte pur, HTML, PostScript, RTF, PDF, etc.
La documentation est plus "intelligente", afin que plus de choses "intelligentes" puissent �tre faites avec. Par exemple, il devient possible de g�n�rer automatiquement un index qui r�pertorie toutes les commandes cit�es dans une documentation.
C'est un peu comme les feuilles de style de Microsoft� Word, simplement beaucoup plus puissant.
Bien s�r, cette performance a un prix :
Parce que le nombre de tags que vous utilisez est beaucoup plus important, cela prend plus de temps pour les apprendre tous, et pour savoir les utiliser � bon escient.
Un bon moyen d'apprendre SGML et DocBook est de lire la source de nombreux textes, en �tudiant la mani�re dont d'autres auteurs ont r�dig� des documents similaires.
Le processus de conversion n'est pas ais�.
Et si je ne connais pas DocBook ? Puis-je quand m�me participer ?
Bien s�r ! N'importe quelle documentation vaut mieux que rien du tout. Si vous avez � fournir quelque chose, m�me non format� en DocBook, ne vous faites pas de souci.
Soumettez la documentation comme d'habitude. Quelqu'un d'autre du Projet marquera votre documentation pour vous et la soumettra � son tour. Avec un peu de chance, ils vous renverront le texte format�. C'est commode, puisque vous pouvez ainsi avoir un aper�u "avant et apr�s" du texte format�, et peut-�tre en apprendrez-vous encore un peu plus sur l'�tape de marquage.
De toute �vidence, ceci ralentit le processus de participation au Projet, puisque votre documentation doit �tre marqu�e. Ceci peut prendre quelques heures r�parties sur quelques jours. Mais elle rejoindra les autres.
Plus d'informations sur SGML et DocBook ?
Commencez par lire le Documentation Project Primer. Il se veut �tre une explication p�dagogique de tout ce que vous avez besoin de conna�tre pour travailler avec la Documentation FreeBSD. C'est un long document, divis� en de nombreuses pages courtes. Vous pouvez �galement le trouver sous la forme d'une seule longue page.
- http://www.oasis-open.org/cover/sgml-xml.html
LA page web SGML/XML. Contient d'innombrables liens vers de l'information sur SGML.
- http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html
L'"Introduction progressive � SGML". Recommand�e pour toute personne d�sirant aborder SGML avec une approche de d�butant.
- http://www.oasis-open.org/docbook/
La DTD DocBook est suivie par OASIS. Ces pages sont destin�es aux utilisateurs d�j� � l'aise en SGML, et qui d�sirent apprendre DocBook.