Flexible Erweiterbarkeit mit DITA

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

Die flexible Architektur von DITA basiert auf zwei Grundpfeilern:

  • Die Definition der Informationsstrukturen, das heißt, der Domains, Topics und Maps ist in DITA modular aufgebaut.
  • Die Verarbeitungsprozesse sind so konzipiert, dass sie auch Elemente verarbeiten können, die aus den bestehenden Informationsstrukturen neu abgeleitet worden sind.

Die beiden Eigenschaften der DITA-Architektur ermöglichen es, die Informationsstrukturen über den Mechanismus der Spezialisierung zu erweitern oder auch zu reduzieren.

Im folgenden Abschnitt werden zunächst die Informationsstrukturen von DITA im einzelnen vorgestellt. Wie zu erkennen ist, wird maximale Modularität angestrebt, um auch die Wiederverwendung der Informationsstrukturen zu ermöglichen.

Danach werden dann einige Regeln vorgestellt, die bei der Spezialisierung von Topics, Maps und Domains zu beachten sind. Insbesondere gilt es zu berücksichtigen, dass eine spezialisierte DITA-Informationsstruktur wieder eine DITA-konforme Informationsstruktur generiert.

Im vorletzten Abschnitt wird darauf eingegangen, was eine Spezialisierung für die Produktionsprozesse bedeutet, die über das DITA Open Toolkit laufen.

Im letzen Abschnitt schließlich wird gezeigt, welche neuen Wege DITA, abseits der Software-Dokumentation, inzwischen beschreitet.

Informationsstrukturen in DITA

Die Informationsstrukturen von DITA sind nicht in einer einzigen DTD erfasst, sondern in einer Vielzahl von DTDs, Moduldateien und Entity-Dateien.

Zu jeder DTD in DITA gehört eine Moduldatei, in der die Elemente für die DTD definiert sind. So sind beispielsweise in der task.mod-Datei die Elemente des Topictyps „Aufgabe“ definiert, der über die task.dtd erstellt werden kann. Mit DTDs werden Topic- und Maptypen definiert.

Die semantischen Auszeichnungen, die thematisch in Domains gruppiert sind, werden in einer Moduldatei referenziert und in einer entsprechenden Entity-Datei definiert. So sind beispielsweise in der uiDomain.mod-Datei die Entitätsreferenzen auf die Elemente der user interface-Domain enthalten, die in der Entity-Datei uiDomain.ent definiert sind.

