DocBook Publishing

Es ist wichtig zu verstehen, dass sich bei diesem Framework nicht um eine WYSIWYG Lösung handelt oder eine „Klick-Klack-Anwendung“ (eine Windows-Applikation, die sich per Maus bedienen lässt). Vielmehr werden Artikel im Quelltext in DocBook (also XML) geschrieben und anschließend „compiliert“. Das erinnert manchen vielleicht noch an die alten TEX-Zeiten, wo das Schreiben eines Dokuments so ähnlich abgelaufen ist.

Wer sich also gänzlich vor der Kommandozeile scheut, der sollte vielleicht lieber die Finger davon lassen und sich weiter mit gängigen Officetools bescheiden.

Der Umgang mit XML und etwas XSLT sollte einem ebenso geläufig sein, damit man nicht schon an den einfachsten Dingen scheitert. Alles Weitere will ich hier versuchen so weit zu erläutern, dass man schon bald ein erstes Ergebnis erzielen kann.

Um alle Formate erzeugen zu können, werden einige Software-Pakete benötigt.

Java wird am besten direkt bei Sun heruntergeladen. Unter http://java.sun.com/j2se/1.3/download.html kann man die Runtime 1.3.1_06^[1] für Windows herunterladen. Sun liefert ein ganz normales Setup, so dass die Installation keine großen Probleme bereiten sollte.

Wichtig: Damit das Haupt-Batch-File, welches Ant startet, das Java auch findet, muss man eine Environmentvariable JAVA_HOME setzen. Alternativ kann man den Java-Installations-Pfad auch direkt in das Batchfile reinschreiben.

Wenn man alles richtig gemacht hat, dann kann man an der Kommandozeile folgende Tests machen:

[C:\ ]$ echo %JAVA_HOME% 
 C:\Programme\JavaSoft\jdk1.3.1_06 
 [C:\ ]$ %JAVA_HOME%\bin\java 
 Usage: java [-options] class [args...]
 (to execute a class)
 or java -jar [-options] jarfile [args...]
 (to execute a jar file)
 ... 

