<!doctype debiandoc system>
<book>
<title>Manuel de Debiandoc-SGML
<author>Ian Jackson <email>ijackson@gnu.ai.mit.edu
<author>Traduction de Christophe Le Bars <email>clebars@debian.org
<version><date>
<copyright>Copyright &copy;1996 Ian Jackson.
<p>

Debiandoc-SGML, dont fait partie ce manuel, est un logiciel libre;
vous pouvez le redistribuer et/ou le modifier selon les
termes de la Licence Publique Générale GNU publiée par la
Free Software Foundation, version 2 ou supérieure.
<p>

Debiandoc-SGML est distribué car potentiellement utile, mais
<em>sans aucune garantie</em>; sans même la garantie implicite
de commercialisation ou adéquation à une tâche particulière. Consultez
la Licence Publique Générale GNU pour plus de détails.
<p>

Vous devez avoir reçu une copie de la Licence Publique Générale GNU
avec votre système Debian GNU/Linux, dans <tt>/usr/doc/copyright/GPL</tt>,
ou avec le paquet source <prgn/debiandoc-sgml/ dans le fichier
<tt>COPYING</tt>. Sinon, écrivez à la Free Software Foundation,
Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

<toc sect>

<chapt id="markup">Balises SGML et caractères spéciaux
<p>

Puisqu'il est saisi avec un éditeur de texte, un document SGML
est constitué de texte entremêlé de balises marquant
le début et la fin d'éléments.
<p>

Les balises sont de la forme <tt/&lt;<var/element/&gt;/ pour
commencer l'élément <var/element/ et <tt>&lt;/<var/element/&gt;</>
pour le finir.
<p>

Il y a quelques raccourcis que vous pouvez utiliser:
<tt>&lt;<var/element//<var/contenu//</> spécifie un élément
<var/element/ qui contient <var/contenu/ - mais le <var/contenu/
ne peut pas contenir une barre oblique <tt>/</>. <tt>&lt;/&gt;</>
ferme l'élément encore ouvert le plus proche. 
<p>

Certains types de balises de début d'élément peuvent avoir
des attributs; ceux-ci apparaissent à l'intérieur des crochets
angulaires et sont séparés du nom de l'élément par un espace.
Les attributs autorisés pour une balise de début d'élément
particulière sont décrits en même temps que cet élément.
<p>

