Eine Anpassungsdatei für die DocBook-Stylesheets

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

Für sehr viele Parameter oder für Templates benötigen Sie eine Anpassungsdatei. Der minimale Inhalt dieser Datei besteht aus dem Wurzelelement xsl:stylesheet, einer Importanweisung für die Original-Stylesheets und den entsprechenden Parametern oder anzupassenden Template-Regeln.

Eine Anpassungsdatei hat folgende Vorteile:

  • Ihre Änderungen bleiben erhalten, wenn eine neue Version der DocBook-Stylesheets auf Ihrem System installiert wird. Je nachdem wie tiefgreifend Ihre Anpassungen sind, profitieren Sie sogar von Fehlerkorrekturen oder neuen Funktionen in den Original-Stylesheets.
  • Eine Anpassungsdatei lässt sich an jeden Ort legen, auf dem Sie Schreibzugriff besitzen. Wenn Sie die Original-Stylesheets ändern, ist dies möglicherweise nicht möglich.
  • Änderungen und Originalversion sind getrennt und dadurch leichter zu unterscheiden, als wenn Sie Ihre Anpassung direkt vornehmen würden.
  • Die Originalversion bleibt unangetastet; andere Anwender finden somit ein gewohntes System vor das nicht plötzlich ein anderes Verhalten zeigt.
  • Eine Anpassungsdatei ist die einzige Möglichkeit, Templates und Attributmengen zu überschreiben.

Je nachdem, welche DocBook-Version Sie verarbeiten, benötigen Sie einen anderen Basis-URIs für Ihre Anpassungsdatei. Durch den Basis-URI haben Sie den Vorteil, dass sich die Original-Stylesheets plattformunabhängig ansprechen lassen – ähnlich den Bezeichnern bei einer DTD.

Tabelle: Basis-URIs für DocBook 4 und DocBook 5

DocBook 4 "http://docbook.sourceforge.net/release/xsl/current/"
DocBook 5 "http://docbook.sourceforge.net/release/xsl-ns/current"/

Für DocBook 4 sieht Ihre Anpassungsdatei wie im folgenden Beispiel aus:

Beispiel: Struktur einer Anpassungsdatei für DocBook 4 (customize-db4.xsl)

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/FORMAT/docbook.xsl"/>
  <!-- Überschreiben von Parametern -->
  <xsl:param name="admon.graphics" select="1"/>
  <xsl:template match="command">
    <!-- ... -->
  </xsl:template>
</xsl:stylesheet> 

Eine Anpassungsdatei für DocBook 5 sieht wie folgt aus:

Beispiel: Struktur einer Anpassungsdatei für DocBook 5 (customize-db5.xsl)

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" exclude-result-prefixes="d xlink"> 
  <xsl:import href="http://docbook.sourceforge.net/release/xsl-ns/current/FORMAT/docbook.xsl"/>
    <!-- Überschreiben von Parametern -->
  <xsl:param name="admon.graphics" select="1"/>
  <xsl:template match="d:command">
    <!-- ... -->
  </xsl:template>
</xsl:stylesheet>

Zeile 2: Der DocBook 5-Namensraum ist zwingend. Der Namensraum von XLink (Präfix xi). Sie benötigen ihn, wenn Sie auf XLink-Attribute wie xlink:href zugreifen müssen. Das exclude-result-prefixes-Attribut verhindert, dass die deklarierten Namensräume in das Ausgabeformat übernommen werden.
Zeile 3: Die DocBook XSL NS Stylesheets benötigen einen etwas anderen URI als die Stylesheets für DocBook 4. Ersetzen Sie FORMAT durch das Zielformat, das Sie generieren möchten. Mögliche Ersetzungen sind eclipse, epub, fo, html, htmlhelp, javahelp, manpages, xhtml oder xhtml-1_1.
Zeile 5: Viele Parameter der DocBook-Stylesheets sind unabhängig von der Stylesheet-Variante oder dem Ausgabeformat.
Zeile 6: Jedes DocBook 5-Element muss mit dem deklarierten Präfix erweitert werden (hier d). Überall dort, wo XSLT nach DocBook 5-Elementen sucht, wird der Präfix benötigt. Fehlt dieser, wird das Element nicht erkannt und die Template-Regel nicht darauf angewendet. Dies führt zu unerwünschten Resultaten.

Wo Sie Ihre Anpassungsdatei ablegen, ist Geschmackssache. Manche Anwender legen Sie im selben Verzeichnis wie ihre XML-Dokumente ab, andere speichern sie an einem zentraleren Platz. Der Ort ist zweitrangig, wichtig ist, dass Sie Ihre Anpassungsdatei aufrufen, damit sie wirksam wird.

  

<< zurück vor >>
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