Maps

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

Maps sind in DITA die Informationsstruktur, mit der Sie Topics organisieren können. In Maps werden Topics über Referenzierungen sowohl in ihrer Reihenfolge als auch in ihrer Hierarchie zusammengestellt.

In den folgenden Abschnitten erfahren Sie, wie Sie

• Topics in Map referenzieren,
• Beziehungstabellen aufbauen,
• Meta-Daten vergeben,
• und mit Attributen die Verarbeitung von Maps steuern können.

Topics in Maps referenzieren

Mit einer Map werden Topics organisiert und in eine hierarchische Struktur gebracht. Dabei werden die Topics in einer Map referenziert. Eine Map ist auch der Ausgangspunkt für die Erstellung eines Inhaltsverzeichnisses oder der Navigation für eine Online-Hilfe.

Die Grundstruktur einer Map sieht wie folgt aus:

Eine Map-Datei ist eine XML-Datei und beginnt daher mit einer XML- und einer DOCTYPE-Deklaration. In der DOCTYPE-Deklaration wird die map.dtd-Datei referenziert, die wiederum auf die map.mod-Datei verweist, in der die Elemente für die Map definiert sind.

Eine Map wird durch das Wurzel-Element <map> identifiziert. Um eine Map eindeutig referenzieren zu können, muss der Map eine ID zugeordnet werden.

Über das <title>-Element kann der Map ein Titel vergeben werden. Der Titel wird bei Online-Hilfen im Fenstertitel und bei PDF-Dateien auf dem Deckblatt angezeigt.

Eine Map-Datei wird durch die Dateiendung .ditamap identifiziert. Viele XML-Editoren, die DITA unterstützen, fügen diese Dateiendung beim erstmaligen Abspeichern einer Map automatisch hinzu.

Topics werden über das <topicref>-Element referenziert. Im href-Attribut, wie es aus dem <a>-Element von HTML her bekannt ist, wird auf ein Topic verwiesen.

Soll beispielsweise die Datei maps_erstellen.xml referenziert werden, die im gleichen Verzeichnis wie die Map-Datei liegt, so wird das <topicref>-Element wie folgt verwendet:

 <topicref href="maps_erstellen.xml"/> 

das heißt, die Map-Datei sieht dann wie folgt aus:

<topicref>-Elemente können Sie in beliebiger Tiefe verschachteln, das heißt, ein <topicref>-Element kann weitere <topicref>-Elemente enthalten. Auf diese Weise kann eine Hierarchie aufgebaut werden, wie sie von klassischen Inhaltsverzeichnissen her bekannt ist.

Ist in einem <topicref>-Element kein weiteres <topicref>-Element verschachtelt, so kann wie in dem obigen Beispiel die Kurzschreibweise

 <topicref href="maps_erstellen.xml"/> 

statt

 <topicref href="maps_erstellen.xml"></topicref> 

verwendet werden. Der / (slash) vor der schließenden spitzen Klammer zeigt an, dass es sich um ein leeres Element handelt.

Die Verschachtelung von <topicref>-Elementen soll am Beispiel der Topics, aus denen "Maps" aufgebaut ist, demonstriert werden. Die einzelnen Unterabschnitte sind in separate DITA XML-Dateien abgespeichert, wobei diese beispielsweise den Topictyp „Konzept“ enthalten können:

• topics_in_maps_referenzieren.xml
• meta-daten_fuer_maps.xml
• map_attribute.xml
• das_chunk_attribut.xml

Diese vier Dateien befinden sich in der Hierarchie unter der Datei maps_erstellen.xml. Somit sieht die Map-Datei wie folgt aus:

Das DITA Open Toolkit sorgt bei der Generierung des entsprechenden Ausgabemediums dafür, dass die Hierarchie sich im Inhaltsverzeichnis oder in der dem Ausgabemedium angepassten Navigationsstruktur wiederfindet. Als Titel für die Navigation werden dabei die Inhalte der <title>-Elemente oder der <navtitle>-Elemente aus den referenzierten Topics verwendet.

Durch das Hinzufügen weiterer <topicref>-Elemente kann die Hierarchie weiter ausgebaut werden:

Wie sich bei dem Beispiel zeigt, ist die Wiederverwendung von Topics in Maps ohne Weiteres zu realisieren. Das <topicref>-Element mit der Referenz zu dem Topic, das mehrmals in einer Map referenziert werden soll, wird einfach an die gewünschte Stelle in der Hierarchie kopiert.

Innerhalb einer Map können Sie die zudem <topicref>-Elemente gruppieren. Dies geschieht über das <topicgroup>-Element. Die Gruppierung hat keinen Einfluss auf die Hierarchie in der Map. Bei einer Gruppierung werden die Attribute des <topicgroup>-Elements an die eingefassten <topicref>-Elemente vererbt.

