Natürlich könnte ich das alles manuell machen, aber da ich diesen »Prozess« relativ häufig benötige, starte ich nur den Ant-Task und widme mich wieder meiner eigentlichen Arbeit.

Installation des Plugins

Die Installation des Netbeans Ant-Plugins ist recht schnell erledigt. Unter Tools -> Plugins sucht man nach Ant und installiert das Paket. Zu diesem Paket kommen noch eine Hand voll abhängige Pakete, die automatisch mit installiert werden.

Installation des JDK

Falls kein JDK installiert ist, wird Netbeans eines einfordern. Das benötigte JDK ist hier [2] zu bekommen.

Wenn das Paket heruntergeladen und ausgepackt ist, muss man Netbens noch mitteilen, dass es nun dieses JDK verwenden soll. Im Installationsverzeichnis gibt es im etc Verzeichnis die netbeans.conf welche auf das JDK Verzeichnis geändert werden muss.

Beispiel:

netbeans_jdkhome="C:\Programme\Java\jdk1.6.0_14"

Zucker

Ja, ich gebe zu, ich bin faul – sehr faul. Das geht nicht nur so weit, dass ich Ant-Tasks von Hand starte. Ich gehe einen Schritt weiter und lasse Tasks permanent automatisch aufrufen. Natürlich ist das keine neue Idee, schließlich gibt es cron-Jobs seit langem. Aber es gibt, soweit ich weiß, nur ein Cron-Job Plugin für Netbeans, um Ant-Tasks kontinuierlich ablaufen zu lassen. Dieses Plugin ist hier [3] zu bekommen.

Fazit

Die Ant-Tasks schaffen lästige, wiederkehrende Arbeit aus dem Fokus und sorgen dafür, dass mit einem simplen Aufruf vielfältige Aufgaben übernommen werden können. Im Zusammenspiel mit dem Cronjob-Plugin für Netbeans lassen sich die Aufgaben vollständig automatisiert im Hintergrund erledigen. Ant ist leicht zu erlernen [4] und wenn die Build-Scripts einmal aufgebaut sind, können sie von Projekt zu Projekt weiter vererbt und angepasst werden.

Nun gibt es auch eine firebug-Erweiterung mit dem Namen firePHP. Diese Erweiterung ermöglicht dem Entwickler die Inhalte aus einer Debug-Session auch im firebug auszugeben. Das hat den großen Vorteil, dass Debug-Ausgaben nicht mehr mit print(_r) oder mit der Ausgabe im error_log gemacht werden müssen. Zum einen wird so das Layout nicht übermäßig zerstört, zum anderen das error_log nicht stetig vollgemüllt.

Um firePHP nutzen zu können, müssen ein paar Dinge vorbereitet werden. Zum einen benötigt man das Plugin für den Firebug welches [1] hier zu bekommen ist. Zum anderen benötigen wir noch die php Klassen bzw Funktionen, die vom Autoren zur Verfügung gestellt werden.

Die benötigten Klassen bzw Funktion können über den PEAR Installer heruntergeladen werden.

pear channel-discover pear.firephp.org
pear install firephp/FirePHPCore

Der Entwickler von firePHP bietet mehrere Möglichkeiten in der Firebug Konsole Debug-Meldungen auszugeben.
Zum einen gibt es die Funktionen im Paradigma der Prozeduralen Programmierung bzw Aufrufe der Methoden der objektorientierten Programmierung. Je nach vorgehen müssen verschiedene includes getätigt werden.

require_once('FirePHPCore/FirePHP.class.php'); //oder
require_once('FirePHPCore/fb.php');

Um es einfach zu halten, stelle ich allerdings nur die objektorientierte Variante vor.
Zunächst sollte eine Instanz erzeugt werden (Alle Methoden sind auch statisch abrufbar).

$firephp = FirePHP::getInstance(true);

Die interessantesten Methoden die firePHP zur Verfügung stehen sind:

$firephp->log($Object, $Label = null); 
$firephp->info($Object, $Label = null); 
$firephp->warn($Object, $Label = null);
$firephp->error($Object, $Label = null);
$firephp->trace($Label);
$firephp->table($Label, $Table);
$firephp->group($Lable);
$firephp->groupEnd();

