path: root/de_DE.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml

<?xml version="1.0" encoding="ISO8859-1" standalone="no"?>
<!-- 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.

     $FreeBSD$
     $FreeBSDde$
     basiert auf: r38826
-->

<!--?
o SGML-Kontext sollte besser mit Umgebung uebersetzt werden.

Oliver Fischer

-->

<chapter id="sgml-primer">
  <title>Die SGML-Fibel</title>

  <para>Die Mehrzahl der Dokumente des FDPs sind in SGML geschrieben.
    Ziel dieses Kapitels ist es, genau zu erkl&auml;ren, was
    das bedeutet und wie man die SGML-Quellen liest und versteht.
    Ebenso werden die in den Quellen genutzten Kniffe erkl&auml;rt,
    auf die man beim Lesen der Dokumente sto&szlig;en wird.</para>

  <para>Teile dieses Kapitels basieren auf Mark Galassis <quote><ulink
    url="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get
    Going With DocBook</ulink></quote>.</para>

  <sect1 id="sgml-primer-overview">
    <title>&Uuml;berblick</title>

    <para>In den guten alten Zeiten war der Umgang mit
      <quote>elektronischem</quote> Text einfach. Man musste
      lediglich wissen, welcher Zeichensatz (ASCII, EBCDIC oder ein
      anderer) vorlag. Text war einfach Text und sah so aus, wie man
      ihn sah. Keine Extras, keine Formatierungen und kein sonstiger
      Schnickschnack.</para>

    <para>F&uuml;r viele Zwecke war dies allerdings nicht ausreichend.
      Von einem machinenlesbaren Text wird erwartet, dass er auch von
      Maschinen gelesen und intelligent weiterverarbeitet werden kann.
      Einzelne Stellen sollen hervorgehoben werden, andere sollen in ein
      Glossar aufgenommen werden oder auf andere Textstellen
      verweisen. Dateinamen wiederum sollen in einer
      <quote>schreibmaschinen&auml;hnlichen</quote> Schrift auf dem
      Bildschirm dargestellt werden, der Ausdruck soll jedoch in
      <quote>Schr&auml;gschrift</quote> oder in einer beliebigen anderen
      Darstellungsform erfolgen.</para>

    <para>Anf&auml;nglich gab es die Hoffnung, dass die
      K&uuml;nstliche Intelligenz (KI) helfen w&uuml;rde, dieses Ziel
      zu erreichen. Computer sollte den Text lesen und dazu in der Lage
      sein, selbstst&auml;ndig wichtige Formulierungen, Dateinamen,
      Benutzereingaben oder Beispiele zu erkennen.  Leider verlief die
      Entwicklung in diesem Bereich nicht wie gew&uuml;nscht und Computer
      ben&ouml;tigen nach wie vor etwas Unterst&uuml;tzung, bevor sie
      Texte vern&uuml;nftig verarbeiten k&ouml;nnen.</para>

    <para>Genauer gesagt, man muss ihnen sagen, was was ist. Sehen
      wir uns folgende Zeilen an:</para>

      <blockquote>
	<para>L&ouml;schen Sie <filename>/tmp/foo</filename> mittels &man.rm.1;.</para>

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

    <para>Es f&auml;llt uns leicht, zu erkennen, was ein Dateiname, ein
      einzugebender Befehl oder ein Verweis auf eine Hilfeseite ist. Das
      kann ein Computer, der einen Text verarbeitet, nicht. Aus diesem
      Grund ist es notwendig, Texte mit weiteren Informationen
      <quote>auszuzeichnen</quote>.</para>

    <para>Der Begriff <quote>Auszeichnung<footnote> <para>Im
            angels&auml;chischschen Sprachraum wird von
            <quote>markup</quote>
            gesprochen.</para></footnote></quote> bedeutet, dass
      sich der Wert eines Textes erh&ouml;ht, aber auch seine Kosten.
      Durch Auszeichnungen wird einem Dokument zus&auml;tzlicher Text
      hinzugef&uuml;gt, der aber von dem eigentlichen Dokumenteninhalt
      auf eine bestimmte Art und Weise unterschieden werden kann, so
      dass Programme die Auszeichnung erkennen k&ouml;nnen und
      mittels dieser Informationen w&auml;hrend der Verarbeitung in
      der Lage sind, Entscheidungen zu treffen. Texteditoren
      k&ouml;nnen diese Auszeichnungselemente vor dem Benutzer
      verbergen, um zu vermeiden, dass er durch sie abgelenkt
      wird.</para>

    <!--<para><quote>Markup</quote> is commonly used to describe <quote>adding
    value</quote> or <quote>increasing cost</quote>.  The term takes on both
    these meanings when applied to text.  Markup is additional text included
    in the document, distinguished from the document's content in some way,
    so that programs that process the document can read the markup and use
    it when making decisions about the document.  Editors can hide the
    markup from the user, so the user is not distracted by it.</para>-->


    <para>Die durch die Auszeichnungselemente im Textdokument
      zus&auml;tzlich abgelegten Informationen erh&ouml;hen den Wert
      des Dokuments. Allerdings muss diese Arbeit in den meisten
      F&auml;llen von einem Menschen getan werden &ndash; w&auml;ren
      Maschinen dazu f&auml;hig, w&auml;ren zus&auml;tzliche
      Auszeichnungselemente unn&ouml;tig. Der damit verbundene Aufwand
      <emphasis>erh&ouml;ht die Kosten</emphasis>, die durch die
      Erstellung des Dokuments entstehen.</para>

    <para>Das etwas weiter oben gegebene Beispiel sieht im Quelltext
      so aus:</para>

    <programlisting><![CDATA[
<para>L&ouml;schen Sie <filename>/tmp/foo</filename> mittels &man.rm.1;.</para>

<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>]]></programlisting>

    <para>Die Auszeichnungselemente sind deutlich vom eigentlichen
      Inhalt zu unterscheiden.</para>

    <para>Die Einf&uuml;hrung von Auszeichnungselementen setzt voraus,
      dass festgelegt wird, welche Bedeutung einzelne Elemente haben
      und wie diese interpretiert werden.  Sie brauchen daher eine
      Auszeichnungssprache, der Sie folgen, wenn Sie eigene
      Dokumente verfassen.</para>

    <para>Nat&uuml;rlich kann es keine universelle
      Auszeichnungssprache geben und eine einzige mag nicht
      ausreichend f&uuml;r alle m&ouml;glichen Anwendungsf&auml;lle
      sein. Eine  Sprache f&uuml;r technische Dokumente wird sich
      wahrscheinlich stark von einer f&uuml;r Kochrezepte
      unterscheiden. Die universelle L&ouml;sung ist eine
      Basissprache, mit deren Hilfe weitere Sprachen entwickelt werden
      k&ouml;nnen &ndash; eine
      <emphasis>Meta-Auszeichungssprache</emphasis> also.</para>

    <para>Genau diese Anforderung wird von der Standard Generalized
      Markup Language (<abbrev>SGML</abbrev>) erf&uuml;llt. Mit ihrer
      Hilfe wurden viele andere Auszeichungssprachen wie
      beispielsweise HTML und DocBook, welche beide von FDP genutzt
      werden, entwickelt.</para>

    <para>Die eigentliche Sprachdefinition erfolgt in einer
      Dokumenten-Typ-Definition (DTD). Innerhalb dieser DTD werden die
      Namen der einzelnen Elemente, deren m&ouml;gliche Reihenfolge
      und Verschachtelung sowie weitere Informationen
      festgelegt.</para>

      <!-- Der letzte Satz dieses Absatzes muss noch &uuml;bersetzt werden.
      Ich habe keine gute &Uuml;bersetzung daf&uuml;r bis jetzt
      gefunden. Oliver Fischer -->

      <!--<para>Each language definition is more properly called a Document Type
      Definition (DTD).  The DTD specifies the name of the elements that can
      be used, what order they appear in (and whether some markup can be used
      inside other markup) and related information.  A DTD is sometimes
      referred to as an <emphasis>application</emphasis> of SGML.</para>-->

    <para id="sgml-primer-validating">Eine DTD ist eine
      <emphasis>vollst&auml;ndige</emphasis> Definition aller
      m&ouml;glichen Sprachelemente, ihrer
      Reihenfolge<footnote><para>Bei nat&uuml;rlichen Sprachen spricht
          man vom Satzbau  &ndash; demjenigen Konstrukt, das unter
          anderem die Position des Subjekts, Objekts und
          Pr&auml;dikats in einem Satz festlegt.</para></footnote>,
      optionaler Elemente und so weiter und so weiter. Dank dieser
      recht formalen Festlegung ist es m&ouml;glich,
      SGML-<emphasis>Parser</emphasis> zu entwickeln, die sowohl ein
      Dokument  als auch seine DTD einlesen und anhand dieser DTD
      pr&uuml;fen k&ouml;nnen, ob das Dokument allen Anforderungen der
      DTD entspricht. Dieser Vorgang wird allgemein als
      <emphasis>Validierung des Dokuments</emphasis>
      bezeichnet.</para>

    <note>
      <para>Das Validieren eines SGML-Dokuments gegen eine DTD
        &uuml;berpr&uuml;ft lediglich die korrekte Syntax des
        Dokuments, dass hei&szlig;t, ob nur g&uuml;ltige
        Auszeichnungselemente verwendet wurden und ihre Reihenfolge
        stimmt. Dabei wird <emphasis>nicht</emphasis> gepr&uuml;ft, ob
        die Elemente der DTD <emphasis>sinngem&auml;&szlig;</emphasis>
        verwandt wurden. Sollten beispielsweise alle Dateinamen als
        Funktionsnamen ausgezeichnet worden sein, so w&uuml;rde der
        Parser keinen Fehler signalisieren. Formaler ausgedr&uuml;ckt:
        Der Parser pr&uuml;ft die Syntax, aber nicht die
        Semantik.</para>
      </note>

    <para>Es ist anzunehmen, dass, wenn man selber vor hat
      Dokumentation f&uuml;r das FDP zu schreiben, der
      gr&ouml;&szlig;te Teil davon mit Hilfe von HTML oder DocBook
      geschrieben werden wird. Aus diesem Grunde wird an dieser Stelle
      nicht erkl&auml;rt, wie eine DTD entwickelt wird.</para>
    </sect1>

    <sect1 id="sgml-primer-elements">
    <title>Von Elementen, Tags und Attributen</title>

    <!-- Bei der &Uuml;bersetzung des ersten Satzes bin ich mir nicht
      sicher, ob es einee bessere gibt. Oliver Fischer -->

    <para>Alle in SGML geschriebenen DTDs haben bestimmte gemeinsame
      Eigenschaften. Das ist nicht verwunderlich, da sich die hinter
      SGML stehende Idee unweigerlich bemerkbar macht. <!--?
      Kandidat fuer ein Umformulierung. Oliver Fischer --> Zwei der
      markantesten Merkmale dieser Idee sind die Begriffe
      <emphasis>Inhalt</emphasis> und
      <emphasis>Element</emphasis>.</para>

    <!--<para>All the DTDs written in SGML share certain characteristics.  This is
    hardly surprising, as the philosophy behind SGML will inevitably show
    through. One of the most obvious manifestations of this philosophy is
    that of <emphasis>content</emphasis> and
    <emphasis>elements</emphasis>.</para>-->

    <!--? Vielleicht sollte man nicht von Elementen sondern von Teilen
    sprechen. Oliver Fischer -->

    <!--?
    Hier muss die endlose Rekursion noch besser zum Ausdruck kommen.
    -->
    <para>Von einem Dokument, unabh&auml;ngig, ob es sich um  eine
      einzelne Webseite oder ein langes Buch handelt, wird angenommen,
      dass es einen wie auch immer gearteten Inhalt hat. Dieser
      l&auml;sst sich selbst wiederum in Teilelemente
      aufspalten, die ebenso zerlegbar sind. Durch die Aufnahme von
      Auszeichnungselementen in einen Text, werden diese einzelnen
      Elemente eindeutig benannt und voneinander abgegrenzt.</para>

      <!--<para>Your documentation (whether it is a single web page, or a lengthy
      book) is considered to consist of content.  This content is then divided
      (and further subdivided) into elements.  The purpose of adding markup is
      to name and identify the boundaries of these elements for further
      processing.</para>-->

    <!--? Begriff Element erscheint hier ploetzlich. Sollte
    besser eingefuehrt werden. Oliver Fischer -->

    <para>Nimmt man zum Beispiel ein typisches Buch, so kann man es
      auf der obersten Ebene als ein Ganzes, als ein Element
      betrachten. Dieses <quote>Buch</quote>-Element enth&auml;lt nun
      Kapitel, die wiederum selbst als Elemente bezeichnet werden
      k&ouml;nnen. Jedes einzelne Kapitel enth&auml;lt weitere
      Elemente. So gibt es beispielsweise Abs&auml;tze, Zitate und
      Fu&szlig;noten. Jeder Absatz kann wiederum selbst Elemente
      enthalten, die helfen, den Absatzinhalt als direkte Rede oder
      als Namen eines der Protagonisten einer Geschichte zu
      identifizieren.</para>

    <para>Wenn man m&ouml;chte, kann man sich das als
      <quote>Unterteilung</quote><footnote><para>Im
          angels&auml;chsichen Sprachraum wird hier von
          <quote>chunking</quote> gesprochen.</para></footnote> des
      Inhalts vorstellen. Auf der obersten Ebene gibt es ein Element:
      das Buch selbst. Schaut man ein wenig tiefer, findet man weitere
      Teilelemente: die einzelnen Kapitel. Diese sind wiederum
      unterteilt in Abs&auml;tze, Fu&szlig;noten, Namen und so weiter
      und so weiter.</para>

    <para>Anzumerken ist an dieser Stelle, dass das eben gesagte
      ohne weiteres auf jeden Inhaltstyp angewandt werden kann, auch
      ohne dass von <acronym>SGML</acronym> die Rede ist. Man
      k&ouml;nnte beispielsweise einfach verschiedene Stifte nehmen
      und einen Ausdruck dieser Fibel vor sich hinlegen und dann mit
      verschiedenen Farben die einzelnen Abschnitte des Buchinhalts
      markieren.</para>

    <para>Leider gibt es  keinen elektronischen Stift, um das zu tun.
      Deshalb muss ein anderer Weg gew&auml;hlt werden, um zu
      bestimmen, zu welchem Element die einzelnen Inhalte
      geh&ouml;ren. In SGML-basierten Auszeichnungssprachen wie HTML
      und DocBook  werden daf&uuml;r so genannte
      <emphasis>Tags</emphasis> eingesetzt.</para>

    <para>Mit einem solchen Tag wird eindeutig festgelegt, wo ein
      bestimmtes Element beginnt und wo es endet. <emphasis>Allerdings
        geh&ouml;rt der Tag selber nicht zum Element.</emphasis> Er
      legt lediglich die Grenzen des Elements fest. Da jede DTD mit dem Ziel
      entwickelt wurde, einen speziellen Inhaltstyp auszuzeichnen,
      wird jede DTD verschiedene Elemente kennen, die daher
      nat&uuml;rlich auch unterschiedlich benannt sein werden.</para>

    <para>Der Starttag f&uuml;r ein imagin&auml;res Element mit dem
      Namen <replaceable>elementname</replaceable> ist
      <sgmltag>&lt;<replaceable>elementname</replaceable>&gt;</sgmltag>.
      Sein Gegenst&uuml;ck, der schlie&szlig;ende Endtag, ist
      <sgmltag>&lt;/<replaceable>elementname</replaceable>&gt;</sgmltag>.</para>

    <example>
      <title>Verwendung eines Elements (Start- und Endtag)</title>

      <para>HTML kennt das Element <sgmltag>p</sgmltag>, um
        festzulegen, dass ein bestimmter abgegrenzter Bereich
        einen Absatz darstellt. Dieses Element hat sowohl einen Start-
        als auch einen Endtag.</para>

      <programlisting><![CDATA[<p>Das ist ein Absatz. Er beginnt mit Starttag
  f&uuml;r das Element 'p' und endet mit dem Endtag f&uuml;r
  das Element 'p'.</p>

<p>Das ist ein etwas k&uuml;rzerer Absatz.</p>]]></programlisting>
    </example>

    <para>Elemente m&uuml;ssen nicht notwendigerweise einen Endtag
      haben. Ebenso ist es nicht notwendig, dass Elemente einen
      Inhalt haben. Beispielsweise kann in HTML-Dokumenten mittels
      eines speziellen Elements festgelegt werden, dass eine
      horizontale Linie an einer bestimmten Stelle erscheinen soll. Da
      dieses Element offensichtlich keinen Inhalt hat, wird auch kein
      Endtag ben&ouml;tigt.</para>

    <example>
      <title>Verwendung eines Elements (nur Starttag)</title>

      <para>In HTML kann man mit dem Element <sgmltag>hr</sgmltag>
        festlegen, dass an einer bestimmten Stelle eine
        horizontale Linie angezeigt werden soll. Da dieses Element
        keinen Inhalt umschlie&szlig;t, hat es nur einen
        Starttag.</para>

      <programlisting><![CDATA[<p>Das ist ein Abschnitt.</p>

<hr>

<p>Das ist ein weiterer Absatz. Eine horizontale Linie
  trennt ihn vom vorherigen Absatz.</p>]]></programlisting>
    </example>

    <para>Elemente k&ouml;nnen andere Elemente enthalten.  Im
      anfangs erw&auml;hnten Buch enthielt das Buch-Element
      alle Kapitel-Elemente, die wiederum alle Absatz-Elemente
      enthielten und so fort.</para>

    <example>
      <title>Verschachtelte Elemente: <sgmltag>em</sgmltag></title>

      <programlisting><![CDATA[<p>Das ist ein einfacher <em>Abschnitt</em>, in dem
  einige <em>Worte</em> <em>hervorgehoben</em> wurden.]]></programlisting>
    </example>

    <para>Welche Elemente andere Elemente enthalten k&ouml;nnen und
      welche das sind, wird innerhalb der DTD eines Dokuments
      festgelegt.</para>

    <!--
    <para>The DTD will specify the rules detailing which elements can contain
    other elements, and exactly what they can contain.</para>
    -->

    <important>
      <para>Viele Leute sind oft verwirrt, wenn es um die richtige
        Benutzung der Begriffe Tag und Element geht. Im Ergebnis werden
        sie oft so genutzt, als w&auml;ren sie austauschbar.
        Allerdings sind sie das nicht.</para>

      <para>Ein Element ist ein konzeptioneller Teil eines Dokuments
        und hat einen festgelegten Anfang und ein festgelegtes
	Ende. Ein Tag hingegen markiert die Stelle, an der ein Element
	beginnt und endet.</para>

      <para>Wenn in diesem Dokument vom <quote>Tag <sgmltag>p</sgmltag></quote>
        gesprochen wird, ist damit der Text
        gemeint, der aus den drei Zeichen <literal>&lt;</literal>,
        <literal>p</literal> und <literal>&gt;</literal> besteht. Wird
        hingegen von dem <quote>Element <sgmltag>p</sgmltag></quote>
        gesprochen, ist damit das gesamte Element gemeint.</para>

      <para>Diese Unterscheidung ist sicherlich subtil. Trotzdem
        sollte man sie sich vergegenw&auml;rtigen.</para>
    </important>

    <para>Elemente k&ouml;nnen selber Attribute haben, die aus einem
      Namen und einem Wert bestehen.  Die Attribute haben die Aufgabe,
      dem Element zus&auml;tzliche Informationen hinzuzuf&uuml;gen.
      Denkbar sind hier Festlegungen &uuml;ber die Darstellung,
      Bezeichner, &uuml;ber die das Element eindeutig identifiziert
      werden kann, oder beliebige andere Informationen.</para>

    <para>Elementattribute werden in den <emphasis>Starttag</emphasis>
      eingef&uuml;gt und haben die Form
      <literal><replaceable>Attributename</replaceable>="<replaceable>Wert</replaceable>"</literal>.</para>

    <para>Bei einigen HTML-Versionen kennt das Element
      <sgmltag>p</sgmltag> das Attribut <sgmltag>align</sgmltag>, mit
      dessen Hilfe die Textausrichtung eines Absatzes bestimmt werden
      kann.</para>

    <para><literal>align</literal> akzeptiert einen von vier
      vorgegebenen Werten: <literal>left</literal>,
      <literal>center</literal>, <literal>right</literal> und
      <literal>justify</literal>. Ist <literal>align</literal> nicht
      angegeben, wird vom Standardwert <literal>left</literal>
      ausgegangen.</para>

    <example>
      <title>Elemente mit Attributen nutzen</title>

      <programlisting><![CDATA[<p align="left">Die Verwendung des align-Attributs
  f&uuml;r diesen Absatz ist &uuml;berfl&uuml;ssig, da left
  der Standardwert ist.</p>

<p align="center">Dieser Absatz wird hoffentlich mittig dargestellt.</p>]]></programlisting>
    </example>

    <para>Einige Attribute akzeptieren nur bestimmte Werte, wie
      beispielsweise <literal>left</literal> oder
      <literal>justify</literal>. Andere akzeptieren jeden beliebigen
      Wert. Enth&auml;lt Attributwert doppelte Anf&uuml;hrungszeichen
      (<literal>"</literal>), wird der Wert in einfachen
      Anf&uuml;hrungszeichen eingeschlossen.</para>

    <example>
      <title>Attribute mit einfachen Anf&uuml;hrungszeichen</title>

      <programlisting><![CDATA[<p align='right'>Ich stehe rechts!</p>]]></programlisting>
    </example>


    <para>Manchmal k&ouml;nnen die Anf&uuml;hrungszeichen um den
      Attributwert weggelassen werden.  Allerdings sind die Regeln,
      die festlegen wann dies zul&auml;ssig ist, sehr spitzfindig.
      Am besten schlie&szlig;en Sie Attributwerte
      <emphasis>immer</emphasis> in Anf&uuml;hrungszeichen ein.</para>

    <para>Die Informationen &uuml;ber Attribute, Elemente und Tags
      sind in SGML-Katalogen abgelegt und werden von den verschiedenen
      Werkzeugen des Dokumentationsprojektes genutzt, um die
      geschriebenen Dokumente zu validieren. Die Programme die durch
      <filename role="package">textproc/docproj</filename> installiert
      werden, bringen ihre eigenen Katalogvarianten mit, zudem pflegt
      das FDP seine  eigenen Kataloge. Beide Katalogarten m&uuml;ssen
      von allen Programmen gefunden werden k&ouml;nnen.</para>

    <sect2>
      <title>Was daf&uuml;r getan werden muss;&hellip;</title>

      <para>Damit die Beispiele dieser Fibel ausgef&uuml;hrt werden
        k&ouml;nnen, ist es notwendig, dass einige Programme auf
        dem Rechner installiert sind und das eine Umgebungsvariable
        korrekt gesetzt wird.</para>

      <procedure>
        <step>
          <para>Der erste Schritt ist die Installation des Ports
            <filename role="package">textproc/docproj</filename>
            &uuml;ber das FreeBSD-Portsystem. <filename
              role="package">textproc/docproj</filename> ist ein
            <emphasis>Metaport</emphasis>, der alle vom FDP
            ben&ouml;tigten Programme und Daten aus dem Netz laden und
            installieren sollte.</para>
        </step>

        <step>
          <para>Anschlie&szlig;end muss in den Shellkonfigurationsdateien die
            Variable <envar>SGML_CATALOG_FILES</envar>
            <footnote><simpara>Sofern man nicht an der deutschen
                Dokumentation arbeitet, m&uuml;ssen die
                Verzeichnisangaben entsprechend angepasst
                werden.</simpara>
              </footnote> gesetzt werden.</para>

            <example id="sgml-primer-envars">
              <title><filename>.profile</filename>, f&uuml;r &man.sh.1; und
                &man.bash.1; Benutzer</title>

	    <programlisting>SGML_ROOT=/usr/local/share/sgml
SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=/usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES
export SGML_CATALOG_FILES</programlisting>
	  </example>
            <!--?
              Hier muesste geprueft werden, ob sich die letzten beiden Zeilen
              vertragen oder nicht. Gibt es Entitaeten, die in beiden
              vorhanden sind, aber unterschiedliche Uebersetzungen haben?

              Oliver Fischer
            -->

          <example>
            <title><filename>.cshrc</filename>, f&uuml;r &man.csh.1;- und
              &man.tcsh.1;-Benutzer</title>

            <programlisting>setenv SGML_ROOT /usr/local/share/sgml
setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES /usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES /usr/doc/de_DE.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES</programlisting>
            </example>

          <para>Damit die &Auml;nderungen wirksam werden, meldet man
            sich ab und anschlie&szlig;end wieder an &ndash; oder man
            f&uuml;hrt die obigen Anweisungen direkt in der Shell
            aus und setzt so die ben&ouml;tigten Umgebungsvariablen.</para>

        </step>
      </procedure>

      <procedure>
        <step>
          <para>Nun sollte man eine Datei
            <filename>beispiel.sgml</filename> anlegen, die den
            folgenden Text enth&auml;lt:</para>

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

<html>
  <head>
    <title>Eine Beispieldatei in HTML</title>
  </head>

  <body>
    <p>Das ist ein Absatz mit etwas Text.</p>

    <p>Das ist ein Absatz mit anderem Text.</p>

    <p align="right">Dieser Absatz wird rechtsb&uuml;ndig
      ausgerichtet.</p>
  </body>
</html>]]></programlisting>
        </step>

        <step>
          <para>Nachdem die Datei abgespeichert wurde, kann sie
            mit Hilfe eines SGML-Parsers validiert werden.</para>

          <para>Bestandteil von <filename role="package">textproc/docproj</filename>
            ist <command>onsgmls</command> - ein <link
            linkend="sgml-primer-validating">validierender Parser</link>.
            <command>onsgmls</command> liest ein Dokument entsprechend einer SGML-DTD
            ein und gibt anschlie&szlig;end ein Element-Structure-Information-Set
            (ESIS) aus. Allerdings ist das an dieser Stelle nicht weiter
            wichtig.</para>

          <para>Wird <command>onsgmls</command> mit der Option <option>-s</option>
            aufgerufen, werden nur Fehlermeldungen ausgegeben. Dadurch
            kann leicht gepr&uuml;ft werden, ob ein Dokument g&uuml;ltig
            ist oder nicht.</para>

          <para>So pr&uuml;ft man mit <command>onsgmls</command>, ob die neuangelegte
            Beispieldatei g&uuml;ltig ist:</para>

            <screen>&prompt.user; <userinput>onsgmls -s beispiel.sgml</userinput></screen>

          <para>Sofern das Beispiel korrekt abgetippt wurde, wird sich
            <command>onsgmls</command> ohne jegliche Ausgabe beenden. Das bedeutet,
            dass das Dokument erfolgreich validiert werden konnte
            und somit g&uuml;ltig ist.</para>
        </step>

        <step>
          <para>Jetzt sollten die Tags <sgmltag>title</sgmltag> und
            <sgmltag>/title</sgmltag> aus dem Dokument gel&ouml;scht
            und das Dokument erneut validiert werden:</para>

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

          <para>Die Fehlermeldungen, die von <command>onsgmls</command>
	    ausgegeben werden, sind in durch Doppelpunkte getrennte
	    Spalten unterteilt.</para>

          <informaltable frame="none" pgwide="1">
            <tgroup cols="2">
              <thead>
                <row>
                  <entry>Spalte</entry>
                  <entry>Bedeutung</entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry>1</entry>
                  <entry>Der Name des Programms, das den Fehler
                    meldet. Hier wird immer <literal>onsgmls</literal>
                    stehen.</entry>
                </row>

                <row>
                  <entry>2</entry>
                  <entry>Der Name der fehlerhaften Datei.</entry>
                </row>

                <row>
                  <entry>3</entry>
                  <entry>Die Zeilennummer des Fehlers.</entry>
                </row>

                <row>
                  <entry>4</entry>
                    <entry>Die Spaltenummer des Fehlers.</entry>
                </row>

                <row>
                  <entry>5</entry>
                  <entry>Ein einbuchstabiger Code, der &uuml;ber die
                    Art des Fehlers informiert. <literal>I</literal>
                    steht f&uuml;r eine informelle Meldung,
                    <literal>W</literal> f&uuml;r eine Warnung und
                    <literal>E</literal> f&uuml;r Fehler<footnote>
                      <para>Nicht immer besteht eine Meldung aus
                        f&uuml;nf Spalten. Die Ausgabe von
                        <command>onsgmls -sv</command> ist
                        beispielsweise <literal>onsgmls:I: SP version
                          "1.3"</literal> (nat&uuml;rlich
                        abh&auml;ngig von der Version). Wie man sehen
                        kann, handelt es sich hier um eine informelle
                        Meldung.</para>
                    </footnote> und <literal>X</literal> f&uuml;r
                    einen Querverweis. Bei den oben stehenden Ausgaben
                    handelt es sich also um Fehlermeldungen.</entry>
                  </row>

                <row>
                  <entry>6</entry>
                  <entry>Die Meldung.</entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>

          <para>Durch das Weglassen des Tags <sgmltag>title</sgmltag>
            sind zwei unterschiedliche Fehler entstanden.</para>

          <para>Der erste Fehler besagt, dass Inhalt (in diesem
            Falle Zeichen anstatt eines Starttags) an einer Stelle
            gefunden wurde, an der der Parser etwas anderes erwartet
            hat. Genauer gesagt wurde der Starttag eines Elements
            erwartet, das innerhalb von <sgmltag>head</sgmltag>
            auftreten kann.</para>

          <para>Der zweite Fehler wurde dadurch verursacht, dass
            das Element <sgmltag>head</sgmltag> ein
            Element <sgmltag>title</sgmltag> enthalten
            <emphasis>muss</emphasis> und <command>onsgmls</command>
            nicht ber&uuml;cksichtigt, dass dieser Fehler auf dem
            vorhergehenden beruht. Es wird lediglich festgestellt,
            dass der Endtag von <sgmltag>head</sgmltag> auftritt,
	    obwohl nicht alle notwendigen Elemente vorhanden sind.</para>
        </step>

        <step>
          <para>Zum Schlu&szlig; sollte der Tag
            <sgmltag>title</sgmltag> wieder in die Beispieldatei
            eingef&uuml;gt werden.</para>
          </step>
        </procedure>
    </sect2>
  </sect1>

  <sect1 id="sgml-primer-doctype-declaration">
    <!--? Oliver Fischer: Man sollte mal feststellen, welche Bezeichung
    von w3c.de oder so hier verwendet wird.-->
    <title>Die DOCTYPE-Deklaration</title>

    <para>Am Anfang jedes Dokuments muss der Name der dem
      Dokument zugrundeliegenden DTD angegeben werden. Mit Hilfe
      dieser Information k&ouml;nnen SGML-Parser die verwendete DTD
      feststellen und pr&uuml;fen, ob das Dokument zu ihr konform ist.</para>

    <para>&Uuml;blicherweise steht diese Information in einer Zeile,
      die als DOCTYPE-Deklaration bezeichnet wird.</para>


    <para>Eine Deklaration f&uuml;r ein HTML-Dokument, das nach den
      Vorgaben der DTD f&uuml;r HTML 4.0 geschrieben wurde, sieht so
      aus:</para>

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

    <para>und besteht aus verschiedenen Teilen.</para>

    <!--<para>That line contains a number of different components.</para>-->

    <!--?
    Hier bin ich mir nicht sicher, ob ich genau &uuml;bersetzt habe oder
    das Orginal sprachlich ungenau ist. Man sollte hier mal
    in den Standardspezikationen nachschlagen und gegebenenfalls
    das Orginal korrigieren.
    Oliver Fischer
    -->

    <variablelist>
      <varlistentry>
        <term><literal>&lt;!</literal></term>

        <listitem>
          <para>Die Zeichenkette <literal>&lt;!</literal> dient hier
            als <emphasis>Indikator</emphasis>, dass es sich bei
            diesem Ausdruck um eine SGML-Deklaration handelt und diese
            Zeile den Dokumententyp festlegt.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>DOCTYPE</literal></term>

        <listitem>
          <para>Zeigt an, dass dies die SGML-Deklaration f&uuml;r
            den Dokumententyp ist.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>html</literal></term>

        <listitem>
          <para>Nennt das erste <link
              linkend="sgml-primer-elements">Element</link>, das im
            Dokument auftaucht.</para>
        </listitem>
      </varlistentry>

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

        <listitem>
          <para>Nennt den Formalen &Ouml;ffentlichen Bezeichner
            <footnote>
              <simpara>auf Englisch <foreignphrase>Formal Public
                  Identifier (FPI) </foreignphrase></simpara>
            </footnote> der DTD des Dokuments. Diese Information wird
            von SGML-Parsern ausgewertet, um die von dem Dokument
            referenzierte DTD zu bestimmen.</para>

          <para>Das Schl&uuml;sselwort <literal>PUBLIC</literal>
            geh&ouml;rt nicht zum &ouml;ffentlichen Bezeichner,
            sondern legt fest, wie ein SGML-Parser die DTD finden
            kann. Alternative Wege eine DTD zu referenzieren werden
            <link linkend="sgml-primer-fpi-alternatives">sp&auml;ter
              gezeigt</link>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>&gt;</literal></term>

        <listitem>
          <para>Schlie&szlig;t den mit <literal>&lt;!</literal> begonnenen
            Ausdruck ab.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <sect2>
      <title>Formale &Ouml;ffentliche Bezeichner</title>

      <!--? -->
      <note>
        <para>Dieser Abschnitt braucht nicht unbedingt zu gelesen zu
          werden. Dennoch ist es empfehlenswert, da er n&uuml;tzliche
          Hintergrundinformationen enth&auml;lt, die hilfreich sein
          k&ouml;nnen, falls der SGML-Prozessor die genutzte DTD nicht
          finden kann.</para>
      </note>

      <para>Jeder &ouml;ffentliche Bezeichner muss eine bestimmte Syntax
        haben, die wie folgt lautet:</para>

      <!-- Oliver Fischer: Ich habe hier Owner mit Besitzer uebersetzt.
      Mein Gef&uuml;hl sagt mir, dass dies nicht 100% richtig ist.
      Vielleicht ist Aussteller bessert? -->

      <programlisting>"<replaceable>Besitzer</replaceable>//<replaceable>Schl&uuml;sselwort</replaceable> <replaceable>Beschreibung</replaceable>//<replaceable>Sprache</replaceable>"</programlisting>

      <variablelist>
        <varlistentry>
          <term><replaceable>Besitzer</replaceable></term>

          <listitem>
            <para>Nennt den Besitzer des &ouml;ffentlichen Bezeichners.</para>

            <para>Falls diese Zeichenkette mit <quote>ISO</quote>
              beginnt, geh&ouml;rt der Bezeichner dem ISO-Kommitee.
              Der Bezeichner <literal>"ISO 8879:1986//ENTITIES Greek
                Symbols//EN"</literal> nennt <quote>ISO
                8879:1986</quote> als den Besitzer des Satzes von
              Entit&auml;ten f&uuml;r griechische Zeichen. ISO
              8879:1986 ist die ISO-Bezeichnung f&uuml;r den
              SGML-Standard.</para>


            <!--? Die Formulierung gef&auml;llt mir nicht. Oliver Fischer -->
            <para>Beginnt die Zeichenkette nicht mit
              <quote>ISO</quote>, sieht sie entweder so
              <literal>-//<replaceable>Besitzer</replaceable></literal>
              oder so
              <literal>+//<replaceable>Besitzer</replaceable></literal>
              aus. Beide Varianten unterscheiden sich also nur durch
              das anf&auml;ngliche <literal>+</literal> bzw.
              <literal>-</literal>.</para>

            <para>Sofern am Anfang ein <literal>-</literal> steht, ist
              der Bezeichner nicht &ouml;ffentlich registriert, steht
              hingegen ein <literal>+</literal> am Anfang, ist er
              registriert.</para>


            <!--? Vielleicht besser: Wie Namen registeriert werden?
            Oliver Fischer -->
            <!--? Mit der &Uuml;bersetzung des letzten Satzes bin ich mir
            nicht sicher.... Das muss irgendwie besser ausgedr&uuml;ckt
            werden.... -->

            <para>Im ISO-Standard ISO 9070:1991 wurde festgelegt, wie
              registrierte Namen erzeugt werden k&ouml;nnen. Unter
              anderem k&ouml;nnen sie von den Bezeichnungen von
              ISO-Publikationen, von ISBN-Nummern oder einer
              Organisationsbezeichnungen entsprechend ISO 6523
              abgeleitet werden. Antr&auml;ge f&uuml;r neue offiziell
              registrierte Bezeichner werden vom ISO-Kommitee an das
              American National Standards Institute (ANSI)
              weitergeleitet.</para>



            <!--?
            Eine Zeichenkette kann kein Besitzer sein.
            Wie koennte man das besser ausdruecken?
            -->

            <para>Da das FreeBSD-Projekt seine Bezeichner nicht hat
              registrieren lassen, ist der Besitzer
              <literal>-//FreeBSD</literal>. Unter anderem kann man
              daran auch sehen, dass das W3C sich nicht hat
              registrieren lassen.</para>

          </listitem>
        </varlistentry>

        <varlistentry>
          <term><replaceable>Schl&uuml;sselwort</replaceable></term>

          <listitem>
            <para>Es gibt verschiedene Schl&uuml;sselw&ouml;rter mit
              denen man die Art der gegebenen Informationen beschreiben
              kann. Einige der &uuml;blichsten sind
              <literal>DTD</literal>, <literal>ELEMENT</literal>,
              <literal>ENTITIES</literal> und <literal>TEXT</literal>.
              <literal>DTD</literal> wird nur f&uuml;r Dateien mit
              DTDs verwandt, <literal>ELEMENT</literal> findet
              f&uuml;r Dateien mit Fragmenten von DTDs Verwendung, die
              nur Deklarationen f&uuml;r Entit&auml;ten und Elemente
              enthalten. <literal>TEXT</literal> wird f&uuml;r
              SGML-Inhalte (Texte und Tags) verwendet.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><replaceable>Beschreibung</replaceable></term>

          <listitem>
            <para>Eine frei w&auml;hlbare Beschreibung des Inhalts der
              referenzierten Datei. M&ouml;glich sind hier
              Versionsnummern oder ein kurzer und sinnvoller Text, der
              innerhalb der SGML-Welt eindeutig ist.</para>

          </listitem>
        </varlistentry>

        <varlistentry>
          <term><replaceable>Sprache</replaceable></term>

          <listitem>
            <para>Ein ISO-Code aus zwei Buchstaben, der die f&uuml;r
              die Datei verwendete Sprache nennt.
              <literal>EN</literal> steht hier f&uuml;r Englisch,
              <literal>DE</literal> f&uuml;r Deutsch.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <sect3>
        <title>Die <filename>catalog</filename>-Dateien</title>

        <para>Wenn man die oben beschriebene Syntax f&uuml;r
          Bezeichner verwendet und ein Dokument durch einen
          SGML-Prozessor schickt, muss dieser die
          M&ouml;glichkeit haben, den Bezeichner auf eine real
          existierende Datei abzubilden, die die ben&ouml;tigte DTD
          enth&auml;lt.</para>

        <para>Einer der m&ouml;glichen Wege hierf&uuml;r sind
          Katalogdateien. Eine solche Datei, die &uuml;blicherweise
          <filename>catalog</filename> hei&szlig;t, besteht aus
          einzelnen Zeilen, die Bezeichner auf Dateinamen abbilden.
          Enth&auml;lt ein Katalog beispielsweise die Zeile</para>

        <programlisting>PUBLIC "-//W3C//DTD HTML 4.0//EN"             "4.0/strict.dtd"</programlisting>

        <para>kann ein SGML-Prozessor dar&uuml;ber feststellen, dass die
          ben&ouml;tigte DTD in der Datei <filename>strict.dtd</filename>
          im Unterverzeichnis <filename class="directory">4.0</filename>
          des Verzeichnisses des Katalogs zu finden ist.</para>

        <para>Ein gutes Beispiel f&uuml;r einen Katalog ist
          <filename>/usr/local/share/sgml/html/catalog</filename>.
          Diese Datei enth&auml;lt den Katalog f&uuml;r alle HTML
          DTDs, die im Zuge der Installation von <filename
            role="package">textproc/docproj</filename> installiert
          wurden.</para>

      </sect3>

      <sect3>
        <title>Die Variable <envar>SGML_CATALOG_FILES</envar></title>

        <para>Nat&uuml;rlich muss einem SGML-Prozessor noch
          mitgeteilt werden k&ouml;nnen, wo er seine Kataloge finden
          kann. Viele Programme bieten hierf&uuml;r
          Kommandozeilenoptionen an, &uuml;ber die man einen oder
          mehrere Kataloge angeben kann.</para>

        <para>Zus&auml;tzlich besteht noch die M&ouml;glichkeit mit
          der Umgebungsvariablen <envar>SGML_CATALOG_FILES</envar> auf
          SGML-Kataloge zu verweisen. Die Eintr&auml;ge von
          <envar>SGML_CATALOG_FILES</envar> m&uuml;ssen aus den
          vollst&auml;ndigen Pfadnamen der Kataloge, jeweils durch
          Komma getrennt, bestehen.</para>


        <!--? Stimmt die Formulierung? Oliver Fischer -->
        <para>&Uuml;blicherweise werden die folgenden Kataloge &uuml;ber
            <envar>SGML_CATALOG_FILES</envar> f&uuml;r
          die Arbeit an den Dokumenten des FDPs eingebunden:</para>

        <itemizedlist>
          <listitem>
            <para><filename>/usr/local/share/sgml/docbook/4.1/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>Allerdings sollte das
          <link linkend="sgml-primer-envars">schon geschehen
            sein</link>.</para>

      </sect3>
    </sect2>

    <sect2 id="sgml-primer-fpi-alternatives">
      <title>Alternativen zu Formalen &Ouml;ffentlichen Bezeichnern</title>

      <para>Anstatt mit einem Bezeichner die zum Dokument
        geh&ouml;rende DTD zu referenzieren, kann auch explizit auf
        die Datei der DTD verwiesen werden.</para>

      <para>Die Syntax des DOCTYPE-Deklaration ist in diesem Falle
        anders:</para>
      <!--<para>The syntax for this is slightly different:</para>-->

      <programlisting><![CDATA[<!DOCTYPE html SYSTEM "/pfad/zur/dokumenten.dtd">]]></programlisting>

      <para>Das Schl&uuml;sselwort <literal>SYSTEM</literal> legt
        fest, dass ein SGML-Prozessor die DTD auf
        <quote>systemspezifische</quote> Art und Weise bestimmen soll.
        Meistens, aber nicht immer, wird so auf eine Datei im
        Dateisystem verwiesen.</para>

      <para>Allerdings sollte man &ouml;ffentliche Bezeichner aus
        Gr&uuml;nden der Portabilit&auml;t bevorzugen, da man so
        nicht eine Kopie der DTD mit dem Dokument selber verteilen
        muss, beziehungsweise da man, wenn man mit
        <literal>SYSTEM</literal> arbeitet, nicht davon ausgehen kann,
        dass  die ben&ouml;tigte DTD auf anderen Systemen genau
        unter dem gleichen Pfad verf&uuml;gbar ist.</para>

    </sect2>
  </sect1>

  <sect1 id="sgml-primer-sgml-escape">
    <title>Die R&uuml;ckkehr zu SGML</title>

    <para>An einer fr&uuml;heren Stelle wurde erw&auml;hnt, dass
      man SGML nur ben&ouml;tigt, falls man selbst eine DTD entwickeln
      m&ouml;chte. Genaugenommen ist das nicht 100%ig richtig. Einige
      Teile der SGML-Syntax k&ouml;nnen auch in normalen Dokumenten
      verwendet werden, falls dies gew&uuml;nscht oder notwendig
      ist.</para>

    <para>In diesem Falle muss daf&uuml;r Sorge getragen werden,
      dass ein SGML-Prozessor feststellen kann, dass ein
      bestimmter Abschnitt des Inhalts SGML ist, das er verarbeiteten
      muss.</para>

    <para>Solche SGML-Abschnitte werden mittels
      <literal>&lt;!&nbsp;...&nbsp;&gt;</literal> in Dokumenten
      besonders gekennzeichnet. Alles, was sich zwischen diesen
      Begrenzungen befindet, ist SGML, wie es auch in DTDs gefunden
      werden kann.</para>

    <para>Demnach ist die <link
        linkend="sgml-primer-doctype-declaration">DOCTYPE-Deklaration</link>
      ein gutes Beispiel f&uuml;r SGML, das in Dokumenten verwendet
      werden muss&hellip;</para>

  </sect1>

  <sect1 id="sgml-primer-comments">
    <title>Kommentare</title>

    <para>Kommentare sind SGML-Konstrukte, die normalerweise nur
      in DTDs g&uuml;ltig sind. Dennoch ist es, wie in
      <xref linkend="sgml-primer-sgml-escape"/> gezeigt,
      m&ouml;glich Fragmente mit SGML-Syntax in Dokumenten zu
      verwenden.</para>

    <para>Zum Abgrenzen von SGML-Kommentaren wird ein doppelter
      Bindestrich <quote><literal>--</literal></quote> verwendet. Mit
      seinem ersten Auftreten &ouml;ffnet er einen Kommentar, mit
      seinem zweiten schlie&szlig;t er ihn wieder.</para>

    <example>
      <title>Beispiele f&uuml;r Kommentare in SGML</title>

      <programlisting>&lt;!-- Testkommentar --></programlisting>

      <programlisting><![CDATA[
<!-- Text innerhalb eines Kommentars -->

<!-- Ein anderer Kommentar    -->

<!-- So k&ouml;nnen mehrzeilige Kommentare
     genutzt werden -->

<!-- Eine andere M&ouml;glichkeit f&uuml;r --
  -- mehrzeilige Kommentare.     -->]]></programlisting>
    </example>

    <!--? Noch zu uebersetzen. Oliver Fischer -->
    <![%output.print;[
      <important>
	<title>Es sind zwei Bindestriche</title>

	<para>Es gibt ein Problem mit den PostScript- oder
	  PDF-Versionen dieses Dokuments.  Das obige Beispiel
	  zeigt vielleicht nur einen Bindestrich (<literal>-</literal>)
	  hinter <literal>&lt;!</literal> und vor
	  <literal>&gt;</literal>.</para>

	<para>Es <emphasis>m&uuml;ssen</emphasis> zwei Bindestriche
	  und <emphasis>nicht</emphasis> nur einer benutzt werden.
	  Die PostScript- und PDF-Versionen haben vielleicht
	  beide Bindestriche zu einem l&auml;ngeren Strich, dem
	  <emphasis>em-dash</emphasis>, zusammengefasst.</para>

	<para>Die HTML-, nur-Text und RTF-Versionen dieses Dokuments
	  sind nicht von diesem Problem betroffen.</para>
      </important>
    ]]>

    <para>Hat man fr&uuml;her schon Erfahrungen mit HTML gesammelt,
      wird man vielleicht andere Regeln f&uuml;r den Gebrauch von
      Kommentaren kennengelernt haben. Beispielsweise wird oft
      angenommen, dass Kommentare mit <literal>&lt;!--</literal>
      begonnen und nur mit <literal>--&gt;</literal> beendet
      werden.</para>

    <para>Dies ist <emphasis>nicht</emphasis> der Fall. Viele
      Webbrowser haben fehlerhafte HTML-Parser, die dies akzeptieren.
      Die SGML-Parser, die vom FDP verwendet werden, halten sich
      strenger an die SGML-Spezifikation und verwerfen Dokumente mit
      solchen Fehlern.</para>

    <example>
      <title>Fehlerhafte SGML-Kommentare</title>

      <programlisting><![CDATA[
<!-- Innerhalb eines Kommentars --

     DIES IST NICHT TEIL EINES KOMMENTARS

  -- Wieder innerhalb eines Kommentars -->]]></programlisting>

      <para>SGML-Parser w&uuml;rden die mittlere Zeile wie folgt
        interpretieren:</para>
      <!--<para>The SGML parser will treat this as though it were actually;</para>-->

      <programlisting>&lt;!DIES IST NICHT TEIL EINES KOMMENTARS&gt;</programlisting>

      <para>Da es sich hierbei nicht um g&uuml;ltiges SGML handelt, kann
        diese Zeile zur verwirrenden  Fehlermeldungen f&uuml;hren.</para>

      <programlisting><![CDATA[<!--------------- Eine wirklich schlechte Idee  --------------->]]></programlisting>

      <para>Wie das Beispiel zeigt, sollten solche Kommentare
        tunlichst vermieden werden.</para>

      <!--<para>As the example suggests, <emphasis>do not</emphasis> write
      comments like that.</para>-->

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

      <para>Ein solcher Kommentar ist (ein wenig) besser, kann aber
        jemanden, der mit SGML noch nicht so vertraut ist,
        verwirren.</para>

    </example>

    <sect2>
      <title>Finger&uuml;bungen&hellip;</title>

      <procedure>
        <step>
          <para>Zur &Uuml;bung k&ouml;nnen Sie einige Kommentare in
            die Datei <filename>beispiel.sgml</filename> einf&uuml;gen
            und &uuml;berpr&uuml;fen, ob die Datei nun noch erfolgreich
            von <command>onsgmls</command> validiert werden kann.</para>
        </step>

        <step>
          <para>Zu Testzwecken sollten Sie
            auch noch ein paar fehlerhafte Kommentare hinzuf&uuml;gen
            und sich die resultierenden Fehlermeldungen von
	    <command>onsgmls</command> ansehen.</para>
        </step>
      </procedure>
    </sect2>
  </sect1>

  <sect1 id="sgml-primer-entities">
    <title>Entit&auml;ten</title>

    <para>Entit&auml;ten stellen einen Mechanismus dar, mit dem
      einzelnen Dokumententeilen  ein Name zugewiesen werden kann.
      Findet ein SGML-Parser w&auml;hrend des Parsens eine
      Entit&auml;t, ersetzt er diese durch den ihr zugewiesenen
      Inhalt.</para>

    <para>Dadurch steht eine einfache M&ouml;glichkeit zur
      Verf&uuml;gung, mit der  variabler Inhalt in SGML-Dokumenten
      eingebunden werden kann. Zus&auml;tzlich sind Entit&auml;ten der
      einzige Weg, &uuml;ber den eine Datei in eine andere Datei mit
      SGML-Mitteln eingebunden werden kann.</para>

    <para>Es werden zwei Arten von Entit&auml;ten unterschieden:
      <emphasis>Allgemeine Entit&auml;ten</emphasis> und
      <emphasis>Parameterentit&auml;ten</emphasis>.</para>

    <sect2 id="sgml-primer-general-entities">
      <title>Allgemeine Entit&auml;ten</title>

      <para>Allgemeine Entit&auml;ten k&ouml;nnen nur in
	Dokumenten benutzt werden.  Sie k&ouml;nnen zwar im
	SGML-Kontext definiert aber dort nicht benutzt
	werden.  Vergleichen Sie dies mit
        Im <link linkend="sgml-primer-parameter-entities">Parameterentit&auml;ten</link>.</para>

      <para>Jede allgemeine Entit&auml;t hat einen Namen, &uuml;ber
        den sie angesprochen werden kann, um den von ihr
        referenzierten Inhalt in ein Dokument einzubinden. Daf&uuml;r
        muss an der betreffenden Stelle der Namen der
        Entit&auml;t per
        <literal>&amp;<replaceable>entitaetenname</replaceable>;</literal>
        einf&uuml;gt werden. Eine Entit&auml;t
        <literal>current.version</literal> k&ouml;nnte beispielsweise
        durch die aktuelle Versionsnummer eines Programms ersetzt
        werden. Man k&ouml;nnte also schreiben:</para>

      <!--?
      Der vorhergehende Satz ist nicht 100% sinngemae&szlig; uebersetzt.
      Klingt zudem doof.
      Oliver Fischer
      -->

      <!--<para>Each general entity has a name.  When you want to reference a
      general entity (and therefore include whatever text it represents in
      your document), you write
      <literal>&amp;<replaceable>entity-name</replaceable>;</literal>.  For
      example, suppose you had an entity called
      <literal>current.version</literal> which expanded to the current
          version number of your product.  You could write;</para>-->

      <programlisting><![CDATA[<para>Die aktuelle Version des
  Programms ist &current.version;.</para>]]></programlisting>

      <para>Wenn sich die Versionsnummer &auml;ndert, muss
	nur die Entit&auml;t angepasst und anschlie&szlig;end
	das Dokument neu erzeugt werden.</para>

      <para>Eine weitere Einsatzm&ouml;glichkeit f&uuml;r Allgemeine
        Entit&auml;ten ist das Einbinden von Zeichen, die auf andere
        Weise nicht in ein SGML-Dokument eingef&uuml;gt werden
        k&ouml;nnten. Ein Beispiel f&uuml;r solche Zeichen sind
        <literal>&lt;</literal> und <literal>&amp;</literal>, die
        normalerweise nicht direkt in
        SGML-Dokumenten erlaubt sind. St&ouml;&szlig;t ein SGML-Parser
        bei seiner Arbeit auf das Symbol <literal>&lt;</literal>,
        nimmt er an, dass der Anfang eines Start- oder Endtags
        gefunden wurde. Bei einem <literal>&amp;</literal> wird er
        annehmen, den Anfang einer Entit&auml;t gefunden zu haben.</para>

      <para>Wenn eines der beiden Zeichen ben&ouml;tigt wird, werden
	daher die allgemeinen Entit&auml;ten <literal>&amp;lt;</literal>
	und <literal>&amp;amp;</literal> verwendet.</para>

      <para>Allgemeine Entit&auml;ten k&ouml;nnen nur in einem
        SGML-Kontext definiert werden. &Uuml;blich ist es, dies direkt
        nach der DOCTYPE-Deklaration zu tun:</para>

      <example>
        <title>Allgemeine Entit&auml;ten festlegen</title>

        <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY current.version    "3.0-RELEASE">
