PDF Dokumente erzeugen mittels DocBook

ArticleCategory: [Choose a category for your article]

Applications

AuthorImage:[Here we need a little image form you]

TranslationInfo:[Author and translation history]

AboutTheAuthor:[A small biography about the author]

Egon fing 1999 beim niederländischen LF Team an und wurde im Frühjahr diesen Jahres zweiter Editor. Er studiert Chemie an der Universität von Nijmegen, spielt Basketball und klettert gerne.

Abstract:[Here you write a little summary]

Dieser Artikel erläutert den Einsatz von DocBook zur Erstellung von PDF Dokumenten. Desweiteren werden Werkzeuge für die Bearbeitung von DocBook Dateien und deren Konvertierung in PDF Dokumente vorgestellt. Da auf die Installation der benötigten Programme nicht explizit eingegangen wird, richtet sich dieser Artikel an den erfahreneren Linux Benutzer.

Der erste Teil dieses Artikels ist dem Aufbau eines DoBook Dokumentes gewidmet. Nach der Einführung von DocBook werden dann die Werkzeuge vorgestellt, mit denen DocBook Dateien in PDF Dokumente konvertiert werden können, welche dann z.B. mit dem Acrobat Reader angezeigt werden können.

ArticleIllustration:[This is the title picture for your article]

ArticleBody:[The article body]

Was ist nun DocBook?

DocBook [1] ist eine SGML Sprachdefinition für Dokumente, ähnlich wie HTML Dokumente für das Netz definiert. Im Gegensatz zu HTML jedoch, kann mit DocBook nicht das Layout eines Dokumentes gesteuert werden. Deswegen müssen diese Dokumente in ein anderes Format konvertiert werden, bevor sie dargestellt werden können. Diese Konvertierung in andere Formate wird mit Hilfe von Programmen realisiert, welche jeweils mittels einer bestimmten Formatvorlage (Stylesheet) das DocBook Dokument konvertieren.

Figure 1: Konvertierung von DocBook nach PDF mit einem Stylesheet

Im Verlauf dieses Artikels wird beschrieben, welche Formatvorlage verwendet werden muss und welches Programm für dieses Stylesheet zum Einsatz kommt. Zuerst wird jedoch das Format von DocBook Dokumenten näher beleuchtet.

Schreiben eines Artikels

DocBook kann für die Erzeugung von zwei Arten von Dokumenten verwendet werden: Artikel und Bücher. Da sie prinzipiell gleich sind, wird die Erzeugung eines Artikels als Beispiel vorgeführt. Zuvor aber noch einige grundlegende Dinge über DocBook:

DocBook is prinzipiell eine SGML Ausprägung, wie HTML. Daneben gibt es aber noch eine XML Version von DocBook. Diese ist etwas restriktiver, allerdings lesbarer und deshalb einfacher zu erlernen. Da XML selbst ebenfalls eine Ausprägung von SGML ist, können alle SGML Werkzeuge weiterhin verwendet werden. Es folgen die Hauptunterschiede zwischen der SGML und der XML Version (welche im übrigen für alle XML Ausprägungen gelten):

XML Elemente müssen immer abgeschlossen sein
XML Elemente müssen immer korrekt verschachtelt werden

Dies bedeutet zum Einen, dass nicht einfach   verwendet werden kann (wie in HTML), sondern vielmehr die Kombination  . Desweiteren muss bei der Schachtelung von Elementen auf die Reihenfolge geachtet werden, d.h.:
<A HREF="eine_url">hier klicken</A> ist nicht erlaubt, vielmehr muss es heissen:
<A HREF="eine_url">hier klicken</A>

Nach diesen wichtigen formalen Aspekten nun zum ersten DocBook Artikel:

    <?xml version="1.0"?>
    <article>
      <title>Artikel mit DocBook erzeugen</title>
      <artheader>
        <abstract>
	Dieser Artikel erlaeutert, wie mittels DocBook PDF Dokumente
	erzeugt werden koennen und welche Werkzeuge benoetigt werden,
	um DocBook Artikel zu bearbeiten und in PDF Dokumente zu konvertieren.
        </abstract>
        <author>
          <firstname>Egon</firstname>
          <surname>Willighagen</surname>
        </author>
        <date></date>
      </artheader>
    </article>

Das sieht ja nun nicht allzu schwierig aus, oder? Der Artikel beginnt mit einem Titel, einer kurzen Zusammenfassung, dem Datum, an dem er geschrieben wurde und dem Namen des Autors.

Der nächste Schritt besteht darin, weitere Abschnitte hinzuzufügen. Dazu werden <section> Elemente verwendet:

    <?xml version="1.0"?>
    <article>
      <title>Artikel mit DocBook erzeugen</title>
      <artheader>
        ... der Kopf des Artikels ...
      </artheader>
  
      <section>
        <title>Einleitung</title>
      </section>

      ... andere Abschnitte ...

    </article>

Es wurde nun ein Abschnitt Einleitung dem Artikel hinugefügt. Analog können beliebige weitere Abschnitte, wie etwa Ergebnisse oder Schlussfolgerung eingefügt werden.

