ubuntuusers.de

Wiki

DITA Single Source Publishing

Hinweis: Dies ist ein statischer Snapshot unseres Wikis vom März 25, 2017 und kann daher nicht bearbeitet werden. Der aktuelle Artikel ist unter wiki.ubuntuusers.de zu finden.

Wiki

Mitmachen

Konfiguration

DITA Single Source Publishing

Archivierte Anleitung

Dieser Artikel wurde archiviert, da er - oder Teile daraus - nur noch unter einer älteren Ubuntu-Version nutzbar ist. Diese Anleitung wird vom Wiki-Team weder auf Richtigkeit überprüft noch anderweitig gepflegt. Zusätzlich wurde der Artikel für weitere Änderungen gesperrt.

Zum Verständnis dieses Artikels sind folgende Seiten hilfreich:

  1. Installation von Programmen

  2. Archive entpacken

  3. Programme zum Menü hinzufügen

  4. Rechte für Dateien und Ordner ändern

  5. Sich im Terminal zurecht finden

Hinweis:

Diese Anleitung bietet eine Schritt-für-Schritt (= Wie?) Anleitung zur Einrichtung einer dita Single Source Publishing Umgebung. Hintergrund (= Was?) Informationen gibt es im Wiki Artikel Darwin Information Typing Architecture. Um einen Lost-in-Hyperspace-Effekt zu vermeiden, wurden die meisten weiterführenden Hyperlinks dita-like unter der Überschrift Links am Ende dieses Wikibeitrags angelegt. Ausnahmen sind Links zu Download-Archiven, die den direkten Download einer Datei auslösen und nicht die Gefahr eines Lost-in-Hyperspace provozieren.

Inhaltsverzeichnis
  1. Grundinstallation
  2. Editor
    1. Pixware XMLmindEditor
      1. Besonderheiten
  3. DITA Transformation
    1. DITA Open Tool Kit
      1. Überprüfung der DITA Open Tool Kit-Ins...
      2. Dokumentationen produzieren
      3. Plugins
      4. Fehlerbehebung
    2. EMC DITA XProc Pipelines
    3. XMLmind DITA Converter
  4. Verwaltung der DITA Dateien (Topics)
    1. ActiveState Komodo Editor
    2. Eclipse IDE
    3. Versionsverwaltungssoftware
  5. Links

./dita-logo-f-uude.jpg

Grundinstallation

Die folgende Anleitung sollte ähnlich auch unter anderen Linux-Distributionen funktionieren. Folgende Pakete müssen installiert sein. Die Dateibezeichnungen für die Java Laufzeitumgebung (JRE) und das Java Development Kit (JDK) können abweichen [1].

Hinweis:

Sun Java ist noch bis Ubuntu 11.04 in der Paketquelle Canonical Partner enthalten. Ansonsten siehe Java/Oracle Java.

  • CHM-Betrachter (Auswahl):

    • gnochm (universe) - für GNOME optimiert, nur bis Ubuntu 10.04

    • kchmviewer (universe) - für KDE optimiert

    • xchm (universe) - JavaScript-Elemente wie Mouseover-Informationen werden nicht unterstützt.

    • fbreader (universe) - allgemeiner e-book Reader

Achtung: Diese Anleitung geht von einer Standard Desktop Ubuntu Installation aus. Auf einer Standard Desktop Ubuntu Installation sind keine Ant-Softwarepakete vorinstalliert.

Optional:

  • Versionsverwaltungssystem

Der XMLmindEditor von Pixware funktioniert ausschließlich mit der offiziellen Java Version von Oracle.

Um herauszufinden, welche Java Runtime Environment (JRE) momentan aktiviert ist, wird im Terminal [5] folgendes eingegeben:

java -version

Bei folgender Ausgabe sind einige Einstellungen zu korrigieren:

java version "1.4.2"
gij (GNU libgcj) version 4.1.0 (Ubuntu 4.1.0-1ubuntu8)

Copyright (C) 2006 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Sollte dies der Fall sein, sind folgende Pakete zu entfernen:

  • gij-4.1

  • java-gcj-compat[1]

Bei folgenden Terminal-Ausgaben wird der XMLmindEditor von Pixware ordnungsgemäß funktionieren:

