<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.

     Redistribution and use in source (SGML DocBook) and 'compiled' forms
     (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
     modification, are permitted provided that the following conditions
     are met:

      1. Redistributions of source code (SGML DocBook) must retain the above
         copyright notice, this list of conditions and the following
         disclaimer as the first lines of this file unmodified.

      2. Redistributions in compiled form (transformed to other DTDs,
         converted to PDF, PostScript, RTF and other formats) must reproduce
         the above copyright notice, this list of conditions and the
         following disclaimer in the documentation and/or other materials
         provided with the distribution.

     THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
     INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
     SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
     STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
     ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
     POSSIBILITY OF SUCH DAMAGE.

     The FreeBSD Documentation Project
     The FreeBSD French Documentation Project

     $FreeBSD$
     Original revision: 1.8 
-->

<chapter id="sgml-primer">
  <title>Introduction &agrave; SGML</title>

  <para>La majorit&eacute; des documentations du FDP utilisent SGML. Ce chapitre vous
    explique ce que cela signifie exactement, comment lire et comprendre le
    source de la documentation et d&eacute;crit la fa&ccedil;on d'utiliser le SGML que vous
    recontrerez dans la documentation.</para>

  <para>Des parties de cette section se sont inspir&eacute;es du livre de Mark
    Galassi, <ulink
      url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html">&ldquo;<foreignphrase>Get Going With DocBook</foreignphrase>&rdquo;</ulink>.</para>
  
  <sect1>
    <title>Introduction</title>

    <para>Il &eacute;tait autrefois facile de travailler sur des documents
      &eacute;lectroniques. Vous n'aviez normalement &agrave; conna&icirc;tre que le jeu de
      caract&egrave;res utilis&eacute; (ASCII, EBCDIC, ou l'un des nombreux autres) et
      c'&eacute;tait &agrave; peu pr&egrave;s tout. Le texte &eacute;tait du texte, et vous voyiez 
      vraiment ce que vous obteniez. Pas de sophistication, pas de formatage,
      pas d'intelligence.</para>

    <para>Cela devint in&eacute;vitablement insuffisant. Une fois que vous avez du
      texte qu'une machine peut lire, vous vous attendez &agrave; ce que la machine
      puisse l'utiliser et le manipuler intelligemment. Vous aimeriez pouvoir
      pr&eacute;ciser que certaines phrases sont accentu&eacute;es, y ajouter un glossaire 
      ou des hyper-liens. Vous voulez que les noms de fichiers apparaissent
      en police &ldquo;machine &agrave; &eacute;crire&rdquo; &agrave; l'&eacute;cran et en italique &agrave;
      l'impression, et tout un tas d'autres options de pr&eacute;sentation
      encore.</para>

    <para>Il fut un temps o&ugrave; l'on pensait que l'Intelligence Artificielle (IA)
      rendrait cela facile. Votre ordinateur pourrait lire le document et 
      identifier les phrases cl&eacute;s, les noms de fichiers, le texte que
      l'utilisateur devait taper, et d'autres encore. Malheureusement, la
      r&eacute;alit&eacute; est un peu diff&eacute;rente, et il faut aider nos ordinateurs &agrave;
      manipuler intelligemment notre texte.</para>

    <para>Plus pr&eacute;cisement, il faut les aider &agrave; indentifier ce qui est quoi.
      Vous et moi, &agrave; la vue de&nbsp;:</para>

      <blockquote>
	<para>Pour effacer <filename>/tmp/foo</filename>, utilisez
          &man.rm.1;&nbsp;:</para>

	<screen>&prompt.user; <command>rm /tmp/foo</command></screen>
      </blockquote>

      <para>distinguons facilement ce qui est nom de fichier, commande &agrave;
        taper, r&eacute;f&eacute;rence aux pages de manuel, et ainsi de suite. Mais
        l'ordinateur lui ne le peut pas. Pour cela, Nous avons besoin des
        marques.</para>
    
    <para>Le &ldquo;marquage&rdquo; est commun&eacute;ment qualifi&eacute; de &ldquo;valeur
      ajout&eacute;e&rdquo; ou &ldquo;co&ucirc;t augment&eacute;&rdquo;. Le terme prend ces deux
      sens quand il s'applique au texte. La marquage est du texte en 
      suppl&eacute;ment dans le document, distinct par un moyen ou un autre du
      contenu du document, de fa&ccedil;on &agrave; ce que les programmes qui traitent le
      document puisse le lire et l'utiliser pour prendre des d&eacute;cisions. Les
      &eacute;diteurs peuvent masquer le marquage &agrave; l'utilisateur, de fa&ccedil;on &agrave; ce
      qu'il ne soit pas perturb&eacute; par ces marques.</para>
      
    <para>L'information suppl&eacute;mentaire donn&eacute;e avec les marques
      <emphasis>ajoute de la valeur</emphasis> au document. Le marquage doit
      habituellement &ecirc;tre manuel&nbsp;-&nbsp;apr&egrave;s tout, si les ordinateurs
      pouvait analyser suffisamment le texte pour ajouter les marques, il n'y
      en aurait alors en fait pas besoin. Cela <emphasis>augment le
      co&ucirc;t</emphasis> du document.</para>

    <para>L'exemple pr&eacute;c&eacute;dent est cod&eacute; comme suit dans le pr&eacute;sent
      document&nbsp;:</para>

    <programlisting><![ CDATA [
<para>Pour effacer <filename>/tmp/foo</filename>, utilisez
  &man.rm.1;.</para>

<para><command>rm /tmp/foo</command></para>]]></programlisting>

    <para>Comme vous pouvez le constater, le marquage est clairement s&eacute;par&eacute; du
      contenu.</para>

    <para>Bien &eacute;videmment, si vous devez utiliser des marques, vous devrez
      d&eacute;finir ce que les marques veulent dire et comment elles doivent &ecirc;tre
      trait&eacute;es. Il vous faudra un language de marquage auquel vous r&eacute;f&eacute;rer
      pour marquer vos documents.</para>
    
    <para>Un seul language de marquage peut bien s&ucirc;r ne pas suffire. Les
      besoins de marquage d'une documentation technique diff&egrave;rent &eacute;norm&eacute;ment
      de ceux de recettes de cuisines. ces derniers seront &agrave; leur tour
      diff&eacute;rents de ceux d'un language de marquage pour de la po&eacute;sie. Vous
      avez en fait besoin d'un language qui vous permette de d&eacute;finir ces
      autres languages de marquage. Un <emphasis>m&eacute;ta-language de
      marquage</emphasis>.</para>
    
    <para>C'est exactement ce qu'est <foreignphrase>Standard Generalised
      Markup Language (SGML)</foreignphrase>&nbsp;-&nbsp;Language de Marquage
      Standard G&eacute;n&eacute;ralis&eacute;. De nombreux languages de marquage sont &eacute;crits en
      SGML, dont les deux languages les plus utilis&eacute;s par le FDP, HTML et
      DocBook.</para>
    
    <para>Chaque d&eacute;finition d'un language s'appelle plus exactement une
      <foreignphrase>Document Type Definition 
      (DTD)</foreignphrase>&nbsp;-&nbsp;D&eacute;finition de Type de Document. La DTD
      d&eacute;finit les noms des &eacute;l&eacute;ments utilisables, leur ordre d'apparition (et 
      leur hi&eacute;rarchie) et les informations qui s'y rapportent. Une DTD est 
      parfois d&eacute;sign&eacute;e comme une <emphasis>application</emphasis> de
      SGML.</para>

    <para id="sgml-primer-validating">Une DTD est une sp&eacute;cification
      <emphasis>compl&egrave;te</emphasis> de tous les &eacute;l&eacute;ments autoris&eacute;s, de l'ordre
      dans lequel ils doivent &ecirc;tre utilis&eacute;s, quels sont ceux qui sont
      obligatoires, quels sont ceux qui sont facultatifs, et ainsi de suite.
      Il est alors possible d'&eacute;crire un <emphasis>analyseur</emphasis> qui
      lise et la DTD et le document qui pr&eacute;tend s'y conformer. L'analyseur
      peut alors v&eacute;rifier si tous les &eacute;l&eacute;ments requis sont bien pr&eacute;sents dans
      l'ordre voulu dans le document et s'il y a des erreurs dans le marquage.
      On appelle habituellement cela <quote>valider le
      document</quote>.</para>

    <note>
      <para>Ce traitement ne valide uniquement que le choix des &eacute;l&eacute;ments, leur
        ordre, et ainsi de suite, se conforme &agrave; ce que d&eacute;finit la DTD. Il ne
        v&eacute;rifie <emphasis>pas</emphasis> que vous avez utilis&eacute; les marques
        <emphasis>appropri&eacute;es</emphasis> au document. Si vous marquez tous les
        noms de fichiers de votre document comme des noms de fonctions, 
        l'analyseur ne le signalera pas comme une erreur (en supposant, bien
        s&ucirc;r, que votre DTD d&eacute;finisse des &eacute;l&eacute;ments pour les noms de fichiers et
        de fonctions et qu'ils aient le droit d'appara&icirc;tre aux m&ecirc;mes
        endroits).</para>
    </note>
    
    <para>Il est probable que vos contributions au Projet de Documentation
      consiste en documents marqu&eacute;s soit en HTML soit en DocBook, plut&ocirc;t qu'en
      modifications aux DTDs. Pour cette raison, cet ouvrage n'abordera pas la
      fa&ccedil;on d'&eacute;crire une DTD.</para>
  </sect1>
  
  <sect1 id="sgml-primer-elements">
    <title>El&eacute;ments, marques et attributs</title>

    <para>Toutes les DTDs &eacute;crites en HTML ont des caract&eacute;ristiques communes.
      Ce n'est gu&egrave;re surprenant comme le montre in&eacute;vitablement la philosophie
      qui sous-tend SGML. Une des manifestations les plus visibles de cette
      philosophie est la caract&eacute;risation en <emphasis>contenu</emphasis> et
      <emphasis>&eacute;l&eacute;ments</emphasis>.</para>

    <para>Votre documentation (que ce soit une seule page Web ou un ouvrage
      volumineux) est vue comme &eacute;tant un contenu. Ce contenu est alors divis&eacute;
      (et ensuite subdivis&eacute;) en &eacute;l&eacute;ments. L'objectif de l'ajout de marques est
      de nommer et de d&eacute;finir le d&eacute;but et la fin de ces &eacute;l&eacute;ments pour
      traitement ult&eacute;rieur.</para>

    <para>Consid&eacute;rez par exemple un livre type. Au plus haut niveau, ce livre
      lui-m&ecirc;me est un &eacute;l&eacute;ment.  Cet &eacute;l&eacute;ment &ldquo;livre&rdquo; contient
      &eacute;videmment des chapitres, qui peuvent aussi &ecirc;tre l&eacute;gitimement consid&eacute;r&eacute;s
      comme des &eacute;l&eacute;ments. Chaque chapitre contiendra &agrave; son tour des &eacute;l&eacute;ments,
      tels que des paragraphes, des citations et de notes de bas de page.
      Chaque paragraphe peut lui-m&ecirc;me contenir encore des &eacute;l&eacute;ments, pour
      identifier le texte parl&eacute; par exemple, ou les noms des personnages de
      l'histoire.</para>

    <para>Vous pouvez si vous le voulez voir cela comme un
      &ldquo;morcelement&rdquo; du contenu. A la racine, vous avez un morceau,
      le livre. Un niveau en dessous, vous avez plus de morceaux, les
      chapitres individuels. Ils sont &agrave; leur tour morcel&eacute;s en pargraphes,
      notes de bas de page, noms des personnages, et ainsi de suite.</para>

    <para>Remarquez que vous pouvez diff&eacute;rencier les &eacute;l&eacute;ments sans utiliser
      la terminologie SGML. C'est vraiment imm&eacute;diat. Vous pouvez le faire avec
      un surligneur et un livre imprim&eacute;, en utilisant des couleurs diff&eacute;rentes
      pour chaque type d'&eacute;l&eacute;ment.</para>

    <para>Nous n'avons bien s&ucirc;r pas de surligneur &eacute;lectronique, il nous faut
      donc un autre moyen d'indiquer &agrave; quel &eacute;l&eacute;ment appartient chaque morceau
      du contenu. Dans les languages &eacute;crits avec SGML ,(HTML, DocBook, et
      al.), cela se fait avec des <emphasis>marques</emphasis>.</para>

    <para>Une marque sert &agrave; dire o&ugrave; commence et o&ugrave; finit un &eacute;l&eacute;ment.
      <emphasis>La marque ne fait pas partie de l'&eacute;l&eacute;ment lui-m&ecirc;me</emphasis>. 
      Comme chaque DTD est habituellement &eacute;crite pour marquer des types
      d'informations sp&eacute;cifiques, chacune reconna&icirc;tra des &eacute;l&eacute;ments diff&eacute;rents,
      et aura donc des noms diff&eacute;rents pour les marques.</para>

    <para>Pour un &eacute;l&eacute;ment appel&eacute; <replaceable>nom-de-l'&eacute;l&eacute;ment</replaceable>,
      la marque de d&eacute;but sera normalement
      <literal>&lt;<replaceable>nom-de-l'&eacute;l&eacute;ment</replaceable>&gt;</literal>.
      La marque de fin correspondante sera
      <literal>&lt;/<replaceable>nom-de-l'&eacute;l&eacute;ment</replaceable>&gt;</literal>.</para>

    <example>
      <title>Utiliser un &eacute;l&eacute;ment (marques de d&eacute;but et de fin)</title>

      <para>HTML dispose d'un &eacute;l&eacute;ment pour indiquer que le contenu inclus est
        un paragraphe, appel&eacute; <literal>p</literal>. Cet &eacute;l&eacute;ment a une marque
        de d&eacute;but et une de fin.</para>
      
      <programlisting>