<!ENTITY last.version       "2.2.7-RELEASE">
]>]]></programlisting>

        <para>Wichtig ist an dieser Stelle, dass die
          DOCTYPE-Deklaration durch eine eckige Klammer am Ende der
          ersten Zeile erweitert wurde. Die beiden Entit&auml;ten
          selber werden in den folgenden zwei Zeilen definiert, bevor
          in der letzten Zeile die eckige Klammer und die
          DOCTYPE-Deklaration wieder geschlossen werden.</para>

        <!--?
        UEbersetzung mit dem Orginal vergleichen und nach einer
        besseren UEbersetzung suchen.
        -->

        <para>Die eckigen Klammern sind notwendig um festzulegen, dass
          man die &uuml;ber DOCTYPE genannte DTD erweitern m&ouml;chte.</para>

      </example>
    </sect2>

    <sect2 id="sgml-primer-parameter-entities">
      <title>Parameterentit&auml;ten</title>

      <para>Genau wie <link
          linkend="sgml-primer-general-entities">Allgemeine
          Entit&auml;ten</link> werden Parameterentit&auml;ten
        eingesetzt um wiederverwendbare Inhaltsteile mit Namen zu
        versehen. Im Gegensatz zu Allgemeinen Entit&auml;ten
        k&ouml;nnen sie aber nur innerhalb eines <link
          linkend="sgml-primer-sgml-escape">SGML-Kontextes</link>
        genutzt werden.</para>

      <para>Die Definition von Parameterentit&auml;ten erfolgt
        &auml;hnlich zu der Allgemeiner Entit&auml;ten. Sie werden
        lediglich mit
        <literal>%<replaceable>entitaetenname</replaceable>;</literal>
        anstelle von
        <literal>&amp;<replaceable>entitaetenname</replaceable>;</literal>
        referenziert<footnote>
          <para>Es wird das Prozentzeichen anstelle des
            kaufm&auml;nnischen Unds verwendet.</para>
        </footnote>. Wichtig ist, dass das
        <literal>%</literal>-Zeichen zwischen
        <literal>ENTITY</literal> und dem Entit&auml;tennamen ein Teil
        der Definition ist.</para>

      <example>
        <title>Parameterentit&auml;ten festlegen</title>

        <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % param.etwas "etwas">