java version "1.5.0_06"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_06-b05)
Java HotSpot(TM) Client VM (build 1.5.0_06-b05, mixed mode, sharing)
java version "1.6.0_06"
Java(TM) SE Runtime Environment (build 1.6.0_06-b02)
Java HotSpot(TM) Client VM (build 10.0-b22, mixed mode, sharing)

Editor

Vom Prinzip her lässt sich jeder XML-Editor verwenden. Die DTD's lassen sich von der entsprechenden OASIS Web Ressource herunterladen und müssen dann in den jeweiligen XML-Editor eingebunden werden.

XML-Editoren besitzen sehr strikte Vorgaben bei der Eingabe von neuen Elementen des jeweiligen XML-Dialektes (z.B. DITA, DocBook etc). Diese Vorgaben wurden von Spezialisten auf dem jeweiligen Gebiet erarbeitet. Sollte ein Element an einer bestimmten Stelle im DITA-Dokument im Editor nicht verfügbar sein, wird dies einen Grund haben. So hat es z.B. unter DITA keinen Sinn nach einem stepresult ein abstract Element einzufügen. Sollte der Cursor nach dem stepresult gesetzt sein, ist das abstract Element nicht verfügbar. Die Qualitätssicherung findet damit zum überwiegenden Teil während der Eingabe statt bzw. wird gemäß den Vorgaben in der DTD validiert.

Pixware XMLmindEditor

Soweit kein anderer vorkonfigurierter DITA-Editor vorhanden ist, kann der für den Privatgebrauch kostenlose Pixware XMLmindEditor in der Personal- (früher Standard-) Version heruntergeladen {en} werden. Die heruntergeladene xxe-perso-X_X_X.tar.gz-Datei wird in den Ordner ~/dita-ssp/apps/Pixware-XMLmindEditor entpackt [2]. Gestartet wird der Editor mit der Datei ~/dita-ssp/apps/Pixware-XMLmindEditor/xxe-perso-X_X_X/bin/xxe

Alternativ empfiehlt sich das Anlegen einer Starterverknüpfung [3] auf die Datei ~/dita-ssp/apps/Pixware-XMLmindEditor/xxe-perso-X_X_X/bin/./xxe

Eine Installation ist nicht notwendig. Entgegen den aufgeführten Mindestanforderungen ist der XMLmindEditor auch auf älteren Maschinen benutzbar. Um die Performance des Editors zu erhöhen, sollte die Rechtschreibprüfung per "Options -> Preferences -> Tools -> (englischen) Spellchecker" deaktiviert werden. Nach dem erstmaligen Start vom XMLmindEditor ist per "Options -> Install Add-ons..." die DITA DTD-Konfiguration herunterzuladen. Dafür ist eine bestehende Internetverbindung notwendig. Seit dem XMLmindEditor Version 4.9.0 ist das Dita-Add-on schon standardmäßig vorinstalliert bzw. eingebunden.

Besonderheiten

Der XMLmindEditor besitzt eine Vielzahl von versteckten Funktionen - aber auch Einschränkungen, auf die an dieser Stelle hingewiesen werden soll:

  • Drag & Drop-Aktionen werden unter Linux aus dem Dateimanager wie z.B. Konqueror heraus werden akzeptiert. Drag & Drop Aktionen aus GTK-basierten Dateimanagern wie z.B. dem Nautilus werden seit Feisty Fawn (GNOME 2.18 ) unterstützt.

  • Der XMLmindEditor akzeptiert Drag & Drop Aktionen u.a. aus der Adressenzeile eines XUL basierten Browsers. Dazu ist die entsprechende *.dita-Datei im Browser zu öffnen. Direkt links neben der Adressenzeilen-Anzeige file:///... befindet sich ein Lesezeichensymbol das per Drag & Drop und über das Eindrücken der XMLmindEditor Schaltfläche in der Tasksleiste in die Ditamap Eimer des XMLmindEditor gezogen werden kann. Damit lassen sich also durch Drag & Drop href-Verweise aus der Adresszeile des Browsers in der Ditamap des Editors anlegen.

  • In der Standardeinstellung lässt sich der Editor gleichzeitig mehrfach öffnen. So ist es z.B. möglich eine ditamap in einer anderen Instanz als die dita-topic-Dateien zu öffnen. Drag & Drop Aktionen zwischen den verschiedenen Editor-Instanzen funktioniert über die entsprechenden Schaltflächen in der Taskleiste sehr gut.

  • In einer ditamap können referenzierte topic-Dateien durch "Edit -> Reference -> Edit Referencing Document" angezeigt und bearbeitet werden. Dies funktioniert allerdings nur bei einer laufenden Editor-Instanz.

  • Innerhalb des Editors ist das Umsortieren der abgelegten href-Verweis-Liste nur durch "Cut -> Paste before" oder "Paste after" derzeit möglich.

  • Abhängig von der verfügbaren Monitorgröße empfiehlt sich im XXE Optionen Menü sowohl die Baum- (mit 50% Breite) als auch die CSS Style-Ansicht zu aktivieren. Die XML Baumstruktur Ansicht kann das Verständniss von Dita erleichtern.

