Ce chapitre décrit les trois langages de marquage que vous rencontrerez si vous contribuez au Projet de Documentation de FreeBSD. Chaque section décrit le langage et détaille les marques que vous serez probablement amenés à utiliser, ou qui sont déjà utilisées.
Ces langages sont riches en éléments et il est parfois difficile de savoir lequels employer dans un contexte particulier. Cette section décrit ceux dont vous aurez probablement besoin et donne des exemples de la manière de s'en servir.
Ce n'est pas une liste
exhaustive d'éléments, cela ne ferait que reprendre le contenu de la
documentation de chacun de ces langages. L'objectif de cette section est de lister les
éléments qui ont le plus de chance de vous être utiles. Si vous avez
des questions sur le type de marque à employer dans un contexte particulier,
posez-les s'il vous plaît à la liste de diffusion du Projet de Documentation
de FreeBSD, <freebsd-doc@freebsd.org>.
En ligne vs. de bloc : Dans la suite de ce document, quand on décrira des éléments, en ligne signifie que l'élément peut apparaître à l'intérieur d'un bloc et ne génère pas de passage à la ligne. A l'inverse un élément de bloc provoque un passage à la ligne (et d'autres opérations) lorsqu'on le rencontre.
HTML, l'HyperText Markup Language - Langage de Marquage de l'Hypertexte - est le langage de prédilection du World Wide Web. Vous trouverez plus d'informations sur <URL:http://www.w3.org/>.
HTML est utilisé pour marquer les pages du site Web de FreeBSD. Il ne devrait (habituellement) pas servir pour d'autre type de documentation, parce que DocBook offre un jeu de marques beaucoup plus riche. Vous ne devriez donc rencontrez des pages HTML que si vous écrivez pour le site Web.
Il y a eu plusieurs versions de HTML, 1, 2, 3.0, 3.2, et il existe deux variantes de la dernière version, 4.0 (disponible à la fois en version stricte et relachée).
Les DTDs HTML existent au catalogue des logiciels portés dans textproc/html. Elles sont automatiquement installées par le méta-port textproc/docproj.
Il y a un certain nombre de FPIs HTML, selon la version (qu'on appelle aussi le niveau) de HTML avec laquelle vous voulez que votre document soit compatible.
La plupart des documents HTML du site Web de FreeBSD respectent strictement la version relachée de HTML 4.0 :
PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
Un document HTML est habituellement composé de deux sections. La première section, appelée head - en-tête, contient des informations sur le document, comme son titre, le nom de son auteur, le document dans lequel il est inclus, et ainsi de suite. La seconde section, le body - corps, contient ce qui sera affiché.
Ces sections sont dénotées par les éléments <head> et <body> respectivement. Ces éléments appartiennent à l'élément de premier niveau <html>.
HTML vous permet d'avoir jusqu'à six niveaux de titres différents dans votre document.
Le titre le plus gros et le plus visible est <h1>, puis <h2>, jusqu'à <h6>.
Le contenu de l'élément est le texte du titre.
Exemple 4-2. <h1>, <h2>, etc.
Utilisez :
<h1>Première section</h1> <!-- Introduction du document --> <h2>C'est le titre de la première section</h2> <!-- Contenu de la première section --> <h3>C'est le titre de la première sous-section</h3> <!-- Contenu de la première sous-section --> <h2>C'est le titre de la seconde section</h2> <!-- Contenu de la seconde section -->
Un page HTML doit normalementi avoir un titre de premier niveau (<h1>). Il peut contenir plusieurs titres de second niveau (<h2>), et à leur tour, de nombreux titres de troisième niveau. Chaque élément <hn> doit appartenir à un même élément de niveau supérieur. Il faut éviter de sauter d'un cran dans la numérotation.
HTML n'a qu'un seul élément paragraphe, <p>.
Une citation d'un long extrait d'un autre document, qui ne doit pas apparaître dans le paragraphe en cours, mais est mise dans un bloc de citation.
Exemple 4-5. <blockquote>
Utilisez :
<p>Un court extrait de la Constitution des Etats-Unis :</p> <blockquote>Nous le Peuple des Etats-Unis, dans le But de former une Union plus parfaite, d'établir la Justice, d'assurer la Tranquilité domestique, de défendre chacun, de promouvoir le Bien-être général, et de garantir les Bénédictions de la Liberté à nous-mêmes et à notre Postérité, décidons et établissons cette Constitution des Etats-Unis d'Amérique.</blockquote>
Il y a trois types de listes que vous pouvez afficher : ordonnée, non ordonnée et de définition.
Typiquement, chaque entrée d'une liste ordonnée sera numérotée, alors que chaque entrée d'une liste non ordonnée sera précédée d'une puce. Les listes de définition ont deux sections pour chaque entrée. La première est le terme que l'on définit et la seconde sa définition.
Les listes ordonnées sont dénotées par l'élément <ol>, les listes non ordonnées par l'élément <ul> et les listes de définition par l'élément <dl> element.
Les listes ordonnées et non ordonnées contiennent des éléments de liste, notés avec l'élément <li>. Un élément de liste peut contenir du texte, ou être décomposé en plusieurs éléments <p>.
Les listes de définition contiennent des termes à définir (<dt>) et leurs définitions (<dd>). Le terme à définir n'est composé que de texte. La définition peut comporter d'autres éléments de blocs.
Exemple 4-6. <ul> et <ol>
Utilisez :
<p>Une liste non ordonnée. Les éléments de la liste seront
probablement précédés par des puces.</p>
<ul>
<li>Premier élément</li>
<li>Second élément</li>
<li>Troisième élément</li>
</ul>
<p>Une liste ordonnée, dont les éléments comportent plusieurs paragraphes.
Chaque élément (note : et non chaque paragraphe) sera numéroté.</p>
<ol>
<li><p>C'est le premier élément. Il n'a qu'un paragraphe..</p></li>
<li><p>C'est le premier paragraphe du second élément.</p>
<p>C'est le second paragraphe du second élément.</p>
<li><p>C'est le premier et seul paragraphe du troisième élément.</p></li>
</ol>
Exemple 4-7. Listes de définition avec <dl>
Utilisez :
<dl>
<dt>Terme 1</dt>
<dd><p>Paragraphe 1 de la définition 1.</p></dd>
<p>Paragraphe 2 de la définition 1.</p></dd>
<dt>Terme 2</dt>
<dd><p>Paragraphe 1 de la définition 2.</p></dd>
<dt>Terme 3</dt>
<dd>Paragraphe 1 de la définition 3. Remarquez que l'élément <p> n'est
pas obligatoire dans le cas d'un paragraphe unique.</dd>
</dl>
Vous pouvez préciser que du texte doit apparaître exactement comme il est présenté dans le fichier. Cela signifie habituellement que le texte est affiché en police fixe, que les blancs successifs sont conservés et que les passages à la ligne dans le texte sont significatifs.
Pour cela, il faut mettre ce texte dans un élément <pre>.
Exemple 4-8. <pre>
Vous pouvez utiliser <pre> pour marquer le texte d'un courrier électronique :
<pre>
From: nik@freebsd.org
To: freebsd-doc@freebsd.org
Subject: Nouvelle documentation disponible
Une nouvelle version de mon introduction pour les nouveaux
participants au Projet de Documentation de FreeBSD est
disponible à l'adresse suivante :
<URL:http://www.freebsd.org/~nik/primer/index.html>
Commentaires souhaités.
N
</pre>
Note : La plupart des navigateurs en mode texte (comme Lynx) n'affichent pas très bien les tables. Si vous utilisez ce type de présentation en tableaux, vous devriez envisager d'utiliser d'autres marques pour éviter la confusion.
Marquez les tableaux avec l'élément <table>. Un tableau est composé d'une ou plusieurs lignes (<tr>), chacune contenant une ou plusieurs cellules (<td>). Chaque cellule peut contenir d'autres éléments de bloc, des paragraphes ou des listes par exemple. Elle peut aussi contenir d'autres tables (cet emboîtement peut se répéter indéfiniment). Si la cellule ne contient qu'un seul paragraphe, l'élément <p> n'est pas obligatoire.
Exemple 4-9. Emploi simple de <table>
Utilisez :
<p>C'est une table 2x2 simple.</p>
<table>
<tr>
<td>Cellule en haut à gauche</td>
<td>Cellule en haut à droite</td>
</tr>
<tr>
<td>Cellule en bas à gauche</td>
<td>Cellule en bas à droite</td>
</tr>
</table>
Une cellule peut occuper plusieurs lignes ou colonnes. Pour le préciser, ajoutez les attributs rowspan et/ou colspan, dont les valeurs donnent le nombre de lignes et de colonnes occupées.
Exemple 4-10. Emploi de rowspan
Utilisez :
<p>Une grande cellule à gauche, deux petites cellule à droite.</p>
<table>
<tr>
<td rowspan="2">Grande et mince</td>
</tr>
<tr>
<td>Cellule du haut</td>
<td>Cellule du bas</td>
</tr>
</table>
Exemple 4-11. Emploi de colspan
Utilisez :
<p>Une grande cellule en haut, deux petites cellules en dessous.</p>
<table>
<tr>
<td colspan="2">Cellule du haut</td>
</tr>
<tr>
<td>Cellule du bas à gauche</td>
<td>Cellule du bas à droite</td>
</tr>
</table>
Exemple 4-12. Emploi de rowspan et colspan ensemble
Use:
<p>Sur une grille 3x3, la cellule en haut à gauche d'étend sur deux
lignes et deux colonnes. Les autres cellules sont normales.</p>
<table>
<tr>
<td colspan="2" rowspan="2">Grande cellule en haut à gauche</td>
<td>Cellule en haut à droite</td>
</tr>
<tr>
<!-- Comme la grande cellule se prolonge
sur cette colonne, la première cellule
marquée par <td> se trouvera à sa droite -->
<td>Cellule du milieu à droite</td>
</tr>
<tr>
<td>Cellule en bas à gauche</td>
<td>Cellule en bas au milieu</td>
<td>Cellule en bas à droite</td>
</tr>
</table>
Il y a deux niveaux d'accentuation disponibles en HTML, <em> et <strong>. <em> marque une accentuation normale et <strong> une accentuation plus prononcée.
<em> est généralement rendu en italiques et <strong> en gras. Ce n'est malgré tout pas toujours le cas, et il ne faut pas se baser là-dessus.
HTML comporte des marques pour la présentation, vous pouvez donc aussi préciser qu'un contenu donné doit apparaître en gras ou en italiques. Les éléments pour cela sont respectivement <b> et <i>.
S'il y a du texte qui doit être affiché en police fixe (machine à écrire), servez-vous de <tt> ( pour ``télétype'').
Vous pouvez préciser qu'un contenu doit être affiché en police plus grande ou plus petite. Il y a trois façons de le faire.
Utilisez <big> et <small> pour encadrer le texte dont vous voulez modifier la taille. Ces marques peuvent être imbriquées, il est donc possible d'avoir : <big><big>C'est bien plus gros</big></big>.
Servez-vous de <font> avec l'attribut size prenant respectivement les valeurs +1 ou -1. C'est la même chose que d'utiliser <big> ou <small>. Mais cette façon de faire est obsolète.
Utilisez <font> avec l'attribut size prenant une valeur de 1 à 7. La taille de police par défaut est 3. Cette façon de faire est aussi obsolète.
Exemple 4-16. <big>, <small> et <font>
Les trois extraits suivants ont le même résultat :
<p>Ce texte est <small>un peu plus petit</small>. Mais celui-là <big>est un peu plus gros</big>.</p> <p>Ce texte est <font size="-1">un peu plus petit</font>. Mais celui-là <font size="+1">est un peu plus gros</font>.</p> <p>Ce texte est <font size="2">un peu plus petit</font>. Mais celui-là <font size="4">est un peu plus gros</font>.</p>
Note : Les liens font aussi partie du contenu du document.
Pour mettre un lien sur un autre document sur le WWW, il faut que vous connaissiez l'URL de ce document.
Ce lien est noté avec <a> et l'attribut href contient l'URL du document cible. Le lien est le contenu de l'élément, il est habituellement présenté d'une façon ou d'une autre à l'utilisateur (souligné, couleur différente, curseur de forme différente quand on passe dessus, et ainsi de suite).
Exemple 4-17. Emploi de <a href="...">
Utilisez :
<p>Vous trouverez plus d'informations sur le <a href="http://www.freebsd.org/">site Web de FreeBSD</a>.</p>
Ces liens amèneront l'utilisateur au début du document sélectionné.
Pour mettre un lien sur un endroit précis d'un autre (ou du même) document, il faut que l'auteur de ce document y ait mis des points d'ancrage sur lequels vous pouvez pointer.
Les points d'ancrage sont notés avec <a> et l'attribut name au lieu de href.
Exemple 4-18. Emploi de <a name="...">
Utilisez :
<p><a name="para1">Ce</a> paragraphe peut être référencé par d'autres liens via le nom <tt>para1</tt>.</p>
Pour mettre un lien sur une partie nommée d'un document, utilisez un lien ordinaire, mais ajoutez-y le nom du point d'ancrage précédé d'un symbole #.
Exemple 4-19. Lien sur une partie nommée d'un autre document
Supposons que l'exemple para1 se trouve dans un document appelé foo.html.
<p>Vous trouverez plus d'informations au <a href="foo.html#para1">premier paragraphe</a> de <tt>foo.html</tt>.</p>
Si le lien pointe sur un point d'ancrage nommé du même document, vous pouvez ommettre son URL et ne mettre que le nom du point d'ancrage (précédé de #).
Ce document, ainsi que d'autres peut être téléchargé sur ftp.FreeBSD.org/pub/FreeBSD/doc/.
Pour toutes questions à propos de FreeBSD, lisez la documentation avant de contacter <questions@FreeBSD.org>.
Pour les questions sur cette documentation, contactez <doc@FreeBSD.org>.