<![ CDATA [<p>C'est un paragraphe. Il commence avec la marque de d&eacute;but pour
  l'&eacute;l&eacute;ment 'p', et se terminera avec la marque de fin pour
  l'&eacute;l&eacute;ment 'p'</p>

<p>C'est un autre paragraphe. Mais il est beaucoup plus
  court.</p>]]></programlisting>	  
    </example>

    <para>Tous les &eacute;l&eacute;ments n'ont pas besoin d'une marque de fin. Certains
      n'ont pas de contenu. En HTML, par exemple, vous pouvez indiquer que
      vous voulez avoir une ligne horizontal dans votre document. Cette ligne
      n'a bien s&ucirc;r aucun contenu, vous n'avez donc besoin que de la marque de
      d&eacute;but pour cet &eacute;l&eacute;ment.</para>

    <example>
      <title>Utiliser un &eacute;l&eacute;ment (marque de d&eacute;but uniquement)</title>

      <para>HTML dispose d'un &eacute;l&eacute;ment pour inclure une ligne horizontale, 
        appel&eacute; <literal>hr</literal>. C'est un &eacute;l&eacute;ment sans contenu, il n'a
        donc qu'une marque de d&eacute;but.</para>

      <programlisting>
<![ CDATA [<p>C'est un paragraphe.</p>

<hr>

<p>C'est un autre paragraphe. Une ligne horizontale le s&eacute;pare
  du pr&eacute;c&eacute;dent.</p>]]></programlisting>
    </example>
    
    <para>Si ce n'&eacute;tait pas encore clair, les &eacute;l&eacute;ments peuvent contenir
      d'autres &eacute;l&eacute;ments. Dans l'exemple du livre plus haut, ce livre contenait
      tous les chapitres, qui &agrave; leur tour contenaient tous les paragraphes, et
      ainsi de suite.</para>

    <example>
      <title>El&eacute;ments dans des &eacute;l&eacute;ments&nbsp;; <sgmltag>em</sgmltag></title>
      
      <programlisting>
<![ CDATA [<p>C'est un <em>paragraphe</em> simple o&ugrave; certains
  <em>mots</em> ont &eacute;t&eacute; <em>mis en valeur</em>.</p>]]></programlisting>
    </example>
    
    <para>La DTD d&eacute;finira les r&egrave;gles qui disent quels &eacute;l&eacute;ments peuvent &ecirc;tre
      inclus dans quels autres &eacute;l&eacute;ments, et ce qu'ils peuvent pr&eacute;cisement
      contenir.</para>

    <important>
      <para>Les gens confondent souvent marques et &eacute;l&eacute;ments comme si c'&eacute;taient
        des termes interchangeables. Ce n'est pas le cas.</para>

      <para>Un &eacute;l&eacute;ment est une partie de la structure d'un document. Un
        &eacute;l&eacute;ment a un d&eacute;but et une fin. Les marques d&eacute;finissent o&ugrave; commence et
        o&ugrave; finit le document.</para>

      <para>Quand le pr&eacute;sent document (ou quelqu'un d'autre qui connait le
        SGML) parle de la marque &ldquo;the &lt;p&gt; tag&rdquo;, cela se
        rapporte au texte compos&eacute; des trois caract&egrave;res
        <literal>&lt;</literal>, <literal>p</literal>
        et <literal>&gt;</literal>. Mais la phrase &ldquo;l'&eacute;l&eacute;ment
        &lt;p&gt;&rdquo; d&eacute;signe tout l'&eacute;l&eacute;ment.</para>

      <para>Cette distinction <emphasis>est</emphasis> tr&egrave;s subtile. Mais
        gardez la &agrave; l'esprit.</para>
    </important>
      
    <para>Les &eacute;l&eacute;ments peuvent avoir des attributs. Un attribut a un nom et
      une valeur, et sert &agrave; donner des informations suppl&eacute;mentaires
      concernant l'&eacute;l&eacute;ment. Ce peuvent &ecirc;tre des informations qui pr&eacute;cisent
      comment l'&eacute;l&eacute;ment doit &ecirc;tre format&eacute;, ou un identifiant unique pour cette
      occurrence de l'&eacute;l&eacute;ment, ou autre chose encore.</para>

    <para>Les attributs d'un &eacute;l&eacute;ment sont donn&eacute;s <emphasis>dans</emphasis> la
      marque de d&eacute;but de l'&eacute;l&eacute;ment et ont la forme
      <literal><replaceable>nom-de-l'attribut</replaceable>="<replaceable>valeur-de-l'attribut</replaceable>"</literal>.</para>

    <para>Dans les versions r&eacute;centes d'HTML, l'&eacute;l&eacute;ment <sgmltag>p</sgmltag> a
      un attribut appel&eacute; <literal>align</literal>, qui sugg&egrave;re un alignement
      (justification) du paragraphe au programme affichant l'HTML.</para>

    <para>L'attribut <literal>align</literal> peut prendre l'une des quatre
      valeurs pr&eacute;d&eacute;finies, <literal>left</literal>, <literal>center</literal>,
      <literal>right</literal> et <literal>justify</literal>. Si l'attribut
      n'est pas pr&eacute;cise, la valeur par d&eacute;faut est
      <literal>left</literal>.</para>

    <example>
      <title>Utiliser un &eacute;l&eacute;ment avec un attribut</title>
      
      <programlisting>