Soll in einer Map nur der nicht verlinkte Titel eines Topics aufgenommen werden, dann steht dazu das <topichead>-Element zur Verfügung. Das
<topichead>-Element können Sie beispielsweise dann verwenden, wenn Sie in die Navigation einen Titel aufnehmen wollen, der nicht verlinkt sein soll.

Beziehungstabellen

Um die Beziehung der Topics untereinander darstellen zu können, stellt DITA so genannte Beziehungstabellen (relationship tables) zur Verfügung. Eine Beziehungstabelle wird mit dem <reltable>-Element definiert, das innerhalb des <map>-Elements platziert wird.

Mit dem <relheader>-Element definieren Sie den Tabellenkopf einer Beziehungstabelle. Im <realheader>-Element wird über die Anzahl der <relcolspec>-Elemente die Anzahl der Spalten festgelegt. Im Tabellenkopf gibt es nur eine Zeile. Im <relcolspec>-Element können Sie mit dem type-Attribut angegeben, was für ein Topictyp in der Spalte aufgelistet wird. Werte für das type-Attribut sind concept, task, reference sowie topic.

Zur Definition einer Zeile in der Beziehungstabelle wird das <relrow>-Element verwendet.

Jede Spalte ist durch das <relcell>-Element festgelegt. Das Topic, welches in einer Zelle über das <topicref>-Element referenziert wird, steht in Beziehung zu den anderen Topics, die in der Zeile aufgelistet sind.

Eine komplette Beziehungstabelle weist dann zum Beispiel folgende Struktur auf:

In der Darstellung sieht diese Beziehungstabelle wie folgt aus:

Enthält eine Beziehungstabelle mehrere Zeilen, so sind die Beziehungen der Topics untereinander nur für die entsprechende Zeile definiert. Beziehungen über Zeilen hinweg zu definieren ist mit Beziehungstabellen nicht möglich.

Wie in dem Beispiel angegeben, können in einer Zelle auch mehrere Topics angegeben werden. Standardmäßig wird bei DITA davon ausgegangen, dass die Topics in einer Zelle nicht miteinander in Beziehung stehen. Ist jedoch eine Beziehung vorhanden, so können Sie die <topicref>-Elemente mit dem <topicgroup>-Element gruppieren. Mit dem collection-type-Attribut können Sie spezifizieren, in welcher Beziehung die Topics im <topicgroup>-Element stehen. Stehen die Topics miteinander in Beziehung, so wird für das collection-type-Attribut der Wert family verwendet.

Meta-Daten in Maps

In einer Map können zu den <topicref>-Elementen Meta-Daten hinzugefügt werden. Dies geschieht über das <topicmeta>-Element.

Sind sowohl Meta-Daten im Topic als auch in der Map aufgeführt, so werden beim Verarbeiten der Map durch das DITA Open Toolkit die Meta-Daten des Topics durch die Meta-Daten der Map überschrieben. Wenn beispielsweise im Topictyp „Konzept“ maps_erstellen.xml das <shortdesc>-Element verwendet wird, und in der Map-Datei im <topicmeta>-Element zu einem <topicref>-Element ebenfalls, so wird bei der Produktion des Ausgabemediums das <short-desc>-Element aus der Map verwendet.

Im <topicmeta>-Element können folgende Elemente enthalten sein:

• <author>: Gibt an, wer das Topic zusammengestellt hat.

• <audience>: Die Zielgruppe des Topics wird im <audience>-Element erfasst. Das type-Attribut spezifiziert dabei die anvisierte Zielgruppe mit möglichen Werten wie user, purchaser oder executive. Mit dem job-Attribut kann so zusätzlich so eine Art Aufgabenbeschreibung definiert werden, mit Werten wie installing, customzing, maintaining oder migrating. Den Grad der notwendigen Expertise des Lesers des Topics können Sie über das experiencelevel-Attribut angeben. Innerhalb des <prolog>-Elements können Sie das <audience>-Element mehrfach verwenden, wenn die Definition mehrerer Zielgruppen notwendig sein sollte. Das <audience>-Element wird innerhalb des <metadata>-Elements verwendet.

• <copyright>: Informationen zum Copyright des Topics werden im <copyright>-Element erfasst. Innerhalb des <copright>-Elements wird im <copyrholder>-Element der Name des Copyright-Inhabers und im <copyryear>-Element über das year-Attribut das Jahr für das Copyright angegeben.