Text und andere Informationen hinzufügen

Text wird immer in <para> Elementen eingeschlossen, vergleichbar mit den  Elementen in HTML

    <section>
      <title>Einleitung</title>
      <para>
	DocBook ist ein SGML Ausprägung, entwickelt für die Erzeugung
	von Dokumenten, ähnlich wie HTML für Netzdokumente.
      </para>
    </section>

Es gibt aber noch weitere Elemente. Im Folgenden wird gezeigt, wie Informationen, etwa Beispiele, Listen, Bilder und andere in einen Artikel eingefügt werden.

Beispiele

Beispiele können mittels dem <example> Element eingefügt werden, wie im folgenden Beispiel, in welchem ein Beispielprogramm gezeigt wird:

<example>
  <title>Ein Perl Programm welches XML Dokumente in HTML Seiten konvertiert.</title>
  <programlisting>
    #!/usr/bin/perl -w
    use diagnostics;
    use strict;
    use XML::XSLT;

    my $XSLTparser = XML::XSLT->new();
    $XSLTparser->open_project ("file.xml", "stylesheet.xsl", "FILE", "FILE");
    $XSLTparser->process_project;
    $XSLTparser->print_result();    
  </programlisting>
</example>

Aber natürlich können Beispiele auch selber Text, Bilder uvm. enthalten.

Listen

Wie in HTML können in DocBook auch Listen verwendet werden. Diese werden durch <itemizedlist> Elemente definiert, die ein oder mehrere <listitem> Elemente enthalten können:

<itemizedlist>
  <listitem>
    <para>Ein Element</para>
  </listitem>
  <listitem>
    <para>ein weiteres</para>
  </listitem>
  <listitem>
    <para>und noch eines</para>
  </listitem>
</itemizedlist>

Zu beachten ist, dass hier wieder der Text von <para> Elementen umfasst wird. Textpassagen müssen immer von diesen Elementen umfasst werden!

Man kann auch geordnete Listen (mit nummerierten Elementen) erzeugen. Dazu verwendet man das Element <orderedlist> anstatt <itemizedlist>. Durch einen optionalen Parameter numeration kann die Art der Nummerierung festgelegt werden, z.B.:
<orderedlist numeration="Arabic">

Bilder

Auch Bilder können in einen Artikel eingebaut werden:

<mediaobject>
<imageobject>
<imagedata fileref="ein_bild.gif" format="gif"/>
</imageobject>
<textobject>
  <para>
    Wuerden sie jetzt nicht <productname>Lynx</productname> verwenden,
    koennten Sie nun ein Bild sehen
  </para>
</textobject>
</mediaobject>

Neben dem Bild selbst wurde auch noch ein Text hinzugefügt. Tatsächlich könnte man auch eine Animation einfügen. Das jeweilige Programm, welches später das DocBook Dokument in eine PDF Datei umwandelt, könnte sich dann das beste Medium aussuchen, wharscheinlich wohl das Bild.

Interessant an diesem Beispiel ist, dass das Wort Lynx von Elementen umfasst ist. Dies ist typisch für Definitionssprachen, die zwischen Layout und der enthaltenen Information trennen. Hier bedeutet es nichts weiter, als dass Lynx ein Produkt ist, dessen Name halt Lynx ist. Durch die Formatvorlage, die später verwendet wird, könnte dann zum Beispiel festgelegt werden, dass Produktnamen in einer bestimmten Art und Weise dargestellt werden, möglicherweise kursiv geschrieben werden. Im folgenden Abschnitt werden weitere solcher wortbezogenen Elemente betrachtet.

Wortbezogene Elemente

Wie schon im obigen Beispiel gezeigt worden ist, können auch einzelne Worte von bestimmten Elementen umfasst werden. Die folgende Tabelle listet einige dieser Elemente auf:

Element	Description
abbrev	Eine Abkürzung, vorallem, falls sie mit einem Punkt endet. Beispiel: <para><abbrev>z.B.</abbrev> heisst zum Beispiel.</para>
acronym	Ein Akronym Beispiel: <para><acronym>DSM</acronym> (Chemiekonzern) steht für "De StaatsMijnen" (=Die staatlichen Minen).</para>
email	E-Mail Adresse einer Person Beispiel: <para>Meine E-Mail ist: <email>egon.w@linuxfocus.org</email></para>
keyword	Ein Schlüsselwort des Artikels Beispiel: <para>Meiner Meinung nach ist die <keyword>Chemie</keyword> sehr wichtig.</para>

Viele weitere Elemente sind in einer wirklich guten Kurzübersicht aufgeführt [2].

Nach dieser kurzen Einführung in DocBook wird es nun Zeit, sich die Generierung eines PDF Dokumentes anzuschauen.

Konvertieren eines Dokumentes in das PDF Format