<!ENTITY % param.text "Text">
<!ENTITY % param.neu  "%param.etwas mehr %param.text">

<!-- %param.neu ist jetzt "etwas mehr Text" -->
]>]]></programlisting>
        </example>

        <!--? Noch nicht &uuml;bersetzt. Oliver Fischer -->
        <!--<para>This may not seem particularly useful.  It will be.</para>-->
      </sect2>

    <sect2>
      <title>Finger&uuml;bungen&hellip;</title>

      <procedure>
        <step>
          <para>F&uuml;gen Sie in <filename>beispiel.sgml</filename>
            eine Allgemeine Entit&auml;t ein.</para>

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

<html>
  <head>
    <title>Eine HTML-Beispieldatei</title>
  </head>

  <body>
    <p>Das ist ein Absatz mit etwas Text.</p>

    <p>Das ist ein Absatz mit anderem Text.</p>

    <p align="right">Dieser Absatz wird rechtsb&uuml;ndig
      ausgerichtet.</p>

    <p>Die aktuelle Version ist: &amp;version;</p>
  </body>
</html>]]></programlisting>
        </step>

        <step>
          <para>Validieren Sie diese Datei mit
            <command>onsgmls</command></para>
        </step>

        <step>
          <para>&Ouml;ffnen Sie nun <filename>beispiel.sgml</filename>
            mit Ihrem Webbrowser. Es kann notwendig sein, dass
            Sie die Datei vorher in <filename>beispiel.html</filename>
            umbenennen m&uuml;ssen, damit die Datei auch als
            HTML-Dokument erkannt wird.</para>

          <para>Nur wenn Sie einen sehr modernen Browser haben, werden
            Sie sehen k&ouml;nnen, dass
            <literal>&amp;version;</literal> durch die Versionsnummer
            ersetzt wurde. Leider haben die meisten Webbrowser
            sehr einfache SGML-Parser, die nicht richtig mit SGML
            umgehen k&ouml;nnen<footnote>
              <para>Eigentlich ist das eine Schande. Man stelle sich
                vor, welche Probleme und Hacks, wie beispielsweise
                Server Side Includes, man an dieser Stelle h&auml;tte
                vermeiden k&ouml;nnen.</para>
            </footnote>.</para>
        </step>

        <step>
          <para>Die L&ouml;sung hierf&uuml;r ist, das Dokument zu
            <emphasis>normalisieren</emphasis>. Zu diesem Zweck liest
            ein Normer <!--? Sehr freie &Uuml;bersetzung. Oliver -->
            das Dokument ein und gibt anschlie&szlig;end semantisch
            gleichwertiges SGML wieder aus, dass auf verschiedene
            Arten transformiert worden sein kann. Eine dieser
            m&ouml;glichen Transformationen ist das Ersetzen der
            Referenzen auf Entit&auml;ten mit dem von ihnen
            pr&auml;sentierten Inhalt.</para>

          <para>Versuchen Sie, die Beispieldatei mittels
            <command>osgmlnorm</command> zu normalisieren:</para>

            <screen>&prompt.user; <userinput>osgmlnorm beispiel.sgml > beispiel.html</userinput></screen>

          <para>Anschlie&szlig;end sollten Sie eine normalisierte
            Version, dass hei&szlig;t eine, bei der die
            Entit&auml;ten gegen ihren Inhalt ersetzt wurden, in der
            Datei <filename>beispiel.html</filename> finden. Diese
            Datei k&ouml;nnen Sie sich nun mit Ihrem Browser
            ansehen.</para>

        </step>

        <step>
          <para>Wenn Sie sich die Ausgaben von <command>osgmlnorm</command>
            ansehen, werden Sie feststellen, dass
            die DOCTYPE-Deklaration am Anfang der Datei nicht mehr
            enthalten ist. M&ouml;chten Sie die Deklaration behalten,
            muss <command>osgmlnorm</command> mit der Option
            <option>-d</option> aufrufen werden:</para>

          <screen>&prompt.user; <userinput>osgmlnorm -d beispiel.sgml > beispiel.html</userinput></screen>
        </step>
      </procedure>
    </sect2>
  </sect1>

  <sect1 id="sgml-primer-include">
    <title>Dateien mit Entit&auml;ten einbinden</title>

    <!--?
    Dieser kleine Absatz klingt ziemlich h&ouml;lzern.
    Oliver Fischer
    -->

    <para>Sowohl <link
        linkend="sgml-primer-general-entities">Allgemeine</link> als
      auch <link
        linkend="sgml-primer-parameter-entities">Parameterentit&auml;ten</link>
      sind n&uuml;tzliche Helfer, wenn es darum geht, eine Datei in
      eine andere einzubinden.</para>

    <sect2 id="sgml-primer-include-using-gen-entities">
      <title>Dateien mit Allgemeinen Entit&auml;ten einbinden</title>

      <para>Angenommen man hat ein Buch geschrieben, dessen Inhalt
        auf mehrere Dateien aufgeteilt und mittels SGML
        ausgezeichnet. Jedes Kapitel wurde dazu in einer eigenen Datei
        (<filename>kapitel1.sgml</filename>,
        <filename>kapitel2.sgml</filename> usw.) abgelegt und
        &uuml;ber eine Datei <filename>buch.sgml</filename> sollen
        alle physischen Dateien wieder mit der Hilfe von
        Entit&auml;ten zu einem logischen Dokument
        zusammengef&uuml;hrt werden.</para>

      <para>Damit der Inhalt der Dateien mit Entit&auml;ten
	eingebunden werden kann, muss die Deklaration der
        Entit&auml;ten das Schl&uuml;sselwort
        <literal>SYSTEM</literal> enthalten. SGML-Parser werden so
        angewiesen, den Inhalt der referenzierten Datei als Wert
        f&uuml;r die jeweilige Entit&auml;t zu nehmen.</para>

      <example>
        <title>Dateien mit Allgemeinen Entit&auml;ten einbinden</title>

        <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY kapitel.1 SYSTEM "kapitel1.sgml">