• <critdates>: Das Erstellungsdaten und die Daten, die für den Dokumentenlebenszyklus wichtig sind, können Sie im <critdates>-Element angeben. Im <created>-Element wird über das date-Attribut angegeben, wann das Topic erzeugt wurde. Im <revised>-Element können Sie festhalten, wann das Topic zuletzt überarbeitet wurde. Verwenden Sie dazu das modified-Attribut.

• <keywords>: Schlagworte, die in Suchmaschinen oder Retrieval-Systemen suchbar sein sollen, können Sie im <keywords>-Element vergeben. Jedes einzelne Schlagwort wird dabei in einem <keyword>-Element erfasst. Das <keywords>-Element wird innerhalb des <metadata>-Elements verwendet, wie das folgende Beispiel zeigt:

• <permissions>: Über das <permissions>-Element können Sie festlegen, wer Zugriff auf das Topic hat. Dies kann entweder dadurch gesteuert werden, dass die entsprechenden Topics bei der Produktion ausgefiltert werden, oder dass externe Systeme das <permissions>-Element auswerten. Im view-Attribut werden mit den Werten internal, classified, all und entitled die Zugriffsklassen definiert.

• <prodinfo>: Um Informationen zum Produkt hinterlegen zu können, welches im Topic beschrieben wird, steht das <prodinfo>-Element zur Verfügung. Das <prodinfo>-Element enthält das <prodname>-Element mit dem Namen des Produkts, das <vrmlist>-Element mit Informationen zur Version des Produkts, das <prodnum>-Element mit der Produktnummer und das <platform>-Element mit Informationen über die Hard- oder Software des Produkts.

Attribute in Maps

Über Attribute können Sie zu einer Map Informationen hinzufügen, um die Verarbeitung der Map durch das DITA Open Toolkit zu steuern.

In einer Map ist häufig eine hierarchische Struktur abgebildet, bei der die übergeordenten Topics gegenüber den untergeordneten Topics eine Eltern/Kind-Beziehung aufweisen. Für Attribute bedeutet dies, dass die Attribute und deren Werte von den Eltern auf die Kinder vererbt werden. Erst wenn in dem untergeordneten Topic der Wert eines Attributs anders gesetzt ist wie in dem übergeordneten Topic, wird der Attributwert des übergeordneten Topics überschrieben.

Im Folgenden sind die Attribute aufgeführt, die Sie in einer Map und deren Elemente verwenden können;

• collection-type: Mit dem collection-type-Attribut können Sie angeben, in welcher Beziehung die Topics zueinander stehen. Mit dem Wert unordered wird angezeigt, dass die Reihenfolge der Topics für das Verständnis nicht wichtig ist. Mit dem Wert sequence wird darauf hingewiesen, dass die Reihenfolge der angegebenen Topics zum Verständnis wichtig ist. Mit dem Wert choice wird angegeben, dass einer der untergeordneten Topics ausgewählt werden soll. Mit dem Wert family wird angezeigt, dass die Topics nicht nur mit dem aktuellen Topic zusammenhängen, sondern auch untereinander.

• format: Mit dem format-Attribut können Sie im <topicref>-Element angeben, in welchem Dateityp das referenzierte Topic oder eine sonstige referenzierte Quelle vorliegt. Mögliche Werte für das format-Attribut sind dita, html, pdf und ditamap.

• linking: Mit dem linking-Attribut können Sie die Richtung der Links von Topics in Maps kontrollieren. Mit dem Wert targetonly kann zu einem Topic nur verlinkt werden; aber es kann nicht von diesem ein Link zu anderen Topics führen. Umgekehrt verhält es sich, wenn der Wert sourceonly angegeben wird. Ein Link kann nicht zum Topic führen, dagegen aber Links vom Topic zu anderen Topics. Keine Links sind möglich, wenn Sie den Wert none verwenden. Das standardmäßige Verhalten, nämlich dass Links zu einem Topic hin- und vom Topic wegführen können, wird mit dem Attributwert normal ausgedrückt.

• locktitle: Mit dem locktitle-Attribut können Sie festlegen, dass der Inhalt des navtitle-Attributs des <topicref>-Elements in der Map verwendet wird. Mögliche Werte des locktitle-Attributs sind yes und no.

• print: Mit dem print-Attribut können Sie angeben, ob ein im <topicref>-Element referenziertes Topic in eine PDF-Datei aufgenommen werden soll. Mögliche Werte des print-Attributs sind yes, no und printonly. Mit dem printonly-Attribut wird bei der Verarbeitung das übergeordnete <topicref>-Element bei anderen Ausgabemedien als PDF nicht ausgegeben.
  Der Wert des print-Attributs wird auf untergeordnete <topicref>-Elemente vererbt, wo der lokale Wert den übergeordneten Wert überschreibt.

 <topicref href="how_to_use_help.xml" print="no"/> 

