Domains

(Auszug aus "DITA - Der neue Standard für Technische Dokumentation" von Johannes Hentrich)

Ziel einer Domain-Spezialisierung ist, eine neue Semantik für Topics bereitzustellen. Bei einer Domain-Spezialisierung werden zwei Dateien erstellt und bearbeitet:

mod-Datei: Alle Elemente, die für die spezialisierte Domain zur Verfügung gestellt werden sollen, sind in einer mod-Datei, das heißt, in einer Moduldatei, definiert. Als Vorlage für die spezialisierte mod-Datei wird eine bestehende mod-Datei von DITA verwendet.
ent-Datei: Diese Datei enthält alle Parameter-Entitäten und Text-Entitäten der spezialisierten Domain.

Zusätzlich können noch die XSLT-Stylesheets für die neuen Elemente angepasst werden.

Beispiel für eine Domain-Spezialisierung

Ebenso wie bei der Topic-Spezialisierung empfiehlt es sich bei der Domain-Spezialisierung zuerst ein Modell-Dokument zu erstellen, welches die spezialisierten Elemente in der gewünschten Form enthält. Insbesondere wenn die spezialisierten Elemente als Inhaltsmodell weitere Elemente enthalten und nicht nur einen einfachen Datentyp wie PCDATA, ist eine solche Vorgehensweise dringend anzuraten. Denn bei einigen Domains gibt es einige Elemente zur semantischen Auszeichnung mit einem komplexen Inhaltsmodell.

Mit einem Modell-Dokument ist dann der Test einer Domain-Spezialisierung auch wesentlich einfacher möglich.

Im folgenden Beispiel wird eine Domain-Spezialisierung für das <keyword>-Element vorgestellt. Laut DITA-Spezifikation ist dieses Element dazu gedacht, um beispielsweise Befehle, Parameter oder Produktnamen auszuzeichnen. Bei dieser breiten inhaltlichen Palette ist das <keyword>-Element geradezu prädestiniert, spezialisiert zu werden.

Im Folgenden wird das <keyword>-Element dahingehend spezialisiert, Elemente der XML-Syntax, in diesem Fall Elemente, Attribute, Text-Entitäten und Parameter-Entitäten, semantisch auszeichnen zu können.

Folgende vier Elemente sollen mit der Domain-Spezialisierung zur Verfügung stehen:

<xmlelement>: Dient zur Auszeichnung von XML-Elementen.
<xmlattribute>: Dient zur Auszeichnung von XML-Attributen.
<textentity>: Dient zur Auszeichnung von Text-Entitäten.
<parameterentity>: Dient zur Auszeichnung von Parameter-Entitäten.

Aufgrund der Übersichtlichkeit werden in dem folgenden Beispiel nur Elemente verwendet, denen der einfache Datentyp PCDATA zugeordnet ist. Jedes der Elemente könnte durchaus auch weitere Elemente enthalten. Jedoch muss das Inhaltsmodell des spezialisierten Elemente stets restriktiver sein als das Inhaltsmodell des Ausgangselements. Informationen, welche Regeln es bei der Erstellung eines Inhaltsmodells zu befolgen gibt, erhalten Sie in Flexible Erweiterbarkeit.

Folgende Schritte sind notwendig, um eine Domain-Spezialisierung durchführen zu können:

Erstellen Sie eine mod-Datei, das heißt eine, Moduldatei, in der die spezialiserten Elemente definiert sind.
Erstellen Sie eine ent-Datei, in der die Parameter-Entitäten und die Text-Entitäten der Domain definiert sind.
Integrieren Sie die neu erstellte mod-Datei in eine oder mehrere Mantel-DTDs.

Der erste Schritt bei einer Domain-Spezialisierung ist die Erstellung einer mod-Datei, in der die neuen Elemente definiert werden.

Der einfachste Weg, eine neue mod-Datei für eine Domain-Spezialisierung zu erstellen, besteht darin, dass Sie eine bestehende mod-Datei kopieren und diese gemäß Ihren Anforderungen anpassen. In der neuen mod-Datei können Sie die Deklaration der neuen Elemente hinzufügen und die Deklaration von nicht benötigten Elementen löschen.

Im Gegensatz zu der Spezialisierung von Topics werden bei der Domain-Spezialisierung häufig nur wenige Deklarationen von einer bestehenden mod-Dateien benötigt, sodass die Neuerstellung einer mod-Datei häufig schneller ist, als eine bestehende Datei zu modifizieren. Im Folgenden wird gezeigt, wie Sie eine neue mod-Datei für die Spezialisierung des <keyword>-Elements erstellen können. Gehen Sie dabei wie folgt vor:

Erstellen Sie eine mod-Datei mit dem Namen xmlmarkupDomain.mod.
Definieren Sie die Parameter-Entitäten der neuen Elemente.

<!ENTITY % xmlelement "xmlelement">
<!ENTITY % xmlattribute "xmlattribute">
<!ENTITY % textentity "textentity">
<!ENTITY % parameterentity "parameterentity">

Definieren Sie die Elemente und ihre Attribute.

<!ELEMENT xmlelement (#PCDATA)*>
<!ATTLIST xmlelement %univ-atts; outputclass CDATA #IMPLIED>

<!ELEMENT xmlattribute (#PCDATA)*>
<!ATTLIST xmlattribute %univ-atts; outputclass CDATA #IMPLIED>

<!ELEMENT testentity (#PCDATA)*>
<!ATTLIST textentity %univ-atts; outputclass CDATA #IMPLIED>

<!ELEMENT parameterentity (#PCDATA)*>
<!ATTLIST parameterentity %univ-atts; outputclass CDATA #IMPLIED>

Bei der Definition der Attribute wird in diesem Beispiel die %univ-atts-Parameter-Entität aufgeführt, in der praktisch alle Attribute definiert sind, die in den Elementen zur Verfügung stehen. Mit outputclass wird ein weiteres Standard-DITA-Attribut hinzugefügt, welches bei der Verarbeitung der XML-Datein zu HTML-Dateien ausgewertet wird.

Definieren Sie die class-Attribute für die neu definierten Elemente.

Wie bei der Topic-Spezialisierung spielt auch bei der Domain-Spezialisierung das class-Attribut eine zentrale Rolle. Mit ihm wird festgelegt, wie sich die spezialisierten Informationsstrukturen von den ursprünglichen Informationsstrukturen ableiten.

In den mod-Dateien von DITA wird die Definition für das class-Attribut von sonstigen Attribut-Definitionen eines Elements getrennt. Dies geschieht, um ein Maximum an Modularität zu erzielen.

Die Deklaration für die class-Attribute für die vier Elemente sieht wie folgt aus:

<!ATTLIST xmlelement %global-atts; class CDATA "+ topic/keyword xmlmarkup-d/xmlelement ">

<!ATTLIST xmlattribute %global-atts; class CDATA "+ topic/keyword xmlmarkup-d/xmlattribute ">

<!ATTLIST textentity %global-atts; class CDATA "+ topic/keyword xmlmarkup-d/textentity ">

<!ATTLIST parameterentity %global-atts; class CDATA "+ topic/keyword xmlmarkup-d/parameterentity ">

Das Pluszeichen in der Definition des class-Attributs gibt an, dass hier eine Domain-Spezialisierung vorliegt. Nach einem Leerzeichen folgt die Definition topic/keyword xmlmarkup-d/xmlelement, die angibt, wie sich das <xmlelement>-Element aus der xmlmarkup-d-Domain von dem <keyword>-Element aus der topic-Domain ableitet. Der Name der neuen Domain, hier xmlmarkup-d, wird auch in der korrespondierenden ent-Datei verwendet. Gemäß der Konvention wird ein -d angefügt, um anzuzeigen, dass es sich um ein Modul für eine Domain handelt. Nach der Defini-tion der Abbildung von topic/keyword auf xmlmarkup-d/xmlelement muss wieder ein Leerzeichen erfolgen. Erst dann ist die Definition des class-Attributs abgeschlossen.

Mit der Definition der class-Attribute ist die xmlmarkup.mod-Datei vollständig. Mit den in DITA in den mod-Dateien üblichen Überschriften sieht die xmlmarkup.mod-Datei wie folgt aus:

<!-- ============================================= -->
<!-- ELEMENT NAME ENTITIES -->
<!-- ============================================= -->
<!ENTITY % xmlelement "xmlelement">
<!ENTITY % xmlattribute "xmlattribute">
<!ENTITY % textentity "textentity">
<!ENTITY % parameterentity "parameterentity">
<!-- ============================================= -->
<!-- ELEMENT DECLARATIONS -->
<!-- ============================================= -->
<!ELEMENT xmlelement (#PCDATA)* >    
<!ATTLIST xmlelement %univ-atts; outputclass CDATA #IMPLIED>
<!ELEMENT xmlelement (#PCDATA)*>
<!ATTLIST xmlelement %univ-atts; outputclass CDATA #IMPLIED>
<!ELEMENT xmlattribute (#PCDATA)*>
<!ATTLIST xmlattribute %univ-atts; outputclass CDATA #IMPLIED>
<!ELEMENT testentity (#PCDATA)*>
<!ATTLIST textentity %univ-atts; outputclass CDATA #IMPLIED>
<!ELEMENT parameterentity (#PCDATA)*>
<!ATTLIST parameterentity %univ-atts; outputclass CDATA #IMPLIED>
<!-- ============================================= -->
<!-- SPECIALIZATION ATTRIBUTE DECLARATIONS -->
<!-- ============================================= -->
<!ATTLIST xmlelement %global-atts; class CDATA "+ topic/keyword xmlmarkup-d/xmlelement ">
<!ATTLIST xmlattribute %global-atts; class CDATA "+ topic/keyword xmlmarkup-d/xmlattribute ">
<!ATTLIST textentity %global-atts; class CDATA "+ topic/keyword xmlmarkup-d/textentity ">
<!ATTLIST parameterentity %global-atts; class CDATA "+ topic/keyword xmlmarkup-d/parameterentity ">

Nachdem die mod-Datei für die neue Domain erstellt wurde, wird im zweiten Schritt die dazugehörende ent-Datei erstellt. Gehen Sie dabei wie folgt vor:

Erstellen Sie eine neue ent-Datei mit dem Namen xmlmarkupDomain.ent.
Fügen Sie folgende Deklarationen in die xmlmarkupDomain.ent-Datei ein:

<!ENTITY % xmlmarkup-d-keyword xmlelement | xmlattribute | textentity | parmenterentity“>

<!ENTITY xmlmarkup-d-att "(topic xmlmarkup-d)">

In der xmlmarkupDomain.ent-Datei wird eine Parameter-Entität deklariert, in der alle Elemente der neuen Domain aufgelistet werden. Zusätzlich wird eine Text-Entität definiert, die den Namen der neuen Domain festlegt.

Gemäß der DITA-Konvention wird der Name in der Form Modulname-d-att vergeben, hier also xmlmarkup-d-att.

Das Schlüsselwort topic zeigt an, dass es sich um eine Topic-Domain handelt. Mit dem Schlüsselwort map würde angezeigt werden, dass es sich um eine Map-Domain handelt. Der Name des Moduls ist hier xmlmark-up-d. Dieser Name wurde bereits in den Definitionen der class-Attribute in der xmlmarkupDomain.mod-Datei verwendet.

Mit den in DITA üblichen Überschriften in den ent-Dateien sieht die xmlmarkupDomain.ent-Datei wie folgt aus:

<!--================================================== -->
<!-- ELEMENT EXTENSION ENTITY DECLARATIONS -->
<!-- ================================================= -->
<!ENTITY % xmlmarkup-d-keyword "xmlelement | xmlattribute | textentity | parmenterentity">
<!-- ================================================= -->
<!-- DOMAIN ENTITY DECLARATION -->
<!-- ================================================= -->
<!ENTITY xmlmarkup-d-att "(topic xmlmarkup-d)" >

Nachdem die xmlmarkupDomain.mod-Datei und die xmlmarkupDomain.ent-Datei fertiggestellt sind, gilt es, diese beiden Dateien in eine Mantel-DTD zu integrieren. Bei der Integration muss die Reihenfolge, mit der die beiden Dateien integriert werden, beachtet werden. In einer DTD wird bei mehreren Entitäts-Deklarationen stets die erste Deklaration einer Entität verwendet, das heißt, die nachfolgenden Entitäts-Deklarationen werden vernachlässigt. Dies gilt es zu beachten, wenn Entitäten verwendet werden, die in weiteren Dateien eingeschlossen sind und überschrieben werden sollen.

Daher wird zunächst die ent-Datei in die Mantel-DTD importiert. Diese enthält die modulspezifischen Entitätsdeklarationen, die die Standard-Definitionen in den mod-Dateien überschreibt. Danach wird die mod-Datei in die Mantel-DTD importiert. In ihr sind die Parameter-Entitäten der Elemente mit den Attributlisten enthalten.

Gehen Sie bei der Erstellung einer Mantel-DTD wie folgt vor:

Erstellen Sie eine Kopie der concept.dtd-Datei und vergeben Sie der Kopie einen neuen Namen, zum Beispiel domain_concepts.dtd.
Fügen Sie im DOMAIN ENTITY DECLARATIONS-Abschnitt die Parameter-Entität zur xmlmarkupDomain.ent-Datei ein.

<!ENTITY % xmlmarkup-d-dec SYSTEM "xmlmarkupDomain.ent">
%xmlmarkup-d-dec;

Fügen Sie im DOMAIN EXTENSIONS-Abschnitt die Parameter-Entität xmlmarkup-d-keyword hinzu. Die Parameter-Entität xmlmarkup-d-keyword wurde in der markupDomain.ent-Datei definiert.

<!ENTITY % keyword "keyword | %xmlmarkup-d-keyword;">

Da das <keyword>-Element spezialisiert wurde, muss im DOMAIN EXTEN-SIONS-Abschnitt die % keyword-Parameter-Entität modifiziert werden.

Fügen Sie im DOMAINS ATTRIBUTE OVERRIDE-Abschnitt die Parameter-Entität für den Domainnamen ein. Der Name der Domain wurde in der xmlmarkupDomain.ent-Datei definiert.

<!ENTITY included-domains "&ui-d-att; &hi-d-att; &prd-att; &sw-d-att; &ut-d-att; &indexing-d-att; &xmlmarkup-d-att;">

Fügen Sie folgenden Eintrag in den DOMAIN ELEMENT INTEGRATION-Abschnitt der Mantel-DTD ein:

<!ENTITY % xmlmarkup-d-def SYSTEM "xmlmarkup.mod">
%xmlmarkup-d-def;

Dabei entspricht der vergebene Name xmlmarkup-d-def den Konventionen in DITA, bei dem mit -d eine Domain und mit -def eine Definition angezeigt wird. Mit den in DITA üblichen Überschriften finden sich dann in einer Mantel-DTD die folgenden Einträge, die die Domain-Spezialisierung betreffen:

<!-- ============================================= -->
<!-- DOMAIN ENTITY DECLARATIONS -->
<!-- ============================================= -->
<!ENTITY % xmlmarkup-d-dec SYSTEM "xmlmarkupDomain.ent">
%xmlmarkup-d-dec;
<!-- ================================================= -->
<!-- DOMAIN EXTENSIONS -->
<!-- ================================================= -->
<!ENTITY % keyword "keyword | %xmlmarkup-d-keyword;">
<!-- ================================================= -->
<!-- DOMAIN EXTENSIONS -->
<!-- ================================================= -->
<!ENTITY included-domains "&ui-d-att; &hi-d-att; &pr-datt; &sw-d-att; &ut-d-att; &indexing-d-att; &xmlmarkup-d-att;">
<!-- ================================================= -->
<!-- DOMAIN ELEMENT INTEGRATION -->
<!-- ================================================= -->
<!ENTITY % xmlmarkup-d-def SYSTEM "xmlmarkup.mod">
%xmlmarkup-d-def;

XSLT-Stylesheets anpassen

Im folgenden Beispiel wird gezeigt, wie die XSLT-Stylesheets für die Produktion von XHTML-Dateien verändert werden müssen, damit sie die spezialisierten Elemente <xmlelement>, <xmlattribute>, <textentity> und <parameterentity> aus dem letzten Abschnitt verarbeiten können.

Im xsl-Verzeichnis des DITA Open Toolkits liegen die XSLT-Stylesheets, die die Produktion der einzelnen Ausgabemedien steuern. Für die Produktion von XHTML-Dateien ist die dita2xhtml.xsl-Datei zuständig.

In einem neu erstellten XSLT-Stylesheet, in welchem die XSLT-Templates zur Verarbeitung der spezialisierten Elemente definiert werden, wird die dita2xhtml.xsl-Datei importiert. Damit wird die bestehende Verarbeitung durch neue Verarbeitungsregeln ergänzt.

Im Einzelnen sind folgende Schritte notwendig, um ein XSLT-Stylesheet für die Verarbeitung von spezialisierten Elementen erstellen zu können:

Erstellen Sie ein XSLT-Stylesheet, das die dita2xhtml.xsl-Datei importiert.
Definieren Sie die XSLT-Templates, damit die gewünschte Ausgabe für die spezialisierten Elemente erzeugt wird.
Erzeugen Sie bei Bedarf ein CSS, mit dem die transformierten Elemente in XHTML formatiert werden können.

Im folgenden Beispiel sollen alle spezialisierten Elemente mit dem HTML-Element <code> ausgegeben werden. Beim <xmlelement>-Element soll zusätzlich noch vor dem Inhalt eine geöffnete spitze Klammer (<) und nach dem Inhalt eine geschlossene spitze Klammer (>) ausgegeben werden. Für das <textentity>-Element soll vor dem Inhalt ein kaufmännisches Und (&) und nach dem Inhalt ein Semikolon (;) ausgegeben werden. Für das <parameterentity>-Element soll vor dem Inhalte ein Prozentzeichen (%) und nach dem Inhalt ein Semikolon (;) ausgegeben werden.

Da in diesem XSLT-Stylesheets keine Klassen für ein CSS produziert werden, wird nachfolgend auch kein CSS definiert.

Gehen Sie bei der Erstellung des XSLT-Stylesheets wie folgt vor:

Erstellen Sie das folgende leere XSLT-Stylesheet mit dem Namen xmlmark-up2html.xsl.

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE xsl:stylesheet [
!ENTITY gt "&gt;">
<!ENTITY lt "&lt;">
<!ENTITY rbl " ">
<!ENTITY nbsp "&#xA0;">
<!ENTITY quot "&#34;">
<!ENTITY copyr "&#169;">
]>

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:param name="toolkitDir" select="'file:///c:/ditaot14/'"/>
  <xsl:import href="{$toolkitDir}xsl/dita2xhtml.xsl"/>
</xsl:stylesheet>

In der Deklaration des XSLT-Stylesheets ist der Pfad zum Installationsverzeichnis des DITA Open Toolkits angegeben, hier c:/ditaot14.

Speichern Sie das XSLT-Sytlesheet in einem Verzeichnis außerhalb des Installationsverzeichnisses des DITA Open Toolkits ab.
Erstellen Sie das XSLT-Template für die Verarbeitung des <xmlelement>-Elements wie folgt:

<xsl:template match="*[contains(@class, ' xmlmarkup-d/xmlelement ')]" priority="10">
    <code>
        <xsl:text>&lt;</xsl:text>
        <xsl:apply-templates/>
        <xsl:text>&gt;</xsl:text>
    </code>
</xsl:template>

Erstellen Sie das XSLT-Template für die Verarbeitung des <xmlattribute>-Elements wie folgt:

<xsl:template match="*[contains(@class, ' xmlmarkup-d/xmlattribute ')]" priority="10">
    <code>
        <xsl:apply-templates/>
    </code>
</xsl:template>

Erstellen Sie das XSLT-Template für die Verarbeitung des <textentity>-Elements wie folgt:

<xsl:template match="*[contains(@class, ' xmlmarkup-d/textentity ')]" priority="10">
    <code>
        <xsl:text>&</xsl:text>
        <xsl:apply-templates/>
        <xsl:text>;</xsl:text>
    </code>
</xsl:template>

Erstellen Sie das XSLT-Template für die Verarbeitung des <parameterentity>-Elements wie folgt:

<xsl:template match="*[contains(@class, ' xmlmarkup-d/parameterentity ')]" priority="10">
    <code>
        <xsl:text>%</xsl:text>
        <xsl:apply-templates/>
        <xsl:text>;</xsl:text>
    </code>
</xsl:template>

Damit sieht das XSLT-Stylesheet xmlmarkup2html.xsl wie folgt aus:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE xsl:stylesheet [
!ENTITY gt "&gt;">
<!ENTITY lt "&lt;">
<!ENTITY rbl " ">
<!ENTITY nbsp "&#xA0;">
<!ENTITY quot "&#34;">
<!ENTITY copyr "&#169;">
]>

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:param name="toolkitDir" select="'file:///c:/ditaot14/'"/>
    
    <xsl:import href="{$toolkitDir}xsl/dita2xhtml.xsl"/>
    
    <xsl:template match="*[contains(@class, ' xmlmarkup-d/xmlelement ')]" priority="10">
        <code>
            <xsl:text>&lt;</xsl:text>
            <xsl:apply-templates/>
            <xsl:text>&gt;</xsl:text>
        </code>
    </xsl:template>
    <xsl:template match="*[contains(@class, ' xmlmarkup-d/xmlattribute ')]" priority="10">
        <code>
            <xsl:apply-templates/>
        </code>
    </xsl:template>
    <xsl:template match="*[contains(@class, ' xmlmarkup-d/textentity ')]" priority="10">
        <code>
            <xsl:text>&</xsl:text>
            <xsl:apply-templates/>
            <xsl:text>;</xsl:text>
        </code>
    </xsl:template>
</xsl:stylesheet>
<xsl:template match="*[contains(@class, ' xmlmarkup-d/parameterentity')]" priority="10">
    <code>
        <xsl:text>%</xsl:text>
        <xsl:apply-templates/>
        <xsl:text>;</xsl:text>
    </code>
</xsl:template>

Sie können dieses XSLT-Stylesheet testen, indem Sie mittels der domain_concepts.dtd-Datei aus dem letzten Abschnitt eine XML-Datei erstellen und das neu erstellte XSLT-Stylesheet zur Produktion von XHMTL verwenden. Weitrere Informationen zur Produktion von XHTML-Dateien erhalten Sie in ANT.

<< zurück

vor >>