<!ENTITY kapitel.2 SYSTEM "kapitel2.sgml">
<!ENTITY kapitel.3 SYSTEM "kapitel3.sgml">
<!-- Und so weiter... -->
]>

<html>
  <!-- Jetzt werden die Kapitel &uuml;ber die Entit&auml;ten eingebunden -->

  &amp;kapitel.1;
  &amp;kapitel.2;
  &amp;kapitel.3;
</html>]]></programlisting>
      </example>

      <warning>
        <para>Wenn man Allgemeine Entit&auml;ten benutzt, um andere
          Dateien einzubinden, d&uuml;rfen diese Dateien
          (<filename>kapitel1.sgml</filename>,
          <filename>kapitel2.sgml</filename>, ...)
          <emphasis>keine</emphasis> eigene DOCTYPE-Deklaration
          haben.</para>
      </warning>
    </sect2>

    <sect2>
      <title>Dateien mit Parameterentit&auml;ten einbinden</title>

      <para>Wie bereits festgestellt, k&ouml;nnen
        Parameterentit&auml;ten nur innerhalb eines SGML-Kontexts
        genutzt werden. Warum m&ouml;chte man aber Dateien innerhalb
        eines SGML-Kontexts einbinden? Der Vorteil liegt in der
        M&ouml;glichkeit, die Deklaration von Entit&auml;ten in eine
        andere Datei auslagern zu k&ouml;nnen, wodurch diese leichter
        wiederverwendbar sind.</para>

      <para>Angenommen das Buch aus dem vorherigen Kapitel besteht aus
        sehr vielen Kapiteln und diese sollen auch in einem anderen
        Buch, aber in einer anderen Reihenfolge, verwendet werden.
        Eine M&ouml;glichkeit w&auml;re es, die daf&uuml;r notwendigen
        Entit&auml;ten am Anfang jedes Buches einzeln festzulegen
        &ndash; was allerdings mit der Zeit unhandlich und
        fehlertr&auml;chtig wird.</para>

      <para>Alternativ bietet sich dazu an, die Deklarationen in eine
        separate Datei auszulagern und deren Inhalt anschlie&szlig;end
        in beide B&uuml;cher &uuml;ber Parameterentit&auml;ten
        einzubinden.</para>

      <example>
        <title>Dateien mit Parameterentit&auml;ten einbinden</title>

        <para>Zuerst werden die Entit&auml;ten in einer separaten
          Datei namens <filename>kapitel.ent</filename> deklariert.
          <filename>kapitel.ent</filename> enth&auml;lt f&uuml;r
          dieses Beispiel die folgenden Zeilen:</para>

        <programlisting><![CDATA[<!ENTITY kapitel.1 SYSTEM "kapitel1.sgml">
<!ENTITY kapitel.2 SYSTEM "kapitel2.sgml">
<!ENTITY kapitel.3 SYSTEM "kapitel3.sgml">]]></programlisting>

        <para>Im zweiten Schritt f&uuml;gt man in beide B&uuml;cher
          eine Parameterentit&auml;t ein, die den Inhalt von
          <filename>kapitel.ent</filename> referenziert, und l&auml;dt
          &uuml;ber diese dann die Deklarationen. Anschlie&szlig;end
          k&ouml;nnen die so geladenen Entit&auml;ten wie gewohnt
          genutzt werden.</para>

	<programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!-- Definieren einer Parameterentit&auml;t um die Allgemeinen Entit&auml;ten f&uuml;r -->