Wurde einmal ein DocBook Dokument erstellt, kann es in verschiedene Formate überführt werden. Neben dem offensichtlichsten Format, PDF, ist es ebenso möglich, eine HTML Seite, ein PostScript Dokument, eine TeX Quelltextdatei oder ein RTF (Rich TextFormat) Dokument zu erstellen, welches mittels WordPerfect, Word, StarWriter und anderen Textverarbeitungsprogammen eingelesen werden kann. In diesem Artikel steht aber die Umwandlung in ein PDF Dokument im Vordergrund.

DocBook Dokumente können mit einem beliebigen Texteditor, wie etwa vi oder Nedit erstellt werden. Noch besser ist Emacs: Norman Walsh schrieb einen Emacs Modus für DocBook [3], welcher einige nützliche Hilfen, wie das Vervollständigen von Elementnamen oder das Einfügen von kompletten Musterelementen, bereitstellt.
Der interessierte Leser kann sich, neben seinen eigenen experimentellen DocBook Artikel, auch meine Version herunterladen, welche die Beispiele dieses Artikels beinhaltet.

Wie anfangs schon erwähnt, werden sowohl eine Formatvorlage, als auch ein Programm, welches diese für die Konvertierung des DocBook Artikels in das PDF Format verwendet, benötigt. Das Stylesheet konvertiert nun nicht direkt von DocBook nach PDF, sondern legt noch einen TeX Zwischenschritt ein. Die hier verwendeten Formatvorlagen sind Norman Walshs Modular DocBook Stylesheets [4], welche in DSSSL geschrieben sind.

Um diese DSSSL Stylesheets zu verwenden, wird ein Programm zur Verarbeitung von DSSSL gebraucht. Das hier verwendete Programm heisst Jade [5] und wurde von James Clark entwickelt (er hat mittlerweile die Arbeit an dem Programm eingestellt). Der Nachfolger heisst OpenJade [6]. Auf ihn wird jedoch hier nicht weiter eingegangen.

Hinweis: Für alle paketorientierten Linux Distributionen, wie RedHat, Suse, Corel oder Debian, existieren entsprechende Softwarepakete der Modular Stylesheets, Jade und JadeTex (siehe unten). Wer diese sucht, sollte also zuerst seine Distribution oder deren Webseite durchstöbern!

Auf meinem Debian System sind die Modular Stylesheets für die Konvertierung nach PD unter /usr/lib/sgml/stylesheets/dsssl/docbook/nwalsh/print/ installiert. Dieser Pfad wird Jade mit der Option -d übergeben. Die Option -t veranlasst Jade dazu, ein TeX Backend zu verwenden:

egonw@localhost> ls -al
total 3
-rw-r--r--    1 egonw    egonw        2887 Apr  8 22:06 docbook_article.xml
egonw@localhost> jade -t tex -d /usr/lib/sgml/stylesheets/dsssl/docbook/nwalsh/print/docbook.dsl docbook_article.xml
egonw@localhost> ls -al
total 21
-rw-r--r--    1 egonw    egonw        2887 Apr  8 22:06 docbook_article.xml
-rw-r--r--    1 egonw    egonw       17701 Apr  8 22:29 docbook_article.tex

Wie man sieht erzeugt Jade hier eine TeX Datei. Diese kann nun mit dem Programm pdfjadetex, welches mit dem Paket JadeTeX[7] mitkommt, in ein PDF Dokument umgewandelt werden:

egonw@localhost> ls -al
total 21
-rw-r--r--    1 egonw    egonw        2887 Apr  8 22:06 docbook_article.xml
-rw-r--r--    1 egonw    egonw       17701 Apr  8 22:29 docbook_article.tex
egonw@localhost> pdfjadetex docbook_article.tex

Als Ergebnis erhält man docbook_article.pdf. Man achte auf die Layoutelemente, die hinzugekommen sind, wie etwa der Titel des Artikels am Anfang jeder Seite und die Verwendung eines anderen Schriftsatzes für den Programmquelltext. Die meiste Zeit für DocBook verbrachte ich anfangs damit, die verschiedenen Möglichkeiten auszuprobieren, von denen nur einige in diesem Artikel vorgestellt worden sind.

Zum Schluß

DocBook XML ist eine recht umfangreiche Sprache. Ebenso gibt es eine Fülle von Formaten, in die DocBook Dokumente konvertiert werden können. Dieser Artikel kann nicht mehr, als nur eine kurze Einführung darstellen. Eventuelle Fragen können auf den Talkback Seiten dieses Artikels gern gestellt werden. Desweiteren sind weitereführende Informationen unter [8] und [9] zu finden! (Das letzte Dokument ist übrigens gänzlich mit DocBook erstellt worden!)

Weiterführende Aspekte von DocBook, die nicht in diesem Artikel Platz fanden, wie etwa:

umfangreiche Methoden für die Verwendung von bibliographischen Informationen
Verweise auf andere Abschnitte, Beispiele

könnten durchaus Grundlage eines weiteren Artikels darstellen.

Literaturverweise

1. DocBook website

2. Quick Reference: DocBook Elements

3. Emacs major mode for DocBook

4. The Modular DocBook Stylesheets

5. Jade

6. OpenJade

7. JadeTeX

8. Norman Walsh's DocBook site

9. DocBook: The Definate Guide on SGML variant