Die Methoden log, info, warn und error sind vom Prinzip identisch, allerdings werden sie mit unterschiedlichen Farben innerhalb des Firebugs gekennzeichnet.

Ein sehr nettes Feature von firePHP, ist die Darstellung von Variablen und deren Inhalte. So ist jede Debug-Ausgabe ordentlich verpackt und sauber dargestellt:

Die einzigen Methoden, die man ein wenig gesondert betrachten muss, sind $firephp->group($lable) und $firephp->groupEnd().
Diese Methoden beschreiben eine Gruppe im Firebug. Alle Methoden die zwischen den beiden Aufrufen verwendet werden, werden dann innerhalb einer Gruppe dargestellt.

Wie man sehen kann, sind alle wichtigen fierbug Funktionen auch für firePHP verfügbar. So steht also einer entspannten und komfortablen Debug-Session nichts mehr im Wege.

Für eine komplette Transformation von DocBook zu PDF benötigen wir ein paar Komponenten, die noch installiert werden müssen:

• Ein DocBook-Dokument ( hier ein Beispieldokument)
• einen XSLT-Prozessor
• die XSL-Stylesheets von DocBook
• einen XSL-FO Prozessor

Der XSLT-Prozessor erzeugt mit Hilfe der XSL-Stylesheets aus unserem DocBook ein XSL-FO Dokument. XSL-FO dient als Zwischenstufe für andere Ausgabeformaten wie z.B. PDF, PostScript und Rich Text Format. Um von diesem Zwischenformat weiter zu unserem Wunschformat zu kommen benötigen wir den XSL-FO Prozessor.

Installation Windows

Ich verwende unter Windows sowie Linux xsltproc. Die benötigten Pakete für Windows sind [1] hier zu finden.
Für die Installation unter Windows werden folgende Ziparchive benötigt:

• iconv*.zip
• libxml2*.zip
• libxmlsec*.win32.zip
• libxslt*.win32.zip
• openssl*.win32.zip
• xsldbg*.win32.zip
• zlib*.win32.zip

Weiterhin benötigen wir noch die XSL-Stylesheets von DocBook; die uns eine Basis zur Generierung von PDFs bereit stellt. Dieses Archiv ist [2] hier zu finden. Dort benötigen wie das docbook-xsl-[version].zip.

Zu guter Letzt benötigen wir noch den [3] FOP, der das eigentliche PDF erzeugen wird.

Jetzt da wir alle unsere Werkzeuge zusammen haben, geht es an die Installation. Zunächst erstellen wir ein Verzeichnis – nennen wir es

»docbook«. In Dieses Verzeichnis entpacken wir nun, in separate Unterverzeichnisse, den FOP und die XSL-Stylesheets.

Unter Windows ist die Installation des xsltproc leider keine saubere Sache. Es gibt zwei Möglichkeiten den xsltproc in der comand line bereitzustellen.
Wir können zum Einen alle dlls in das win32 Verzeichnis verschieben. Allerdings hat nicht jeder die Administratorrechte, die es dazu braucht.
Der zweite Weg ist, das Verzeichnis mit in unser DockBook zu verschieben und die gesamten Pfade im batch File auszulagern.

Zur Erleichterung ist hier noch eine kleines batch File, dass uns die Generierung abnimmt.

@echo off
TITLE MakeDocBook

REM ==============================================================
REM Edit these lines:
SET scriptpath=C:\Programme\docbook
SET stylepath=%scriptpath%\docbook-xsl-1.74.0\fo
SET foppath=%scriptpath%\fop-0.95
set repository=%scriptpath%\repository
set src=T:\docbook\repository
set fooutput=%repository%\fo
set pdfoutput=%src%\pdf
set xsltproc_home=%scriptpath%\install
REM ==============================================================
 
 
%xsltproc_home%\xsltproc --xinclude --nonet --stringparam section.autolabel 1 --stringparam xref.with.number.and.title 0  --stringparam body.start.indent 0mm -o %fooutput%\%1.fo %stylepath%\docbook.xsl %src%\src\%1.xml
%foppath%\fop.bat -fo %fooutput%\%1.fo -pdf %pdfoutput%\%1.pdf > nul

