XML Entwicklerhandbuch

3.5.1 DITA

DITA ↗ ist so ein Standard für die Technische Dokumentation. Allgemeine Teile können von allen Systemen verarbeitet werden - also alle Teile der Information, die für die Aussenwelt verfügbar gemacht werden sollen, das ist z.B. eine Zulieferdokumentation für bestimmte Maschinenbauteile.

Spezifische Information, wie z.B. Referenzen in eine interne Datenbank, würde dagegen ein externer DITA Prozessor entweder verschlucken oder anderweitig kennzeichnen - je nachdem wie die Abarbeitung von unbekannten Elementen im externen System realisiert ist.

3.5.1.1 DITA vs Docbook

Grob betrachtet ähnelt die DITA Struktur derer von Docbook ↗. Sie hat die typische Kapitelverschachtelung.

Zum Vergleich ist im folgenden ein Docbook Grundgerüst und ein DITA Grundgerüst (Wikipedia) abgebildet.

Docbook Grundgerüst

<book id="einfaches_buch"
    <title>Ein sehr einfaches Buch</title>
    <chapter id="einfaches_kapitel">
        <title>Kapitel</title>
        <para>Hallo Welt!</para>
    </chapter>
</book>

DITA Grundgerüst

<topic id="maintaining" xml:lang="en-us">
   <title>Maintaining</title>
   <shortdesc>
      You maintain your solution to ensure that all components 
      are operating at maximum efficiency.
   </shortdesc>
   <body>
      <p>
         Maintenance is a task that you perform along 
	 with configuration to get the most from your solution.
      </p>
   </body>
</topic>

Während beim Docbook Standard noch ein Element <book> die einzelnen Kapitel klammert, ist die Vorgehensweise beim DITA Standard topic-basiert - Stichwort: Topic Based Authoring.

Hier konzentriert sich der Redakteur nicht mehr so sehr auf das Buch als Ganzes, sondern mehr auf die Abgeschlossenheit und Referenzierbarkeit der einzelnen Topics (= Informationseinheiten), um diese in einer anderen Publikation ggf. in einem anderen Format (Online, Print, Smartphone) leicht wiederverwenden zu können.

Im obigen XML Schnippsel vermutet man z.B., dass das Element <shortdesc> in einer elektronischen Publikation auf einer Übersichtsseite angezeigt werden könnte ( - um die Referenz zum eigentlichen Topic zu charakterisieren), während in einer Print-Publikation diese Information als einleitender Kurztext gedruckt werden könnte.

Was ist aber nun der Clou beim DITA Standard? Dokumenttyp Definitionen (DTDs), die einige Elemente umbenennen und ein paar semantische Besonderheiten bereitstellen, gibt es viele.

3.5.1.2 Der Clou bei DITA

Ich denke, das Besondere bei DITA sind ein paar technische Kniffe, die eine gewisse Generizität des Ansatzes realisieren. Wenn wir im obigen XML Schnippsel noch die DTD mit angeben:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic SYSTEM "ditadtd/topic.dtd">
<topic id="maintaining" xml:lang="en-us">
   [...]
</topic>

und eine Identity-Transformation ausführen, so sind magischerweise weitere Attribute hinzugekommen, vgl.

<?xml version="1.0" encoding="UTF-8"?>
<topic xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/" 
       id="maintaining" xml:lang="en-us" 
       ditaarch:DITAArchVersion="1.3" 
       domains="(topic ui-d) (topic hi-d) (topic pr-d) (topic sw-d) 
               (topic ut-d) (topic indexing-d)" 
       class="- topic/topic ">
    <title class="- topic/title ">Maintaining</title>
    <shortdesc class="- topic/shortdesc ">
        You maintain your solution to ensure that all components 
        are operating at maximum efficiency.
    </shortdesc>
    <body class="- topic/body ">
        <p class="- topic/p ">
            Maintenance is a task that you perform along 
            with configuration to get the most from your solution.
        </p>
    </body>
</topic>

Besonders interessant ist hier das @class Attribut. Wie ist das nun passiert?

DITA definiert eine Reihe von #FIXED Attributen ↗ mit einem festen Wert, die der Parser beim Validieren automatisch an die Elemente hängen muss. Ungeparst sieht ein Topic recht einfach aus. Geparst kann das DITA XML dagegen recht aufgebläht wirken.

XSLT Regeln in einem DITA Prozessor matchen nun nicht auf die Elementnamen, sondern auf die @class Attribute, z.B. so:

<xsl:template match="*[contains(@class,' topic/topic ')]/
                     *[contains(@class,' topic/title ')]">
[...]

Hier soll der Titel des Topics formatiert werden. In einer Spezialisierung ↗ des Topics - das wäre z.B. ein Concept:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="concept_kl3_knd_f3b">
    <title>My concept</title>
    <shortdesc>Just a concept to illustrate specialization</shortdesc>
    <conbody>
        <p>Yeah, we need some content here, too!</p>
    </conbody>
</concept>

werden nun die #FIXED Attribute folgendermassen gesetzt:

<?xml version="1.0" encoding="UTF-8"?>
<concept xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/" 
         id="concept_kl3_knd_f3b" 
         ditaarch:DITAArchVersion="1.3" 
         class="- topic/topic concept/concept ">
    <title class="- topic/title ">My concept</title>
    <shortdesc class="- topic/shortdesc ">Just a concept to 
        illustrate specialization</shortdesc>
    <conbody class="- topic/body  concept/conbody ">
        <p class="- topic/p ">Yeah, we need some content here, too!</p>
    </conbody>
</concept>

Unsere Regel von oben mit

<xsl:template match="*[contains(@class,' topic/topic ')]/
                     *[contains(@class,' topic/title ')]">
[...]

die einen Titel formatiert, würde also sowohl für Topic-Elemente, als auch für Concept-Elemente gelten. Will man eine Spezialformatierung für Concept-Elemente, so müsste man die folgende Regel noch zur Regelbasis mithinzunehmen:

<xsl:template match="*[contains(@class,' concept/concept ')]/
                     *[contains(@class,' topic/title ')]">
[...]

Warum ist das Ganze nun so clever? Wenn bspw. Firma XYZ noch keine Concept-Definitionen erstellt hat, kann sie trotzdem Concept-Elemente der Firma ABC verarbeiten, weil die Match-Regeln nicht auf Elementnamen operieren, sondern auf dynamisch durch die DTD hinzugefügte Klassenattribute - die neben der Bezeichner der Spezialisierung auch die Bezeichner der Generalisierung enthalten. Diese kennt jeder DITA Prozessor und kann zumindest einen Default bereitstellen.

Für obiges Beispiel - bzgl. des Titels - würde das bedeuten, dass der Concept-Titel in Firma XYZ nicht so schön (oder an einer bestimmten Stelle) dargestellt wird, wie er in Firma ABC angedacht war. Der wichtige Content wird aber trotzdem dargestellt.

Die Referenzimplementierung für DITA ist übrigens das DITA Open Toolkit ↗

Das Erstellen einer redundanzarmen DITA DTD ist allerdings eine Wissenschaft für sich. Schliesslich will man ja auch für eigene Spezialisierungen den generischen Ansatz beibehalten. Der DITA Redakteur oder besser der Dokumentationsbeauftragte muss sich deshalb einer ziemlich komplizierten Namens- und Strukturkonvention unterziehen.