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

# 3.8. Sections marquées

SGML fournit un mécanisme pour définir quelles parties d'un document doivent être traitées de façon particulière. On appelle cela des ``sections marquées''.

Exemple 3-14. Structure d'une section marquée

    <![ MOT-CLE [
      Contenu de la section marquée
    ]]>

Comme vous pouviez vous y attendre, une section marquée est une fonctionnalité SGML et commence donc par `<!`.

Le premier crochet ouvrant délimite la section marquée.

Le `MOT-CLE` définit comment cette section marquée doit être traitée par l'analyseur.

Le second crochet ouvrant indique que le contenu de la section marquée commence là.

La section marquée se termine par deux crochets fermants, puis un `>` pour indiquer que l'on quitte le contexte SGML et que l'on revient au document.

## 3.8.1. Mots-clés pour les sections marquées

### 3.8.1.1. `CDATA`, `RCDATA`

Ces deux mots-clés définissent des sections marquées comme modèle de contenu et vous permettent de modifier sa valeur par défaut.

Quand un analyseur SGML traite un docuemnt, il mémorise ce que l'on appelle le ``modèle de contenu''.

En bref, le modèle de contenu décrit ce que l'analyseur doit s'attendre à trouver comme contenu, et ce qu'il doit en faire quand il le rencontre.

Les deux modèles de contenu que vous trouverez certainement les plus utiles sont `CDATA` et `RCDATA`.

`CDATA` signifie ``Character Data'' - données caractères. Si l'analyseur est à l'intérieur de ce modèle de contenu, il s'attend à trouver des caractères, et uniquement des caractères. Les symboles < et & perdent alors leur signification particulière et sont traités comme de simples caractères.

`RCDATA` signifie ``Références à des entités et données caractères''. Si l'analyseur est à l'intérieur de ce modèle de contenu, il s'attend à trouver des caractères et des entités. < perd sa signification particulière, mais & est toujours compris comme le début d'une entité générale.

C'est particulièrement utile si vous incluez du texte qui contient de nombreux caractères < et &. Vous pourriez bien sûr contrôler que dans votre texte tous les < sont écrits &lt; et tous les & &amp;, il peut être plus facile de marquer la section comme ne contenant que des ``CDATA''. Quand SGML rencontre l'instruction correspondante, il ignorera les symboles < et & qui apparaîtront dans le contenu.

Exemple 3-15. Utiliser une section marquée CDATA

    <para>Voici un exemple de la façon dont vous pourriez inclure
      un texte comportant de nombreux &lt; et &amp;. L'exemple
      lui-même est en HTML. Le texte qui l'encadre (<para> et
      <programlisting>) est du DocBook.</para>

    <programlisting>
      <![ CDATA [
        <p>Cet exemple vous montre quelques &eacute;l&eacute;ments de HTML. Comme les
          caract&egrave;res < et > y sont si fr&eacute;quemment utilis&eacute;s, il est plus
          facile de marquer tout l'exemple comme CDATA plut&ocirc;t que de se
          servir des entit&eacute;s &agrave; la place de ces caract&egrave;res dans tout le
          texte.</p>

        <ul>
          <li>C'est un &eacute;l&eacute;ment de liste</li>
          <li>C'est un second &eacute;l&eacute;ment de liste</li>
          <li>C'est un troisi&egrave;me &eacute;l&eacute;ment de liste</li>
        </ul>

        <p>C'est la fin de l'exemple.</p>
      ]]>
    </programlisting>

Si vous consultez le source de ce document, vous verrez qu'il utilise constamment cette technique.

### 3.8.1.2. `INCLUDE` et `IGNORE`

Si le mot-clé est `INCLUDE`, alors le contenu de la section marquée sera pris en compte. Si le mot-clé est `IGNORE`, alors la section marquée sera ignorée. Il n'apparaîtra pas dans les sorties.

Exemple 3-16. Utiliser `INCLUDE` et `IGNORE` dans les sections marquées

    <![ INCLUDE [
      Ce texte sera traité et inclus.
    ]]>

    <![ IGNORE [
      Ce texte ne sera pas traité ou inclus.
    ]]>

En soi, cela ne sert pas à grand-chose. Si vous vouliez supprimer du texte de votre document, vous auriez pu l'enlever ou le mettre en commentaires.

Cela devient plus utile quand vous comprenez que vous pouvez vous servir des entités paramètres pour contrôler ces sections. Rappelez-vous que les entités paramètres ne peuvent être utilisées que dans un contexte SGML, et une section marquée est un contexte SGML.

Si par exemple, vous générez une version imprimée et une version électronique de votre document, vous pourriez vouloir inclure dans la version électronique un contenu supplémentaire qui ne devra pas apparaître dans la version imprimée.

Créez une entité paramètre et donnez lui comme contenu `INCLUDE`. Rédigez votre document en utilisant des sections marquées pour délimiter le contenu qui ne doit apparaître que dans la version électronique. Dans ces sections marquées, servez-vous de l'entité paramètre au lieu du mot-clé.

Lorsque vous voulez générer la version électronique, changez la valeur de l'entité paramètre en `IGNORE` et retraitez le document.

Exemple 3-17. Utiliser une entité paramètre pour contrôler une section marquée

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
    <!ENTITY % version.electronique "INCLUDE">
    ]]>

    ...

    <![ %version.electronique [
      Ce texte ne doit apparaître que dans
      la version électronique du document.
    ]]>

Pour générer la version imprimée, changez la définition de l'entité en :

    <!ENTiTY % version.electronique "IGNORE">

A la seconde passe sur le document, les sections marquées qui utilisent `%version.electronique` comme mot-clé seront ignorées.

## 3.8.2. A faire...

1. Créez un nouveau fichier, `section.sgml`, qui contienne :

       <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
       <!ENTITY % text.output "INCLUDE">
       ]>

       <html>
         <head>
           <title>Exemple d'utilisation des sections marquées</title>
         </head>

         <body>
           <p>Ce paragraphe <![ CDATA [contient de nombreux
             caractères < (< < < < <) il est donc
             plus facile de l'inclure dans une section marquée
             CDATA ]]></p>

           <![ IGNORE [
           <p>Ce paragraphe n'apparaîtra jamais dans les
             sorties.</p>
           ]]>

           <![ %sortie.texte [
           <p>Ce paragraphe apparaîtra peut-être dans les
             sorties.</p>

           <p>Cela dépend de l'entité paramètre
             %sortie.texte.</p>
           ]]>
         </body>
       </html>

2. Normalisez le fichier avec sgmlnorm(1) et examinez le résultat. Notez quels paragraphes ont été conservés et quels paragraphes ont été supprimés, et ce qu'est devenu le contenu des sections marquées CDATA.

3. Modifiez la définition de l'entité `sortie.texte` de `INCLUDE` en `IGNORE`. Normalisez de nouveau le fichier et regardez ce qui a changé dans le résultat.

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

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