<![ CDATA [<p align="left">L'attribut align est superflus pour ce paragraphe,
  puisque 'left' est la valeur par d&eacute;faut.</p>

<p align="center">Ce paragraphe sera peut-&ecirc;tre centr&eacute;.</p>]]></programlisting>
    </example>
    
    <para>Certains attributs ne prennent que des valeurs pr&eacute;d&eacute;finies, comme
      <literal>left</literal> ou <literal>justify</literal>. D'autres peuvent
      prendre les valeurs que vous voulez. Si vous avez besoin de quotes
      (<literal>"</literal>) dans un attribut, mettez la valeur de l'attribut
      entre simples quotes.</para>

    <example>
      <title>Simples quotes dans un attribut</title>
      
      <programlisting>
<![ CDATA [<p align='right'>Je suis &agrave; droite&nbsp;!</p>]]></programlisting>
    </example>

    <para>Vous n'avez pas toujours besoin de mettre la valeur de l'attribut
      entre simples quotes. Les r&eacute;gles &agrave; ce sujet sont cependant subtiles, et
      il est beaucoup plus simple de <emphasis>toujours</emphasis> mettre
      entre simples quotes les valeurs des attributs.</para>

    <sect2>
      <title>A faire&hellip;</title>

      <para>Pour tester les exemples donn&eacute;s dans ce document, vous devrez
        installer des logiciels sur votre syst&egrave;me et v&eacute;rifiez qu'une variable
        d'environnement est correctement d&eacute;finie.</para>
    
      <procedure>
	<step>
	  <para>T&eacute;l&eacute;chargez et installez <filename>textproc/docproj</filename>
            du catalogue des logiciels port&eacute;s de FreeBSD. C'est un
            <emphasis>m&eacute;ta-port</emphasis> qui doit t&eacute;l&eacute;charger et installer
            tous les programmes et fichiers utilis&eacute;s par le Projet de
            Documentation.</para>
	</step>
	
        <step>
          <para>Ajoutez les lignes pour d&eacute;finir
            <envar>SGML_CATALOG_FILES</envar> &agrave; vos proc&eacute;dures
            d'initialisation de l'interpr&eacute;teur de commandes.</para>
    
	  <example id="sgml-primer-envars">
	    <title><filename>.profile</filename>, pour les utilisateurs de
              &man.sh.1; et &man.bash.1;</title>
	    
	    <programlisting>
SGML_ROOT=/usr/local/share/sgml	    
SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES
export SGML_CATALOG_FILES</programlisting>
	  </example>

	  <example>
	    <title><filename>.login</filename>, pour les utilisateurs de
              &man.csh.1; et &man.tcsh.1;</title>
	    
	    <programlisting>
setenv SGML_ROOT /usr/local/share/sgml
setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES</programlisting>
          </example>
    
          <para>D&eacute;connectez-vous et reconnectez-vous ensuite, ou ex&eacute;cutez ces
            commandes pour d&eacute;finir la variable d'environnement.</para>
	</step>
    
	<step>
	  <para>Cr&eacute;ez un fichier <filename>exemple.sgml</filename>, o&ugrave; vous
            mettrez&nbsp;:</para>

	  <programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0
  Transitional//EN">

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

  <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-&ecirc;tre justifi&eacute; &agrave;
      droite.</p>
  </body>	    
</html>]]></programlisting>
	</step>

	<step>
	  <para>Essayez de le valider avec un analyseur syntaxique
            SGML.</para>

	  <para><link linkend="sgml-primer-validating">L'analyseur
              syntaxique</link> &man.nsgmls.1; fait partie de
            <filename>textproc/docproj</filename>. &man.nsgmls.1; lit
            normalement un document marqu&eacute; en utilisant une DTD SGML et g&eacute;n&egrave;re
            l'<foreignphrase>Element Structure Information Set
            (ESIS)</foreignphrase>&nbsp;-&nbsp;Informations sur la
            Structuration  en El&eacute;ments&nbsp;-&nbsp;mais cela ne nous concerne
            pas pour le moment.</para>

	  <para>N&eacute;anmoins, avec le param&egrave;tre <option>-s</option>,
            &man.nsgmls.1; ne g&eacute;n&egrave;re rien mais affiche simplement les messages
            d'erreurs &eacute;ventuels. C'est utile pour v&eacute;rifier si votre document
            est correct ou non.</para>

	  <para>Utilisez &man.nsgmls.1; pour v&eacute;rifier si votre document est
	    valide&nbsp;:</para>

          <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput></screen>

	  <para>Vous constaterez que &man.nsgmls.1; n'affiche rien. Cela
            signifie qu'il a valid&eacute; votre document.</para>
	</step>

	<step>
	  <para>Voyez ce qui ce passe si vous oubliez un &eacute;l&eacute;ment requis.
	    Supprimez les marques <sgmltag>title</sgmltag> et
	    <sgmltag>/title</sgmltag> et relancer la validation.</para>

          <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput>
