Installation der Programme

(Auszug aus "DITA - Der neue Standard für Technische Dokumentation" von Johannes Hentrich)

Als Voraussetzung für die Installation des DITA Open Toolkits wird das Java Development Kit benötigt, welches die erforderliche Java-Umgebung für das DITA Open Toolkit bereitstellt. In "Java Development Kit (JDK)" erfahren Sie, wie Sie das Java Development Kit installieren können.

Das DITA Open Toolkit kann nach der Installation des Java Development Kits auf den Betriebssystemen Windows, Linux und MacOs installiert werden.

Das DITA Open Toolkit steht als eine der folgenden Distributionen zur Verfügung:

• Vollständiges Paket (full easy install package distribution)
• Kleines Paket (small package distribution)
• Quelldateien (source distribution)

Mit dem vollständigen Paket werden neben dem eigentlichen DITA Open Toolkit noch zahlreiche weitere Programme mitgeliefert. Dazu gehören:

• ANT-Prozessor
• XML-Katalog Resolver
• FOP-Prozessor
• Xalan (XSLT-Prozessor)

Im kleinen Paket ist der ANT-Prozessor und Xalan als XSLT-Prozessor nicht enthalten. Wenn Sie statt des vollständigen Pakets das kleine Paket des DITA Open Toolkits installieren wollen, dann ist im Gegensatz zum vollständigen Paket noch zusätzlich die Installation von ANT und eines XSLT-Prozessors notwendig. Dabei kann entweder der Xalan oder Saxon als XSLT-Prozessor installiert werden. Das kleine Paket wird häufig dann verwendet, wenn bereits ein XSLT-Prozessor installiert ist und nicht noch ein zusätzlicher XSLT-Prozessor mit dem vollständigen Paket installiert werden soll. Die Installation von ANT wird in "ANT" beschrieben. In "XSLT-Prozessor: Xalan, Saxon" wird dann gezeigt, wie Sie den XSLT-Prozessor Xalan und/oder den XSLT-Prozessor Saxon installieren können.

Als drittes Paket stehen für das DITA Open Toolkit noch die Quelldateien zur Verfügung. Falls Sie das Innenleben des DITA Open Toolkits genauer studieren möchten, so bietet sich hier die beste Gelegenheit.

Wenn Sie eine möglichst schnelle und einfache Installation des DITA Open Toolkits wünschen, empfiehlt sich die Verwendung des vollständigen Pakets, das ab Version 1.4.2 noch den Beinamen „easy install“ trägt. Mit diesem Paket werden automatisch ANT und Xalan als XSLT-Prozessor installiert. Bei der Installation des kleinen Pakets hingegen müssen diese Programme noch separat installiert werden. "DITA Open Toolkit" zeigt, wie Sie das vollständige Paket und das kleine Paket des DITA Open Toolkits installieren können.

Über zusätzliche Programme können dann schließlich die Ausgabemedien produziert werden. Zu diesen Programmen gehören:

• Microsoft HTML Help Workshop
• JavaHelp-Prozessor

In den Abschnitten Microsoft HTML Help und JavaHelp wird gezeigt, wie Sie den Microsoft Help Workshop und den JavaHelp-Prozessor installieren können.

Java Development Kit (JDK)

Das Java Development Kit ist die Basis für das DITA Open Toolkit und einiger weiterer benötigter Programme, wie dem im DITA Open Toolkit mitgelieferten XSLT-Prozessor Xalan.

Für das DITA Open Toolkit wird Java Development Toolkit (JDK) benötigt, das leicht mit dem Java Runtime Environment (JRE) verwechselt werden kann. In der Installationsanleitung zum DITA Open Toolkit wird angegeben, dass die Version 1.4.2_13 benötigt wird. Wahrscheinlich wird diese Version im Internet nicht mehr zu finden sein, sondern eher eine Version mit einer höheren fortlaufenden Nummer wie zum Beispiel 1.4.2_15. Entscheidend ist jedoch die vorstehende Nummer 1.4.2.