<!-- die Kapitel laden zu k&ouml;nnen                                        -->
<!ENTITY % kapitel SYSTEM "kapitel.ent">

<!-- Nun wird der Inhalt der referenzierten Datei geladen -->
%kapitel;
]>

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

    <sect2>
      <title>Finger&uuml;bungen&hellip;</title>

        <sect3>
          <title>Binden Sie Dateien &uuml;ber Allgemeine Entit&auml;ten ein</title>

          <procedure>
            <step>
              <para>Legen Sie drei Dateien (<filename>absatz1.sgml</filename>,
                <filename>absatz2.sgml</filename> und <filename>absatz3.sgml</filename>)
                mit jeweils einer Zeile wie

                <!--     <para>Create three files, <filename>para1.sgml</filename>,
                <filename>para2.sgml</filename>, and
                <filename>para3.sgml</filename>.</para>-->

                <!--<para>Put content similar to the following in each file;</para>-->

                <programlisting><![CDATA[<p>Erster Absatz.</p>]]></programlisting>
                an.</para>
	  </step>

	  <step>
	    <para>&Auml;ndern Sie <filename>beispiel.sgml</filename> so
              ab, dass sie wie folgt aussieht:</para>

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

<html>
  <head>
    <title>Eine HTML-Beispieldatei</title>
  </head>

  <body>
    <p>Die aktuelle Version dieses Dokuments ist &version;</p>

    &absatz1;
    &absatz2;
    &absatz3;
  </body>
