<?xml version="1.0" encoding="iso-8859-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�ren, was
das bedeutet und wie man die SGML-Quellen liest und versteht.
Ebenso werden die in den Quellen genutzten Kniffe erkl�rt,
auf die man beim Lesen der Dokumente sto�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>�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�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�hnlichen</quote> Schrift auf dem
Bildschirm dargestellt werden, der Ausdruck soll jedoch in
<quote>Schr�gschrift</quote> oder in einer beliebigen anderen
Darstellungsform erfolgen.</para>
<para>Anf�nglich gab es die Hoffnung, dass die
K�nstliche Intelligenz (KI) helfen w�rde, dieses Ziel
zu erreichen. Computer sollte den Text lesen und dazu in der Lage
sein, selbstst�ndig wichtige Formulierungen, Dateinamen,
Benutzereingaben oder Beispiele zu erkennen. Leider verlief die
Entwicklung in diesem Bereich nicht wie gew�nscht und Computer
ben�tigen nach wie vor etwas Unterst�tzung, bevor sie
Texte vern�nftig verarbeiten k�nnen.</para>
<para>Genauer gesagt, man muss ihnen sagen, was was ist. Sehen
wir uns folgende Zeilen an:</para>
<blockquote>
<para>L�schen Sie <filename>/tmp/foo</filename> mittels &man.rm.1;.</para>
<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>
</blockquote>
<para>Es f�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�chischschen Sprachraum wird von
<quote>markup</quote>
gesprochen.</para></footnote></quote> bedeutet, dass
sich der Wert eines Textes erh�ht, aber auch seine Kosten.
Durch Auszeichnungen wird einem Dokument zus�tzlicher Text
hinzugef�gt, der aber von dem eigentlichen Dokumenteninhalt
auf eine bestimmte Art und Weise unterschieden werden kann, so
dass Programme die Auszeichnung erkennen k�nnen und
mittels dieser Informationen w�hrend der Verarbeitung in
der Lage sind, Entscheidungen zu treffen. Texteditoren
k�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�tzlich abgelegten Informationen erh�hen den Wert
des Dokuments. Allerdings muss diese Arbeit in den meisten
F�llen von einem Menschen getan werden – w�ren
Maschinen dazu f�hig, w�ren zus�tzliche
Auszeichnungselemente unn�tig. Der damit verbundene Aufwand
<emphasis>erh�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�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�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�rlich kann es keine universelle
Auszeichnungssprache geben und eine einzige mag nicht
ausreichend f�r alle m�glichen Anwendungsf�lle
sein. Eine Sprache f�r technische Dokumente wird sich
wahrscheinlich stark von einer f�r Kochrezepte
unterscheiden. Die universelle L�sung ist eine
Basissprache, mit deren Hilfe weitere Sprachen entwickelt werden
k�nnen – eine
<emphasis>Meta-Auszeichungssprache</emphasis> also.</para>
<para>Genau diese Anforderung wird von der Standard Generalized
Markup Language (<abbrev>SGML</abbrev>) erf�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�gliche Reihenfolge
und Verschachtelung sowie weitere Informationen
festgelegt.</para>
<!-- Der letzte Satz dieses Absatzes muss noch �bersetzt werden.
Ich habe keine gute �bersetzung daf�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�ndige</emphasis> Definition aller
m�glichen Sprachelemente, ihrer
Reihenfolge<footnote><para>Bei nat�rlichen Sprachen spricht
man vom Satzbau – demjenigen Konstrukt, das unter
anderem die Position des Subjekts, Objekts und
Pr�dikats in einem Satz festlegt.</para></footnote>,
optionaler Elemente und so weiter und so weiter. Dank dieser
recht formalen Festlegung ist es m�glich,
SGML-<emphasis>Parser</emphasis> zu entwickeln, die sowohl ein
Dokument als auch seine DTD einlesen und anhand dieser DTD
pr�fen k�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
�berpr�ft lediglich die korrekte Syntax des
Dokuments, dass hei�t, ob nur g�ltige
Auszeichnungselemente verwendet wurden und ihre Reihenfolge
stimmt. Dabei wird <emphasis>nicht</emphasis> gepr�ft, ob
die Elemente der DTD <emphasis>sinngem��</emphasis>
verwandt wurden. Sollten beispielsweise alle Dateinamen als
Funktionsnamen ausgezeichnet worden sein, so w�rde der
Parser keinen Fehler signalisieren. Formaler ausgedr�ckt:
Der Parser pr�ft die Syntax, aber nicht die
Semantik.</para>
</note>
<para>Es ist anzunehmen, dass, wenn man selber vor hat
Dokumentation f�r das FDP zu schreiben, der
gr��te Teil davon mit Hilfe von HTML oder DocBook
geschrieben werden wird. Aus diesem Grunde wird an dieser Stelle
nicht erkl�rt, wie eine DTD entwickelt wird.</para>
</sect1>
<sect1 id="sgml-primer-elements">
<title>Von Elementen, Tags und Attributen</title>
<!-- Bei der �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�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�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�lt nun
Kapitel, die wiederum selbst als Elemente bezeichnet werden
k�nnen. Jedes einzelne Kapitel enth�lt weitere
Elemente. So gibt es beispielsweise Abs�tze, Zitate und
Fu�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�chte, kann man sich das als
<quote>Unterteilung</quote><footnote><para>Im
angels�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�tze, Fu�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�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�hlt werden, um zu
bestimmen, zu welchem Element die einzelnen Inhalte
geh�ren. In SGML-basierten Auszeichnungssprachen wie HTML
und DocBook werden daf�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�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�rlich auch unterschiedlich benannt sein werden.</para>
<para>Der Starttag f�r ein imagin�res Element mit dem
Namen <replaceable>elementname</replaceable> ist
<sgmltag><<replaceable>elementname</replaceable>></sgmltag>.
Sein Gegenst�ck, der schlie�ende Endtag, ist
<sgmltag></<replaceable>elementname</replaceable>></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�r das Element 'p' und endet mit dem Endtag f�r
das Element 'p'.</p>
<p>Das ist ein etwas k�rzerer Absatz.</p>]]></programlisting>
</example>
<para>Elemente m�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�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�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�nnen andere Elemente enthalten. Im
anfangs erw�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�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�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><</literal>,
<literal>p</literal> und <literal>></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�rtigen.</para>
</important>
<para>Elemente k�nnen selber Attribute haben, die aus einem
Namen und einem Wert bestehen. Die Attribute haben die Aufgabe,
dem Element zus�tzliche Informationen hinzuzuf�gen.
Denkbar sind hier Festlegungen �ber die Darstellung,
Bezeichner, �ber die das Element eindeutig identifiziert
werden kann, oder beliebige andere Informationen.</para>
<para>Elementattribute werden in den <emphasis>Starttag</emphasis>
eingef�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�r diesen Absatz ist �berfl�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�lt Attributwert doppelte Anf�hrungszeichen
(<literal>"</literal>), wird der Wert in einfachen
Anf�hrungszeichen eingeschlossen.</para>
<example>
<title>Attribute mit einfachen Anf�hrungszeichen</title>
<programlisting><![CDATA[<p align='right'>Ich stehe rechts!</p>]]></programlisting>
</example>
<para>Manchmal k�nnen die Anf�hrungszeichen um den
Attributwert weggelassen werden. Allerdings sind die Regeln,
die festlegen wann dies zul�ssig ist, sehr spitzfindig.
Am besten schlie�en Sie Attributwerte
<emphasis>immer</emphasis> in Anf�hrungszeichen ein.</para>
<para>Die Informationen �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�ssen
von allen Programmen gefunden werden k�nnen.</para>
<sect2>
<title>Was daf�r getan werden muss;…</title>
<para>Damit die Beispiele dieser Fibel ausgef�hrt werden
k�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>
�ber das FreeBSD-Portsystem. <filename
role="package">textproc/docproj</filename> ist ein
<emphasis>Metaport</emphasis>, der alle vom FDP
ben�tigten Programme und Daten aus dem Netz laden und
installieren sollte.</para>
</step>
<step>
<para>Anschlie�end muss in den Shellkonfigurationsdateien die
Variable <envar>SGML_CATALOG_FILES</envar>
<footnote><simpara>Sofern man nicht an der deutschen
Dokumentation arbeitet, m�ssen die
Verzeichnisangaben entsprechend angepasst
werden.</simpara>
</footnote> gesetzt werden.</para>
<example id="sgml-primer-envars">
<title><filename>.profile</filename>, f�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�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 �nderungen wirksam werden, meldet man
sich ab und anschlie�end wieder an – oder man
f�hrt die obigen Anweisungen direkt in der Shell
aus und setzt so die ben�tigten Umgebungsvariablen.</para>
</step>
</procedure>
<procedure>
<step>
<para>Nun sollte man eine Datei
<filename>beispiel.sgml</filename> anlegen, die den
folgenden Text enth�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�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�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�ft werden, ob ein Dokument g�ltig
ist oder nicht.</para>
<para>So pr�ft man mit <command>onsgmls</command>, ob die neuangelegte
Beispieldatei g�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�ltig ist.</para>
</step>
<step>
<para>Jetzt sollten die Tags <sgmltag>title</sgmltag> und
<sgmltag>/title</sgmltag> aus dem Dokument gel�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 �ber die
Art des Fehlers informiert. <literal>I</literal>
steht f�r eine informelle Meldung,
<literal>W</literal> f�r eine Warnung und
<literal>E</literal> f�r Fehler<footnote>
<para>Nicht immer besteht eine Meldung aus
f�nf Spalten. Die Ausgabe von
<command>onsgmls -sv</command> ist
beispielsweise <literal>onsgmls:I: SP version
"1.3"</literal> (nat�rlich
abh�ngig von der Version). Wie man sehen
kann, handelt es sich hier um eine informelle
Meldung.</para>
</footnote> und <literal>X</literal> f�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�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� sollte der Tag
<sgmltag>title</sgmltag> wieder in die Beispieldatei
eingef�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�nnen SGML-Parser die verwendete DTD
feststellen und pr�fen, ob das Dokument zu ihr konform ist.</para>
<para>�blicherweise steht diese Information in einer Zeile,
die als DOCTYPE-Deklaration bezeichnet wird.</para>
<para>Eine Deklaration f�r ein HTML-Dokument, das nach den
Vorgaben der DTD f�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 �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><!</literal></term>
<listitem>
<para>Die Zeichenkette <literal><!</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�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 �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�sselwort <literal>PUBLIC</literal>
geh�rt nicht zum �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�ter
gezeigt</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>></literal></term>
<listitem>
<para>Schlie�t den mit <literal><!</literal> begonnenen
Ausdruck ab.</para>
</listitem>
</varlistentry>
</variablelist>
<sect2>
<title>Formale �ffentliche Bezeichner</title>
<!--? -->
<note>
<para>Dieser Abschnitt braucht nicht unbedingt zu gelesen zu
werden. Dennoch ist es empfehlenswert, da er n�tzliche
Hintergrundinformationen enth�lt, die hilfreich sein
k�nnen, falls der SGML-Prozessor die genutzte DTD nicht
finden kann.</para>
</note>
<para>Jeder �ffentliche Bezeichner muss eine bestimmte Syntax
haben, die wie folgt lautet:</para>
<!-- Oliver Fischer: Ich habe hier Owner mit Besitzer uebersetzt.
Mein Gef�hl sagt mir, dass dies nicht 100% richtig ist.
Vielleicht ist Aussteller bessert? -->
<programlisting>"<replaceable>Besitzer</replaceable>//<replaceable>Schl�sselwort</replaceable> <replaceable>Beschreibung</replaceable>//<replaceable>Sprache</replaceable>"</programlisting>
<variablelist>
<varlistentry>
<term><replaceable>Besitzer</replaceable></term>
<listitem>
<para>Nennt den Besitzer des �ffentlichen Bezeichners.</para>
<para>Falls diese Zeichenkette mit <quote>ISO</quote>
beginnt, geh�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�ten f�r griechische Zeichen. ISO
8879:1986 ist die ISO-Bezeichnung f�r den
SGML-Standard.</para>
<!--? Die Formulierung gef�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�ngliche <literal>+</literal> bzw.
<literal>-</literal>.</para>
<para>Sofern am Anfang ein <literal>-</literal> steht, ist
der Bezeichner nicht �ffentlich registriert, steht
hingegen ein <literal>+</literal> am Anfang, ist er
registriert.</para>
<!--? Vielleicht besser: Wie Namen registeriert werden?
Oliver Fischer -->
<!--? Mit der �bersetzung des letzten Satzes bin ich mir
nicht sicher.... Das muss irgendwie besser ausgedr�ckt
werden.... -->
<para>Im ISO-Standard ISO 9070:1991 wurde festgelegt, wie
registrierte Namen erzeugt werden k�nnen. Unter
anderem k�nnen sie von den Bezeichnungen von
ISO-Publikationen, von ISBN-Nummern oder einer
Organisationsbezeichnungen entsprechend ISO 6523
abgeleitet werden. Antr�ge f�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�sselwort</replaceable></term>
<listitem>
<para>Es gibt verschiedene Schl�sselw�rter mit
denen man die Art der gegebenen Informationen beschreiben
kann. Einige der �blichsten sind
<literal>DTD</literal>, <literal>ELEMENT</literal>,
<literal>ENTITIES</literal> und <literal>TEXT</literal>.
<literal>DTD</literal> wird nur f�r Dateien mit
DTDs verwandt, <literal>ELEMENT</literal> findet
f�r Dateien mit Fragmenten von DTDs Verwendung, die
nur Deklarationen f�r Entit�ten und Elemente
enthalten. <literal>TEXT</literal> wird f�r
SGML-Inhalte (Texte und Tags) verwendet.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>Beschreibung</replaceable></term>
<listitem>
<para>Eine frei w�hlbare Beschreibung des Inhalts der
referenzierten Datei. M�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�r
die Datei verwendete Sprache nennt.
<literal>EN</literal> steht hier f�r Englisch,
<literal>DE</literal> f�r Deutsch.</para>
</listitem>
</varlistentry>
</variablelist>
<sect3>
<title>Die <filename>catalog</filename>-Dateien</title>
<para>Wenn man die oben beschriebene Syntax f�r
Bezeichner verwendet und ein Dokument durch einen
SGML-Prozessor schickt, muss dieser die
M�glichkeit haben, den Bezeichner auf eine real
existierende Datei abzubilden, die die ben�tigte DTD
enth�lt.</para>
<para>Einer der m�glichen Wege hierf�r sind
Katalogdateien. Eine solche Datei, die �blicherweise
<filename>catalog</filename> hei�t, besteht aus
einzelnen Zeilen, die Bezeichner auf Dateinamen abbilden.
Enth�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�ber feststellen, dass die
ben�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�r einen Katalog ist
<filename>/usr/local/share/sgml/html/catalog</filename>.
Diese Datei enth�lt den Katalog f�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�rlich muss einem SGML-Prozessor noch
mitgeteilt werden k�nnen, wo er seine Kataloge finden
kann. Viele Programme bieten hierf�r
Kommandozeilenoptionen an, �ber die man einen oder
mehrere Kataloge angeben kann.</para>
<para>Zus�tzlich besteht noch die M�glichkeit mit
der Umgebungsvariablen <envar>SGML_CATALOG_FILES</envar> auf
SGML-Kataloge zu verweisen. Die Eintr�ge von
<envar>SGML_CATALOG_FILES</envar> m�ssen aus den
vollst�ndigen Pfadnamen der Kataloge, jeweils durch
Komma getrennt, bestehen.</para>
<!--? Stimmt die Formulierung? Oliver Fischer -->
<para>�blicherweise werden die folgenden Kataloge �ber
<envar>SGML_CATALOG_FILES</envar> f�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 �ffentlichen Bezeichnern</title>
<para>Anstatt mit einem Bezeichner die zum Dokument
geh�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�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 �ffentliche Bezeichner aus
Gr�nden der Portabilit�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�tigte DTD auf anderen Systemen genau
unter dem gleichen Pfad verf�gbar ist.</para>
</sect2>
</sect1>
<sect1 id="sgml-primer-sgml-escape">
<title>Die R�ckkehr zu SGML</title>
<para>An einer fr�heren Stelle wurde erw�hnt, dass
man SGML nur ben�tigt, falls man selbst eine DTD entwickeln
m�chte. Genaugenommen ist das nicht 100%ig richtig. Einige
Teile der SGML-Syntax k�nnen auch in normalen Dokumenten
verwendet werden, falls dies gew�nscht oder notwendig
ist.</para>
<para>In diesem Falle muss daf�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><! ... ></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�r SGML, das in Dokumenten verwendet
werden muss…</para>
</sect1>
<sect1 id="sgml-primer-comments">
<title>Kommentare</title>
<para>Kommentare sind SGML-Konstrukte, die normalerweise nur
in DTDs g�ltig sind. Dennoch ist es, wie in
<xref linkend="sgml-primer-sgml-escape"/> gezeigt,
m�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 �ffnet er einen Kommentar, mit
seinem zweiten schlie�t er ihn wieder.</para>
<example>
<title>Beispiele f�r Kommentare in SGML</title>
<programlisting><!-- Testkommentar --></programlisting>
<programlisting><![CDATA[
<!-- Text innerhalb eines Kommentars -->
<!-- Ein anderer Kommentar -->
<!-- So k�nnen mehrzeilige Kommentare
genutzt werden -->
<!-- Eine andere M�glichkeit f�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><!</literal> und vor
<literal>></literal>.</para>
<para>Es <emphasis>m�ssen</emphasis> zwei Bindestriche
und <emphasis>nicht</emphasis> nur einer benutzt werden.
Die PostScript- und PDF-Versionen haben vielleicht
beide Bindestriche zu einem l�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�her schon Erfahrungen mit HTML gesammelt,
wird man vielleicht andere Regeln f�r den Gebrauch von
Kommentaren kennengelernt haben. Beispielsweise wird oft
angenommen, dass Kommentare mit <literal><!--</literal>
begonnen und nur mit <literal>--></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�rden die mittlere Zeile wie folgt
interpretieren:</para>
<!--<para>The SGML parser will treat this as though it were actually;</para>-->
<programlisting><!DIES IST NICHT TEIL EINES KOMMENTARS></programlisting>
<para>Da es sich hierbei nicht um g�ltiges SGML handelt, kann
diese Zeile zur verwirrenden Fehlermeldungen f�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�bungen…</title>
<procedure>
<step>
<para>Zur �bung k�nnen Sie einige Kommentare in
die Datei <filename>beispiel.sgml</filename> einf�gen
und �berpr�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�gen
und sich die resultierenden Fehlermeldungen von
<command>onsgmls</command> ansehen.</para>
</step>
</procedure>
</sect2>
</sect1>
<sect1 id="sgml-primer-entities">
<title>Entit�ten</title>
<para>Entit�ten stellen einen Mechanismus dar, mit dem
einzelnen Dokumententeilen ein Name zugewiesen werden kann.
Findet ein SGML-Parser w�hrend des Parsens eine
Entit�t, ersetzt er diese durch den ihr zugewiesenen
Inhalt.</para>
<para>Dadurch steht eine einfache M�glichkeit zur
Verf�gung, mit der variabler Inhalt in SGML-Dokumenten
eingebunden werden kann. Zus�tzlich sind Entit�ten der
einzige Weg, �ber den eine Datei in eine andere Datei mit
SGML-Mitteln eingebunden werden kann.</para>
<para>Es werden zwei Arten von Entit�ten unterschieden:
<emphasis>Allgemeine Entit�ten</emphasis> und
<emphasis>Parameterentit�ten</emphasis>.</para>
<sect2 id="sgml-primer-general-entities">
<title>Allgemeine Entit�ten</title>
<para>Allgemeine Entit�ten k�nnen nur in
Dokumenten benutzt werden. Sie k�nnen zwar im
SGML-Kontext definiert aber dort nicht benutzt
werden. Vergleichen Sie dies mit
Im <link linkend="sgml-primer-parameter-entities">Parameterentit�ten</link>.</para>
<para>Jede allgemeine Entit�t hat einen Namen, �ber
den sie angesprochen werden kann, um den von ihr
referenzierten Inhalt in ein Dokument einzubinden. Daf�r
muss an der betreffenden Stelle der Namen der
Entit�t per
<literal>&<replaceable>entitaetenname</replaceable>;</literal>
einf�gt werden. Eine Entit�t
<literal>current.version</literal> k�nnte beispielsweise
durch die aktuelle Versionsnummer eines Programms ersetzt
werden. Man k�nnte also schreiben:</para>
<!--?
Der vorhergehende Satz ist nicht 100% sinngemae� 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>&<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 ¤t.version;.</para>]]></programlisting>
<para>Wenn sich die Versionsnummer �ndert, muss
nur die Entit�t angepasst und anschlie�end
das Dokument neu erzeugt werden.</para>
<para>Eine weitere Einsatzm�glichkeit f�r Allgemeine
Entit�ten ist das Einbinden von Zeichen, die auf andere
Weise nicht in ein SGML-Dokument eingef�gt werden
k�nnten. Ein Beispiel f�r solche Zeichen sind
<literal><</literal> und <literal>&</literal>, die
normalerweise nicht direkt in
SGML-Dokumenten erlaubt sind. St��t ein SGML-Parser
bei seiner Arbeit auf das Symbol <literal><</literal>,
nimmt er an, dass der Anfang eines Start- oder Endtags
gefunden wurde. Bei einem <literal>&</literal> wird er
annehmen, den Anfang einer Entit�t gefunden zu haben.</para>
<para>Wenn eines der beiden Zeichen ben�tigt wird, werden
daher die allgemeinen Entit�ten <literal>&lt;</literal>
und <literal>&amp;</literal> verwendet.</para>
<para>Allgemeine Entit�ten k�nnen nur in einem
SGML-Kontext definiert werden. �blich ist es, dies direkt
nach der DOCTYPE-Deklaration zu tun:</para>
<example>
<title>Allgemeine Entit�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�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 �ber DOCTYPE genannte DTD erweitern m�chte.</para>
</example>
</sect2>
<sect2 id="sgml-primer-parameter-entities">
<title>Parameterentit�ten</title>
<para>Genau wie <link
linkend="sgml-primer-general-entities">Allgemeine
Entit�ten</link> werden Parameterentit�ten
eingesetzt um wiederverwendbare Inhaltsteile mit Namen zu
versehen. Im Gegensatz zu Allgemeinen Entit�ten
k�nnen sie aber nur innerhalb eines <link
linkend="sgml-primer-sgml-escape">SGML-Kontextes</link>
genutzt werden.</para>
<para>Die Definition von Parameterentit�ten erfolgt
�hnlich zu der Allgemeiner Entit�ten. Sie werden
lediglich mit
<literal>%<replaceable>entitaetenname</replaceable>;</literal>
anstelle von
<literal>&<replaceable>entitaetenname</replaceable>;</literal>
referenziert<footnote>
<para>Es wird das Prozentzeichen anstelle des
kaufm�nnischen Unds verwendet.</para>
</footnote>. Wichtig ist, dass das
<literal>%</literal>-Zeichen zwischen
<literal>ENTITY</literal> und dem Entit�tennamen ein Teil
der Definition ist.</para>
<example>
<title>Parameterentit�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 �bersetzt. Oliver Fischer -->
<!--<para>This may not seem particularly useful. It will be.</para>-->
</sect2>
<sect2>
<title>Finger�bungen…</title>
<procedure>
<step>
<para>F�gen Sie in <filename>beispiel.sgml</filename>
eine Allgemeine Entit�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�ndig
ausgerichtet.</p>
<p>Die aktuelle Version ist: &version;</p>
</body>
</html>]]></programlisting>
</step>
<step>
<para>Validieren Sie diese Datei mit
<command>onsgmls</command></para>
</step>
<step>
<para>�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�ssen, damit die Datei auch als
HTML-Dokument erkannt wird.</para>
<para>Nur wenn Sie einen sehr modernen Browser haben, werden
Sie sehen k�nnen, dass
<literal>&version;</literal> durch die Versionsnummer
ersetzt wurde. Leider haben die meisten Webbrowser
sehr einfache SGML-Parser, die nicht richtig mit SGML
umgehen k�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�tte
vermeiden k�nnen.</para>
</footnote>.</para>
</step>
<step>
<para>Die L�sung hierf�r ist, das Dokument zu
<emphasis>normalisieren</emphasis>. Zu diesem Zweck liest
ein Normer <!--? Sehr freie �bersetzung. Oliver -->
das Dokument ein und gibt anschlie�end semantisch
gleichwertiges SGML wieder aus, dass auf verschiedene
Arten transformiert worden sein kann. Eine dieser
m�glichen Transformationen ist das Ersetzen der
Referenzen auf Entit�ten mit dem von ihnen
pr�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�end sollten Sie eine normalisierte
Version, dass hei�t eine, bei der die
Entit�ten gegen ihren Inhalt ersetzt wurden, in der
Datei <filename>beispiel.html</filename> finden. Diese
Datei k�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�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�ten einbinden</title>
<!--?
Dieser kleine Absatz klingt ziemlich h�lzern.
Oliver Fischer
-->
<para>Sowohl <link
linkend="sgml-primer-general-entities">Allgemeine</link> als
auch <link
linkend="sgml-primer-parameter-entities">Parameterentit�ten</link>
sind n�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�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
�ber eine Datei <filename>buch.sgml</filename> sollen
alle physischen Dateien wieder mit der Hilfe von
Entit�ten zu einem logischen Dokument
zusammengef�hrt werden.</para>
<para>Damit der Inhalt der Dateien mit Entit�ten
eingebunden werden kann, muss die Deklaration der
Entit�ten das Schl�sselwort
<literal>SYSTEM</literal> enthalten. SGML-Parser werden so
angewiesen, den Inhalt der referenzierten Datei als Wert
f�r die jeweilige Entit�t zu nehmen.</para>
<example>
<title>Dateien mit Allgemeinen Entit�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 �ber die Entit�ten eingebunden -->
&kapitel.1;
&kapitel.2;
&kapitel.3;
</html>]]></programlisting>
</example>
<warning>
<para>Wenn man Allgemeine Entit�ten benutzt, um andere
Dateien einzubinden, d�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�ten einbinden</title>
<para>Wie bereits festgestellt, k�nnen
Parameterentit�ten nur innerhalb eines SGML-Kontexts
genutzt werden. Warum m�chte man aber Dateien innerhalb
eines SGML-Kontexts einbinden? Der Vorteil liegt in der
M�glichkeit, die Deklaration von Entit�ten in eine
andere Datei auslagern zu k�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�glichkeit w�re es, die daf�r notwendigen
Entit�ten am Anfang jedes Buches einzeln festzulegen
– was allerdings mit der Zeit unhandlich und
fehlertr�chtig wird.</para>
<para>Alternativ bietet sich dazu an, die Deklarationen in eine
separate Datei auszulagern und deren Inhalt anschlie�end
in beide B�cher �ber Parameterentit�ten
einzubinden.</para>
<example>
<title>Dateien mit Parameterentit�ten einbinden</title>
<para>Zuerst werden die Entit�ten in einer separaten
Datei namens <filename>kapitel.ent</filename> deklariert.
<filename>kapitel.ent</filename> enth�lt f�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�gt man in beide B�cher
eine Parameterentit�t ein, die den Inhalt von
<filename>kapitel.ent</filename> referenziert, und l�dt
�ber diese dann die Deklarationen. Anschlie�end
k�nnen die so geladenen Entit�ten wie gewohnt
genutzt werden.</para>
<programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!-- Definieren einer Parameterentit�t um die Allgemeinen Entit�ten f�r -->
<!-- die Kapitel laden zu k�nnen -->
<!ENTITY % kapitel SYSTEM "kapitel.ent">
<!-- Nun wird der Inhalt der referenzierten Datei geladen -->
%kapitel;
]>
<html>
&kapitel.1;
&kapitel.2;
&kapitel.3;
</html>]]></programlisting>
</example>
</sect2>
<sect2>
<title>Finger�bungen…</title>
<sect3>
<title>Binden Sie Dateien �ber Allgemeine Entit�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>�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>�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> �bernommen
wurde.</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Binden Sie Dateien mit Parameterentit�ten ein</title>
<note>
<para>Hierf�r m�ssen Sie die vorherige Finger�bung gemacht haben.</para>
</note>
<procedure>
<step>
<para>�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>�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> �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�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><![ <replaceable>SCHL�SSELWORT</replaceable> [
Inhalt des markierten Bereiches
]]></programlisting>
</example>
<para>Da es sich bei markierten Bereichen um SGML-Konstrukte
handelt, werden sie mit <literal><!</literal> eingeleitet.
Der eigentliche Anfang des markierten Bereiches wird von der
folgenden eckigen Klammer bestimmt. Das darauf folgende
<replaceable>SCHL�SSELWORT</replaceable> legt fest, wie der
<quote>markierte Inhalt</quote> durch einen SGML-Prozessor
w�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�enden eckigen Klammern am Ende des Bereiches. Mit
Hilfe des <literal>></literal> Zeichens wird der mit
<literal><!</literal> begonnene SGML-Kontext wieder
verlassen.</para>
<sect2>
<title>Schl�sselworte f�r markierte Bereiche</title>
<sect3>
<title><literal>CDATA</literal> und <literal>RCDATA</literal></title>
<para>Die Schl�sselworte <literal>CDATA</literal> und
<literal>RCDATA</literal> bestimmen das
<emphasis>Inhaltsmodell</emphasis> f�r markierte
Bereiche. Dadurch ist es m�glich, vom Standardmodell
abzuweichen.</para>
<para>Ein SGML-Prozessor muss w�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�tzlichsten Inhaltsmodelle. <!--? Die richtige
Uebersetzung ist Buchstabendaten. Oliver Fischer -->
<literal>CDATA</literal> steht f�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�rigen Dokumentenbereich nur
<quote>gew�hnliche</quote> Zeichen befinden. Das
bedeutet, dass <literal><</literal> und
<literal>&</literal> ihre besondere Bedeutung
verlieren und als einfache Zeichen behandelt werden.</para>
<para><literal>RCDATA</literal> steht f�r
Entit�tenreferenzen und Zeichendaten<footnote><para>auf
Englisch
<foreignphrase>Entity references and character
data</foreignphrase></para></footnote>. F�r einen
Bereich mit diesem Inhaltsmodell, wird ein Parser davon
ausgehen, dass er sowohl Zeichen als auch
Enit�tenreferenzen finden kann. <literal><</literal>
verliert hier zwar auch seine besondere Bedeutung, doch
<literal>&</literal> wird weiterhin als Anfang einer
Entit�t interpretiert.</para>
<para>N�tzlich ist das <literal>CDATA</literal>-Modell
vor allem dann, wenn es darum geht Texte eins-zu-eins zu
�bernehmen, in denen <literal><</literal> und
<literal>&</literal> geh�uft
auftreten. Zwar kann man solche Texte �berarbeiten und
jedes <literal><</literal> durch ein
<literal>&lt;</literal> und jedes
<literal>&</literal> durch ein <literal>&amp;</literal>
ersetzen, doch es wird in den meisten F�llen
einfacher sein, f�r den betreffenden Text
<literal>CDATA</literal> als Inhaltsmodell festzulegen. Ein
SGML-Parser wird dann, sobald er auf
<literal><</literal> oder <literal>&</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�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�ltig ist,
muss auf andere Weise sichergestellt werden. Denkbar ist
beispielsweise, es in einem separaten Dokument zu
erstellen, dort zu pr�fen und erst dann in das
eigentliche Dokument einzuf�gen.</para>
</note>
<!-- The nesting of CDATA within the next example is disgusting -->
<example>
<title>CDATA als Inhaltsmodell f�r markierte Bereiche</title>
<programlisting><para>Das ist ein Beispiel, wie man einen Text,
der viele <literal>&lt;</literal>- und <literal>&amp;</literal>-
Entit�ten enth�lt, in ein Dokument einbinden kann.
Das Beispiel selbst, das sich innerhalb des markierten Bereiches befindet,
ist ein HTML-Fragment. Der diesen Text umschlie�ende Tag, beginnend mit
mit <sgmltag>para</sgmltag> und endend mit <sgmltag>/para</sgmltag>, stammt aus der DocBook DTD.</para>
<programlisting>
<![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�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>]]>
]]>
</programlisting></programlisting>
<para>Liest man die Quellen dieser Fibel, wird man
feststellen, dass diese Technik durchg�ngig
angewandt wurde.</para>
</example>
</sect3>
<sect3>
<title><literal>INCLUDE</literal> und
<literal>IGNORE</literal></title>
<para>Das Schl�sselwort <literal>INCLUDE</literal> legt
fest, dass der Inhalt des betreffenden Abschnittes
mitverarbeitet wird. Demgegen�ber bestimmt
<literal>IGNORE</literal>, dass er ignoriert wird,
dass hei�t, dass er bei der Verarbeitung
�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><![ INCLUDE [
Dieser Text wird verarbeitet und eingebunden.
]]>
<![ IGNORE [
Dieser Text wird weder verarbeitet noch eingebunden.
]]></programlisting>
</example>
<para>F�r sich alleine ist <literal>IGNORE</literal> als
Anweisung nicht besonders n�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�ten</link>,
steht so ein Weg zur Verf�gung, um dessen Anwendung
besser steuern zu k�nnen. Zwar k�nnen
Parameterentit�ten nur in einem SGML-Kontext einsetzt
werden, da aber markierte Bereiche ebenfalls SGML-Konstrukte
sind, ist diese Einschr�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�tzliche Informationen enthalten, kann dies mit
einem Trick erreicht werden.</para>
<para>Man definiert eine Parameterentit�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�sselwort die zuvor definierte
Parameterentit�t ein.</para>
<para>Soll anstelle der digitalen die gedruckte Variante
produziert werden, muss lediglich der Entit�t
<literal>IGNORE</literal> als Wert zugewiesen und das
Ursprungsdokument erneut durch den SGML-Prozessor geschickt
werden.</para>
<example>
<title>Kontrolle von markierten Bereichen �ber
Parameterentit�ten</title>
<programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % digitale.kopie "INCLUDE">
]]>
...
<![ %digitale.kopie [
Dieser Satz sollte nur in der digitalen Version enthalten sein.
]]> </programlisting>
<para>Bei der Produktion der gedruckten Variante muss
der Wert der Entit�t ge�ndert werden.</para>
<programlisting><!ENTITY % digitale.kopie "IGNORE"></programlisting>
<para>Bei der Verarbeitung wird als Schl�sselwort in
beiden F�llen der von
<literal>%digitale.kopie</literal> repr�sentierte
Wert verwendet. Im ersten Fall wird der Inhalt des
markierten Bereichs mitverarbeitet, im zweiten Fall
nicht.</para>
</example>
</sect3>
</sect2>
<sect2>
<title>Finger�bung…</title>
<procedure>
<step>
<para>Legen Sie eine neue Datei
<filename>abschnitt.sgml</filename> an, die folgenden
Inhalt hat:</para>
<programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % text.ausgabe "INCLUDE">
]>
<html>
<head>
<title>Ein Beispiel mit markierten Abschnitten</title>
</head>
<body>
<p>Dieser Absatz <![CDATA[beinhaltet viele <
Zeichen (< < < < <). Weshalb es einfacher ist,
ihn als CDATA Bereich auszuweisen. ]]></p>
<![ IGNORE [
<p>Dieser Absatz wird NICHT in der Ausgabe enthalten sein.</p>
]]>
<![ <![CDATA[%text.ausgabe]]> [
<p>Dieser Absatz wird in Abh�ngigkeit von <literal>%text.ausgabe</literal>
mitausgegeben.</p>
]]>
</body>
</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�tze
enthalten beziehungsweise nicht enthalten sind und was aus
den <literal>CDATA</literal>-Bereichen geworden ist.</para>
</step>
<step>
<para>�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�bemerkung</title>
<para>Aus Platzgr�nden, und um der Verst�ndlichkeit
Willen, wurden viele Gesichtspunkte nicht in aller Tiefe
beziehungsweise gar nicht besprochen. Trotzdem sollte in den
bisherigen Kapiteln gen�gend Wissen �ber SGML
vermittelt worden sein, um den Aufbau der Dokumentation des FDPs
zu verstehen.</para>
</sect1>
</chapter>