Dennoch ist dies nicht die aktuelle Version des JDK. Doch kann man mit dieser Version sichergehen, dass damit das DITA Open Toolkit funktioniert. Wer sich jedoch nicht vor Experimenten scheut, kann sich auch an aktuelleren Versionen des JDK, zum Beispiel 1.6.0, versuchen.

Das JDK können Sie wie folgt installieren:

1. Laden Sie JDK 1.4.2_15 aus dem Internet herunter.
2. Installieren Sie die .exe-Datei, beispielsweise j2sdk-1_4_2_15-windows-i586-p.exe.
3. Legen Sie das Installationsverzeichnis direkt auf Ihren primären lokalen Datenspeicher, also zum Beispiel auf C:\j2sdk1.4.2_15.
4. Setzen Sie die Umgebungsvariable für das JDK. Wenn die Umgebungsvariable gesetzt ist, können die Programme des JDK von jedem beliebigen Verzeichnis aus aufgerufen werden.

Das Setzen einer Umgebungsvariablen ist oftmals etwas ungewohnt, da man auf Computern, die unter Windows, MacOS oder Linux laufen, fast jedes Programm stets zur Verfügung hat. Wenn dies nicht der Fall ist, müssen Umgebungsvariablen gesetzt werden. Daher wird im Folgenden beschrieben, wie Sie die Umgebungsvariable für Computer mit dem Windows-Betriebssystem setzen können.

Die Umgebungsvariablen können Sie wie folgt setzen:

1. Wählen Sie Start -> Einstellungen -> Systemsteuerung.
2. Doppelklicken Sie auf System.
3. Klicken Sie in der Registerkarte Erweitert auf die Schaltfläche Umgebungsvariablen.

Ein Dialogfeld wie das folgende wird angezeigt:

Abbildung: Die Umgebungsvariablen für Windows.

4. Klicken Sie im Abschnitt Systemvariablen auf Neu.
5. Geben Sie in das Eingabefeld Name der Variablen den Wert JAVA_HOME ein.
6. Geben Sie in das Eingabefeld Wert der Variablen den Wert C:\j2sdk1.4.2_15 ein. Dies entspricht dem Installationsverzeichnis des JDK.
7. Finden Sie im Abschnitt Systemvariablen die Variable mit dem Namen PATH (die Groß-/Kleinschreibung ist hier nicht von Bedeutung, sodass die Variable auch Path heißen kann). Falls es keine Variable mit dem Namen PATH gibt, erzeugen Sie eine neue Variable mit diesem Namen.
8. Doppelklicken Sie auf den Eintrag mit dem Variablennamen PATH.
9. Geben Sie in das Eingabefeld Wert der Variablen den Wert %JAVA_HOME%\bin ein. Wenn mehrere Werte eingetragen werden müssen, so wird zur Trennung ein Semikolon verwendet. Achten Sie darauf, dass vor und nach dem Semikolon keine Leerzeichen vorhanden sein dürfen.
10. Bestätigen Sie Ihre Eingaben.

Damit kann jetzt das vollständige Paket DITA Open Toolkit installiert werden. Informationen dazu finden Sie in DITA Open Toolkit.

Falls Sie das kleine Paket des DITA Open Toolkits installieren wollen, wird noch ANT und ein XSLT-Prozessor benötigt. Die Installation dieser beiden Programme wird in den nächsten beiden Abschnitten beschrieben.

ANT

Mit ANT (Another Neat Tool) kann über Build-Dateien die Transformationen der DITA XML-Dateien durch das DITA Open Toolkit gesteuert werden.

ANT können Sie wie folgt installieren:

1. Laden Sie sich die aktuelle Version von ANT aus dem Internet herunter.

   Das DITA Open Toolkit ist auf keine spezielle Version von ANT festgelegt. Zum Zeitpunkt des Schreibens des Buchs stand ANT in der Version 1.7.0 zur Verfügung. Für Windows ist damit die Datei apache-ant-1.7.0-bin.zip herunterzuladen.