DITA Transformation

Es ist auch möglich das DITA Open Tool Kit mit einer graphischen Oberfläche durch das Eclipse "Run > As" Menü auszuführen. Genauere Hinweise für die Einrichtung können im Ditainfocenter gefunden werden.

DITA Open Tool Kit

Mit dem DITA Open Tool Kit (Open Source) können auf der Kommandozeile DITA konforme Inhalte in diverse Layout-Formate wie z.B. PDF, HTML, JavaHelp und EclipseHelp transformiert werden. Das Dita Open Tool Kit kann von der entsprechenden Projektseite {en} heruntergeladen und ohne administrative Rechte benutzt werden.

Die nachfolgende Beschreibung bezieht sich auf das FullPackage DITA-OT1.5.2_full_easy_install_bin.tar.gz . Das heruntergeladene *.tar.gz-Paket wird in das Homeverzeichnis ausgepackt. Nachfolgend sollte dann der Dateipfad ~/DITA-OT1.5/ vorhanden sein.

Achtung: Das FullPackage DITA-OT1.5.2_full_easy_install_bin.tar.gz enthält schon eine Ant-Installation. Es sollten keine zusätzlichen Ant-Softwarepakete über die Ubuntu-Paketverwaltung nachinstalliert werden.

Nun wird dem startcmd.sh-Skript die Ablage des /DITA-OT1.5/-Wurzelordners im Dateisystem mitgeteilt.

cd ~/DITA-OT1.5.2 
export DITA_HOME="$HOME/DITA-OT1.5.2"

Nachdem die Datei ~/DITA-OT1.5.2/startcmd.sh Datei ausführbar [4] gemacht worden ist, startet man in einem Terminal [5] oder per Starter bzw. Desktopverknüpfung [3] das DITA Open Tool Kit. Dabei werden automatisch die geeigneten Umgebungsvariablen für die Verwendung der beteiligten Java Werkzeuge (Ant, Saxon XSLT Processor usw.) gesetzt. 

~/DITA-OT1.5.2/./startcmd.sh

Achtung: Durch diese Befehlseingabe gibt das Terminal keine Rückmeldung bzw. Bestätigungsausgabe zurück. Das DITA-OT1.5.2 ist aber mit dieser Befehlseingabe aktiv geschalten und wartet auf weitere Transformationseingaben. Dieses Aktivieren/Scharfstellen ist zwingend wichtig! Dieser Befehl darf nicht übersprungen werden! Ansonsten wird der Build-Prozess nicht erfolgreich durchlaufen!

Das DITA Open Tool wird in der Standardeinstellung nicht automatisch beim Ubuntu-Systemstart gestartet.

Überprüfung der DITA Open Tool Kit-Installation

Um die Installation zu überprüfen, wechselt man im Terminal [5] in den DITA Open Tool Kit-Ordner (~/DITA-OT1.5.2/).

Mit folgendem Befehl wird eine einfache Transformation in HTML durchgeführt:

ant samples.web -f build_demo.xml

Mit folgenden Befehl werden alle verfügbaren Transformationen durchgeführt.

ant all -f build_demo.xml

Mit folgendem Befehl ist es möglich während der Transformation interaktiv Grundeinstellungen vorzunehmen.

ant -f build_demo.xml

Der Transformationsprozess wird gestartet und endet im Normalfall mit einer Erfolgsmeldung.

Buildfile: build_demo.xml
BUILD SUCCESSFUL
Total time: X minutes X seconds