nsgmls:example.sgml:5:4:E: character data is not allowed here
nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>

	  <para>Les messages d'erreur de &man.nsgmls.1; sont structur&eacute;s en
            colonnes s&eacute;par&eacute;s par des deux-points ou des
            points-virgules.</para>

	  <informaltable frame="none">
	    <tgroup cols="2">
	      <thead>
		<row>
		  <entry>Colonne</entry>
		  <entry>Signification</entry>
		</row>
	      </thead>
	      
	      <tbody>
		<row>
		  <entry>1</entry>
		  <entry>Nom du programme qui a g&eacute;n&eacute;r&eacute; l'erreur. Ce sera
                    toujours <literal>nsgmls</literal>.</entry>
		</row>

		<row>
		  <entry>2</entry>
		  <entry>Nom du fichier o&ugrave; se trouve l'erreur.</entry>
		</row>

		<row>
		  <entry>3</entry>
		  <entry>Num&eacute;ro de la ligne o&ugrave; se trouve l'erreur.</entry>
		</row>

		<row>
		  <entry>4</entry>
		  <entry>Num&eacute;ro de la colonne o&ugrave; se trouve l'erreur.</entry>
		</row>

		<row>
		  <entry>5</entry>
		  <entry>Une lettre donnant le type de message d'erreur.
		    <literal>I</literal> pour un message d'information,
                    <literal>W</literal> pour un message d'avertissement,
		    <literal>E</literal> pour un message d'erreur et
                    <literal>X</literal> pour les r&eacute;f&eacute;rences crois&eacute;es. (Ce
                    n'est cependant pas toujours la cinqui&egrave;me colonne.
                    <command>nsgmls -sv</command> affiche
                    <literal>nsgmls:I: SP version
                    "1.3"</literal>&nbsp;-&nbsp;selon la version install&eacute;e.
                    Comme vous pouvez le constater, c'est un message
                    d'information.) Vous voyez donc que nous avons dans notre
                    exemple des messages d'erreurs.</entry>
		</row>

		<row>
		  <entry>6</entry>
		  <entry>Le texte du message d'erreur.</entry>
		</row>
	      </tbody>
	    </tgroup>
	  </informaltable>

          <para><ulink
              url="http://www.cs.duke.edu/~dsb/kgv-faq/errors.html">Vous
              aurez plus d'informations sur les erreurs de
              &man.nsgmls.1;</ulink> dans la <ulink
              url="http://www.cs.duke.edu/~dsb/kgv-faq/">Unofficial 'Kindler,
              Gentler HTML Validator' FAQ</ulink>.</para>

	  <para>Ne pas mettre les marques <sgmltag>title</sgmltag> a g&eacute;n&eacute;r&eacute;
	    2 erreurs diff&eacute;rentes.</para>

	  <para>La premi&egrave;re erreur indique que l'analyseur SGML a rencontr&eacute; un
            contenu (ici, des caract&egrave;res, au lieu d'une marque de d&eacute;but
            d'&eacute;l&eacute;ment) alors qu'il attendait autre chose. Dans le cas pr&eacute;sent,
            l'analyseur attendait une marque de d&eacute;but pour un &eacute;l&eacute;ment valide
            &agrave; l'int&eacute;rieur de <sgmltag>head</sgmltag>
            (<sgmltag>title</sgmltag> par exemple).</para>

	  <para>La deuxi&egrave;me erreur est due au fait que les &eacute;l&eacute;ments
            <sgmltag>head</sgmltag> doivent contenir un &eacute;l&eacute;ment
	    <sgmltag>title</sgmltag>. &man.nsgmls.1; consid&egrave;re alors que
            l'&eacute;l&eacute;ment n'est pas complet. La marque de fin indique donc que
            l'&eacute;l&eacute;ment se termine alors qu'il n'est pas correctement
            renseign&eacute;.</para>
	</step>

	<step>
	  <para>Remettez l'&eacute;l&eacute;ment <literal>title</literal> en place.</para>
	</step>
      </procedure>
    </sect2>
  </sect1>

  <sect1 id="sgml-primer-doctype-declaration">
    <title>La d&eacute;claration DOCTYPE</title>

    <para>Au d&eacute;but de chaque document que vous r&eacute;digez, vous devez pr&eacute;ciser le
      nom de la DTD &agrave; laquelle le document se conforme. Cela pour que les
      analyseurs syntaxiques SGML la connaissent et puissent valider le
      document.</para>

    <para>Cette information est habituellement donn&eacute;e sur une seule ligne,
      dans la d&eacute;claration DOCTYPE.</para>

    <para>Voici une d&eacute;claration typique pour un document conforme &agrave; la version
      4.0 de la DTD HTML&nbsp;:</para>

    <programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting>

    <para>Cette ligne a plusieurs composants distincts&nbsp;:</para>

    <variablelist>
      <varlistentry>
	<term><literal>&lt;!</literal></term>
	
	<listitem>
	  <para>C'est l'<emphasis>indicateur</emphasis> qui dit que c'est une
            d&eacute;claration SGML. Cette ligne d&eacute;finit le type de document.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>DOCTYPE</literal></term>
	
	<listitem>
	  <para>Pr&eacute;cise que c'est la d&eacute;claration SGML du type de
            document.</para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
	<term><literal>html</literal></term>
	
	<listitem>
	  <para>D&eacute;finit le premier <link 
              linkend="sgml-primer-elements">&eacute;l&eacute;ment</link> qui appara&icirc;tra
            dans le document.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>PUBLIC "-//W3C//DTD HTML 4.0//EN"</literal></term>

	<listitem>
	  <para>Donne le <foreignphrase>Formal Public Identifier
            (FPI)</foreignphrase>&nbsp;-&nbsp;Identifiant Public
            Officiel&nbsp;-&nbsp;de la DTD &agrave; laquelle le document se
            conforme.</para>

	  <para><literal>PUBLIC</literal> n'appartient pas au FPI, mais
            indique au processeur SGML comment trouver la DTD r&eacute;f&eacute;renc&eacute;e par
            le FPI. Les autres fa&ccedil;ons de dire &agrave; l'analyseur SGML comment
            trouver la DTD sont donn&eacute;es <link
	      linkend="sgml-primer-fpi-alternatives">plus loin</link>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>&gt;</literal></term>
	
	<listitem>
	  <para>Retour au document.</para>
	</listitem>
      </varlistentry>
    </variablelist>
    
    <sect2>
      <title><foreignphrase>Formal Public Identifiers
        (FPIs)</foreignphrase>&nbsp;-&nbsp;Identifiants Publics
        Officiels</title>

      <note>
	<para>Vous n'avez pas besoin de conna&icirc;tre ce qui suit, mais ce n'est
          n'est pas inutile, et cela peut vous aider &agrave; r&eacute;soudre des probl&egrave;mes,
          si votre processeur SGML ne trouve pas la DTD que vous
          utilisez.</para>
      </note>
      
      <para>Les FPIs doivent respecter une syntaxe pr&eacute;cise. La 
        voici&nbsp;:</para>

      <programlisting>
"<replaceable>Propri&eacute;taire</replaceable>//<replaceable>Mot-Cl&eacute;</replaceable> <replaceable>Description</replaceable>//<replaceable>Langue</replaceable>"</programlisting>

      <variablelist>
	<varlistentry>
	  <term><replaceable>Propri&eacute;taire</replaceable></term>
	  
	  <listitem>
	    <para>Indique qui d&eacute;tient le FPI.</para>

	    <para>Si la cha&icirc;ne de caract&egrave;res commence par &ldquo;ISO&rdquo;,
              c'est un FPI ISO. Par exemple, le FPI <literal>"ISO
		8879:1986//ENTITIES Greek Symbols//EN"</literal> donne
	      <literal>ISO 8879:1986</literal> comme propri&eacute;taire du jeu
              d'entit&eacute;s pour les lettres grecques. ISO 8879:1986 est le
              num&eacute;ro ISO du standard SGML.</para>

	    <para>Sinon, cette cha&icirc;ne sera de la forme
	      <literal>-//<replaceable>Propri&eacute;taire</replaceable></literal> ou
	      <literal>+//<replaceable>Propri&eacute;taire</replaceable></literal> 
              (remarquez que la seule diff&eacute;rence est le <literal>+</literal>
	      ou <literal>-</literal> du d&eacute;but).</para>

	    <para>Si la cha&icirc;ne commence par un <literal>-</literal>, c'est que
              le propri&eacute;taire n'est pas enregistr&eacute;, il l'est si elle commence
              par un <literal>+</literal>.</para>

	    <para>L'ISO 9070:1991 d&eacute;finit comment sont g&eacute;n&eacute;r&eacute;s les noms 
              enregistr&eacute;s&nbsp;; ils peuvent d&eacute;river du num&eacute;ro d'une
              publication ISO, d'un code ISBN ou d'un code d'organisation
              affect&eacute; selon l'ISO 6523. De plus, il pourrait y avoir une
              autorit&eacute; d'enregistrement pour l'affectation de ces noms. Le
              conseil ISO a d&eacute;l&eacute;gu&eacute; cela &agrave; l'<foreignphrase>American National
              Standards Institute (ANSI)</foreignphrase>&nbsp;-&nbsp;Institut
              National Am&eacute;ricain des Standards.</para>

	    <para>Comme le Projet FreeBSD n'est pas enregistr&eacute;, la cha&icirc;ne
	      utilis&eacute;e est <literal>-//FreeBSD</literal>. Comme vous pouvez 
              vous en rendre compte, le W3C n'est pas non plus un propri&eacute;taire
	      enregistr&eacute;.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><replaceable>Mot-Cl&eacute;</replaceable></term>
	  
	  <listitem>
	    <para>Il y a plusieurs mots-cl&eacute;s qui d&eacute;finissent le type
              d'information dans le fichier. Les mots-cl&eacute;s les plus courants
              sont&nbsp;: <literal>DTD</literal>, <literal>ELEMENT</literal>,
	      <literal>ENTITIES</literal> et <literal>TEXT</literal>.
	      <literal>DTD</literal> ne sert que pour les DTD,
	      <literal>ELEMENT</literal> sert habituellement pour les extraits
              de DTD qui ne contiennent que des entit&eacute;s ou des d&eacute;clarations
              d'&eacute;l&eacute;ments. <literal>TEXT</literal> sert pour le contenu SGML
              (texte et marques).</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><replaceable>Description</replaceable></term>
	  
	  <listitem>
	    <para>La description que vous souhaitez donner du contenu du
              fichier. Cela peut inclure des num&eacute;ros de version et n'importe
              quel texte court qui ait un sens et soit unique au syst&egrave;me
              SGML.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><replaceable>Langue</replaceable></term>
	  
	  <listitem>
	    <para>C'est une code ISO de deux caract&egrave;res qui identifie la
              langue utilis&eacute;e dans le fichier. Pour l'anglais, c'est 
              <literal>EN</literal>.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
      
      <sect3>
	<title>Fichiers <filename>catalog</filename></title>
	
	<para>Si vous avez utilis&eacute; la syntaxe d&eacute;crite plus haut et essay&eacute;
          d'utiliser un processeur SGML pour traiter votre document, il aura
          besoin de convertir le FPI en un nom de fichier sur votre ordinateur
          qui d&eacute;crive la DTD.</para>
	
        <para>Vous pouvez pour cela vous servir d'un fichier catalogue 
	  (habituellement appel&eacute; <filename>catalog</filename>). Il contient
          des lignes qui donnent les correspondances entre FPIs et noms de
          fichiers. Par exemple, s'il y a la ligne&nbsp;:</para>
	
	<programlisting>
PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>

	<para>le processeur SGML cherchera la DTD dans le fichier
	  <filename>strict.dtd</filename> du sous-r&eacute;pertoire
          <filename>4.0</filename> o&ugrave; se trouve le fichier
	  <filename>catalog</filename> qui comporte cette ligne.</para>

	<para>Jettez un oeil au fichier
	  <filename>/usr/local/share/sgml/html/catalog</filename>. C'est le
          fichier catalogue pour les DTDs HTML qui ont &eacute;t&eacute; install&eacute;es par le
	  logiciel port&eacute; <filename>textproc/docproj</filename>.</para>
      </sect3>

      <sect3>
	<title><envar>SGML_CATALOG_FILES</envar></title>

	<para>Pour trouver un fichier <filename>catalog</filename>, votre
          processeur SGML doit savoir o&ugrave; chercher. La plupart d'entre eux ont
          des param&egrave;tres de leur ligne de commande pour donner le chemin
          d'acc&egrave;s &agrave; un ou plusieurs catalogues.</para>

	<para>Vous pouvez par ailleurs d&eacute;finir 
          <envar>SGML_CATALOG_FILES</envar> pour d&eacute;signer ces fichiers. Cette
          variable d'environnement doit contenir une liste de fichiers
          catalogues (donn&eacute;s par leurs chemins d'acc&egrave;s complets) s&eacute;par&eacute;s par
          des points-virgules.</para>

	<para>Habituellement, vous incluerez les fichiers
          suivants&nbsp;:</para>

	<itemizedlist>
	  <listitem>
	    <para><filename>/usr/local/share/sgml/docbook/catalog</filename></para>
	  </listitem>

	  <listitem>
	    <para><filename>/usr/local/share/sgml/html/catalog</filename></para>
	  </listitem>

	  <listitem>
	    <para><filename>/usr/local/share/sgml/iso8879/catalog</filename></para>
	  </listitem>

	  <listitem>
	    <para><filename>/usr/local/share/sgml/jade/catalog</filename></para>
	  </listitem>
	</itemizedlist>

<!--
	<para>Vous devriez <link linkend="sgml-primer-envars">d&eacute;j&agrave; l'avoir
	    fait</link>.</para>
-->
      </sect3>
    </sect2>
    
    <sect2 id="sgml-primer-fpi-alternatives">
      <title>Alternatives aux FPIs</title>
      
      <para>Au lieu d'utiliser un FPI pour pr&eacute;ciser la DTD utilis&eacute;e (et donc
        le fichier qui contient la DTD), il est possible de donner
        explicitement le nom du fichier.</para>
      
      <para>La syntaxe pour le faire est l&eacute;g&egrave;rement diff&eacute;rente&nbsp;:</para>
      
      <programlisting>
<![ CDATA [<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting>
      
      <para>Le mot-cl&eacute; <literal>SYSTEM</literal> indique que le processeur
        SGML doit localiser le fichier d'une fa&ccedil;on qui d&eacute;pend du syst&egrave;me. Cela
        signifie habituellement (mais pas toujours) que la DTD sera d&eacute;finie
        par un nom de fichier.</para>
      
      <para>Il est pr&eacute;f&eacute;rable d'utiliser des FPIs pour des raisons de
        portabilit&eacute;. Vous ne voulez pas livrer un exemplaire de la DTD avec
        votre document, et si vous avez utilis&eacute; l'identifiant
        <literal>SYSTEM</literal>, il faudra que chacun ait ses DTDs aux m&ecirc;mes
	endroits.</para>
    </sect2>
  </sect1>
  
  <sect1 id="sgml-primer-sgml-escape">
    <title>Revenir au SGML</title>

    <para>On a dit plus haut dans cette introduction que le SGML n'&eacute;tait 
      utilis&eacute; que pour &eacute;crire les DTDs. Ce n'est pas tout &agrave; fait vrai. Il y a
      des &eacute;l&eacute;ments de la syntaxe SGML que vous voudrez pouvoir utiliser dans 
      vos documents. Par exemple, vous pouvez y inclure des commentaires, qui
      seront ignor&eacute;s par les analyseurs. Les commentaires sont inclus en
      utilisant une syntaxe SGML. D'autres utilisations du SGML dans les
      documents seront mentionn&eacute;es plus loin.</para>
      
    <para>Il vous faut &eacute;videmment un moyen d'indiquer au processeur SGML que
      ce qui va suivre n'est pas constitu&eacute; d'&eacute;l&eacute;ments du document, mais est du
      SGML que le processeur doit prendre en compte.</para>

    <para>Ces sections sont marqu&eacute;s avec <literal>&lt;! ...  &gt;</literal> 
      dans votre document. Tout ce qui se trouve entre ces d&eacute;limiteurs est du
      code SGML comme on en trouve dans les DTDs.</para>

    <para>Comme vous venez peut-&ecirc;tre de vous en rendre compte, la <link
	linkend="sgml-primer-doctype-declaration">d&eacute;claration DOCTYPE</link>
      est un exemple de syntaxe SGML que vous devez inclure dans votre
      document&hellip;</para>
  </sect1>
  
  <sect1>
    <title>Commentaires</title>
    &sgml.todo;
    
    <para>Les commentaires suivent une syntaxe SGML et ne sont normalement
      autoris&eacute;s que dans une DTD. Cependant comme la
      <xref linkend="sgml-primer-sgml-escape"> le montre, il est possible
      d'inclure du SGML dans vos documents.</para>

    <para>Les d&eacute;limiteurs pour les commentaires SGML sont constitu&eacute;s de la
      cha&icirc;ne de caract&egrave;res &ldquo;<literal>--</literal>&rdquo;. Une premi&egrave;re
      occurence ouvre le commentaire, et la seconde le ferme.</para>

    <example>
      <title>Commentaire SGML g&eacute;n&eacute;rique</title>

      <programlisting>
<!-- commentaire de test --></programlisting>
      
      <programlisting><![ CDATA [
<!-- C'est le texte du commentaire -->

<!-- C'est un autre commentaire -->

<!-- Voici une fa&ccedil;on de mettre un commentaire
     sur plusieurs lignes -->

<!-- Voici une autre fa&ccedil;on --
  -- de le faire -->]]></programlisting>
    </example>

    <![ %output.print; [
    <important>
      <title>Utilisez 2 tirets</title>

      <para>Vous aurez un probl&egrave;me avec les versions PostScript et PDF de ce
        document. Les exemples pr&eacute;c&eacute;dents n'auront probablement qu'un simple
        tiret, <literal>-</literal> apr&egrave;s <literal>&lt;!</literal> et avant
	<literal>&gt;</literal>.</para>

      <para>Il <emphasis>faut</emphasis> utiliser deux <literal>-</literal>,
        et <emphasis>non</emphasis> un seul. Les versions PostScript et PDF
        ont converti les deux <literal>-</literal> de l'original en un seul
	<emphasis>double tiret</emphasis> plus professionnel, et d&eacute;form&eacute;
        l'exemple au passage.</para>

      <para>Les versions HTML, texte et RTF de ce document ne sont pas 
	sujettes &agrave; ce probl&egrave;me.</para>
    </important>
    ]]>
    
    <para>Si vous avez d&eacute;j&agrave; utilis&eacute; HTML auparavant, on vous a peut-&ecirc;tre
      donn&eacute; des r&egrave;gles diff&eacute;rentes pour les commentaires. En particulier, vous
      pensez peut-&ecirc;tre qu'ils commencent par <literal>&lt;!--</literal> et 
      ne se terminent qu'avec <literal>--&gt;</literal>.</para>

    <para>Ce n'est <emphasis>pas</emphasis> le cas. Les analyseurs syntaxiques
      de nombreux navigateurs sont d&eacute;fectueux et acceptent cette syntaxe. Ceux
      qu'utilisent le Projet de Documentation sont plus rigoureux et
      rejetteront les documents qui comportent cette erreur.</para>

    <example>
      <title>Commentaires SGML erronn&eacute;s</title>

      <programlisting><![ CDATA [
<!-- C'est en commentaire --

     CE N'EST PAS EN COMMENTAIRE!

  -- retour au commentaire -->]]></programlisting>

      <para>L'analyseur SGML traitera cela comme s'il trouvait&nbsp;:</para>

      <programlisting>
&lt;!CE N'EST PAS EN COMMENTAIRE&gt;</programlisting>

      <para>Ce qui n'est pas du SGML valide et donnera des messages d'erreur
        source de confusion.</para>

      <programlisting>
<![ CDATA [<!--------------- C'est un tr&egrave;s mauvaise id&eacute;e --------------->]]></programlisting>

      <para>Comme l'exemple le sugg&egrave;re, ne mettez <emphasis>pas</emphasis> de
        commentaires de ce type.</para>

      <programlisting>
<![ CDATA [<!--===================================================-->]]></programlisting>

      <para>C'est une (l&eacute;g&egrave;rement) meilleure id&eacute;e, mais c'est toute de m&ecirc;me
        une source de confusion potentielle pour les d&eacute;butants en SGML.</para>
    </example>

    <sect2>
      <title>A faire&hellip;</title>

      <procedure>
	<step>
	  <para>Ajoutez des commentaires &agrave; <filename>exemple.sgml</filename>
            et validez vos modifications avec &man.nsgmls.1;</para>
	</step>

	<step>
	  <para>Ajoutez des commentaires incorrects &agrave;
	    <filename>exemple.sgml</filename>, pour voir quels messages
            d'erreur produit alors &man.nsgmls.1;.</para>
	</step>
      </procedure>
    </sect2>
  </sect1>

  <sect1>
    <title>Entit&eacute;s</title>

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

    <para>C'est un bon moyen pour avoir du texte r&eacute;utilisable et facile &agrave;
      modifier. C'est aussi le seul moyen d'inclure, en utilisant SGML, un
      fichier marqu&eacute; dans un autre.</para>
       
    <para>Il y a deux sortes d'entit&eacute;s SGML qui s'utilisent dans des
      situations diff&eacute;rentes&nbsp;: les <emphasis>entit&eacute;s g&eacute;n&eacute;rales</emphasis>
      et les <emphasis>entit&eacute;s param&egrave;tres</emphasis>.</para>
    
    <sect2 id="sgml-primer-general-entities">
      <title>Entit&eacute;s G&eacute;n&eacute;rales</title>
      
      <para>Vous ne pouvez pas employer les entit&eacute;s g&eacute;n&eacute;rales dans un contexte
        SGML (bien que ce soit l&agrave; que vous les d&eacute;finissiez). Elles ne peuvent
        &ecirc;tre utilis&eacute;es que dans votre document. Comparez cela au cas des
	<link linkend="sgml-primer-parameter-entities">entit&eacute;s
	  param&egrave;tres</link>.</para>

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

      <programlisting>
<![ CDATA [<para>La version courante de notre produit est la
  &version.courante;.</para>]]></programlisting>

      <para>Quand le num&eacute;ro de version change, il vous suffit de modifier la
        d&eacute;finition de l'entit&eacute; g&eacute;n&eacute;rale et de recompiler votre
        document.</para>

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

      <para>Heureusement, il y a deux entit&eacute;s g&eacute;n&eacute;rales, &amp;lt; et
	&amp;amp; pour le cas o&ugrave; vous auriez besoin d'inclure l'un ou l'autre
        de ces symboles.</para>
	
      <para>Une entit&eacute; g&eacute;n&eacute;rale ne peut &ecirc;tre d&eacute;finie que dans un contexte
        SGML. On le fait habituellement imm&eacute;diatement apr&egrave;s la d&eacute;claration
        DOCTYPE.</para>

      <example>
	<title>D&eacute;finition d'entit&eacute;s g&eacute;n&eacute;rales</title>

	<programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY version.courante    "3.0-RELEASE">
<!ENTITY derniere.version  "2.2.7-RELEASE">
]>]]></programlisting>
	  
	<para>Remarquez que la d&eacute;claration DOCTYPE est suivie d'un crochet
          ouvrant &agrave; la fin de la premi&egrave;re ligne. Les deux entit&eacute;s sont 
          d&eacute;finies aux deux lignes suivantes, avant le crochet fermant. La
          d&eacute;claration DOCTYPE se termine ensuite.</para>

	<para>Les crochets sont n&eacute;cessaires pour dire que nous ajoutons un
          compl&eacute;ment &agrave; la DTD mentionn&eacute;e par la d&eacute;claration DOCTYPE.</para>
      </example>
    </sect2>
    
    <sect2 id="sgml-primer-parameter-entities">
      <title>Entit&eacute;s param&egrave;tres</title>

      <para>Comme les <link linkend="sgml-primer-general-entities">entit&eacute;s
	  g&eacute;n&eacute;rales</link>, les entit&eacute;s param&egrave;tres servent &agrave; nommer des
        parties r&eacute;utilisables du texte. Cependant, alors que les entit&eacute;s
        g&eacute;n&eacute;rales peuvent &ecirc;tre utilis&eacute;es dans le corps du document, les
        entit&eacute;s param&egrave;tres ne peuvent &ecirc;tre employ&eacute;es que dans un
	<link linkend="sgml-primer-sgml-escape">contexte SGML</link>.</para>

      <para>Les entit&eacute;s param&egrave;tres sont d&eacute;finies de la m&ecirc;me mani&egrave;re que les
        entit&eacute;s g&eacute;n&eacute;rales. Sinon qu'au lieu de vous servir de
        <literal>&amp;<replaceable>inomd-de-l'entit&eacute;</replaceable>;</literal>
        pour y faire r&eacute;f&eacute;rence, vous utiliserez
	<literal>%<replaceable>nom-de-l'entit&eacute;</replaceable>;</literal><footnote>
	  <para>Les entit&eacute;s <emphasis>P</emphasis>aram&egrave;tres employent le
	    symbole <emphasis>P</emphasis>ourcent.</para>
	</footnote>. Leur d&eacute;finition comporte aussi un <literal>%</literal>
        entre le mot-cl&eacute; <literal>ENTITY</literal> et le nom de 
        l'entit&eacute;.</para>
      
      <example>
	<title>D&eacute;finition d'entit&eacute;s param&egrave;tres</title>
	
	<programlisting>
<![ CDATA [<!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" -->
]>]]></programlisting>
      </example>
	
      <para>Cela ne para&icirc;t peut &ecirc;tre pas tr&egrave;s utile. On verra pourtant que &ccedil;a
        l'est.</para>
    </sect2>

    <sect2>
      <title>A faire&hellip;</title>

      <procedure>
	<step>
	  <para>D&eacute;finissez un entit&eacute; g&eacute;n&eacute;rale dans
	    <filename>exemple.sgml</filename>.</para>

	  <programlisting>
<![ CDATA [<!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-&ecirc;tre justifi&eacute; &agrave;
      droite</p>

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

	<step>
	  <para>Validez le document avec &man.nsgmls.1;</para>
	</step>

	<step>
	  <para>Chargez <filename>exemple.sgml</filename> avec votre
            navigateur (vous devrez peut-&ecirc;tre le recopier dans
	    <filename>exemple.html</filename> pour que votre navigateur le
            reconnaisse comme un document HTML).</para>

	  <para>A moins que votre navigateur ne soit tr&egrave;s &eacute;volu&eacute;, il ne 
            remplacera pas la r&eacute;f&eacute;rence <literal>&amp;version;</literal>
            &agrave; l'entit&eacute; par le num&eacute;ro de version. Les analyseurs de la plupart
            des navigateurs sont &eacute;l&eacute;mentaires et ne g&egrave;rent pas correctement
	    le SGML<footnote><para>C'est tout &agrave; fait dommage. Imaginez les 
            probl&egrave;mes et bricolages (comme les <foreignphrase>Server Side
              Includes</foreignphrase>) que cela
            &eacute;viterait.</para></footnote>.</para>
	</step>

	<step>
	  <para>La solution est de <emphasis>normaliser</emphasis> 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&eacute;f&eacute;rences aux entit&eacute;s par leur contenu.</para>

	  <para>Vous pouvez le faire avec &man.sgmlnorm.1;.</para>

          <screen>&prompt.user; <userinput>sgmlnorm exemple.sgml > exemple.html</userinput></screen>

	  <para><filename>exemple.html</filename> doit maintenant contenir une
            version normalis&eacute;e (i.e., o&ugrave; les r&eacute;f&eacute;rences aux entit&eacute;s ont &eacute;t&eacute;
            remplac&eacute;es par leur contenu) de votre document, pr&ecirc;te &agrave; &ecirc;tre
            affich&eacute;e par votre navigateur.</para>
	</step>

	<step>
	  <para>Si vous jetez un oeil au r&eacute;sultat de &man.sgmlnorm.1;, vous
            verrez qu'il ne comporte pas de d&eacute;claration DOCTYPE au d&eacute;but. Pour
            qu'elle y soit, utilisez l'option
            <option>-d</option>&nbsp;:</para>

          <screen>&prompt.user; <userinput>sgmlnorm -d exemple.sgml > exemple.html</userinput></screen>
	</step>
      </procedure>
    </sect2>
  </sect1>
  
  <sect1>
    <title>Utiliser les entit&eacute;s pour inclure des fichiers</title>
    
    <para>Les entit&eacute;s (<link
	linkend="sgml-primer-general-entities">g&eacute;n&eacute;rales</link> et <link
	linkend="sgml-primer-parameter-entities">param&egrave;tres</link>) sont
      particuli&egrave;rement utiles pour inclure un fichier dans un autre.</para>

    <sect2 id="sgml-primer-include-using-gen-entities">
      <title>Utiliser les entit&eacute;s g&eacute;n&eacute;rales pour inclure des fichiers</title>
      
      <para>Supposons que le contenu d'un livre SGML soit d&eacute;coup&eacute; en fichiers,
        &agrave; raison d'un fichier par chapitre, appel&eacute;s
	<filename>chaptitre1.sgml</filename>,
	<filename>chapitre2.sgml</filename>, et ainsi de suite, et que le
        fichier <filename>livre.sgml</filename> inclue ces chapitres.</para>

      <para>Pour que vos entit&eacute;s aient pour valeur le contenu de ces fichiers,
        vous les d&eacute;clarerez avec le mot-cl&eacute; <literal>SYSTEM</literal>. Cela
        indique &agrave; l'analyseur SGML qu'il doit utiliser le contenu du fichier
        mentionn&eacute; comme valeur de l'entit&eacute;.</para>

      <example>
        <title>Utiliser les entit&eacute;s g&eacute;n&eacute;rales pour inclure des
          fichiers</title>
	
	<programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY chapitre.1 SYSTEM "chapitre1.sgml">
<!ENTITY chapitre.2 SYSTEM "chapitre2.sgml">
<!ENTITY chapitre.3 SYSTEM "chapitre3.sgml">
<!-- Et ainsi de suite -->
]>

<html>
  <!-- Utilisation des entit&eacute;s pour inclure les chapitres -->

  &chapitre.1;
  &chapitre.2;
  &chapitre.3;
</html>]]></programlisting>
      </example>
      
      <warning>
	<para>Quand vous vous servez d'entit&eacute;s g&eacute;n&eacute;rales pour inclure d'autres
          fichiers dans un document, les fichiers inclus
	  (<filename>chapitre1.sgml</filename>,
	  <filename>chapitre2.sgml</filename>, et ainsi de suite)  ne doivent
          <emphasis>pas</emphasis> commencer par une d&eacute;claration DOCTYPE. Ce
          serait une erreur de syntaxe.</para>
      </warning>
    </sect2>
    
    <sect2>
      <title>Utiliser les entit&eacute;s param&egrave;tres pour inclure des fichiers</title>
      
      <para>Rappelez-vous que les entit&eacute;s param&egrave;tres ne peuvent &ecirc;tre utilis&eacute;es
        que dans un contexte SGML. Quand aurez-vous besoin d'inclure un
        fichier dans un contexte SGML&nbsp;?</para>

      <para>Vous pouvez vous en servir pour &ecirc;tre s&ucirc;r de pouvoir r&eacute;utiliser vos
        entit&eacute;s g&eacute;n&eacute;rales.</para>

      <para>Supposons que votre document comporte de nombreux chapitres, et
        que vous r&eacute;utilisiez ces chapitres dans deux livres diff&eacute;rents, chacun
        organisant ces chapitres de fa&ccedil;on diff&eacute;rente.</para>

      <para>Vous pourriez donner la liste des entit&eacute;s en t&ecirc;te de chaque livre,
        mais cela pourrait rapidement devenit fastidieux &agrave; g&eacute;rer.</para>

      <para>Mettez, au lieu de cela, les d&eacute;finitions des entit&eacute;s g&eacute;n&eacute;rales
        dans un fichier, et utilisez une entit&eacute; param&egrave;tre pour inclure ce
        fichier dans votre document.</para>

      <example>
        <title>Utiliser les entit&eacute;s param&egrave;tres pour inclure des
          fichiers</title>

	<para>Mettez d'abord les d&eacute;finitions de vos entit&eacute;s dans un fichier
          s&eacute;par&eacute;, appel&eacute; <filename>chapitres.ent</filename>. Voici ce qu'il
          contiendra&nbsp;:</para>
	  
	<programlisting>
<![ CDATA [<!ENTITY chapitre.1 SYSTEM "chapitre1.sgml">
<!ENTITY chapitre.2 SYSTEM "chapitre2.sgml">
<!ENTITY chapitre.3 SYSTEM "chapitre3.sgml">]]></programlisting>

	<para>Cr&eacute;ez maintenant une entit&eacute; param&egrave;tre qui fasse r&eacute;f&eacute;rence au
          contenu de ce fichier. Utilisez ensuite cette entit&eacute; pour inclure
          le fichier dans votre document, vous pourrez alors y utiliser les
          entit&eacute;s g&eacute;n&eacute;rales. Ce que vous faites de la m&ecirc;me fa&ccedil;on que
          pr&eacute;c&eacute;demment&nbsp;:</para>

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

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

<html>
  &chapitre.1;
  &chapitre.2;
  &chapitre.3;
</html>]]></programlisting>
      </example>
    </sect2>

    <sect2>
      <title>A faire&hellip;</title>

      <sect3>
	<title>Utiliser les entit&eacute;s g&eacute;n&eacute;rales pour inclure des fichiers</title>

	<procedure>
	  <step>
	    <para>Cr&eacute;ez trois fichiers, <filename>para1.sgml</filename>,
	      <filename>para2.sgml</filename> et
	      <filename>para3.sgml</filename>.</para>

	    <para>Mettez-y quelque chose qui ressemble &agrave; ceci&nbsp;:</para>

	    <programlisting>
