Suche
Index
Kontakt
Impressum
Login

Print
English

Hochschule Ulm
Bewerber

Studierende

Alumni

Unternehmen

Journalisten

Intern

V 1.6.1088.9223/


Dokumentation mit Docbook und PDF

Wozu Docbook, wenn es doch einfachere Textverarbeitungsprogramme gibt? Dazu gibt es einige gute Gründe:

1. Bei der Erstellung einer Docbook-Datei konzentriert man sich voll und ganz auf den eigentlichen Inhalt des Dokumentes. Auf Formatierungen muss zu diesem Zeitpunkt nicht geachtet werden. Damit ist eine gute Trennung von Inhalt und Layout möglich.

2. Das Docbook-Format ist im Gegensatz zu anderen Formaten wie MS-Word oder Open-Office ein streng hierarchisches Format. Beispielsweise kann auf eine Überschrift der Ebene 1 nur eine andere Überschrift der Ebene 1 oder eine Unterüberschirft der Ebene 2 folgen. Jedes Dokument sollte eigentlich diesen Regeln genügen. Textverarbeitungsprogramme lassen aber leider auch viel Unfug zu.

3. Da das verwendete XML-Format eine normale ASCII-Datei ist, kann diese auch mit sehr einfachen Mitteln und einfachen Editoren (Notebook) erstellt werden.

4. Da XML inzwischen auf nahezu allen Plattforment (Betriebssysteme und Programmiersprachen) unterstützt wird, kann XML sehr einfach verarbeitet werden. Damit ist es beispielweise möglich, in das Dokument immer die aktuellen Beispielprogramme einzubinden, ohne dies mühsam per cut-and-paste mit der Hand zu tun (Single-Source-Prinzip).

5. Aus der Docbook-Datei können verschiedene Ausgabeformate wie z.B. PDF oder HTML Seiten erzeugt werden. Der Webserver der Hochschule Ulm versteht beispielsweise das Docbook-Format direkt.

Diese Seite wurde auch als Docbook-Datei erstellt.

Doch wie entsteht nun aus einer Docbook-Datei beispielsweise eine PDF-Datei.

Erstellen der Docbook Datei

Docbook ist ein Dateiformat zum Erstellen von Dokumentationen.Verwendet wird Docbook beipielsweise im Linux-Documentation-Project oder im O'Reilly Verlag zur erstellung von ganzen Büchern.