Während dieses Transformationsprozesses werden die DITA-Quelldateien aus dem Ordner ~/DITA-OT1.5.2/samples/ in die graphischen Layoutformate HTMLHelp, JAVAHelp, PDF und einfaches HTML (Frames) transformiert. Die Transformation bzw. der Build-Prozess kann mittels den Ant-Skripten angepasst werden.

Sollten bei späteren Transformationen Fehlermeldungen aufgeführt werden, wird empfohlen, einen Forenbeitrag in der "Yahoo DITA Users Discussion Group" zu starten.

Alle Sample DITA Transformationen werden in der Standardeinstellung im Ordner ~/DITA-OT1.5.2/out abgelegt.

Test Build fehlgeschlagen

Sollte der Test-Build dieser Testdatei fehlschlagen, ist der Debugging-Modus (= -d Schalter) zu aktivieren und ein weiterer Durchlauf zu starten.

ant all -d build_demo.xml

Zur Problembehebung empfiehlt es sich die komplette Terminalausgabe dieses Debugging-Modus in der Diskussionliste der dita-users {en} Yahoo-Fachgruppe zu posten. In diesem Forum lesen auch die Entwickler der Dita Open Tool Kits mit und können weiterhelfen. Auf diesem Weg ist auch das Dita Open Tool Kit schon einmal (ursprünglich) Ubuntu 8.04 tauglich geworden.

Dokumentationen produzieren

Ablage der DITA Dateien

Es ist wichtig, die DITA-topic-Dateien (also task, concept, reference etc.) entweder in den gleichen Ordner der Dita-Map-Dateien oder in einen Unterordner der Dita-Map-Dateien abzulegen. Wird dies nicht beachtet, kann die Transformation der Dita-Dateien unter Umständen fehlschlagen.

Lone-DITA {en} bietet eine sehr gute DITA Schritt-für-Schritt Anleitung anhand vom XMLmindEditor.

Um eine praktische Transformation durchzuführen, werden die Zip-Archive archspec.zip {dl} und langspec.zip {dl} mit den Quelldateien für die offizielle Dita Version 1.1 Dokumentation heruntergeladen und in einen beliebigen Ordner entpackt. Eine Vielzahl von *.ditamap 's aus der offiziellen Dita Version 1.2 Dokumentation können hier {dl} heruntergeladen werden.

Um während der Erstellung der dita Dateien eine Erfolgskontrolle zu bekommen, empfiehlt es sich in regelmäßigen Abständen eine Transformation z.B. in das PDF Format durchzuführen. Dazu wird die sogenannte dost.jar Steuerdatei direkt angesprochen. Die Ablage der *.ditamap im Dateisystem ist mit dieser Vorgehensweise beliebig und nicht auf einen bestimmten Dateipfad eingeschränkt.

Hierzu wird nun das DITA Open Tool Kit mit ~/DITA-OT1.5/./startcmd.sh gestartet und z.B. die PDF-Transformation einer Ditamap wie folgt eingeleitet:

java -jar lib/dost.jar /i:/Dateipfad/zur/ausgepackten/../archspec.ditamap /transtype:pdf

bzw. eine etwas zeitintensivere komplexe Transformation mit ditaval (Zielgruppen-Inhaltsfilter) und conref (Automatisches Ausfüllen von Inhaltsplatzhaltern) Attributen:

java -jar lib/dost.jar /i:/Dateipfad/zur/ausgepackten/../ditaref-type.ditamap /transtype:pdf

Dabei ist zu beachten daß der Pfad zum Heimatverzeichnis z.B. /home/dita-account/ nicht durch eine Tilde ~ ersetzt wird und der Dateipfad keine Leerstellen enthält! Die Ausgabedateien sind standardmäßig im /home/dita-account/DITA-OT1.5.2/out Ordner zu finden.