Wenn in dem batch File alle benötigten Pfade angepasst sind, kann man nun über die command line das batch File aufrufen, und unser selbst erstelltes PDF bewundern.

Installation Linux

Unter Linux ist die Installation recht simpel. Die benötigten Pakete sind die docbook* und die libxslt* Pakete. Alle benötigten Abhängigkeiten sollten vom jeweiligen Paketmanager automatisch mit aufgelöst werden. Hier ist noch ein Script für das ~/bin Verzeichnis, welches mit einem chmod ausführbar gemacht werden sollte.

#!/bin/bash
 
 
USER_HOME="/home/userhome"
FOP_HOME="/usr/local/fop/fop-0.95/"
DOCBOOK_HOME="$USER_HOME/docbook/"
SOURCE_HOME="$USER_HOME/Documents/documentation"
OUTPUT_HOME="$USER_HOME/Documents/documentation"
docbookfo="/usr/share/xml/docbook/stylesheet/nwalsh/current/fo"
 
# using xslt for xslt:fo
xsltproc	--xinclude \
		--nonet \
		--stringparam section.autolabel 1 \
		--stringparam xref.with.number.and.title 0 \
		--stringparam body.start.indent 0mm \
		--output $1.fo $docbookfo/docbook.xsl $1.xml
# using fop to generate pdf.
$FOP_HOME/fop -fo $1.fo -pdf $1.pdf

Mit den beiden Scripts lassen sich sehr schnell unter den jeweiligen Betriebssystemen ein PDF erstellen. DocBook bringt von sich aus Templates mit, die einem alle möglichen Verzeichnisse automatisiert erstellt (Inhalts- Bilder- Tabellenverzeichnis), welche auch direkt verlinkt sind. Die Positionierung von Bildern geschieht automatisch, sie werden nicht abgeschnitten und die Bild Unter- bzw. Überschriften stehen dort wo sie sein sollen. Das Layout des Dokuments ist konsistent.

Die Konsole gibt dem Entwickler von sich aus jede Menge Informationen zum jeweills ablaufenden JavaScript Geschehen. Man kann die Konsole auch aktiv ansteuern und zum Debuggen verwenden. So entfällt das umständliche und zeitraubende Debuggen mit alert() Aufrufen.

Durch den einfachen Aufruf von console.log(object[, object, ...]); hat man die Möglichkeit, beliebige Objekte auf der Konsole auszugeben. Schleifeninhalte können genauer analysiert werden, indem die Inhalte mit dem Aufruf console.group() und console.groupEnd() umschlossen werden. So sind die Ausgaben aus Schleifen oder Funktionen nicht völlig unübersichtlich.

    console.group("loop call");
    for (var i = 0; i < 5; i++) {
        console.log("loop: " + i);
    }
    console.groupEnd();

Wer die gruppierten Informationen lieber initial eingeklappt haben möchte, ruft statt console.group() einfach console.groupCollapsed() auf.

Unterschied console.group() und console.groupCollapsed()

Es geht noch mehr

Bisher haben wir uns nur um die Darstellung von Daten innerhalb der Konsole gekümmert. Die Konsole erleichtert uns das Entwickeln, indem sie uns erlaubt, JavaScript einzugeben und direkt auszuführen. So kann im Prompt z.B. das Ergebnis einer bestimmten Funktion überprüft werden.

Verwendung des Promts

Die Konsole bietet weiterhin die Funktion $x, die per XPath die Knoten des DOMs abzufragen. Kombiniert mit inspect() lassen sich die Nodesets genauer betrachten. Ist die Auswahl eindeutig, springt man zum gesuchten Element.
inspect($x("//input")[0]);

Die Möglichkeiten, die die Firebug API bietet, sind hier nur kurz angerissen, können aber in der Dokumentation genauer nachgelesen werden.