<![ CDATA [<p>C'est le premier paragraphe.</p>]]></programlisting>
	  </step>

	  <step>
	    <para>Modifiez <filename>exemple.sgml</filename> de la fa&ccedil;on
              suivante&nbsp;:</para>

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

<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>]]></programlisting>
	  </step>

	  <step>
	    <para>G&eacute;n&eacute;rez <filename>exemple.html</filename> en normalisant
	      <filename>exemple.sgml</filename>.</para>

            <screen>&prompt.user; <userinput>sgmlnorm -d exemple.sgml > exemple.html</userinput></screen>
	  </step>

	  <step>
	    <para>Affichez <filename>exemple.html</filename> avec votre
              navigateur Web et v&eacute;rifiez que les fichiers
	      <filename>para<replaceable>n</replaceable>.sgml</filename> ont
	      bien &eacute;t&eacute; inclus dans <filename>exemple.html</filename>.</para>
	  </step>
	</procedure>
      </sect3>

      <sect3>
       <title>Utiliser les entit&eacute;s param&egrave;tres pour inclure des
         fichiers</title>

	<note>
	  <para>Vous devez d'abord avoir mis en pratique l'exemple
            pr&eacute;c&eacute;dent.</para>
	</note>
	
	<procedure>
	  <step>
            <para>Modifiez comme ceci
              <filename>exemple.sgml</filename>&nbsp;:</para>
	    
	    <programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % entites SYSTEM "entites.sgml"> %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>]]></programlisting>
	  </step>

	  <step>
	    <para>Cr&eacute;ez un nouveau fichier, <filename>entites.sgml</filename>, 
	      qui contienne&nbsp;:</para>

	    <programlisting>