Weitere Transformationstypen (transtype's) sind zum derzeitigen Stand: docbook, eclipsehelp, xhtml, eclipsecontent, javahelp, htmlhelp, pdf, troff, wordrtf. Bei einer htmlhelp Transformation müssen die Dateien noch mit z.B. Microsoft Help Workshop {en} kompiliert werden.

Ausführlichere Informationen können bei [ibm.com/developerworks] {en} gefunden werden.

Einarbeitung in das DITA Fachgebiet

Zum Einlesen in den Dita Standard 1.2 empfiehlt sich die Lektüre der DITA1.2-spec.chm {dl} Datei.

Plugins

Das Dita Open Tool kann durch verschiedene Plugins {en} erweitert werden. Das docbook2dita Plugin z.B. erlaubt die Transformation von DocBook Dateien in das Dita Format. Andere Transformationen z.B. in das EPUB Format werden auf der Yahoo DITA Users Discussion Group disskutiert.

Fehlerbehebung

Unable to locate tools.jar. Expected to find it in /usr/lib/jvm/java-1.5.0-sun-1.5.0.06/lib/tools.jar

  • sun-java6-jdk multiverse

Wiki/Vorlagen/Installbutton/button.png mit apturl

Paketliste zum Kopieren: 

sudo apt-get install sun-java6-jdk multiverse 

sudo aptitude install sun-java6-jdk multiverse

und deren abhängige Paketen müssen nachinstalliert werden (ca. 15 MB) [1] [2].

EMC DITA XProc Pipelines

DITA XProc Pipelines ist eine Alternative zum DITA Open Tool Kit. Es benötigt keine Java-Laufzeitumgebung.

XMLmind DITA Converter

Der XMLmind DITA Converter ist eine Alternative zum DITA Open Tool Kit. Es benötigt zwingend eine vorhandene Java-Laufzeitumgebung.

Verwaltung der DITA Dateien (Topics)

Zur Verwaltung der DITA Dateien empfiehlt sich der Einsatz eines speziellen Desktop-Suchprogrammes. Dieses Suchprogramm muss allerdings auch in der Lage sein, einige Tausend und mehr XML-Text-Dateien komplett durchsuchen zu können. Die Suche bzw. Filterung nach Dateinamen ist für die Verwaltung von DITA-Dateien nicht ausreichend.

ActiveState Komodo Editor

Komodo Edit {en} von ActiveState (Open Source) besitzt eine "Finden/Ersetzen in Dateien"-Funktion und kann XML Dateien strukturiert (code folding) anzeigen. Seit einiger Zeit werden Funktionalitäten der kostenpflichtigen Komodo IDE in die Open Source Version des Komodo Edit Editors eingearbeitet. Komodo Edit basiert auf Mozilla Code und ist somit in XUL umgesetzt. Anfassen, Verschieben + Fallenlassen zwischen dem ActiveState KomodoEditor und dem Pixware XMLMindEditor ist möglich. Dazu ist der Tab der geöffneten Dita Datei im KomodoEdit mit der Maus anzufassen und in die Eimer der XMLmindEditor ditamap fallen zulassen.

Eclipse IDE

Dazu ist in Eclipse ein Projekt zu erstellen und der komplette Ordner mit den erstellten Ditamaps und Topics per File -> Import -> Filesystem zu importieren.

Zum Erstellen der Dita-Map-Dateien empfiehlt sich der XMLmindEditor von Pixware. Dann wird die Eclipse Search-Funktion gestartet. Über die "Containing Text"-Suche werden Suchbegriffe in den XML-Dateien gefunden. Danach wird per Rechtsklick auf die gefundene Datei und "Show in Navigator" die betreffende XML-Datei links im Eclipse-Navigator angezeigt. Die hervorgehobene Datei bzw. Verweis/Pointer kann nun per Drag&Drop in eine Ditamap des Pixware XMLmindEditors kopiert bzw. in die entsprechenden Ditamap Eimer fallengelassen werden.

Sollte dies unter GNOME nicht funktionieren, ist wie folgt vorzugehen. Der XMLmindEditor akzeptiert Drag & Drop Aktionen u.a. aus der Adressenzeile eines XUL (z.B. Firefox) basierten Browsers. Dazu ist die entsprechende *.dita-Datei im Browser zu öffnen. Direkt links neben der Adressenzeilen-Anzeige befindet sich ein Lesezeichensymbol, das per Drag & Drop und über das Eindrücken der XMLmindEditor Schaltfläche in der Tasksleiste in die Ditamap Eimer des XMLmindEditor gezogen werden kann. Damit lassen sich also href-Verweise des Browsers in der Ditamap anlegen.

Versionsverwaltungssoftware

Auch der Einsatz einer Source Code Management- bzw. Versionsverwaltungssystem kann zur Verwaltung der DITA-Dateien hilfreich sein.

Diese Revision wurde am 16. Januar 2014 14:35 von aasche erstellt.

  1. Wiki
  2. Archiv
  3. DITA Single Source Publishing