5305bb945d
- Move includes.nav*.sgml to share/sgml/navibar.ent and
<lang>/share/sgml/navibar.l10n.ent.
- Move includes.sgml and includes.xsl to
share/sgml/common.ent, share/sgml/header.ent, <lang>/share/sgml/l10n.ent,
and <lang>/share/sgml/header.l10n.ent.
- Move most of XSLT libraries to share/sgml/*.xsl and
<lang>/share/sgml/*.xsl.
- Move news.xml and other *.xml files for the similar purpose
to share/sgml/*.xml and <lang>/share/sgml/*.xml.
- Switch to use a custom DTD for HTML document. Now we use
"-//FreeBSD//DTD HTML 4.01 Transitional-Based Extension", which is
HTML 4.01 + some entities previously pulled via
"<!ENTITY % includes SYSTEM "includes.sgml"> %includes;" line.
The location of entity file will be resolved by using catalog file.
- Add DOCTYPE declearation to XML documents. This makes the followings
possible:
* Use of &foo; entities for SGML in an XML file instead of defining
{$foo} as the same content.
* &symbolic; entities for Latin characters.
- Duplicated information between SGML and XML, or English and
translated doc, has been removed as much as possible.
167 lines
8.3 KiB
Text
167 lines
8.3 KiB
Text
<!DOCTYPE HTML PUBLIC "-//FreeBSD//DTD HTML 4.01 Transitional-Based Extension//EN" [
|
|
<!ENTITY base CDATA "..">
|
|
<!ENTITY date "$FreeBSD: www/fr/docproj/sgml.sgml,v 1.9 2005/10/29 09:19:06 blackend Exp $">
|
|
<!ENTITY title "Projet de documentation FreeBSD : SGML">
|
|
<!ENTITY % navinclude.docs "INCLUDE">
|
|
]>
|
|
|
|
<!--
|
|
The FreeBSD French Documentation Project
|
|
Original revision: 1.26
|
|
|
|
Version francaise : Thomas Seyrat
|
|
Version francaise (mise a jour) : Stephane Legrand <stephane@freebsd-fr.org>
|
|
Version francaise (mise a jour) : Vincent Tougait <viny@scientiae.net>
|
|
Version francaise (mise a jour) : Antoine Brodin <antoine.brodin@laposte.net>
|
|
-->
|
|
|
|
<html>
|
|
&header;
|
|
|
|
<p>Le Projet de Documentation FreeBSD utilise SGML comme format
|
|
standard pour créer des documents.</p>
|
|
|
|
<p>SGML est le <b>S</b>tandard <b>G</b>eneralized <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. "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 <tt><tag contenu></tt>)
|
|
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.</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 éléments <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 types 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,
|
|
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>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.</p></li>
|
|
|
|
<li><p>Le processus de conversion n'est pas aisé.</p></li>
|
|
</ul>
|
|
|
|
<h2>Et si je ne connais pas 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
|
|
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. Ceci peut prendre quelques heures
|
|
réparties sur quelques jours. Mais elle rejoindra les autres.</p>
|
|
|
|
<h2>Plus d'informations sur SGML et DocBook ?</h2>
|
|
|
|
<p>Commencez par lire le <a
|
|
href="&enbase;/doc/&url.doc.langcode;/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.
|
|
C'est un long document, divisé en de nombreuses pages courtes. Vous pouvez également
|
|
le trouver sous la forme d'<a
|
|
href="&enbase;/doc/&url.doc.langcode;/books/fdp-primer/book.html"><b>une
|
|
seule longue page</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>
|