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.