Dokumentenübergreifende Verweise erzeugen

(Auszug aus "DocBook-XML: Medienneutrales und plattformunabhängiges Publizieren" von Thomas Schraitle)

In Querverweise und Links haben Sie die verschiedenen Möglichkeiten kennen gelernt, wie Sie verweisähnliche Elemente in Ihrem Dokument einsetzen können. Typische Querverweise besitzen an ihrem Ursprung den Datentyp ID und am Ziel IDREF. Dadurch lassen sie sich von einem Schema überprüfen.

Wenn dieser Mechanismus jedoch weder gewünscht noch möglich ist und eine URI-basierte Verlinkung unangebracht erscheint, hilft diese Art der Querverweise nicht. Für diesen Fall gibt es in DocBook als Alternative das Element olink. Die prinzipielle Vorgehensweise von olink ist:

Es gibt einige Dinge, die Sie über olinks wissen sollten, bevor Sie diese verwenden:

  • Der OLink-Mechanismus lässt sich nur bei DocBook-Dokumenten anwenden von denen Sie den Quellcode besitzen.
  • Der OLink-Mechanismus erzeugt Abhängigkeiten zwischen Dokumenten, die bei einem eigenständigen Dokument naturgemäß nicht auftreten.
  • Die Verlinkung wird nicht beim Validieren sondern erst beim Transformieren überprüft. Eventuelle Tippfehler fallen daher erst später im Prozessverlauf auf.
  • Falls Ihre Verweise in (X)HTML und FO/PDF verschieden sind, benötigen Sie unterschiedliche Verweisdateien.
  • Wenn Sie ein Dokument ändern, sollten Sie immer die zugehörige Verweisdatei ebenfalls neu generieren. Empfehlenswert sind entsprechende Mechanismen, welche die Verweisdatei automatisch erstellen (Makefile, Shell oder Bash-Skripte, über Ant, usw.)

Anhand eines Beispiels soll dieser Mechanismus näher erläutert werden:

  1. Welche Dokumente sollen verlinkt werden?
    Entscheiden Sie zuerst, welche Dokumente miteinander verlinkt werden sollen. Im folgenden Beispiel wird angenommen, dass zwei Howtos vorliegen, eines für XML, ein anderes für XSLT. Dies wird im folgenden als Datenkollektion bezeichnet.
  2. Bestimmen einer Dokument-ID
    Bestimmen Sie zwecks Identifizierung für jedes Ihrer Dokumente eine Dokument-ID. Die ID darf in Ihrer gesamten Datenkollektion nur einmal vorkommen. Sie dürfen später beliebige weitere Dokumente zu Ihrer Datenkollektion hinzufügen. Fügen Sie im Wurzelelement eines jeden DocBook-Dokuments einen eindeutigen Bezeichner im Attribut id bzw. xml:id ein. Für dieses Beispiel lauten die Dokumente:

Für DocBook4:

<article id="xmlhowto"> ... </article>
<article id="xslthowto"> ... </article>

Für DocBook5:

<article xml:id="xmlhowto"> ... </article>
<article xml:id="xslthowto"> ... </article>
  1. Auswählen der Ausgabehierarchie für (X)HTML
    Überlegen Sie, wie Ihre Verzeichnisstruktur für (X)HTML aussehen soll. Dies ist zum Einen notwendig, um die relativen Positionen zu wissen, zum Anderen um die Übersichtlichkeit zu erhöhen. Für das Beispiel sieht die Struktur wie folgt aus:

    doku
    |
    +-- howtoxml/
    |
    +-- howtoxsl/

  2. Erstellen einer Verweisdatenbank
    Erstellen Sie eine Datei, welche die Struktur von Schritt 3 abbildet. Für gewöhnlich wird sie olink.db benannt (andere Dateinamen sind möglich). Der folgende Inhalt stimmt mit der Struktur in Schritt 3 überein:

Beispiel: Verweisdatenbank olink.db

<!DOCTYPE targetset SYSTEM 
 "http://docbook.sourceforge.net/release/xsl/current/common/targetdatabase.dtd" 
[ 
  <!ENTITY howto.xml.target SYSTEM "xmlhowto.target.db">  
  <!ENTITY howto.xslt.target SYSTEM "xslthowto.target.db"> 
]> 
<targetset> 
    <targetsetinfo>Beschreibung Ihrer Datenkollektion</targetsetinfo> 
    <sitemap> 
      <dir name="doku">
        <dir name="howtoxml">
          <document targetdoc="xmlhowto" baseuri="howtoxml.html">&howto.xml.target;</document> 
      </dir> 
      <dir name="howtoxslt">
        <document targetdoc="xslthowto" baseuri="howtoxsl.html">&howto.xslt.target;</document> 
      </dir> 
    </dir> 
  </sitemap> 