<![ CDATA [<!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.sgml">
<!ENTITY para2 SYSTEM "para2.sgml">
<!ENTITY para3 SYSTEM "para3.sgml">]]></programlisting>
	  </step>

	  <step>
	    <para>G&eacute;n&eacute;rez <filename>exemple.html</filename> en normalisant
	      <filename>exemple.sgml</filename>.</para>

            <screen>&prompt.user; <userinput>sgmlnorm -d exemple.sgml > exemple.html</userinput></screen>
	  </step>

	  <step>
	    <para>Affichez <filename>exemple.html</filename> avec votre
              navigateur Web et v&eacute;rifiez que les fichiers
	      <filename>para<replaceable>n</replaceable>.sgml</filename> ont
	      bien &eacute;t&eacute; inclus dans <filename>example.html</filename>.</para>
	  </step>
	</procedure>
      </sect3>
    </sect2>
  </sect1>
  
  <sect1 id="sgml-primer-marked-sections">
    <title>Sections marqu&eacute;es</title>
    
    <para>SGML fournit un m&eacute;canisme pour d&eacute;finir quelles parties d'un document
      doivent &ecirc;tre trait&eacute;es de fa&ccedil;on particuli&egrave;re. On appelle cela des
      &ldquo;sections marqu&eacute;es&rdquo;.</para>

    <example>
      <title>Structure d'une section marqu&eacute;e</title>

      <programlisting>