2. Extrahieren Sie die zip-Datei in das Verzeichnis C:\ant.
3. Setzen Sie für ANT die Umgebungsvariablen PATH, ANT_HOME und ANT_OPTS wie folgt:
   • Weisen Sie der Umgebungsvariablen PATH den Wert %ANT_HOME%\bin zu.
   • Weisen Sie der Umgebungsvariablen ANT_HOME den Wert C:\ant zu. Dies entspricht dem Installationsverzeichnis von ANT.
   • Weisen Sie der Umgebungsvariablen ANT_OPTS den Wert -Xmx256M zu.
4. Bestätigen Sie Ihre Eingaben.

XSLT-Prozessor: Xalan, Saxon

Für die Verarbeitung der XSLT-Stylesheets wird ein XSLT-Prozessor benötigt. Dazu kann entweder der XSLT-Prozessor Xalan oder der XSLT-Prozessor Saxon verwendet werden. Es können beide XSLT-Prozessoren mit dem DITA Open Toolkit verwendet werden, aber es wird nur einer benötigt. In diesem Abschnitt wird gezeigt, wie jeder der beiden XSLT-Prozessoren installiert werden kann.

Den XSLT-Prozessor Xalan können Sie wie folgt installieren:

1. Laden Sie sich die aktuelle Version von Xalan aus dem Internet herunter.

Die letzte aktuelle Version von Xalan ist 2.7.1. Die Version 2.7.0 wird für das DITA Open Toolkit empfohlen. Eine Verwendung der Version 2.7.1 ist jedoch ohne Weiteres möglich.

Achten Sie darauf, dass Sie eine Binärversion von Xalan aus dem Internet herunterladen. Diese erkennen Sie daran, dass die Binärversion die Buchstaben bin im Dateinamen trägt, wie zum Beispiel bei der Binärversion für Windows: xalan-j_2_7_0-bin.zip.

2. Extrahieren Sie die zip-Datei in das Verzeichnis C:\xalan.
3. Setzen Sie für Xalan die Umgebungsvariable CLASSPATH.

Finden Sie dazu im Abschnitt Systemvariablen die Variable mit dem Namen CLASSPATH. Falls keine Variable mit dem Namen CLASSPATH vorhanden ist, erzeugen Sie eine neue Variable mit diesem Namen.

4. Doppelklicken Sie auf den Eintrag mit dem Variablennamen CLASSPATH.
5. Geben Sie in das Eingabefeld Wert der Variablen den Wert C:\xalan\bin ein.

Dabei entspricht C:\xalan dem Installationsverzeichnis von Xalan. Wenn mehrere Werte eingetragen werden müssen, so wird zur Trennung ein Semikolon verwendet. Achten Sie darauf, dass vor und nach dem Semikolon keine Leerzeichen vorhanden sind.

6. Bestätigen Sie Ihre Eingaben.

Wenn Sie lieber mit dem XSLT-Prozessor Saxon arbeiten, so können Sie diesen wie folgt installieren:

1. Laden Sie sich die Version 6.5.5 des XSLT-Prozessors Saxon aus dem Internet herunter.

Inzwischen gibt es von Saxon eine aktuelle Version 8.9. Wie die Praxis jedoch zeigt, gibt es immer wieder Schwierigkeiten bei der Verarbeitung der DITA XSLT-Stylesheets.

2. Extrahieren Sie die zip-Datei in das Verzeichnis C:\saxon.
3. Setzen Sie für Saxon die Umgebungsvariable CLASSPATH.

Finden Sie dazu im Abschnitt Systemvariablen die Variable mit dem Namen CLASSPATH. Falls keine Variable mit dem Namen CLASSPATH vorhanden ist, erzeugen Sie eine neue Variable mit diesem Namen.

4. Doppelklicken Sie auf den Eintrag mit dem Variablennamen CLASSPATH.
5. Geben Sie in das Eingabefeld Wert der Variablen den Wert C:\saxon\saxon.jar ein.