Außerdem werden zum Bauen und Transformieren per XSLT noch eine paar Java-Bibliotheken (JARs) gebraucht. Da diese immer dieselben sind für alle Projekte installiert man sie am besten im Lib-Verzeichnis von „JAVA_HOME“ (hier „C:\Programme\JavaSoft\jdk1.3.1_06\lib“. Zum Download gibt's diese Bibliotheken hier.

HTMLDOC gibt's unter http://www.easysw.com/htmldoc/ als Quellcode und als Binary, wobei das Binary in irgendeiner Form eine eingeschränkte Funktionalität haben soll. Ich hab das nicht weiter ausprobiert und stattdessen ein neues Binary kompiliert.

Alles was benötigt wird ist das htmldoc.exe an sich und ein paar Zeichensatz-Dateien, die das Binary als Default unter „C:\Program Files\htmldoc“ erwartet. In diesem ZIP-File sind alle diese Dateien zusammengefasst. Zu beachten ist noch, dass das Binary htmldoc.exe selbst unter dem PATH auch gefunden werden muss. Das erreicht man z.B. dadurch, dass man es in Windows-Verzeichnis kopiert. Wer das nicht mag, der legt am besten ein eigenes Verzeichnis für derartige Tools an (bei mir ist das „C:\Programme\bin“) und erweitert den Pfad entsprechend, so dass dieses Verzeichnis mit einbezogen wird. Testen kann man das am besten dadurch, dass man auf der Eingabeaufforderung einfach mal htmldoc eingibt. Dann sollte etwa folgendes erscheinen.

[C:\ ]$ htmldoc
 ERROR: No HTML files!
HTMLDOC Version 1.8.21 Copyright 1997-2002 Easy Software Products, All Rights Reserved.
This software is governed by the GNU General Public License, Version 2, and is based in part on the work of the Independent JPEG Group.
 
Usage:
 htmldoc [options] filename1.html [ ... filenameN.html ]
 
Options:
 
 --batch filename.book
 ...       

Das Tool w3m für die Ausgabe von Plaintext gibt unter http://www.w3m.org/ zum Download. Das Einzige was im Zusammenhang mit diesem Framework hier benötigt wird ist allerdings das w3m.exe Binary und die CGYWIN-DLL ^[2]. Das kann man alternativ auch direkt hier herunterladen. Ebenso wie in vorherigen Abschnitt beschrieben, kopiert man das EXE und die DLL in ein Verzeichnis, was über den Pfad gefunden wird. Wenn alles korrekt ist dann sieht man an der Kommandozeile folgendes:

[C:\ ]$ w3m
 version w3m/0.1.9
usage: w3m [options] [URL or filename]
options: 

-t tab set tab width
 ... 

Der Hilfecompiler von Microsoft ist direkt bei Microsoft erhältlich z.B. unter dieser URL. Das File HTMLHELP.EXE Version 1.32 ist das benötigte File und wird nach dem Download einfach gestartet. Das Setup installiert den HTML Help Workshop in der Regel unter „C:\Programme\HTML Help Workshop“. Wiederum gilt, soll alles aus dem Stand laufen, muss auch dieses Verzeichnis über den Pfad gefunden werden. Alternativ kann man auch das „hhc.exe“ in das Toolsverzeichnis kopieren. Wenn alles korrekt ist dann sieht man an der Kommandozeile folgendes:

[C:\ ]$ hhc
 Usage: hhc <filename>
 where <filename> = an HTML Help project file
 Example: hhc myfile.hhp       

Python kann man entweder von http://www.python.org/ beziehen oder bei ActiveState das ActivePython herunterladen. Nach erfolgreichem Setup gilt das schon mehrfach gesagte: Python muss über den Pfad erreichbar sein. Beide Distributionen erledigen das normalerweise schon selber. Testen kann man wie immer direkt auf der Kommandozeile:

[C:\ ]$ python
 ActivePython 2.2.1 Build 222 (ActiveState Corp.) based on
Python 2.2.1 (#34, Apr 15 2002, 09:51:39) [MSC 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>     

Um den interaktiven Modus wieder zu verlassen, drücken Sie Crtl-Z.

Wichtig: Damit das Erzeugen des „echten“ Worddokuments funktioniert, müssen die win32com Extension installiert sein. Testen kann man auch das am schnellsten per Kommandozeile:

>>> import win32com
>>> print win32com
<module 'win32com' from 'C:\Python22\Lib\site-packages\win32com\__init__.pyc'>       

So nun ist eigentlich alles komplett, jetzt fehlt nur noch ein erstes Projekt. Sie können z.B. im Abschnitt Download direkt dieses Projekt herunter laden und mit „make all“ alle Seiten und Ausgabeformate erzeugen.

Etwas einfacher und übersichtlicher ist es aber trotzdem zuerst mit dem „Hello World“-Projekt zu beginnen. Wie das aussieht soll im folgenden Abschnitt beschieben werden.

Dieser Bestandteil ist optional, weil man im Prinzip mit jedem beliebigen Editor ein DocBook-Quellcode-File erstellen kann. Allerdings ist es vielleicht gerade für den Anfänger interessant OpenOffice zu benutzen. Der Writer des OpenOffice hat den Vorteil, dass man praktisch WYSIWYG editieren kann, ohne auch nur zu Grunde liegende XML zu Gesicht zu bekommen. Dieser Vorteil kann aber natürlich auch zum Nachteil werden, weil die umfassende Kontrolle über alle Aspekte des DocBook-Publishings verloren geht. OpenOffice kann in der Version 1.0.1 unter http://www.openoffice.org/ heruntergeladen werden.

>>> import ooo2sdbk
>>> print ooo2sdbk
<module 'ooo2sdbk' from 'C:\Python22\Lib\site-packages\ooo2sdbk\__init__.pyc'> 

Die nachfolgenden Ausführungen sind größtenteils an das Referenzwerk von Norman Walsh & und Leonard Muellner angelehnt (siehe hier).

Ein Buch ist typischerweise ein etwas größeres Werk als ein kleiner Artikel. Es umfasst von seiner Struktur einige Meta-Informationen (<bookinfo>), die den Autor, den Titel und einen Copyrightvermerk beschreiben. Es kann ein Vorwort haben und besteht aus Kapiteln, die wiederum in Abschnitte gegliedert sind. Zusätzlich können Anhänge folgen, sowie ein Literaturverzeichnis, ein Glossar und ein Index.

Ein Artikel ist die kleinere Ausgabe, der eben nicht soviel umfasst wie ein komplettes Buch, sondern im wesentlichen die Struktur eines einzelnen Kapitels hat. Er enthält aber genauso Meta-Informationen (<articleinfo>) und kann auch Anhänge, Literaturverzeichnis, Glossar und Index umfassen.

Der XML Ausschnitt unten zeigt die typische Struktur eines DocBook Buches.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"../../common/docbook/dtd/docbookx.dtd">
<book lang="de">
 <title>Mein erstes DocBook Buch</title>
 <bookinfo> 
     <author>
       <honorific>Dipl.-Ing</honorific>
       <firstname>Stefan</firstname>
       <surname>Rinke</surname>
     </author>
 </bookinfo>
 <preface> 
     <title>Vorwort</title>
     <para>In einem Vorwort stehen Dinge über das Buch an sich.</para>
 </preface>
 <chapter> 
     <title>Einführung</title>
     <para>Dies ist ein einfacher Artikel
       <indexterm> 
         <primary>Artikel</primary>
         <secondary>DocBook-Artikel</secondary>
       </indexterm>.
     Das ist nur ein Beispielabsatz.</para>
 </chapter>
 <appendix> 
     <title>Anhang 1</title>
     <para>Das ist ein Anhang.</para>
 </appendix>
 <glossary> 
     <glossdiv>
       <title>Ein Glossar</title>
       <glossentry>
         <glossterm id="DocBook">DocBook</glossterm>
         <glosssee>DocBook ist ein Standard zur Erstellung...</glosssee>
       </glossentry>
     </glossdiv>
 </glossary>
 <index/> 
</book>

	Der Bookinfo-Teil ist eigentlich optional, allerdings wird man in den meisten Fällen als Autor nicht unerwähnt bleiben wollen.
	Auch das Vorwort muß nicht unbedingt dabei sein. Wenn das Werk etwas größer ausfällt, dann hat das Vorwort jedenfalls mindestens diese Struktur.
	Hier folgen nun ein oder mehrere Kapitel, die wiederum mit einem Titel <title> beginnen und in Absätze <para> gegliedert sind.
	Auf diese Weise erzeugt man einen Indexeintrag. Der Zweit-Eintrag ist optional.
	Nun folgen noch ein oder mehrere Anhänge.
	Wer möchte kann noch ein Glossar anfügen.
	Diese Tag markiert nur die Stelle, an der der fertige Index eingefügt werden soll.

Wie ein solches „Buch“ in HTML aussehen kann^[3], sieht man hier.

Ganz entsprechend stellt sich ein einfacher Artikel dar.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"../../common/docbook/dtd/docbookx.dtd">
<article lang="de">
 <title>Mein erster Artikel</title>
 <articleinfo>
     <author>
       <honorific>Dipl.-Ing</honorific>
       <firstname>Stefan</firstname>
       <surname>Rinke</surname>
     </author>
 </articleinfo>
 <para>Dies ist ein einfacher Artikel. Dieser Ausdruck
     <indexterm>
       <primary>Ausdruck</primary>
     </indexterm>
         soll im Index erscheinen.</para>
 <appendix>
     <title>Anhang 1</title>
     <para>Das ist ein Anhang.</para>
 </appendix>
 <glossary>
     <glossdiv>
       <title>Ein Glossar</title>
       <glossentry>
         <glossterm id="DocBook">DocBook</glossterm>
         <glosssee>DocBook ist ein Standard zur Erstellung...</glosssee>
       </glossentry>
     </glossdiv>
 </glossary>
 <index/>
</article>         

Auch wie das aussieht, kann man sich direkt online ansehen.

Wer in das Thema DocBook tiefer einsteigen möchte, der sei an dieser Stelle auf einige andere Online Resourcen verwiesen.

5.4.1. DocBook: The Definitive Guide

Da ist zunächst das Standardwerk: DocBook: The Definitive Guide man kann es direkt online lesen und es liefert wirklich alles vom Einstieg bis zur Referenz.

DocBook: The definitive Guide, Norman Walsh & Leonard Muellner

OpenOffice verwendet für Formatierungen Absatzformate, Zeichenformate und Rahmenformate. Diese sind benannt und an bestimmte Layoutregeln geknüpft. Die Verbindung zwischen DocBook und OpenOffice wird genau über diese vordefinierten Formate hergestellt. Wenn ein Satz bespielweise einen Filenamen enthält, dann wird er in OpenOffice mit dem Zeichenformat „Filename“ formatiert und später in <filename>...</filename> konvertiert.

Mit Absatzformaten für Aufzählungen oder nummerierte Listen verhält es sich genauso, in OpenOffice werden diese wie gewohnt verwendet und dann automatisch in die DocBook Entsprechungen umgesetzt. Damit das immer richtig funktioniert, sollte man allerdings immer eine bestimmte Dokumentvorlage bzw. ein leeres Startdokument verwenden. Ein solches Dokument ist dem Framework beigefügt.

Die meisten korrospondieren Formate / Tags sind intuitiv, die ausführlichere Darstellung liefert Eric Bellot auf seiner Seite.