</html>]]></programlisting>
	  </step>

	  <step>
	    <para>Erzeugen Sie nun die Datei
              <filename>beispiel.html</filename>, indem Sie
              <filename>beispiel.sgml</filename> normalisieren:</para>

            <screen>&prompt.user; <userinput>osgmlnorm -d beispiel.sgml > beispiel.html</userinput></screen>
          </step>

          <step>
            <para>&Ouml;ffnen Sie <filename>beispiel.html</filename>
              nun mit einem Webbrowser und vergewissern Sie sich,
              dass der Inhalt der Dateien
              <filename>absatz<replaceable>N</replaceable>.sgml</filename>
              in <filename>beispiel.html</filename> &uuml;bernommen
              wurde.</para>
          </step>
	</procedure>
      </sect3>

      <sect3>
	<title>Binden Sie Dateien mit Parameterentit&auml;ten ein</title>

	<note>
	  <para>Hierf&uuml;r m&uuml;ssen Sie die vorherige Finger&uuml;bung gemacht haben.</para>
	</note>

	<procedure>
	  <step>
	    <para>&Auml;ndern Sie <filename>beispiel.sgml</filename> so
              ab, dass es wie folgt aussieht:</para>

	    <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % entitaeten SYSTEM "entitaeten.sgml"> %entitaeten;
]>