Docbook ist eine XML-Datei (http://www.w3.org/XML/) und kann somit mit allen gängigen XML-Werkzeugen verarbeitet werden. Das XML eine ASCII-Datei ist, können auch sehr einfache Editoren zum Erstellen der Seit verwendet werden. Eine Referenz zu allen Docbook Elementen finden sich unter: http://docbook.org/.

Idealerweise wird eine Docbookdatei mit einem Editor erstellt, der das Format direkt unterstützt. Wir verwenden dazu den Editor XmlMind (siehe http://www.xmlmind.com/)

Eine Anleitung zum Arbeiten mit XmlMind finden sie unter http://www.hs-ulm.de/Hilfe/Webseitenerstellen/DocBookmitXMLMind/Videoanleitung/.

Der Editor XmlMind kann aus Docbook direkt verschiedene Ausgabeformate erzeugen (HTML, PDF usw.). Verwenden Sie dazu den Menübefehl "Docbook/Convert Document".

Erzeugen der Ausgabedatei

Selbstverständlich kann man eine Ausgabedatei (z.B. PDF) auch selber erzeugen. Dies soll am Beispiel PDF erläutert werden.

PDF wird in zwei Schritten erzeugt.


1. 
Zuerst wird aus Docbook eine XSL-FO Datei erzeugt

2. 
Dann wird mit Hilfe eines FO Prozessors die PDF-Datei erzeugt.

Von Docbook zu XSL-FO

Zuerst wird aus Docbook eine XSL-FO Datei erzeugt (siehe http://www.w3.org/TR/xsl/). XSL-FO ist auch eine XML-Datei, diesmal wird allerdings neben dem Inhalt auch das Layout beschrieben. Dieses Layout ist zunächst noch unabhängig vom Ausgabeforment, wenngleich auch als Ausgabeformat sehr häufig PDF verwendet wird. Als weiteres Ausgabeformat könnte beispielsweise auch XPS verwendet werden. Da bei diesem Prozess eine XML-Datei in ein andere XML-Datei transformiert wird, bietet sich an, diese Transformation mit XSLT durchzuführen (http://www.w3.org/TR/xslt). XSLT enthält im Prinzip eine Menge von Regeln, mit deren Hilfe die Transformation durchgeführt werden kann. Diesen Regelsatz kann man sich von Surceforge herunterladen (http://sourceforge.net/projects/docbook/).

Zum Verarbeiten dieser Regeln (xsl:templates) benötigt man nur noch einen XSLT-Prozessor, der die Transformation durchführt. Unter Windows kann man hierzu den Befehl msxsl verwenden unter Linux gibt es die Befehle xsltproc oder jade.

Angenommen sie erstellen ihre Docbook-Datei mit dem Dateinamen docbook.dbx, dann erfolgt die Transformation unter Windows mit dem Befehl:

msxsl -o fo.xml docbook.dbx .../fo/docbook.xsl

Die ... sind durch das Verzeichnis zu erseten, in denen die Stylesheets installiert sind. An der Hochschule ist dies im PC-Pool dann der Befehl:

msxsl -o fo.xml docbook.dbx t:\rz\WINNT\docbook5-xsl-1.72.0\fo\docbook.xsl

Weitere Beispiele zum Thema XML, XSLT-Transformation und XSL-FO finden sie unter: https://www.hs-ulm.de/login/wir/Personal/PersonalTU/traub/Webengineering/Inhalt/XML/

Von XSL-FO zu PDF

Um diese Datei nun in eine PDF-Datei zu verwandeln ist ein FO Prozessor notwendig. Neben kommerziellen Produkten wie Antenna-House (http://www.antennahouse.com/) oder RenderX (http://www.renderx.com/) ist hier vor allem das Apache Projekt FOP zu nennen (http://xmlgraphics.apache.org/fop/).

FOP ist ein Java-Programm uns wird wie folgt gestartet:

fop fo.xml demo.pdf

An der Hochschule verwenden sie im PC-Pool den Befehl

t:\rz\WINNT\fop-0.93\fop.bat fo.xml demo.pdf

Das Ergebnis ist die PDF-Datei demo.pdf. Die Datei wird allerdings mit einem Standardformat erzeugt, was nicht umbedingt sehr schön ist.

Mit Hilfe der Docbook Stylesheets kann allerdings das Layout sehr individuell beeinflusst werden. Siehe dazu die Liste der möglichen Parameter (http://docbook.sourceforge.net/release/xsl/current/doc/fo/)

Um die Parameter zu verwenden baut man sich einen sogen. Customization-Layer. Dies ist eine XSLT-Datei, die die normale docbook.xsl Datei includiert und einige Parameter überschreibt. Soll beispielsweise die Schriftart geändert werden kann dies mit Hilfe folgender Datei geschehen.

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>

    <xsl:import href="t:/rz/WINNT/docbook5-xsl-1.72.0/fo/docbook.xsl"/>

    <xsl:param name="title.font.family">arial</xsl:param>
    <xsl:param name="body.font.family">arial</xsl:param>

</xsl:stylesheet>

Die Verwendung von Fonts ist bei FOP leider etwas umständlich. Wir verwenden an der Hochschule daher ein kommerzielles Produkt.

Der Webservice an der Hochschule Ulm

An der Hochschule Ulm setzen wir als Rendersoftware das Produkte der Firma Antenna House ein. Der Renderer ist per Webservice (Beta-Phase) erreichbar (http://www.hs-ulm.de/apps/pdf/service.asmx). Einen passenden Webclienten (Kommand) finden sie unter

p:\traub\PDF\topdf <Dateiname>

Der Webservice setzt voraus, dass alle Bilder des Dokumentes im Unterverzeichnis _images (relativ zur Docbookdatei) liegen. Der Service erstellt aus einer Docbook-Datei oder einer XSL-FO Datei eine PDF-Datei.

Ohne weitere Angaben wird auch hier das Standardstylesheet verwerdet. Soll hingegen ihr Dokument den Corporate-Identity Richtlinien der Hochschule entsprechen, so müssen sie lediglich im <article> Tag der Docbook-Datei das Attribut role="skript" angeben.

<?xml version="1.0" encoding="UTF-8"?>
<article version="5.0" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:m="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook" role="skript">

...