25f4e9abb4
fr/docproj/sgml.sgml: MFen 1.20 fr/docproj/submitting.sgml: MFen 1.11 fr/docproj/translations.sgml: MFen 1.53 fr/docproj/who.sgml: MFen 1.11
172 lines
8.5 KiB
Text
172 lines
8.5 KiB
Text
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" [
|
|
<!ENTITY base CDATA "..">
|
|
<!ENTITY date "$FreeBSD$">
|
|
<!ENTITY title "Projet de documentation FreeBSD : SGML">
|
|
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
|
|
]>
|
|
|
|
<!--
|
|
The FreeBSD French Documentation Project
|
|
Original revision: 1.20
|
|
|
|
Version francaise : Thomas Seyrat
|
|
Version francaise (mise a jour) : Stephane Legrand <stephane@freebsd-fr.org>
|
|
-->
|
|
|
|
<html>
|
|
&header;
|
|
|
|
<p>Le Projet de Documentation FreeBSD tente d'imposer SGML comme format
|
|
standard pour créer des documents.</p>
|
|
|
|
<p>SGML est le <b>S</b>tandard <b>G</b>eneralised <b>M</b>arkup
|
|
<b>L</b>anguage (Langage de Balisage Standard Généralisé).</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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 <b>pas</b> du SGML tel quel, mais vous utilisez
|
|
un langage qui est défini à partir de SGML.</p>
|
|
|
|
<p>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é.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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>
|
|
|
|
<pre><![ CDATA [
|
|
<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>
|
|
]]></pre>
|
|
|
|
<p>Le même extrait, écrit en DocBook, ressemblerait à ceci :</p>
|
|
|
|
<pre><![ CDATA [
|
|
<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>
|
|
]]></pre>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>Il y a de nombreux avantages à cette forme plus significative de balisage :</p>
|
|
|
|
<ul>
|
|
<li><p>Elle n'est ni ambiguë ni inconsistante.</p> <p>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' ?"</p> <p>Au lieu de cela, vous utilisez le bon tag
|
|
au bon moment.</p>
|
|
|
|
<p>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.</p>
|
|
</li>
|
|
|
|
<li><p>Vous n'avez plus à vous soucier de l'apparence de votre document,
|
|
et vous pouvez vous concentrer plutôt sur le contenu.</p>
|
|
</li>
|
|
|
|
<li><p>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.</p></li>
|
|
|
|
<li><p>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.</p></li>
|
|
</ul>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>Bien sûr, cette performance a un prix :</p>
|
|
|
|
<ul>
|
|
<li><p>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.</p>
|
|
|
|
<p>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.</p></li>
|
|
|
|
<li><p>Le processus de reconversion n'est pas aisé.</p></li>
|
|
</ul>
|
|
|
|
<p>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.</p>
|
|
|
|
<h2>Et si je ne connais ni LinuxDoc, ni DocBook ? Puis-je quand même
|
|
participer ?</h2>
|
|
|
|
<p>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.</p>
|
|
|
|
<p><a href="submitting.html">Soumettez</a> 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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<h2>Plus d'informations sur SGML et DocBook ?</h2>
|
|
|
|
<p>Vous devriez tout d'abord lire le <a
|
|
href="&base;/doc/en_US.ISO8859-1/books/fdp-primer/index.html"><b>Documentation Project
|
|
Primer</b></a>. Il se veut être une explication pédagogique de tout ce que
|
|
vous avez besoin de connaître pour travailler avec la Documentation FreeBSD.</p>
|
|
|
|
<p>C'est un long document, divisé en de nombreux petits fichiers. Vous pouvez également
|
|
le trouver sous la forme d'<a
|
|
href="&base;/doc/en_US.ISO8859-1/books/fdp-primer/book.html"><b>un
|
|
seul gros fichier</b></a>.</p>
|
|
|
|
<dl>
|
|
<dt><a
|
|
href="http://www.oasis-open.org/cover/sgml-xml.html"><b>http://www.oasis-open.org/cover/sgml-xml.html</b></a></dt>
|
|
|
|
<dd><p>LA page web SGML/XML. Contient d'innombrables liens vers de l'information
|
|
sur SGML.</p></dd>
|
|
|
|
<dt><a
|
|
href="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html"><b>http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html</b></a></dt>
|
|
|
|
<dd><p>L'"Introduction progressive à SGML". Recommandée pour toute personne
|
|
désirant aborder SGML avec une approche de débutant.</p></dd>
|
|
|
|
<dt><a
|
|
href="http://www.oasis-open.org/docbook/"><b>http://www.oasis-open.org/docbook/</b></a></dt>
|
|
|
|
<dd><p>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.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p></p><a href="docproj.html">Projet de Documentation FreeBSD : Accueil</a>
|
|
&footer;
|
|
</body>
|
|
</html>
|