</targetset>

Zeilen 4 und 5: Deklariert für jedes Dokument Ihrer Datenkollektion ein Entity. Der Inhalt der Datei wird separat erzeugt und enthält alle Verweise dieses einen Dokuments.
Zeile 7: Das Wurzelelement
Zeile 8: Enthält eine kurze Beschreibung, um verschiedene Datenkollektionen auseinander zu halten.
Zeile 9: Enthält eine Beschreibung Ihrer Struktur, die Sie sich in Schritt 3 überlegt haben.
Zeilen 10 und 14: Enthält ein übergeordnetes Verzeichnis, das alle anderen Verzeichnisse einschließt.
Zeile 11: Enthält einen Verweis auf das Verzeichnis aller Dateien des Howtos für XML bzw. XSLT (vgl. Schritt 3).
Zeile 12: Das Element document besitzt im Attribut targetdoc die Dokument-ID (vgl. Schritt 2). Das Attribut baseuri benötigen Sie nur, wenn Sie für HTML keine Teildateien erzeugen. An dieser Stelle wird die Verweisdatei eingefügt, die in der internen Teilmenge deklariert wurde (&howto.xml.target;).

  1. Erzeugen einer "Verweisdatei"
    Erzeugen Sie für jede Datei in Ihrer Kollektion eine so genannte Verweisdatei (engl. target file). Diese enthält alle potenziellen Querverweise. Erstellen Sie diese wie folgt:
xsltproc --stringparam targets.filename xmlhowto.target.db \ 
  --stringparam collect.xref.targets "only" \ 
  DB/html/docbook.xsl howtoxml.xml
xsltproc --stringparam targets.filename xslthowto.target.db \ 
  --stringparam collect.xref.targets "only" \ 
  DB/html/docbook.xsl howtoxslt.xml 

In diesem Beispiel wird zusätzlich der Dateiname der Verweisdatei über den Parameter collect.xref.targets angegeben. Dadurch lassen sich die einzelnen Verweisdateien voneinander unterscheiden.

  1. Einfügen der olinks
    Fügen Sie Ihre olink-Elemente in Ihr Dokument ein. Wollen Sie beispielsweise von der Datei howtoxslt.xml einen dokumentenübergreifenden Verweis auf einen Abschnitt in der Datei howtoxml.xml einfügen:
  • Geben Sie für DocBook 4 ein:
<olink targetdoc="howtoxml" targetptr="xml.xmlparser"/>

targetdoc: verweist auf die Dokument-ID des Zieldokuments.
targetptr: verweist auf eine ID im Zieldokument.

  • Für DocBook 5 benötigen Sie XLinks:
<olink xlink:role="http://docbook.org/xlink/role/olink" xlink:href="xmlhowto#xml.xmlparser"/>

xlink:role: Identifiziert das Element als einen dokumentenübergreifenden Link. Dies ist notwendig, da beim Prozess eine spezielle Syntax im Attribut xlink:href verwendet wird.
xlink:href: Identifiziert vor dem Doppelkreuz (#) die Dokumenten-ID (äquivalent zu targetdoc), danach die ID des Zieldokuments (targetptr).

In beiden Fällen wurde auf die Datei howtoxml.xml verwiesen, die eine Dokument-ID howtoxml besitzt. Das olink-Element verweist auf einen Abschnitt mit dem ID-Wert xml.xmlparser.

  1. Erstellen des Zielformats
    Als letzten Schritt erstellen Sie Ihr Zielformat wie folgt, indem Sie die zwei Parameter current.docid und target.database.document im Aufruf verwenden:
xsltproc --output doku/howtoxml/howtoxml.html \ 
  --stringparam current.docid "xmlhowto" \ 
  --stringparam target.database.document "olinkdb.xml" \ 
  DB /html/docbook.xsl howtoxml.xml

xsltproc --output doku/howtoxslt/howtoxslt.html \ 
  --stringparam current.docid "xslhowto" \ 
  --stringparam target.database.document "olinkdb.xml" \ 
  DB/html/docbook.xsl howtoxslt.xml
Tipp der data2type-Redaktion:
Zum Thema DocBook bieten wir auch folgende Schulungen zur Vertiefung und professionellen Fortbildung an:

Copyright © 2009 Millin Verlag
Für Ihren privaten Gebrauch dürfen Sie die Online-Version ausdrucken.
Ansonsten unterliegt dieses Kapitel aus dem Buch "DocBook-XML: Medienneutrales und plattformunabhängiges Publizieren" 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.

Millin Verlag, Siebengebirgsring 36, 53797 Lohmar, info(at)millin.de