&lt;![ <replaceable>MOT-CLE</replaceable> [
  Contenu de la section marqu&eacute;e
]]&gt;</programlisting>
    </example>

    <para>Comme vous pouviez vous y attendre, une section marqu&eacute;e est une
      fonctionnalit&eacute; SGML et commence donc par <literal>&lt!</literal>.</para>

    <para>Le premier crochet ouvrant d&eacute;limite la section marqu&eacute;e.</para>

    <para>Le <replaceable>MOT-CLE</replaceable> d&eacute;finit comment cette section
      marqu&eacute;e doit &ecirc;tre trait&eacute;e par l'analyseur.</para>

    <para>Le second crochet ouvrant indique que le contenu de la section
      marqu&eacute;e commence l&agrave;.</para>
    
    <para>La section marqu&eacute;e se termine par deux crochets fermants, puis un
      <literal>&gt;</literal> pour indiquer que l'on quitte le contexte SGML
      et que l'on revient au document.</para>
    
    <sect2>
      <title>Mots-cl&eacute;s pour les sections marqu&eacute;es</title>
      
      <sect3>
	<title><literal>CDATA</literal>, <literal>RCDATA</literal></title>
	
	<para>Ces deux mots-cl&eacute;s d&eacute;finissent des sections marqu&eacute;es comme
          <emphasis>mod&egrave;le de contenu</emphasis> et vous permettent de
          modifier sa valeur par d&eacute;faut.</para>
	
	<para>Quand un analyseur SGML traite un docuemnt, il m&eacute;morise ce que
          l'on appelle le &ldquo;mod&egrave;le de contenu&rdquo;.</para>
	
	<para>En bref, le mod&egrave;le de contenu d&eacute;crit ce que l'analyseur doit
          s'attendre &agrave; trouver comme contenu, et ce qu'il doit en faire quand
          il le rencontre.</para>

	<para>Les deux mod&egrave;les de contenu que vous trouverez certainement les
          plus utiles sont <literal>CDATA</literal> et
          <literal>RCDATA</literal>.</para>
	
	<para><literal>CDATA</literal> signifie
          &ldquo;<foreignphrase>Character
          Data</foreignphrase>&rdquo;&nbsp;-&nbsp;donn&eacute;es caract&egrave;res. Si
          l'analyseur est &agrave; l'int&eacute;rieur de ce mod&egrave;le de contenu, il s'attend
          &agrave; trouver des caract&egrave;res, et uniquement des caract&egrave;res. Les
          symboles &lt; et &amp; perdent alors leur signification particuli&egrave;re
          et sont trait&eacute;s comme de simples caract&egrave;res.</para>
	
	<para><literal>RCDATA</literal> signifie &ldquo;R&eacute;f&eacute;rences &agrave; des
          entit&eacute;s et donn&eacute;es caract&egrave;res&rdquo;.  Si l'analyseur est &agrave;
          l'int&eacute;rieur de ce mod&egrave;le de contenu, il s'attend &agrave; trouver des
          caract&egrave;res <emphasis>et</emphasis> des entit&eacute;s. &lt; perd sa
          signification particuli&egrave;re, mais &amp; est toujours compris comme le
          d&eacute;but d'une entit&eacute; g&eacute;n&eacute;rale.</para>
	
	<para>C'est particuli&egrave;rement utile si vous incluez du texte qui
          contient de nombreux caract&egrave;res &lt; et &amp;. Vous pourriez bien
          s&ucirc;r contr&ocirc;ler que dans votre texte tous les &lt; sont &eacute;crits
          &amp;lt; et tous les &amp; &amp;amp;, il peut &ecirc;tre plus facile
          de marquer la section comme ne contenant que des
          &ldquo;CDATA&rdquo;. Quand SGML rencontre l'instruction
          correspondante, il ignorera les symboles &lt; et &amp; qui
          appara&icirc;tront dans le contenu.</para>

	<!-- The nesting of CDATA within the next example is disgusting -->
	  
	<example>
	  <title>Utiliser une section marqu&eacute;e CDATA</title>
	  
	  <programlisting>