Si vous voulez inclure des caractères spéciaux SGML (crochets angulaires
<tt/&lt;/ <tt/&gt;/, et commercial <tt/&amp;/) comme texte, vous
devez les désigner par leurs noms (ceci est appelé une référence
d'entité dans le jargon SGML). <tt/&amp;<var/name/;/ produit
le caractère dont le nom est <var/name/. Quelques noms de caractère
utiles sont:
<taglist compact>
<tag><tt/lt/
<item>le symbole inférieur (crochet angulaire gauche) <tt>&lt;</>;
<tag><tt/gt/
<item>le symbole supérieur (crochet angulaire droit) <tt>&gt;</>;
<tag><tt/amp/
<item>le et commercial <tt>&amp;</>;
<tag><tt/copy/
<item>le symbole copyright <tt>&copy;</>;
</taglist>
La liste complète des caractères est empruntée à <prgn/linuxdoc-sgml/, dans
le fichier <tt>rep/latin1/general</>.
<p>

Vous pouvez aussi utiliser <tt/&amp;#<var/number/;/ pour désigner le
caractère dont le numéro est <var/number/ (en ISO-LATIN-1). <var/number/
doit être en décimal.

<chapt id="structure">Structure générale
<p>

La première ligne du document doit être
<example>
&lt!doctype debiandoc system&gt
</example>
pour indiquer que le document est un fichier Debiandoc-SGML.
<p>

Le document doit commencer par la balise <tt/&lt;book&gt;/ et se terminer par
<tt>&lt;/book&gt;</>.
<p>

Ceci doit être suivi par le titre, <tt/&lt;title&gt;/, une ou plusieurs
paires <tt/&lt;author&gt;/-<tt/&lt;email&gt;/ (auteur-adresse électronique),
et optionnellement une <tt/&lt;version&gt;/. Chacune d'elles est une
partie du texte brut balisé - voir <ref id="inline">. La <tt/&lt;version&gt;/
peut aussi contenir <tt/&lt;date&gt;/ qui représente la date et
l'heure de formatage du document.
<p>

Puis peut venir un résumé (<tt/&lt;abstract&gt;/), une note de
<tt/&lt;copyright&gt;/ et une balise de table des matières
(<tt/&lt;toc&gt;/).
<p>

Le résumé (<tt/&lt;abstract&gt;/) contient un seul paragraphe.
<p>

Le <tt/&lt;copyright&gt;/ contient un résumé du copyright (ceci
est utilisé, par exemple, en bas de chaque page HTML) suivi
par un ou plusieurs paragraphes, le premier devant être signalé
par une balise <tt/&lt;p&gt;/ pour le distinguer du résumé.
<p>

La balise <tt/&lt;toc&gt;/ spécifie qu'une table des matières doit
être produite. <tt/&lt;toc&gt;/ ne contient rien dans le
source SGML - son contenu est généré par le formatage. 
<tt/&lt;toc&gt;/ peut avoir un attribut précisant son niveau de détail;
par exemple <tt/&lt;toc sect1&gt;/ précise que les sous-sections doivent
être incluses, tandis que <tt/&lt;toc chapt&gt;/ précise que seuls les
chapitres doivent être inclus. Les valeurs autorisées sont <tt/chapt/,
<tt/sect/, <tt/sect1/ et <tt/sect2/.
<p> 

Après ces parties vient le corps du document - un ou plusieurs
chapitres <tt/&lt;chapt&gt;/.
<p> 

Il n'est pas nécessaire de marquer la fin des éléments <tt/&lt;title&gt;/,
<tt/&lt;author&gt;/, <tt/&lt;version&gt;/, <tt/&lt;abstract&gt;/ et
<tt/&lt;copyright&gt;/ - ils sont implicitement terminés par le 
début de l'élément suivant.

<chapt id="chaptsectpar">Chapitres, sections et paragraphes
<p>

Chaque chapitre commence par une balise <tt/&lt;chapt&gt;/, suivi
par le titre du chapitre. Le titre peut contenir du texte brut balisé,
mais pas de références croisées (voir <ref id="inline">).
<p>

Le corps du chapitre est constitué de zéro à plusieurs paragraphes,
le premier devant être indiqué par une balise <tt/&lt;p&gt/ pour
le distinguer du titre, puis de zéro à plusieurs sections.
<p>

Une section commence par <tt/&lt;sect&gt;/ et possède une structure équivalente:
titre, optionnellement des paragraphes et puis optionnellement des sous-sections.
<p>

Les sous-sections sont <tt/&lt;sect1&gt;/; il y a aussi des divisions
plus petites <tt/&lt;sect2&gt;/, <tt/&lt;sect3&gt;/ and <tt/&lt;sect4&gt;/.
<p>

Les paragraphes sont introduits par <tt/&lt;p&gt;/. Parfois la balise de
début de paragraphe peut être omise, mais elle est obligatoire
après <tt/&lt;chapt&gt;/, <tt/&lt;sect&gt;/ et ainsi de suite. Il n'est
jamais nécessaire de marquer la fin d'un paragraphe avec <tt>&lt;/p&gt;</>.
<p>

Les paragraphes peuvent contenir du texte brut balisé
(voir <ref id="inline">) ainsi que des listes et des exemples
(<ref id="listexamp">).

<chapt id="inline">Texte brut balisé et balisage du style de caractères
<p>

Le texte ordinaire (appelé «texte brut» dans ce document) peut contenir
des éléments de formatage spécial et de référencement croisé. Le texte brut
apparaît dans les titres de chapitres et de sections, dans le
résumé du copyright, à l'intérieur des paragraphe et dans d'autres
endroits équivalents.

<sect>Style de caractères
<p>

Il y a un certain nombre d'éléments pour marquer la signification
particulière de certains morceaux de textes. Pour ceux-ci, la fin
du texte spécial doit être marqué explicitement, en utilisant
une balise de fin explicite <tt>&lt;/<var/element/&gt;</>, la balise
de fin abrégée fermant l'élément le plus proche <tt>&lt;/&gt;</> ou
la barre oblique <tt>/</> qui termine la forme la plus abrégée
des balises. (voir <ref id="markup">).

<taglist>
<tag><tt/&lt;em&gt;/ - emphase
<item>
Indique que le texte contenu est plus important ou plus
significatif que celui environnant.
<p>

Typiquement ceci sera représenté si possible par des italiques, ou
par un texte en gras ou souligné, ou bien dans les formats de texte
seulement, sans styles de caractère spéciaux, en encadrant le texte
avec des astérisques comme *ceci*.

<tag><tt/&lt;var&gt;/ - méta-variable
<item>
Indique que le texte contenu est une méta-variable. C'est-à-dire,
que c'est le nom d'un objet ou d'une pièce syntaxique qui
dans un usage normal serait remplacée par une valeur réelle.
<p>

Typiquement ceci sera représenté par des italiques, ou les formats
de texte seulement en encadrant le texte avec des crochets angulaires
comme &lt;ceci&gt;. Si plusieurs méta-variables apparaissent
successivement, elles doivent chacune utiliser leur propre élément
<tt/&lt;var&gt;/.

<tag><tt/&lt;prgn&gt;/ - nom d'un programme ou d'un fichier bien connu
<item>
Indique que le texte contenu est le nom d'un programme, d'un fichier
bien connu (habituellement sans chemin), d'une fonction ou d'un objet
équivalent ayant un nom pour l'ordinateur.
<p>

Dans les formats de sortie où il existe des styles de caractères spéciaux
et des styles de polices variés, ceci est habituellement représenté en
utilisant une police non-proportionnelle. Dans les formats de sortie 
texte seulement, ces noms ne sont pas spécialement marqués,
puisqu'ils surviennent fréquemment et qu'introduire un encadrement
perturberait le cours du texte.

<tag><tt/&lt;tt&gt;/ - chemin, code ou fragment de sortie, chaîne de commande
<item>
Indique que le texte contenu est une chaîne quelconque provenant
ou étant destiné à un ordinateur. Ceci doit être utilisé pour les
chemins complets, les fragments de code devant être visualisés 
sous forme brute et sans justification (voir aussi <ref id="examples">
pour une autre solution) et ainsi de suite. Il est fréquemment nécessaire
d'introduire des méta-variables dans ces chaînes, qui dans ce cas
doivent faire partie de l'élément <tt/&lt;tt&gt;/ plutôt que des
éléments environnants.
<p>

Ceci sera habituellement représenté en utilisant une police de largeur
fixe; dans les formats texte seulement un encadrement peut être
utiliser autour de l'élément.

<tag><tt/&lt;qref id="<var/refid/"&gt;/ - référence conditionnelle
<item>
Crée une «référence conditionnelle» vers la référence nommée id (voir
<ref id="xref">). Ceci doit être utilisé lorsque une référence croisée
est utile si elle ne perturbe pas le cours du texte, mais 
que non-essentielle, elle peut être abandonnée si elle doit le perturber.
<p>

Dans les formats permettant des références croisées non-perturbantes en
faisant d'une zone de texte un hyperlien sans introduire du nouveau
texte, cet élément fera du texte contenu un hyperlien vers
la cible de la référence croisée. Dans les autres formats cet élément
n'aura aucun effet.
</taglist>

<sect id="xref">Références croisées
<p>

Il y a plusieurs éléments permettant d'introduire des références croisées
soit vers les autres parties d'un même document soit vers d'autres
documents.
<p>

Les références croisées internes au document sont basées sur un schéma
d'identifiants référentiels. Chaque chapitre, section, sous-section, etc.
peut avoir un attribut <tt/id/ lui donnant son identifiant référentiel
- par exemple <tt/&lt;chapt id="spong"&gt;/ spécifie que le chapitre
commençant possède l'identifiant référentiel <tt/spong/. Cet identifiant
référentiel peut alors être pointé dans d'autres parties du document
en utilisant les éléments spéciaux des références croisées.
<p>

L'identifiant référentiel sera aussi utilisé pour générer des noms
de fichiers et des objets référentiels pour les formats tel que HTML
qui produisent plusieurs fichiers de sortie; si aucun identifiant
référentiel n'est spécifié alors les numéros de chapitres et de sections
seront utilisés. C'est une bonne idée de donner au moins à tous vos
chapitres un identifiant référentiel pour que les noms de fichiers ne
changent pas si vous changez l'ordre des chapitres ou des sections
dans votre document. 
<p>

<taglist>
<tag><tt/&lt;ref id="<var/idref/"&gt;/ - Référence interne au document
<item>
Ceci génère une référence croisée à l'intérieur du même document vers
la section ou le chapitre correspondant à l'identifiant <var/idref/.
<p>

L'élément <tt/&lt;ref&gt;/ n'a pas de contenu; le numéro de section ou de 
chapitre, le titre et son numéro de page ou tout autre chose approprié
pour le format de sortie sera inséré dans le texte à l'endroit où la
balise apparaît.
<p>

Syntaxiquement la référence croisée est une phrase sans verbe,
approprié dans des situations tel que
<tt>(voir &lt;ref id="<var/.../"&gt;)</> ou
<tt>plus d'informations dans &lt;ref id="<var/.../"&gt;.</>.

<tag><tt/&lt;manref name="<var/nom/" section="<var/section/"&gt;/ -
page de manuel (manpage)
<item>
Génère une référence croisée vers la page de manuel <var/nom/ de la
section <var/section/. Cette balise n'a pas de contenu; le texte
décrivant la page, typiquement <tt/<var/nom/(<var/section/)/, sera
inséré à l'endroit où <tt/&lt;manref&gt;/ apparaît.

<tag><tt/&lt;email&gt;/ - adresse de courrier électronique (email)
<item>
Indique que le texte contenu est une adresse de courrier électronique
(email). Le contenu de la balise doit uniquement être le texte de
l'adresse elle-même; les balises de style de caractères et les
références croisées sont interdites. Habituellement la balise de fin
<tt>&lt;/email&gt;</> ne doit pas être omise, mais on peut l'oublier
lorsque l'adresse apparaît à la fin d'un élément <tt/&lt;author&gt;/. 
Le début de l'élément suivant impliquera la fin de l'adresse de courrier
électronique.
<p>

Dans certains formats, ceci générera une véritable référence croisée
qui pourra (par exemple) être utiliser pour envoyer un courrier électronique
à l'adresse définie. Dans d'autres, cela marquera simplement le texte
de manière spéciale, habituellement en l'encadrant de crochets angulaires
<tt/&lt;/ <tt/&gt;/.  

<tag><tt/&lt;ftpsite&gt;/ - nom de site FTP anonyme
<tag><tt/&lt;ftppath&gt;/ - chemin dans le dernier site FTP cité
<item>
<tt/&lt;ftpsite&gt;/ indique que le contenu de l'élément est le nom DNS
d'un site FTP anonyme et <tt/&lt;ftppath&gt;/ un chemin dans ce site FTP.
Les deux éléments ne peuvent contenir aucune balise de style de
caractères ou de références croisées.
<p>

Typiquement les deux éléments seront représentés par une police non-proportionnelle;
si possible, le chemin du site (<tt/&lt;ftppath&gt;/) sera
transformé en un hyperlien fonctionnel vers le fichier ou le répertoire
du dernier site FTP (<tt/&lt;ftpsite&gt;/) cité.
<p>

<tt/&lt;ftppath&gt;/ doit toujours être précédé par
<tt/&lt;ftpsite&gt;/ dans le même chapitre, mais une fois qu'un
site FTP a été cité, plusieurs chemins peuvent apparaître.
</taglist>

<sect>Notes de bas de page
<p>

Les notes de bas de page peuvent apparaître dans la plupart des textes
bruts et sont indiquées par <tt>&lt;footnote&gt;<var/.../&lt;/footnote&gt</>.
Le texte de la note de bas de page sera retiré, placé ailleurs
(l'endroit dépendant du format) et remplacé par une référence ou un
hyperlien vers la note de bas de page.
<p>

Le contenu de la note de bas de page doit être un ou plusieurs
paragraphes; le début du premier paragraphe doit être marqué
explicitement. Les balises de texte brut tel que les styles
de caractères n'ont pas d'effet sur le contenu de la note de bas de
page définit à l'intérieur d'eux - la note de bas de page fait table
rase.
<p>

Les notes de bas de page peuvent être imbriquées, mais c'est
rarement une bonne idée.

<chapt id="listexamp">Listes et exemples

<sect>Listes
<p>

Il y a trois sortes de listes:
<list compact>
<item><tt/&lt;list&gt;/ - liste ordinaire (avec puces);
<item><tt/&lt;enumlist&gt;/ - liste numérotée;
<item><tt/&lt;taglist&gt;/ - liste de définitions.
</list>
<p>

Chaque entrée dans une liste ordinaire ou numérotée est introduite
par <tt/&lt;item&gt;/. Chaque entrée dans une liste de
définitions est un ou plusieurs objets <tt/&lt;tag&gt;/s suivis par
un objet <tt/&lt;item&gt;/.
<p>

Il n'est pas nécessaire de marquer la fin de <tt/&lt;tag&gt;/ ou de
<tt/&lt;item&gt;/.
<p>

Les trois types de listes viennent en deux variantes, ceci dépend
de la présence (par ex. <tt>&lt;taglist compact&gt;</>) ou non (par ex.
<tt/&lt;enumlist&gt;/) de l'attribut <tt/compact/.  L'objet
<tt/&lt;tag&gt;/ peut seulement contenir du texte brut.
<p>

Les versions compactes sont prévues pour être utilisées à l'intérieur
des paragraphes. Le formateur n'insèrera pas de blanc autour de la liste
ou entre les entrées.<footnote>Il y a un problème dans ce cas avec HTML.
Le formateur HTML ne le fait pas, en utilisant l'attribut <tt/compact/
des listes HTML pour les listes qu'il génère, mais peu de
navigateurs interprète cela correctement.</footnote> Les entrées dans
une liste compacte doivent être un seul paragraphe (il n'est pas
nécessaire de marquer le début du paragraphe). Toutes les listes 
à l'intérieur d'une liste compacte doivent être elles-mêmes
marquées compactes (même si les formateurs déduiront en faite par
eux-mêmes qu'elles doivent être compactes).
<p>

Les versions non compactes sont prévues pour se comporter comme
des paragraphes. Chaque entrée dans une telle liste peut contenir
plus d'un paragraphe (encore une fois, le début du premier paragraphe
n'a pas besoin d'être marqué). La liste est séparée du texte environnant
et chaque entrée des autres, par des lignes blanches comme il est
d'usage pour les ruptures de paragraphe.

<sect id="examples">Exemples
<p>

Exemples - fragments de codes de plusieurs lignes, scripts et bouts
de textes d'ordinateur équivalents - sont introduits avec 
<tt/&lt;example&gt;/ et finissent avec <tt>&lt;/example&gt;</>.  
<p>

L'exemple sera formatté exactement comme il y a été saisi, en reproduisant
espaces et sauts de lignes. Il sera représenté dans une police
non-proportionnelle, habituellement celle utilisée pour le style 
de caractère <tt/&lt;tt&gt;/, même si le formateur utilise
normalement une police proportionnelle. Toute indentation
appropriée sera ajoutée par le formateur; l'exemple doit
être saisi en commençant dans la colonne la plus à gauche.
<p>

Les exemples peuvent contenir du texte balisé mais ne
peuvent pas contenir des références croisées ou les éléments
de style de caractères <tt/&lt;tt&gt;/, <tt/&lt;prgn&gt;/ et
<tt/&lt;em&gt;/. Voir <ref id="inline">.
<p>

Un exemple ne produit pas de rupture de paragraphe; les exemples
sont considérés comme parties des paragraphes. Si un exemple doit
être un paragraphe par lui-même alors la balise de début de paragraphe
doit être insérée comme approprié.
<p>

Tout caractère spécial SGML dans l'exemple doit être échappé
comme habituellement - voir <ref id="markup">. <tt/&lt;example&gt;/
ne fonctionne pas comme l'environnement TeX <tt/verbatim/.

</book>