• scope: Mit dem scope-Attribut wird angezeigt, wo die Topics in den DITA XML-Dateien relativ zur Map liegen. Mit dem Wert local geben Sie an, dass die Topics und die Map im gleichen Verzeichnis beziehungsweise in den Unterverzeichnissen liegen. Der Wert peer zeigt an, dass die referenzierte Ressource nicht im gleichen Verzeichnis liegt. Bei der Produktion eines Ausgabemediums wird eine mit peer gekennzeichnete Ressource nicht in das Ausgabeverzeichnis des Ausgabemediums kopiert. Ressourcen, die ganz außerhalb liegen, wie zum Beispiel eine Website, erhalten den Wert external.

 <topicref href="http://www.xlcontent-verlag.de" scope="external"/> 

• search: Mit dem search-Attribut können Sie angeben, ob ein im
  <topicref>-Element referenziertes Topic über eine Suchmaschine suchbar sein soll. Mögliche Werte des search-Attributs sind yes und no. Der Wert des search-Attributs wird auf untergeordnete <topicref>-Elemente vererbt, wo der lokale Wert den übergeordneten Wert überschreibt.

 <topicref href="index.xml" search="no"/> 

• toc: Mit dem toc-Attribut können Sie angeben, ob ein im <topicref>-Element referenziertes Topic ins Inhaltsverzeichnis aufgenommen werden soll. Mögliche Werte des toc-Attributs sind yes und no. Der Wert des toc-Attributs wird auf untergeordnete <topicref>-Elemente vererbt, wo der lokale Wert den übergeordneten Wert überschreibt.

 <topicref href="copyright.xml" toc="no"/> 

• type: Mit dem type-Attribut können Sie im <topicref>-Element angeben, welcher Topictyp oder welches spezielles Element referenziert wird. Mög-liche Werte für das type-Attribut sind topic, task, concept, reference sowie fn (footnote), table, fig (figure), li (list) und section.

 <topicref href="installation.xml" type="task"/> 

Ein weiteres wichtiges Attribut für Maps ist das chunk-Attribut, das im nächsten Abschnitt vorgestellt wird.

Das chunk-Attribut

Mit der Version 1.1 von DITA wurde das chunk-Attribut eingeführt, mit dem Sie entweder einzelne Topic-Dateien zu einer einzigen Datei zusammenführen oder aus einer Datei mit vielen Topics wieder einzelne Topic-Dateien erstellen können. Zum Beispiel kann das Zusammenführen mehrerer einzelner Topic-Dateien zu einer Datei erforderlich sein, wenn mehrere Topics auf einer Webseite enthalten sein sollen.

Das chunk-Attribut kann einen oder mehrere der folgenden Werte annehmen:

• by-topic: Das im <topicref>-Element referenzierte Topic wird als separate Einheit für das Zieltopic bei der Ausgabe produziert, wenn der Wert des chunk-Attributs auf by-topic gesetzt ist. Dies gilt auch für die untergeordneten <topicref>-Elemente.

• by-document: Eine separate Einheit wird für das referenzierte Dokument bei der Ausgabe produziert, wenn der Wert des chunk-Attributs auf by-document gesetzt ist.

Als Beispiel sei folgende Datei mit dem Namen eins.xml gegeben:

Dann produziert die folgende Map

ein einzelnes Dokument start.xml, welches das Topic B1 aus der Datei eins.xml enthält. Mit dem Wert to-content (siehe unten) wird eine neue Einheit produziert. Mit dem Wert select-topic (siehe unten) wird genau ein Topic ausgewählt.

• select-topic: Mit dem Wert select-topic wird ein einzeln referenziertes Topic ohne dessen untergeordneten Topics, aus einem Dokument ausgewählt.
• select-document: Sowohl das referenzierte Topic als auch alle anderen Topics im Dokument werden mit dem Wert select-document ausgewählt.

Als Beispiel sei wieder eine Datei mit dem Namen eins.xml gegeben:

Dann produziert die folgende Map

ein einzelnes Dokument, in der alle Topics aus der Datei eins.xml enthalten sind.

• select-branch: Mit dem Wert select-branch wird ein einzelnes Topic und dessen darin enthaltene Topic ausgewählt.

Bei einer vorhandenen Beispiel-Datei eins.xml

produziert die folgende Map

ein einzelnes Dokument, in dem die Topics B1, B1a und B2 enthalten sind.

• to-content: Der Wert to-content produziert bei der Verarbeitung eine neue aus Inhalten bestehende Einheit.
• to-navigation: Der Wert to-navigation produziert bei der Verarbeitung eine neue Einheit für die Navigation.