&lt;para>Voici un exemple de la fa&ccedil;on dont vous pourriez inclure 
  un texte comportant de nombreux &amp;lt; et &amp;amp;. L'exemple
  lui-m&ecirc;me est en HTML. Le texte qui l'encadre (&lt;para> et
  &lt;programlisting>) est du DocBook.&lt;/para>

&lt;programlisting>
  &lt![ CDATA [  <![ 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>]]>
  ]]&gt;
&lt/programlisting></programlisting>

	  <para>Si vous consultez le source de ce document, vous verrez qu'il
            utilise constamment cette technique.</para>
	</example>
      </sect3>
      
      <sect3>
	<title><literal>INCLUDE</literal> et <literal>IGNORE</literal></title>
	
	<para>Si le mot-cl&eacute; est <literal>INCLUDE</literal>, alors le contenu
          de la section marqu&eacute;e sera pris en compte. Si le mot-cl&eacute; est
	  <literal>IGNORE</literal>, alors la section marqu&eacute;e sera ignor&eacute;e. Il
	  n'appara&icirc;tra pas dans les sorties.</para>

	<example>
	  <title>Utiliser <literal>INCLUDE</literal> et
            <literal>IGNORE</literal> dans les sections marqu&eacute;es</title>

	  <programlisting>
&lt;![ INCLUDE [
  Ce texte sera trait&eacute; et inclus.
]]&gt;

&lt;![ IGNORE [
  Ce texte ne sera pas trait&eacute; ou inclus.
]]&gt;</programlisting>
	</example>
	
	<para>En soi, cela ne sert pas &agrave; grand-chose. Si vous vouliez
          supprimer du texte de votre document, vous auriez pu l'enlever ou le
          mettre en commentaires.</para>
	  
	<para>Cela devient plus utile quand vous comprenez que vous pouvez
          vous servir des <link
	    linkend="sgml-primer-parameter-entities">entit&eacute;s param&egrave;tres</link>
          pour contr&ocirc;ler ces sections. Rappelez-vous que les entit&eacute;s
          param&egrave;tres ne peuvent &ecirc;tre utilis&eacute;es que dans un contexte SGML, et
          une section marqu&eacute;e <emphasis>est</emphasis> un contexte SGML.</para>

	<para>Si par exemple, vous g&eacute;n&eacute;rez une version imprim&eacute;e et une version
          &eacute;lectronique de votre document, vous pourriez vouloir inclure dans 
          la version &eacute;lectronique un contenu suppl&eacute;mentaire qui ne devra pas
          appara&icirc;tre dans la version imprim&eacute;e.</para>

	<para>Cr&eacute;ez une entit&eacute; param&egrave;tre et donnez lui comme contenu
	  <literal>INCLUDE</literal>. R&eacute;digez votre document en utilisant des
          sections marqu&eacute;es pour d&eacute;limiter le contenu qui ne doit appara&icirc;tre 
          que dans la version &eacute;lectronique. Dans ces sections marqu&eacute;es,
          servez-vous de l'entit&eacute; param&egrave;tre au lieu du mot-cl&eacute;.</para>

	<para>Lorsque vous voulez g&eacute;n&eacute;rer la version &eacute;lectronique, changez la
          valeur de l'entit&eacute; param&egrave;tre en <literal>IGNORE</literal> et
          retraitez le document.</para>

	<example>
	  <title>Utiliser une entit&eacute; param&egrave;tre pour contr&ocirc;ler une section
	    marqu&eacute;e</title>
	  
	  <programlisting>
&lt;!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
&lt;!ENTITY % version.electronique "INCLUDE">	     
]]&gt;

...

&lt;![ %version.electronique [
  Ce texte ne doit appara&icirc;tre que dans
  la version &eacute;lectronique du document.
]]&gt;</programlisting>

	  <para>Pour g&eacute;n&eacute;rer la version imprim&eacute;e, changez la d&eacute;finition de
            l'entit&eacute; en&nbsp;:</para>
	  
	  <programlisting>
&lt!ENTiTY % version.electronique "IGNORE"></programlisting>

	  <para>A la seconde passe sur le document, les sections marqu&eacute;es qui
            utilisent <literal>%version.electronique</literal> comme mot-cl&eacute;
            seront ignor&eacute;es.</para>
	</example>
      </sect3>
    </sect2>

    <sect2>
      <title>A faire&hellip;</title>

      <procedure>
	<step>
	  <para>Cr&eacute;ez un nouveau fichier, <filename>section.sgml</filename>,
            qui contienne&nbsp;:</para>

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

&lt;html>
  &lt;head>
    &lt;title>Exemple d'utilisation des sections marqu&eacute;es&lt;/title>
  &lt;/head>

  &lt;body>	    
    &lt;p>Ce paragraphe &lt;![ CDATA [contient de nombreux
      caract&egrave;res &lt; (&lt; &lt; &lt; &lt; &lt;) il est donc
      plus facile de l'inclure dans une section marqu&eacute;e
      CDATA ]]&gt;&lt/p>

    &lt;![ IGNORE [
    &lt;p>Ce paragraphe n'appara&icirc;tra jamais dans les
      sorties.&lt;/p>
    ]]&gt;

    &lt;![ <![ CDATA [%sortie.texte]]> [
    &lt;p>Ce paragraphe appara&icirc;tra peut-&ecirc;tre dans les
      sorties.&lt;/p>

    &lt;p>Cela d&eacute;pend de l'entit&eacute; param&egrave;tre
      <![CDATA[%sortie.texte]]>.&lt;/p>	    
    ]]&gt;
  &lt;/body>
&lt;/html></programlisting>	    
	</step>

	<step>
	  <para>Normalisez le fichier avec &man.sgmlnorm.1; et examinez le
            r&eacute;sultat. Notez quels paragraphes ont &eacute;t&eacute; conserv&eacute;s et quels
            paragraphes ont &eacute;t&eacute; supprim&eacute;s, et ce qu'est devenu le contenu des
            sections marqu&eacute;es CDATA.</para>
	</step>

	<step>
	  <para>Modifiez la d&eacute;finition de l'entit&eacute;
            <literal>sortie.texte</literal> de <literal>INCLUDE</literal> en
	    <literal>IGNORE</literal>. Normalisez de nouveau le fichier et
            regardez ce qui a chang&eacute; dans le r&eacute;sultat.</para>
	</step>
      </procedure>
    </sect2>
  </sect1>
  
  <sect1>
    <title>Conclusion</title>
    
    <para>Ici se termine cette introduction &agrave; SGML. Pour des raisons de place
      et de complexit&eacute;, de nombreux points ont &eacute;t&eacute; survol&eacute;s (voire omis).
      Les sections qui pr&eacute;c&eacute;dent d&eacute;crivent n&eacute;anmoins suffisamment d'&eacute;l&eacute;ments
      du SGML pour vous permettre de comprendre comment est organis&eacute;e la
      documentation du FDP.</para>
  </sect1>
</chapter>

<!--
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../book.sgml" "part" "chapter")
     End:
-->
