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

3.7. Utiliser les entités pour inclure des fichiers

Les entités (générales et paramètres) sont particulièrement utiles pour inclure un fichier dans un autre.

3.7.1. Utiliser les entités générales pour inclure des fichiers

Supposons que le contenu d'un livre SGML soit découpé en fichiers, à raison d'un fichier par chapitre, appelés chaptitre1.xml, chapitre2.xml, et ainsi de suite, et que le fichier livre.xml inclue ces chapitres.

Pour que vos entités aient pour valeur le contenu de ces fichiers, vous les déclarerez avec le mot-clé SYSTEM. Cela indique à l'analyseur SGML qu'il doit utiliser le contenu du fichier mentionné comme valeur de l'entité.

Exemple 3-12. Utiliser les entités générales pour inclure des fichiers

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY chapitre.1 SYSTEM "chapitre1.xml">
<!ENTITY chapitre.2 SYSTEM "chapitre2.xml">
<!ENTITY chapitre.3 SYSTEM "chapitre3.xml">
<!-- Et ainsi de suite -->
]>

<html>
  <!-- Utilisation des entités pour inclure les chapitres -->

  &chapitre.1;
  &chapitre.2;
  &chapitre.3;
</html>

Avertissement : Quand vous vous servez d'entités générales pour inclure d'autres fichiers dans un document, les fichiers inclus (chapitre1.xml, chapitre2.xml, et ainsi de suite) ne doivent pas commencer par une déclaration DOCTYPE. Ce serait une erreur de syntaxe.

3.7.2. Utiliser les entités paramètres pour inclure des fichiers

Rappelez-vous que les entités paramètres ne peuvent être utilisées que dans un contexte SGML. Quand aurez-vous besoin d'inclure un fichier dans un contexte SGML ?

Vous pouvez vous en servir pour être sûr de pouvoir réutiliser vos entités générales.

Supposons que votre document comporte de nombreux chapitres, et que vous réutilisiez ces chapitres dans deux livres différents, chacun organisant ces chapitres de façon différente.

Vous pourriez donner la liste des entités en tête de chaque livre, mais cela pourrait rapidement devenit fastidieux à gérer.

Mettez, au lieu de cela, les définitions des entités générales dans un fichier, et utilisez une entité paramètre pour inclure ce fichier dans votre document.

Exemple 3-13. Utiliser les entités paramètres pour inclure des fichiers

Mettez d'abord les définitions de vos entités dans un fichier séparé, appelé chapitres.ent. Voici ce qu'il contiendra :

<!ENTITY chapitre.1 SYSTEM "chapitre1.xml">
<!ENTITY chapitre.2 SYSTEM "chapitre2.xml">
<!ENTITY chapitre.3 SYSTEM "chapitre3.xml">

Créez maintenant une entité paramètre qui fasse référence au contenu de ce fichier. Utilisez ensuite cette entité pour inclure le fichier dans votre document, vous pourrez alors y utiliser les entités générales. Ce que vous faites de la même façon que précédemment :

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!--
     Définissez une entité paramètre pour inclure le fichier
     des entités générales pour les chapitres
-->
<!ENTITY % chapitres SYSTEM "chapitres.ent">

<!-- Utilisez maintenant l'entité générale pour inclure ce fichier -->
%chapitres;
]>

<html>
  &chapitre.1;
  &chapitre.2;
  &chapitre.3;
</html>

3.7.3. A faire…

3.7.3.1. Utiliser les entités générales pour inclure des fichiers

Créez trois fichiers, para1.xml, para2.xml et para3.xml.

Mettez-y quelque chose qui ressemble à ceci :
```
<p>C'est le premier paragraphe.</p>
```

Modifiez exemple.xml de la façon suivante :

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.xml">
<!ENTITY para2 SYSTEM "para2.xml">
<!ENTITY para3 SYSTEM "para3.xml">
]>

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

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

    &para1;
    &para2;
    &para3;
  </body>
</html>

Générez exemple.html en normalisant exemple.xml.
```
% sgmlnorm -d exemple.xml > exemple.html
```
Affichez exemple.html avec votre navigateur Web et vérifiez que les fichiers paran.xml ont bien été inclus dans exemple.html.

3.7.3.2. Utiliser les entités paramètres pour inclure des fichiers

Note : Vous devez d'abord avoir mis en pratique l'exemple précédent.

Modifiez comme ceci exemple.xml :

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % entites SYSTEM "entites.xml"> %entites;
]>

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

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

    &para1;
    &para2;
    &para3;
  </body>
</html>

Créez un nouveau fichier, entites.xml, qui contienne :

<!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.xml">
<!ENTITY para2 SYSTEM "para2.xml">
<!ENTITY para3 SYSTEM "para3.xml">

Générez exemple.html en normalisant exemple.xml.
```
% sgmlnorm -d exemple.xml > exemple.html
```
Affichez exemple.html avec votre navigateur Web et vérifiez que les fichiers paran.xml ont bien été inclus dans example.html.

Précédent	Sommaire	Suivant
Entités	Niveau supérieur	Sections marquées