In DITA 1.1 stehen folgende Dateien zur Definition von Informationsstrukturen zur Verfügung:

  • topic.dtd: Mantel-DTD für das generische Topic.
  • topic.mod: Enthält die Definition der Elemente des generischen Topics.
  • topicDefn.ent: Enthält Entitäten des generischen Topics.
  • concept.dtd: Mantel-DTD für den Topictyp „Konzept“.
  • concept.mod: Enthält die Definition der Elemente des Topictyps „Konzept“.
  • task.dtd: Mantel-DTD für den Topictyp „Aufgabe“.
  • task.mod: Enthält die Definition der Elemente des Topictyps „Aufgabe“.
  • reference.dtd: Mantel-DTD für den Topictyp „Referenz“.
  • reference.mod: Enthält die Definition der Elemente des Topictyps „Referenz“.
  • glossary.dtd: Mantel-DTD für den Topictyp „Glossar“.
  • glossary.mod: Enthält die Definition der Elemente des Topictyps „Glossar“.
  • map.dtd: Mantel-DTD für die Map.
  • map.mod: Enthält die Definition der Elemente für eine Map.
  • mapGroup.mod: Enthält die Definition der Elemente zur Gruppierung von Topics in einer Map.
  • mapGroup.ent: Enthält die Entity-Deklaration der Elemente zur Gruppierung von Topics in einer Map.
  • bookmap.dtd: Mantel-DTD für die Bookmap.
  • bookmap.mod: Enthält die Definition der Elemente der Bookmap.
  • ditabase.dtd: Mantel-DTD für alle Topictypen und Domains.
  • commonElements.mod: Enthält die Definition der Elemente, die in allen Topictypen verwendet werden können.
  • commonElements.ent: Enthält die Parameter-Entitäten der Elemente, die in der commonElements.ent-Datei definiert sind.
  • highlightDomain.mod: Enthält die Definition der Elemente der highlighting-Domain.
  • highlightDomain.ent: Enthält die Parameter-Entitäten der highlighting-Domain.
  • indexing.mod: Enthält die Definition der Elemente der indexing-Domain.
  • indexing.ent: Enthält die Parameter-Entitäten der indexing-Domain.
  • programmingDomain.mod: Enthält die Definition der Elemente der programming-Domain.
  • programmingDomain.ent: Enthält die Parameter-Entitäten der programming-Domain.
  • softwareDomain.mod: Enthält die Definition der Elemente der software-Domain.
  • softwareDomain.ent: Enthält die Parameter-Entitäten der software-Domain.
  • uiDomain.mod: Enthält die Definition der Elemente der user interface-Domain.
  • uiDomain.ent: Enthält die Parameter-Entitäten der user interface-Domain.
  • utilitiesDomain.mod: Enthält die Definition der Elemente der utilities-Domain.
  • utilitiesDomain.ent: Enthält die Parameter-Entitäten der utilities-Domain.
  • xnalDomain.mod: Enthält die Definition der Elemente der xNAL-Domain.
  • xnalDomain.ent: Enthält die Parameter-Entitäten der xNAL-Domain.

Topics und Maps spezialisieren

Werden neue Informationstypen benötigt, so werden dazu Topictypen oder Maptypen spezialisiert. Als Grundprinzip der Spezialisierung wurde bei DITA festgelegt, dass sich jeder spezialisierte Informationstyp auf die Ausgangsstruktur zurückführen lassen muss. Damit verbunden ist die Forderung, dass das Inhaltsmodell der spezialisierten Struktur restriktiver sein muss als die Ausgangsstruktur. Damit wird gewährleistet, dass die spezialisierten Strukturen nach wie vor von den XSLT-Stylesheets des DITA Open Toolkits verarbeitet werden können.

In der folgenden Tabelle sind alle erlaubten Spezialisierungen für mögliche Inhaltstypen innerhalb eines Inhaltsmodells aufgelistet. Zur Verdeutlichung ist für das übergeordnete Element der Elementname allgemein verwendet und für das spezialisierte Element der Elementname speziell.

Inhaltstyp

Erlaubte Spezialisierung

Beispiel

erforderlich

nur umbenennen

<!ELEMENT allgemein (a) >

<!ELEMENT speziell (a.1) >

optional (?)

umbenennen,
erforderlich sein,
löschen

<!ELEMENT allgemein (a?) >

<!ELEMENT speziell (a.1?) >
<!ELEMENT speziell (a.1) >
<!ELEMENT speziell EMPTY >

beliebig häufig (ausschließlich einmal) (+)

umbenennen,
erforderlich sein,
teilen in ein erfordliches Element und weitere Elemente,
teilen in ein oder mehrere Elemente und weitere Elemente

<!ELEMENT allgemein (a+) >

<!ELEMENT speziell (a.1+) >
<!ELEMENT speziell (a.1) >
<!ELEMENT speziell (a.1,a.2,a.3+,a.4*) >
<!ELEMENT speziell (a.1+,a.2,a.3+) >

beliebig häufig (einschließlich keinmal) (*)

umbenennen,
erforderlich sein,
optional sein,
teilen in ein erforderliches Element und weitere Elemente,
teilen in ein optionales Element und weitere Elemente,
teilen ein oder mehrere Elemente und weitere Elemente,
teilen in kein oder mehrere Elemente und weitere Elemente,
löschen

<!ELEMENT allgemein (a+) >