Dabei entspricht C:\saxon dem Installationsverzeichnis von Xalan. Wenn mehrere Werte eingetragen werden müssen, so wird zur Trennung ein Semikolon verwendet. Achten Sie darauf, dass vor und nach dem Semikolon keine Leerzeichen vorhanden sind.

6. Weisen Sie der Umgebungsvariablen ANT_OPTS den Wert -Djavax.xml.transform.TransformerFactory=com.icl.saxon.TransformerFactoryImpl zu.
7. Bestätigen Sie Ihre Eingaben.

DITA Open Toolkit

In diesem Abschnitt wird gezeigt, wie Sie das vollständige Paket und das kleine Paket des DITA Open Toolkits installieren können. Im Gegensatz zum vollständigen Paket des DITA Open Toolkits benötigt das kleine Paket noch die Installation von ANT und eines XSLT-Prozessors. Diese beiden Programme sind im vollständigen Paket bereits enthalten.

Das vollständige Paket des DITA Open Toolkits können Sie wie folgt installieren:

1. Laden Sie das vollständige DITA Open Toolkit-Paket aus dem Internet herunter.

Für das vollständige Paket des DITA Open Toolkits Version 1.4 wird die Datei DITA-OT1.4.2.1_full_easy_install_bin.zip benötigt.

2. Extrahieren Sie die zip-Datei zum Beispiel in das Verzeichnis C:\ditaot14.

Damit ist die Installation des vollständigen Pakets des DITA Open Toolkits bereits abgeschlossen!

Das vollständige Paket benötigt einige Umgebungsvariablen, die Sie jedoch nicht manuell setzen müssen, wenn Sie mit der Batch-Datei startcmd.bat arbeiten, welche sich im Wurzelverzeichnis des DITA Open Toolkits befindet. Diese startcmd.bat-Datei setzt die Umgebungsvariablen für:

• ANT
• XML-Katalog Resolver
• Apache FOP Version 0.20.5
• Xalan
• und einige weitere Java-Programme

Daneben startet die startcmd.bat-Datei auch die Kommandozeile.

Abbildung: Aufruf der startcmd.bat-Datei.

Wenn Sie häufig mit dem DITA Open Toolkit arbeiten, empfiehlt es sich, eine Verknüpfung zu der startcmd.bat-Datei zu erstellen und diese auf den Desktop zu legen.

Mit einem Doppelklick auf die Verknüpfung öffnet sich die Kommandozeile und danach können Sie sofort mit dem DITA Open Toolkit arbeiten.

Im kleinen Paket des DITA Open Toolkits sind der ANT-Prozessor und Xalan als XSLT-Prozessor nicht enthalten. Informationen zur Installation von ANT erhalten Sie in ANT. Wie Sie Xalan installieren können, erfahren Sie in XSLT-Prozessor: Xalan, Saxon.

Für die Installation des kleinen Pakets wird folgende Installationsreihenfolge empfohlen:

• ANT-Prozessor
• Xalan
• kleines Paket des DITA Open Toolkits

Im Gegensatz zum vollständigen Paket steht im kleinen Paket keine Batch-Datei zur Verfügung, mit der die Umgebungsvariablen automatisch gesetzt werden. Daher ist neben der Installation zusätzlich die Konfiguration der Umgebungsvariablen erforderlich.

Das kleine Paket des DITA Open Toolkits können Sie wie folgt installieren:

1. Laden Sie das kleine Paket aus dem Internet herunter.

Für das kleine Paket des DITA Open Toolkits Version 1.4 wird die Datei DITA-OT1.4.2.1_minimal_bin.zip benötigt.

2. Extrahieren Sie die zip-Datei zum Beispiel in das Verzeichnis C:\ditaot14.
3. Fügen Sie zur Umgebungsvariablen CLASSPATH folgende Pfade hinzu:

C:\ditaot14\lib;
C:\ditaot14\lib\dost.jar;
C:\ditaot14\lib\resolver.jar;

