Chapitre 4. Marques SGML

Table des matières
4.1. HTML
4.2. DocBook
4.3. * LinuxDoc

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 lequel 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, .

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.

4.1. HTML

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 relâché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.

4.1.1. Formal Public Identifier (FPI) - Identifiant Public Formel

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 relâchée de HTML 4.0 :


PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"

4.1.2. Sections

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>.

Exemple 4-1. Structure habituelle d'un document HTML


<html>
  <head>
	  <title>Le titre du document</title>
  </head>

  <body>

    …

  </body>
</html>

4.1.3. Eléments de blocs

4.1.3.1. Titres

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 -->

Une page HTML doit normalement 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.

Exemple 4-3. Mauvais ordonnancement des éléments <hn>

Use:


<h1>Première section</h1>

<!-- Introduction du document -->

<h3>Sous-section</h3>

<!-- Ce n'est pas bon, <h2> a été oublié -->

4.1.3.2. Paragraphes

HTML n'a qu'un seul élément paragraphe, <p>.

Exemple 4-4. <p>

Utilisez :


<p>C'est un paragraphe. Il peut contenir pratiquement
  n'importe quel élément.</p>

4.1.3.3. Citations

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&nbsp;:</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é &agrave; nous-mêmes et &agrave; notre Postérité, décidons et
  établissons cette Constitution des Etats-Unis d'Amérique.</blockquote>

4.1.3.4. Listes

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>

4.1.3.5. Texte pré-formaté

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 &agrave; l'adresse suivante :

    <URL:http://www.freebsd.org/~nik/primer/index.html>

  Commentaires souhaités.

  N
</pre>

4.1.3.6. Tables

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 &agrave; gauche</td>

    <td>Cellule en haut &agrave; droite</td>
  </tr>

  <tr>
    <td>Cellule en bas &agrave; gauche</td>

    <td>Cellule en bas &agrave; 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 &agrave; gauche, deux petites cellule &agrave; 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 &agrave; gauche</td>

    <td>Cellule du bas &agrave; droite</td>
  </tr>
</table>

Exemple 4-12. Emploi de rowspan et colspan ensemble

Use:


<p>Sur une grille 3x3, la cellule en haut &agrave; gauche s'étend sur deux
  lignes et deux colonnes. Les autres cellules sont normales.</p>

<table>
  <tr>
    <td colspan="2" rowspan="2">Grande cellule en haut &agrave; gauche</td>

    <td>Cellule en haut &agrave; droite</td>
  </tr>

  <tr>
    <!-- Comme la grande cellule se prolonge
         sur cette colonne, la première cellule
         marquée par <td> se trouvera &agrave; sa droite -->

    <td>Cellule du milieu &agrave; droite</td>
  </tr>

  <tr>
    <td>Cellule en bas &agrave; gauche</td>

    <td>Cellule en bas au milieu</td>

    <td>Cellule en bas &agrave; droite</td>
  </tr>
</table>

4.1.4. Eléments

4.1.4.1. Information d'accentuation

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.

Exemple 4-13. <em> et <strong>

Utilisez :


<p><em>Ceci</em> est accentué, et
  <strong>cela</strong> l'est encore plus.</p>

4.1.4.2. Gras et italiques

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>.

Exemple 4-14. <b> et <i>


<p><b>Ceci</b> est en gras, tandis que <i>cela</i> est
  en italiques.</p>

4.1.4.3. Texte en police fixe

S'il y a du texte qui doit être affiché en police fixe (machine à écrire), servez-vous de <tt> ( pour “télétype”).

Exemple 4-15. <tt>

Utilisez :


<p>L'auteur original de ce document est
  Nik Clayton, qui peut être contacté par courrier
  électronique &agrave; l'adresse : <tt>nik@freebsd.org</tt>.</p>

4.1.4.4. Taille de police

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.

  1. 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>.

  2. 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.

  3. 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&agrave; <big>est un peu plus gros</big>.</p>

<p>Ce texte est <font size="-1">un peu plus petit</font>.
  Mais celui-l&agrave; <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&agrave; <font size="4">est un peu plus gros</font>.</p>

4.1.5. Liens

Note : Les liens font aussi partie du contenu du document.

4.1.5.1. Liens vers d'autres documents sur le WWW

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é.

4.1.5.2. Liens sur d'autres parties des documents

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 lesquels 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 #).

Exemple 4-20. Lien sur une partie nommée du même document

Supposons que l'exemple para1 fasse partie de ce document.


<p>Vous trouverez plus d'informations au
  <a href="#para1">premier paragraphe</a> de
  ce document.</p>

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>.