<!ELEMENT speziell (a.1+) >
<!ELEMENT speziell (a.1) >

<!ELEMENT speziell (a.1?) >

<!ELEMENT speziell (a.1,a.2,a.3+,a.4*) >

<!ELEMENT speziell (a.1?,a.2,a.3+,a.4*) >

<!ELEMENT speziell (a.1+,a.2,a.3*) >

<!ELEMENT speziell (a.1+,a.2?,a.3*) >
<!ELEMENT speziell EMPTY >

Auswahl (entweder-oder) (|)

umbenennen
eines auswählen

<!ELEMENT allgemein (a|b) >

<!ELEMENT speziell (a.1|b.1) >
<!ELEMENT speziell (a.1) >

Tabelle: Regeln für die Spezialisierung von Inhaltstypen

Eine wesentliche Komponente bei der Spezialisierung von Topics und Maps stellt das class-Attribut dar. Wird ein spezialisiertes Elemente definiert, so wird im class-Attribut festgelegt, wie die Zuordnung vom spezialisierten zum übergeordneten Element definiert ist.

Am Beispiel des <reference>-Elements soll der Aufbau des class-Attributs erläutert werden. Der Topictyp „Referenz“ ist eine Spezialisierung des generischen Topictyps. Bei der Spezialisierung wurde das <topic>-Element zum <reference>-Element spezialisiert. Das class-Attribut wird dann für das <reference>-Element wie folgt definiert:

<!ATTLIST reference class CDATA "- topic/topic reference/reference ">

Mit <!ATTLIST reference> werden die Attribute zum <reference>-Element definiert. Der Name des Attributs ist class mit dem Datentyp CDATA. Der Wert des class-Attributs steht zwischen den beiden Anführungsstrichen, das heißt, er beginnt mit einem Minuszeichen (), was anzeigt, dass hier ein class-Attribut für ein Topic definiert wird. Danach folgt ein Leerzeichen. Nach dem Leerzeichen folgt der Topictypname und der Elementname der übergeordneten Informationsstruktur getrennt durch einen Schrägstrich (/). Die übergeordnete Informationsstruktur des Topictyps „Referenz“ ist das generische Topic, dessen Topictypname topic lautet. Der Elementname lautet auch topic und bezeichnet den Namen Wurzel-Element des generischen Topics, das spezialisiert wird. Nach einem Leerzeichen folgt der Topictypname und der Elementname der spezialisierten Informationsstruktur. Der Topictypname ist reference und das aus dem <topic>-Element spezialisierte Element trägt den Namen reference. Nach Abschluss der Definition der Zuordnungen folgt wieder ein Leerzeichen. Dieses darf nicht vergessen werden.

Die Werte des class-Attributs werden in den XSLT-Stylesheets in den dortigen match-Attributen verwendet, um die Elemente und ihre Spezialisierungen verarbeiten zu können.

Mit den Regeln, die für die Spezialisierung von Inhaltsmodellen gelten, und die Definition der class-Attribute ist die praktische Vorgehensweise bei einer Spezialisierung jedoch noch nicht geklärt. Hier empfiehlt sich folgende Vorgehensweise:

  1. Erstellen Sie ein Modell-Dokument, dass später mit dem spezialisierten Topictyp erstellt werden kann.
  2. Legen Sie fest, aus welchen Elementen die neuen Elemente spezialisiert werden sollen. Leiten Sie später daraus die Werte für die class-Attribute ab. Beachten Sie, dass nur aus vorhandenen Elementen neue Elemente spezialisiert werden können. Definieren Sie Elemente, die sich nicht aus bekannten Elementen spezialisieren lassen, so sind die daraus resultierenden DTDs keine DITA DTDs mehr, die mit dem DITA Open Toolkit verarbeitet werden können. Gerade im Zusammenhang mit dem Wissen über den Mechanismus der Spezialisierung wird oftmals die Hoffnung gehegt, sich von der topicbasierten Struktur von DITA lösen und eigene Strukturen etablieren zu können, die zwar auf DITA basieren, aber eben doch nicht ganz DITA sind. Mit einer Spezialisierung ist dies nicht möglich. Das Ergebnis einer Spezialisierung ist immer eine DITA-konforme Informationsstruktur.
  3. Definieren Sie für einen neuen Topictyp das Inhaltsmodell gemäß den in diesem Abschnitt aufgeführten Regeln.
  4. Führen Sie den „mechanischen“ Teil der Spezialisierung durch, das heißt die Erstellung der DTD und der Moduldatei, wie in „Spezialisierung“ beschrieben.
  5. Testen Sie Ihr Modell-Dokument mit der spezialisierten DTD.