Ich habe DocBook schätzen gelernt, als es darum ging, umfangreiche Dokumente zu schreiben. Bei Word & Co. habe ich mich in regelmäßigen Abständen darüber geärgert, dass ich ein gutes Drittel meiner Zeit darauf verwendete, das Layout einigermaßen hinzubiegen. Ich beschäftigte mich also mehr mit der Positionierung der Bilder und deren Beschriftungen, als mit dem eigentlichen Inhalt des Dokuments. Ich hatte auch keine Lust, stetig das Inhalts-, Bilder- oder Tabellenverzeichnis manuell zu aktualisieren, damit es – schlicht& ndash; aktuell ist. Zu guter Letzt gab es immer wieder Probleme mit dem PDF-Export, weil gelegentlich dabei das Layout auseinander gefallen ist. Daran änderte leider auch der Versuch nichts, Bilder, Tabellen und deren Beschriftungen erst zum Schluss einzufügen.

Leider führt die Verwendung von XML dazu, dass diese Art der Dokumentenerstellung kaum akzeptiert wird. Die Begründung lautet oft, dass das Schreiben mit DocBook komplizierter und damit auch langwieriger sei als mit Word & Co. Zum anderen scheinen die Schmerzen bei der Dokumentenerstellung zu gering, um sich generell mit alternativen Möglichkeiten zu beschäftigen.

Aber wie arbeitet man nun mit DocBook? Wie ist das XML aufgebaut und was soll oder muss man beachten?

Der Aufbau eines DocBook-Dokuments ist schnell erklärt.

1
2
3
4
5
6
7
8
9
10
11
12
13

<book xmlns="http://docbook.org/ns/docbook" version="5.0">
  <title>Titel des Buches</title>
  <subtitle>Untertitel</subtitle>
 
  <chapter>
    <title>Dies ist ein Titel zum Kapitel</title>
 
    <section>
      <title>Dies ist der Titel für den Abschnitt</title>
      <para>Dies ist ein Absatz, in dem der ganz <emphasis>wichtige</emphasis> Text steht.</para>
    </section>
  </chapter>
</book>

Natürlich gibt es die Möglichkeit, Bilder, Tabellen oder Verweise in DocBook zu erstellen:

1
2
3
4
5
6
7
8

<figure xml:id="bild_id">
  <title>Bildtitel</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="pfad/zum/bild" />
    </imageobject>
  </mediaobject>
</figure>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<table xml:id="tabellen_id">
  <title>Tabellentitel</title>
  <tgroup cols="2">
    <thead>
      <row>
	<entry>Titel der ersten Spalte</entry>
	<entry>Titel der zweiten Spalte</entry>
      </row>
    </thead>
 
    <tbody>
      <row>
	<entry>
	    <code>Eintrag mit einem monospace Font für z.B. Funktionsnamen </code>
	</entry>
 
	<entry>
	    Zweite spalte
	</entry>
      </row>
    </tbody>
  </tgroup>
</table>

1
2

<!-- Verweis auf die obige Tabelle -->
  <xref linkend="tabellen_id" />

Auf den ersten Blick scheint der Nutzen nicht direkt ersichtlich, und der Overhead mag gerade beim Einbetten von Bildern und Tabellen recht hoch anmunten. Hingegen haben wir den großen Vorteil, dass wir uns das Ausgabeformat beliebig aussuchen, es austauschen und verändern können.

Wie aber komme ich zu einem lesbaren Ausgabeformat wie z.B. PDF? Da es sich bei DocBook um XML handelt, muss dieses transformiert, und so in die gewünschten Ausgabeformate umgewandelt werden. Wie man diese Transformation bewältigt, werde ich in meinem nächsten Eintrag erläutern.

Die Vorteile von DocBook nochmal zusammengefasst:

• Inhalt und Layout sind voneinander getrennt.
• Es gibt (theoretisch) beliebig viele verschiedene Ausgabeformate.
• Aus einem einzigen DocBook-Dokument lassen sich mehrere Ausgaben erzeugen.
• XML ist standardisiert und kann gegen ein Schema validiert werden.
• DocBook bietet alle Möglichkeiten der Erweiterbarkeit und Anpassbarkeit des Layouts.
• DocBook kann auf vielen Plattformen betrieben werden.

Die Nachteile zusammengefasst:

• Es gibt leider nur wenige kooperierende Tools
• Die Akzeptanz bei Nichtprogrammieren ist eher gering.