Le Projet de Documentation FreeBSD tente d'imposer SGML comme format + standard pour créer des documents.
+ +SGML est le Standard Generalised 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. "LinuxDoc" en est un autre. Comme vous vous en doutez, + il fut conçu à l'origine par le groupe de documentation Linux pour écrire + leurs textes, et le Projet de Documentation FreeBSD l'a également adopté.
+ +Un autre langage de balisage défini à partir de SGML est "DocBook". 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 choses entre <...>) + pour décrire les particularités des documents techniques.
+ +Voici un exemple de ce à quoi peut ressembler un bref paragraphe écrit en + HTML (ne vous souciez pas du contenu, mais seulement des tags) :
+ +Les mots de passe du système sont stockés dans /etc/passwd. + Pour modifier ce fichier, vous devez utiliser vipw. + Toutefois, si vous souhaitez simplement ajouter un nouvel utilisateur + vous pouvez utiliser adduser. +]]>+ +
Le même extrait, écrit en DocBook, ressemblerait à ceci :
+ +Les mots de passe du système sont stockés dans ++ +/etc/passwd . Pour modifier ce fichier, vous devez utiliser +vipw . Toutefois, si vous souhaitez simplement ajouter un nouvel utilisateur + vous pouvez utiliseradduser . + +]]>
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 <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 type 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, que vous + êtes peut-être habitué à utiliser. C'est 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.
+ +Je me suis rendu compte que la meilleure manière d'apprendre 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 reconversion n'est pas aisé.
Actuellement, le Projet utilise toujours LinuxDoc pour le Manuel et la FAQ. + Ceci est en train de changer, et il y a notamment un projet en cours pour + convertir la documentation en DocBook.
+ +Bien sûr ! N'importe quelle documentation vaut mieux que rien du tout. + Si vous avez à fournir quelque chose, même non formaté en + LinuxDoc ou 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, ce qui peut prendre un soir + ou deux. Mais elle rejoindra les autres.
+ +Vous devriez tout d'abord 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 nombreux petits fichiers. Vous pouvez également + le trouver sous la forme d'un + seul gros fichier.
+ +LA page web SGML/XML. Contient d'innombrables liens vers de l'information + sur SGML.
L'"Introduction progressive à SGML". Recommandée pour toute personne + désirant aborder SGML avec une approche de débutant.
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.
+