In der Praxis erweisen sich die ersten drei Schritte am zeitaufwändigsten. Ein passendes Modell-Dokument zu entwerfen erfordert in der Regel deutlich viel mehr Zeit als Erstellung der spezialisierten DTD und der Moduldatei.

Wenn man das Inhaltsmodell betrachtet, das DITA von Haus aus anbietet, so ist dieses, wenn DITA für die Software-Dokumentation eingesetzt wird, in der Regel viel zu umfangreich. Zudem werden viele Elemente angeboten, die in der täglichen Arbeit nicht benötigt werden und daher Ballast darstellen. Eine Spezialisierung kann hier sehr hilfreich sein. Dann dient eine Spezialisierung dazu, nicht neue Informationsstrukturen zu schaffen, sondern die bestehenden zu reduzieren. Dies kann die Arbeit eines Technischen Redakteurs wesentlich erleichtern.

Domains spezialisieren

In Domains werden Elemente thematisch gruppiert, die dazu dienen, Inhalte sowohl thematisch als auch typografisch auszeichnen zu können. Domains existieren unabhängig von den einzelnen Topictypen.

Auch unter den Elementen der Domains gibt es Elemente mit einem Inhaltsmodell. Wie bei den Elementen für Topics oder Maps gelten bei einer Spezial-isierung die Regeln für die Inhaltsmodelle, wie im letzten Abschnitt beschrieben.

Ebenso wie die Elemente zur Definition von Topics und Maps weisen die Elemente für Domains ein class-Attribut auf. Hier wird jedoch statt eines Minuszeichens () ein Pluszeichen (+) verwendet, um anzuzeigen, dass das class-Attribut zu einem Domain-Element gehört.

Das folgende Beispiel zeigt die Definition des class-Attributs für das <api-name>-Element, wobei das <apiname>-Element eine Spezialisierung des <keyword>-Elements darstellt:

<!ATTLIST apiname class CDATA "+ topic/keyword pr-d/apiname">

Der Wert des class-Attributs beginnt mit einem Pluszeichen (+) gefolgt von einem Leerzeichen. Danach folgt nach dem Schema Domainname/Elementname die Definition der Hierarchie der Informationsstruktur. Aufmerksamkeit verdient die Definition topic/keyword, denn mit topic sollte die topic-Domain bezeichnet werden. Jedoch gibt es eine topic-Domain im eigentlichen Sinne nicht. Aber in DITA gibt es einige Elemente zur semantischen Auszeichnung, wie das <keyword>-Element, das in keiner der bekannten Domains enthalten ist. Das <keyword>-Element sowie weitere Elemente sind in der commonElements.mod-Datei definiert, die dem generischen Topic zugeordnet sind. Daher herrscht bei diesen Elementen der Sprachgebrauch, dass sie zur topic-Domain gehören.

Mit pr-d/apiname wird das <apiname>-Element aus der programming-Domain bezeichnet. Nach Abschluss der Definition der Zuordnungen zwischen den Domains und den Elementen folgt wieder ein Leerzeichen, das auch hier nicht vergessen werden darf.