<html>
  <head>
    <title>Eine HTML-Beispieldatei</title>
  </head>

  <body>
    <p>Die aktuelle Version dieses Dokuments ist &version;</p>

    &absatz1;
    &absatz2;
    &absatz3;
  </body>
</html>]]></programlisting>
	  </step>

          <step>
            <para>Legen Sie eine weitere Datei <filename>entitaeten.sgml</filename> an,
                die folgenden Inhalt hat:</para>

            <programlisting><![CDATA[<!ENTITY version "1.1">
<!ENTITY absatz1 SYSTEM "absatz1.sgml">
<!ENTITY absatz2 SYSTEM "absatz2.sgml">
<!ENTITY absatz3 SYSTEM "absatz3.sgml">]]></programlisting>
          </step>

          <step>
            <para>Erzeugen Sie die Datei
              <filename>beispiel.html</filename>, indem Sie
              <filename>beispiel.sgml</filename> normalisieren:</para>

            <screen>&prompt.user; <userinput>osgmlnorm -d beispiel.sgml > beispiel.html</userinput></screen>
          </step>

          <step>
            <para>&Ouml;ffnen Sie <filename>beispiel.html</filename>
              nun mit einem Webbrowser und vergewissern Sie sich,
              dass der Inhalt der Dateien
              <filename>absatz<replaceable>N</replaceable>.sgml</filename>
              in <filename>beispiel.html</filename> &uuml;bernommen
              wurde.</para>
          </step>
        </procedure>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="sgml-primer-marked-sections">
    <title>Markierte Bereiche</title>

    <para>SGML erlaubt es, dass bestimmte Dokumentabschnitte
      w&auml;hrend der Verarbeitung besonders behandelt werden sollen.
      Diese Abschnitte werden als <quote>markierte Bereiche</quote>
      <footnote><para>auf Englisch <foreignphrase>marked
            sections</foreignphrase>
        </para></footnote>
        bezeichnet.</para>

    <example>
      <title>Aufbau eines markierten Bereiches</title>

      <programlisting>&lt;![ <replaceable>SCHL&Uuml;SSELWORT</replaceable> [
  Inhalt des markierten Bereiches
]]&gt;</programlisting>
    </example>

    <para>Da es sich bei markierten Bereichen um SGML-Konstrukte
      handelt, werden sie mit <literal>&lt;!</literal> eingeleitet.
      Der eigentliche Anfang des markierten Bereiches wird von der
      folgenden eckigen Klammer bestimmt. Das darauf folgende
      <replaceable>SCHL&Uuml;SSELWORT</replaceable> legt fest, wie der
      <quote>markierte Inhalt</quote> durch einen SGML-Prozessor
      w&auml;hrend der Verarbeitung behandelt werden soll. Der
      <quote>markierte</quote> Inhalt selbst beginnt erst nach der
      zweiten eckigen Klammer und erstreckt sich bis zu den zwei
      schlie&szlig;enden eckigen Klammern am Ende des Bereiches. Mit
      Hilfe des <literal>&gt;</literal> Zeichens wird der mit
      <literal>&lt;!</literal> begonnene SGML-Kontext wieder
      verlassen.</para>

    <sect2>
      <title>Schl&uuml;sselworte f&uuml;r markierte Bereiche</title>

      <sect3>
        <title><literal>CDATA</literal> und <literal>RCDATA</literal></title>

        <para>Die Schl&uuml;sselworte <literal>CDATA</literal> und
          <literal>RCDATA</literal> bestimmen das
          <emphasis>Inhaltsmodell</emphasis> f&uuml;r markierte
          Bereiche. Dadurch ist es m&ouml;glich, vom Standardmodell
          abzuweichen.</para>

        <para>Ein SGML-Prozessor muss w&auml;hrend der
          Verarbeitung eines Dokuments zu jedem Zeitpunkt wissen,
          welches <emphasis>Inhaltsmodell</emphasis> gerade anzuwenden
          ist.</para>

        <para>Was ist ein Inhaltsmodell? Kurz gesagt beschreibt das
          Inhaltsmodell, welche Art von Inhalt der Parser zu erwarten
          und wie er damit umzugehen hat.</para>

        <para>Bei <literal>CDATA</literal> und
          <literal>RCDATA</literal> handelt es sich wahrscheinlich um
          die n&uuml;tzlichsten Inhaltsmodelle. <!--? Die richtige
          Uebersetzung ist Buchstabendaten. Oliver Fischer -->
          <literal>CDATA</literal> steht f&uuml;r
          Zeichendaten<footnote>
            <para>auf Englisch <foreignphrase>character
                data</foreignphrase></para></footnote>. Trifft ein
          Parser auf dieses Inhaltsmodell, wird er annehmen, dass
          sich im zugeh&ouml;rigen Dokumentenbereich nur
          <quote>gew&ouml;hnliche</quote> Zeichen befinden. Das
          bedeutet, dass <literal>&lt;</literal> und
          <literal>&amp;</literal> ihre besondere Bedeutung
          verlieren und als einfache Zeichen behandelt werden.</para>

        <para><literal>RCDATA</literal> steht f&uuml;r
          Entit&auml;tenreferenzen und Zeichendaten<footnote><para>auf
              Englisch
              <foreignphrase>Entity references and character
                data</foreignphrase></para></footnote>. F&uuml;r einen
          Bereich mit diesem Inhaltsmodell, wird ein Parser davon
          ausgehen, dass er sowohl Zeichen als auch
          Enit&auml;tenreferenzen finden kann. <literal>&lt;</literal>
          verliert hier zwar auch seine besondere Bedeutung, doch
          <literal>&amp;</literal> wird weiterhin als Anfang einer
          Entit&auml;t interpretiert.</para>

        <para>N&uuml;tzlich ist das <literal>CDATA</literal>-Modell
          vor allem dann, wenn es darum geht Texte eins-zu-eins zu
          &uuml;bernehmen, in denen <literal>&lt;</literal> und
          <literal>&amp;</literal> geh&auml;uft
          auftreten. Zwar kann man solche Texte &uuml;berarbeiten und
          jedes <literal>&lt;</literal> durch ein
          <literal>&amp;lt;</literal> und jedes
          <literal>&amp;</literal> durch ein <literal>&amp;amp;</literal>
          ersetzen, doch es wird in den meisten F&auml;llen
          einfacher sein, f&uuml;r den betreffenden Text
          <literal>CDATA</literal> als Inhaltsmodell festzulegen. Ein
          SGML-Parser wird dann, sobald er auf
          <literal>&lt;</literal> oder <literal>&amp;</literal> trifft,
          diese als  Zeichen in einem Text betrachten.</para>

        <note>
          <para>Bei der Verwendung von <literal>CDATA</literal> und
            <literal>RCDATA</literal> als Inhaltsmodell f&uuml;r
            SGML-Beispiele, wie sie in diesem Dokument enthalten sind,
            muss bedacht werden, dass der Inhalt eines
            <literal>CDATA</literal>-Bereiches nicht validiert wird.
            dass das SGML in diesen Bereichen g&uuml;ltig ist,
            muss auf andere Weise sichergestellt werden. Denkbar ist
            beispielsweise, es in einem separaten Dokument zu
            erstellen, dort zu pr&uuml;fen und erst dann in das
            eigentliche Dokument einzuf&uuml;gen.</para>
        </note>
          <!-- The nesting of CDATA within the next example is disgusting -->

        <example>
          <title>CDATA als Inhaltsmodell f&uuml;r markierte Bereiche</title>

          <programlisting>&lt;para>Das ist ein Beispiel, wie man einen Text,
  der viele <literal>&amp;lt;</literal>- und <literal>&amp;amp;</literal>-
  Entit&auml;ten enth&auml;lt, in ein Dokument einbinden kann.
  Das Beispiel selbst, das sich innerhalb des markierten Bereiches befindet,
  ist ein HTML-Fragment. Der diesen Text umschlie&szlig;ende Tag, beginnend mit
  mit <sgmltag>para</sgmltag> und endend mit <sgmltag>/para</sgmltag>, stammt aus der DocBook DTD.&lt;/para>

