Introduction au Projet de Documentation de FreeBSD pour les nouveaux participants
Précédent	Chapitre 3. Introduction à SGML	Suivant

3.6. Entités

Les entités fournissent un mécanisme pour désigner des parties d'un contenu. Lorsque l'analyseur SGML traite votre document, il remplace les entités qu'il rencontre par le contenu de ces entités.

C'est un bon moyen pour avoir du texte réutilisable et facile à modifier. C'est aussi le seul moyen d'inclure, en utilisant SGML, un fichier marqué dans un autre.

Il y a deux sortes d'entités SGML qui s'utilisent dans des situations différentes : les entités générales et les entités paramètres.

3.6.1. Entités Générales

Vous ne pouvez pas employer les entités générales dans un contexte SGML (bien que ce soit là que vous les définissiez). Elles ne peuvent être utilisées que dans votre document. Comparez cela au cas des entités paramètres.

Chaque entité générale a un nom. Quand vous voulez y faire référence (et donc inclure le texte qu'elle contient dans votre document), vous mettez &nom-de-l'entité;. Supposons par exemple que vous ayez une entité appelée version.courante qui contienne le numéro de version courante de votre produit. Vous pourriez écrire :

<para>La version courante de notre produit est la
  &version.courante;.</para>

Quand le numéro de version change, il vous suffit de modifier la définition de l'entité générale et de recompiler votre document.

Vous pouvez aussi vous servir d'entités générales pour représenter des caractères que vous ne pouvez pas inclure autrement dans un document SGML. < et &, par exemple, ne doivent normalement pas apparaître dans un document SGML. Quand l'analyseur SGML rencontre un symbole <, il suppose qu'il précède une marque (de début ou de fin), et quand il rencontre un symbole &, il suppose que le texte qui le suit est le nom d'une entité.

Heureusement, il y a deux entités générales, < et & pour le cas où vous auriez besoin d'inclure l'un ou l'autre de ces symboles.

Une entité générale ne peut être définie que dans un contexte SGML. On le fait habituellement immédiatement après la déclaration DOCTYPE.

Exemple 3-10. Définition d'entités générales

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY version.courante    "3.0-RELEASE">
<!ENTITY derniere.version  "2.2.7-RELEASE">
]>

Remarquez que la déclaration DOCTYPE est suivie d'un crochet ouvrant à la fin de la première ligne. Les deux entités sont définies aux deux lignes suivantes, avant le crochet fermant. La déclaration DOCTYPE se termine ensuite.

Les crochets sont nécessaires pour dire que nous ajoutons un complément à la DTD mentionnée par la déclaration DOCTYPE.

3.6.2. Entités paramètres

Comme les entités générales, les entités paramètres servent à nommer des parties réutilisables du texte. Cependant, alors que les entités générales peuvent être utilisées dans le corps du document, les entités paramètres ne peuvent être employées que dans un contexte SGML.

Les entités paramètres sont définies de la même manière que les entités générales. Sinon qu'au lieu de vous servir de &inomd-de-l'entité; pour y faire référence, vous utiliserez %nom-de-l'entité;[1]. Leur définition comporte aussi un % entre le mot-clé ENTITY et le nom de l'entité.

Exemple 3-11. Définition d'entités paramètres

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % param.du "du">
<!ENTITY % param.texte "text">
<!ENTITY % param.encore  "encore %param.du more %param.texte">

<!-- %param.encore contient maintenant "encore du texte" -->
]>

Cela ne paraît peut être pas très utile. On verra pourtant que ça l'est.

3.6.3. A faire…

Définissez un entité générale dans exemple.xml.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY version "1.1">
]>

<html>
  <head>
    <title>Exemple de fichier HTML</title>
  </head>

  <!-- Vous pourriez aussi mettre des commentaires ici -->

  <body>
    <p>C'est un paragraphe avec du texte.</p>

    <p>C'est encore un paragraphe avec du texte.</p>

    <p align="right">Ce paragraphe sera peut-être justifié &agrave;
      droite</p>

    <p>La version courante de ce document est : &version;</p>
  </body>
</html>

Validez le document avec nsgmls(1)
Chargez exemple.xml avec votre navigateur (vous devrez peut-être le recopier dans exemple.html pour que votre navigateur le reconnaisse comme un document HTML).

A moins que votre navigateur ne soit très évolué, il ne remplacera pas la référence &version; à l'entité par le numéro de version. Les analyseurs de la plupart des navigateurs sont élémentaires et ne gèrent pas correctement le SGML[2].
La solution est de normaliser votre document avec un outil de normalisation du SGML. Ce type d'outil lit un document SGML valide et le transforme en un autre document SGML tout aussi valide. En particulier, il y remplace les références aux entités par leur contenu.

Vous pouvez le faire avec sgmlnorm(1).
```
% sgmlnorm exemple.xml > exemple.html
```
exemple.html doit maintenant contenir une version normalisée (i.e., où les références aux entités ont été remplacées par leur contenu) de votre document, prête à être affichée par votre navigateur.
Si vous jetez un oeil au résultat de sgmlnorm(1), vous verrez qu'il ne comporte pas de déclaration DOCTYPE au début. Pour qu'elle y soit, utilisez l'option -d :
```
% sgmlnorm -d exemple.xml > exemple.html
```

Précédent	Sommaire	Suivant
Commentaires	Niveau supérieur	Utiliser les entités pour inclure des fichiers

[1]	Les entités Paramètres employent le symbole Pourcent.
[2]	C'est tout à fait dommage. Imaginez les problèmes et bricolages (comme les Server Side Includes) que cela éviterait.

3.6. Entités

3.6.1. Entités Générales

3.6.2. Entités paramètres

3.6.3. A faire…

Notes