Sind neue Domains erstellt worden, so müssen sie in DTD integriert werden, damit die Inhalte mit den neuen Elementen ausgezeichnet werden können. Eine DTD in DITA legt nicht nur fest, welche Domains zur Verfügung stehen, sondern auch, welche Moduldateien, in denen die Elemente für die Topictypen definiert sind, verwendet werden sollen. Eine DTD, in der die Domains und Moduldateien zusammengestellt sind, bezeichnet man als Mantel-DTD. Der Prozess der Zusammenstellung wird auch als „Integration“ bezeichnet. Informationen zur Erstellung einer Mantel-DTD erhalten Sie in „Spezialisierung“.

Produktionsprozesse erweitern

Das DITA Open Toolkit ist in der Lage, spezialisierte Elemente zu verarbeiten, ohne dass für die spezialisierten Elemente Verarbeitungsanweisungen in den XSLT-Stylesheets vorhanden sein müssen. Dies ist die Folge der verwendeten class-Attribute in den Elementen.

Somit besteht zumindest nicht sofort die dringende Notwendigkeit, die XSLT-Stylesheets modifizieren zu müssen, wenn Topictypen oder Domains spezialisiert wurden. Wenn eine Anpassung dennoch notwendig sein sollte, ist eine entsprechende Methodik dafür vorgesehen.

Im Vergleich zum Methodik zur Anpassung der DTDs und Moduldateien erscheint der Methodik zur Anpassung des XSLT-Stylesheets als vergleichsweise schwerfällig und unübersichtlich.

Bei der Spezialisierung von DTDs und Moduldatein werden die ursprünglichen DITA-Informationsstrukturen als Vorlagen verwendet. Die Element-Definitionen der vorhandenen Elemente dienen als Vorlage für die Element-Definitionen der spezialisierten Elemente.

Bei den Verarbeitungsprozessen wurde diese Idee übernommen, sodass die XSLT-Templates der XSLT-Stylesheets als Vorlage dienen können. Nach einer entsprechenden Anpassung können die XSLT-Templates zur Verarbeitung der spezialisierten Elemente verwendet werden. In der Praxis erweist sich diese Methode jedoch als sehr mühselig. Zum einen ist es nicht ohne Weiteres ersichtlich, in welchem der vielen XSLT-Stylesheets des DITA Open Toolkits sich das gewünschte XSLT-Template befindet. Zum andern kann es unter Umständen große Schwierigkeiten bereiten, das passende XSLT-Template zu finden, das für die Verarbeitung des Elements zuständig ist, das spezialisiert werden soll. Erschwert wird die Suche nach den passenden XSLT-Stylesheets durch die Anzahl der Stylesheets für viele Ausgabemedien und durch die unterschiedlichen Anspassungsmechanismen für die Ausgabemedien.

Das DITA Open Toolkit lässt hier ein einheitliches Konzept vermissen. Gerade bei den XSLT-Stylesheets zur Produktion von PDF-Dateien wirkt sich der Mangel am deutlichsten aus. Eine einheitliche Strategie, wie sie bei der Spezialisierung von DTDs und Moduldateien möglich ist, sucht man bei den XSLT-Stylesheets vergeblich.

DITA ist ein sehr „lebhafter“ Standard, sodass hier bereits an einer Lösung gearbeitet wird. Zu wünschen wäre, dass auch die XSLT-Stylesheets für andere Ausgabemedien von den neu gewonnenen Erkenntnissen profitieren.

  

<< zurück vor >>

 

 

 

Tipp der data2type-Redaktion:
Zum Thema DITA bieten wir auch folgende Schulungen zur Vertiefung und professionellen Fortbildung an:

Copyright © 2008 XLcontent Verlag
Für Ihren privaten Gebrauch dürfen Sie die Online-Version ausdrucken.
Ansonsten unterliegt dieses Kapitel aus dem Buch "DITA - Der neue Standard für Technische Dokumentation" denselben Bestimmungen, wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.

XLcontent Verlag, Pflegerstraße 40, 81247 München