&lt;programlisting>
  &lt;![RCDATA[  <![CDATA[
    <p>Dieses Beispiel demonstriert die Verwendung von HTML-Elementen.
      Da spitze Klammern so oft vorkommen, ist es einfacher, das
      gesamte Beispiel als CDATA Abschnitt auszuweisen, als die
      entsprechenden Entit&auml;ten zu nutzen.</p>

    <ul>
      <li>Das ist ein Listenelement.</li>
      <li>Das ist ein zweites Listenelement.</li>
      <li>Das ist ein drittes Listenelement.</li>
    </ul>

    <p>Und das hier, das ist das Ende des Beispiels.</p>]]>
  ]]&gt;
&lt;/programlisting></programlisting>

          <para>Liest  man die Quellen dieser Fibel, wird man
            feststellen, dass diese Technik durchg&auml;ngig
            angewandt wurde.</para>

        </example>
      </sect3>

      <sect3>
	<title><literal>INCLUDE</literal> und
	  <literal>IGNORE</literal></title>

        <para>Das Schl&uuml;sselwort <literal>INCLUDE</literal> legt
          fest, dass der Inhalt des betreffenden Abschnittes
          mitverarbeitet wird. Demgegen&uuml;ber bestimmt
          <literal>IGNORE</literal>, dass er ignoriert wird,
          dass hei&szlig;t, dass er bei der Verarbeitung
          &uuml;bergangen wird und in der Ausgabe nicht enthalten
          ist.</para>

	<example>
	  <title>Anwendung von <literal>INCLUDE</literal> und
            <literal>IGNORE</literal> in markierten
            Abschnitten</title>

	  <programlisting>&lt;![ INCLUDE [
  Dieser Text wird verarbeitet und eingebunden.
]]&gt;

&lt;![ IGNORE [
  Dieser Text wird weder verarbeitet noch eingebunden.
]]&gt;</programlisting>
          </example>

        <para>F&uuml;r sich alleine ist <literal>IGNORE</literal> als
          Anweisung nicht besonders n&uuml;tzlich, da ein Bereich, der
          von der Verarbeitung ausgenommen sein soll, auch
          auskommentiert werden kann.</para>

        <para>Kombiniert man <literal>IGNORE</literal> hingegen mit
          <link
            linkend="sgml-primer-parameter-entities">Parameterentit&auml;ten</link>,
          steht so ein  Weg zur Verf&uuml;gung, um dessen Anwendung
          besser  steuern zu k&ouml;nnen. Zwar k&ouml;nnen
          Parameterentit&auml;ten nur in einem SGML-Kontext einsetzt
          werden, da aber markierte Bereiche ebenfalls SGML-Konstrukte
          sind, ist diese Einschr&auml;nkung irrelevant.</para>

        <para>Soll beispielsweise ein und dasselbe Dokument in zwei
          unterschiedlichen Varianten produziert werden, einer
          gedruckten und einer digitalen, und soll nur die digitale
          zus&auml;tzliche Informationen enthalten, kann dies mit
          einem Trick erreicht werden.</para>

        <para>Man definiert eine Parameterentit&auml;t, der man als
          Wert die Zeichenkette <literal>INCLUDE</literal> zuweist und
          deklariert den betreffenden Bereich, der nur in der
          digitalen Variante erscheinen soll, als markierten Abschnitt
          und setzt als Schl&uuml;sselwort die zuvor definierte
          Parameterentit&auml;t ein.</para>

        <para>Soll anstelle der digitalen die gedruckte Variante
          produziert werden, muss lediglich der Entit&auml;t
          <literal>IGNORE</literal> als Wert zugewiesen und das
          Ursprungsdokument erneut durch den SGML-Prozessor geschickt
          werden.</para>

        <example>
          <title>Kontrolle von markierten Bereichen &uuml;ber
            Parameterentit&auml;ten</title>

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

...

&lt;![ %digitale.kopie [
  Dieser Satz sollte nur in der digitalen Version enthalten sein.
]]&gt;	  </programlisting>

          <para>Bei der Produktion der gedruckten Variante muss
            der Wert der Entit&auml;t ge&auml;ndert werden.</para>

	  <programlisting>&lt;!ENTITY % digitale.kopie "IGNORE"></programlisting>

          <para>Bei der Verarbeitung wird als Schl&uuml;sselwort in
            beiden F&auml;llen der von
            <literal>%digitale.kopie</literal> repr&auml;sentierte
            Wert verwendet. Im ersten Fall wird der Inhalt des
            markierten Bereichs mitverarbeitet, im zweiten Fall
            nicht.</para>

	</example>
      </sect3>
    </sect2>

    <sect2>
      <title>Finger&uuml;bung&hellip;</title>

      <procedure>
	<step>
          <para>Legen Sie eine neue Datei
            <filename>abschnitt.sgml</filename> an, die folgenden
            Inhalt hat:</para>

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

&lt;html>
  &lt;head>
    &lt;title>Ein Beispiel mit markierten Abschnitten&lt;/title>
  &lt;/head>

  &lt;body>
    &lt;p>Dieser Absatz &lt;![CDATA[beinhaltet viele &lt;
      Zeichen (&lt; &lt; &lt; &lt; &lt;). Weshalb es einfacher ist,
      ihn als CDATA Bereich auszuweisen. ]]&gt;&lt;/p>

    &lt;![ IGNORE [
    &lt;p>Dieser Absatz wird NICHT in der Ausgabe enthalten sein.&lt;/p>
    ]]&gt;

    &lt;![ <![CDATA[%text.ausgabe]]> [
     &lt;p>Dieser Absatz wird in Abh&auml;ngigkeit von <literal>%text.ausgabe</literal>
       mitausgegeben.&lt;/p>
    ]]&gt;
  &lt;/body>
&lt;/html></programlisting>
        </step>

        <step>
          <para>Normalisieren Sie den Inhalt dieser Datei mit Hilfe
            von <command>osgmlnorm</command> und sehen Sie sich das
            Ergebnis an.  Achten Sie dabei darauf, welche Abs&auml;tze
            enthalten beziehungsweise nicht enthalten sind und was aus
            den <literal>CDATA</literal>-Bereichen geworden ist.</para>
	</step>

        <step>
          <para>&Auml;ndern Sie die Definition von
            <literal>text.ausgabe</literal> so, dass es den
            Wert <literal>IGNORE</literal> zugewiesen bekommt.
            Verarbeiten Sie dann die Datei erneut mit
            <command>osgmlnorm</command> und vergleichen die Ausgabe mit
            der vom ersten <command>osgmlnorm</command> Lauf.</para>

        </step>
      </procedure>
    </sect2>
  </sect1>

  <sect1 id="sgml-primer-conclusion">
    <title>Schlu&szlig;bemerkung</title>

    <para>Aus Platzgr&uuml;nden, und um der Verst&auml;ndlichkeit
      Willen, wurden viele Gesichtspunkte nicht in aller Tiefe
      beziehungsweise gar nicht besprochen. Trotzdem sollte in den
      bisherigen Kapiteln gen&uuml;gend Wissen &uuml;ber SGML
      vermittelt worden sein, um den Aufbau der Dokumentation des FDPs
      zu verstehen.</para>

  </sect1>
</chapter>