Erste Schritte

Das erste Dokument

Abbildung 1. Einfaches DocBook-Dokument

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article lang="de">
  <articleinfo>
    <title>Mein erstes Dokument</title>
  </articleinfo>
  <para>Dies ist ein DocBook XML Dokument.</para>
</article>

Abbildung 2. Einfaches Stylesheet

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/>
</xsl:stylesheet>

DocBook DTDs und XSL Stylesheets

[Anmerkung]Hinweis

Es wird absichtlich nicht DocBook XML 4.3 verwendet, da es einen unvollständigen XML Catalog enthält. Wer eine aktuellere DocBook XML Version als 4.2 verwenden möchte, sollte auf DocBook 4.4CR2 zurückgreifen.

Abbildung 3 veranschaulicht die Verzeichnisstruktur.

Abbildung 3. Verzeichnisstruktur

xml/
    docbook-xsl-1.67.2/
    docbook-xml-4.2/
    catalog.xml

Wesentlich ist der XML Catalog catalog.xml direkt unter dem Verzeichnis xml. Es ist ein sogenannter Master Catalog. Dies ist ein XML Catalog, der lediglich die jeweiligen XML Catalogs der einzelnen Schemata (DTDs) oder die Verzeichnisse der Stylesheet-Distributionen referenziert. In unserem Fall sollte die Datei folgendermaßen aussehen:

Abbildung 4. XML Catalog

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/1.67.2/"
              rewritePrefix="docbook-xsl-1.67.2/"/>
  <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/current/"
              rewritePrefix="docbook-xsl-1.67.2/"/>
  <nextCatalog catalog="docbook-xml-4.2/catalog.xml"/>
</catalog>

Momentan ist es nicht wichtig, wie ein XML Catalog selbst genau aufgebaut ist. Die Einträge rewriteURI schreiben URIs, die mit einer gegebenen Zeichenfolge beginnen, um. In diesem Fall, werden alle URIs, die die DocBook XSL auf SourceForge.net referenzieren, umgeschrieben, so dass sie auf die lokalen Unterverzeichnisse verweisen. Der Eintrag nextCatalog liest einen. DocBook XML 4.2 ein URI, der mit einer gewissen Zeichenkette beginnt,

Die meisten Anwendungen (auch libxml), die XML Catalogs unterstützen, fragen die Umgebungsvariable XML_CATALOG_FILES ab. Es ist daher sinnvoll, den Master Catalog dort zu setzen. Unter Windows geschieht ist über die Systemsteuerung möglich (dort System > Erweitert > Umgebungsvariablen).

xmllint und xsltproc

In diesem Abschnitt werden die Tools xmllint und xsltproc (siehe libxml-Seite oder für Windows), um das Dokument zu validieren und mit Hilfe der XSLT-Stylesheets eine entsprechende HTML-Ausgabe zu erzeugen.

[Anmerkung]Anmerkung

Der erste Schritt ist die Validierung des Dokument. Dabei wird sowohl überprüft, ob das Dokument wohlgeformtes XML ist, als auch ob es der DocBook-Dokumenttypdefinition (DTD) entspricht.

xmllint --nonet --noout --valid test.xml

Die Option --nonet stellt sicher, dass Ressourcen (insbesondere DTDs) nicht extern geladen werden. Dies ist eine gute Möglichkeit, um zu überprüfen, ob der XML Catalog richtig konfiguriert ist. Die Option --noout unterdrückt eine erneute Ausgabe des eingelesenen Dokumentes. Dies unterdrückt nicht die Ausgabe von Fehlern, die xmllint beim Parsen und Validieren des Dokumentes findet. Andersherum gilt, wenn xmllint nichts ausgibt, ist das Dokument wohlgeformt und gültig.

Ist das Dokument gültiges DocBook, kann in einem zweiten Schritt die HTML-Ausgabe erzeugt werden. Da das Ausgangsdokument sehr klein ist, ist die Ausgabe natürlich auch entsprechend unspektakulär.

xsltproc --nonet --output test.html html.xsl test.xml

Und weiter…

Wer mag, kann mit dem Dokument nun selbst weiter experimentieren. Dazu ist es sicher hilfreich, die Dokumentation zu den verwendeten Elementen, insbesondere article und para, im DocBook: The Definitive Guide nachzulesen.

[Anmerkung]Anmerkung

Beachte, dass der DocBook: The Definitive Guide auch als Offline-Version herunterladbar ist.

Die folgende Liste von häufig gebrauchten Elementen mag ebenfalls als Ausgangspunkt für eigene Experimente dienen:

Ich hoffe, in den nächsten Wochen die folgende Punkte zu ergänzen:

  • Einfache Anpassungen des XSLT-Stylesheets durch Überschreiben von vordefinierten Parametern

  • Validierung gegen Relax NG-Schemata mit xmllint (oder RNV)