Achten Sie darauf, dass vor und nach dem Semikolon keine Leerzeichen vorhanden sind!

Damit ist dann auch die Installation des kleinen Pakets des DITA Open Toolkits abgeschlossen.

Ob die Installation sowohl des vollständigen Pakets als auch des kleinen Pakets erfolgreich war, können Sie auf eine einfache Weise testen.

Starten Sie dazu zunächst beim vollständigen Paket die startcmd.bat-Datei, um die Kommandozeile aufzurufen.

Beim kleinen Paket starten Sie die Kommandozeile, indem Sie bei Windows Start -> Ausführen wählen und dann cmd eingeben. Wechseln Sie danach in das Wurzelverzeichnis des DITA Open Toolkits, das heißt in diesem Falle C:\ditaot14.

Der Test erfolgt über den Aufruf der build_demo.xml ANT Build-Datei:

Eine detaillierte Beschreibung von ANT und ANT Build-Dateien erhalten Sie in ANT. Hier werden mit dem Aufruf der ANT Build-Datei die Inhalte der Verzeichnisse demo und samples verarbeitet.

Die Verarbeitung kann abhängig von der Prozessorleistung durchaus einige Minuten dauern und liefert dann folgendes Ergebnis auf den Bildschirm:

Abbildung: Erfolgreiche Installation des DITA Open Toolkits.

Ist die Verarbeitung der Beispieldateien erfolgreich, das heißt, nachdem das DITA Open Toolkit erfolgreich installiert wurde, dann wird ein out-Verzeichnis erstellt, in dem sich die Ausgabemedien der verarbeiteten DITA XML-Dateien befinden.

Treten beim Testlauf der Verarbeitung der DITA XML-Dateien Fehler auf, so sind diese häufig darauf zurückzuführen, dass die Umgebungsvariablen nicht richtig gesetzt sind. So ist die Fehlermeldung

Can‘t find resource\messages.xml

darauf zurückzuführen, dass die Umgebungsvariablen für die dost.jar-Datei falsch gesetzt sind. Die Fehlermeldung

NoClassDefFoundError

ist ebenfalls ein Hinweis darauf, dass die CLASSPATH-Umgebungsvariablen nicht korrekt gesetzt wurden.

Microsoft HTML Help

Mit dem Microsoft HTML Help Workshop Version 1.4 kann aus den generierten HTML-Dateien eine Microsoft HTML Help erzeugt werden.

Den Microsoft HTML Help Workshop können Sie wie folgt installieren:

1. Laden Sie den Microsoft HTML Help Workshop aus dem Internet herunter.
2. Doppelklicken Sie auf die Datei htmlhelp.exe und folgen Sie den Installationsanweisungen auf dem Bildschirm.

   Die ANT Build-Datei build_init.xml des DITA Open Toolkits geht davon aus, dass der Microsoft HTML Help Workshop im folgenden Verzeichnis installiert ist: C:\Program Files\HTML Help Workshop

3. Ändern Sie in der build_init.xml-Datei im folgenden <property>-Element den Pfad zum Microsoft Help Workshop gemäß Ihrer Installation:

Damit kann der Microsoft Help Workshop zusammen mit dem DITA Open Toolkit verwendet werden.

JavaHelp

Mit dem JavaHelp-Prozessor kann eine JavaHelp erstellt werden.

Den JavaHelp-Prozessor können Sie wie folgt installieren:

1. Laden Sie den JavaHelp-Prozessor aus dem Internet herunter.

   Die aktuelle Version des JavaHelp-Prozessors ist JavaHelp 2.0_05.

2. Extrahieren Sie die zip-Datei auf dem Laufwerk C:\. Das Verzeichnis C:\jh2.0 wird erstellt.
3. Setzen Sie die Umgebungsvariable JHHOME mit dem Wert des Installationsverzeichnisses, das heißt C:\jh2.0.

Mit der Setzung der Umgebungsvariablen kann das DITA Open Toolkit den JavaHelp-Prozessor finden.