ubuntuusers.de

Darwin Information Typing Architecture

Archivierte Anleitung

Dieser Artikel wurde archiviert. Das bedeutet, dass er nicht mehr auf Richtigkeit überprüft oder anderweitig gepflegt wird. Der Inhalt wurde für keine aktuell unterstützte Ubuntu-Version getestet. Wenn du Gründe für eine Wiederherstellung siehst, melde dich bitte in der Diskussion zum Artikel. Bis dahin bleibt die Seite für weitere Änderungen gesperrt.


Anmerkung: Neuer Informationen findet man in den Artikel Darwin Information Typing Architecture und Archiv/DITA Single Source Publishing

Hinweis:

Dieser Artikel wurde überarbeitet. Siehe Baustellen Beiträge dita-ssp-Hintergrundwissen und dita-ssp. Die Baustellen Artikel werden demnächst freigegeben und sollten dann mit dem Stichwort dita auffindbar sein.

Im Verlauf dieser Anleitung werden eine Vielzahl an Installationsdateien direkt in das Homeverzeichnis kopiert. Dadurch kann die Navigation in den DITA-Anwendungen sehr unübersichtlich werden. Außerdem wird ein Mix aus normalen Benutzerdateien und DITA-Installationsdateien entstehen. Es wird deshalb dringend empfohlen für die nachfolgende Anleitung ein eigenes Benutzerkonto mit dem Namen "dita-account" und dem Benutzerverzeichnis /home/dita-account anzulegen. Zur Einrichtung siehe Artikel Benutzer und Gruppen.

Die Darwin Information Typing Architecture - DITA 🇩🇪 ist ein XML-Dialekt mit einer strikten Trennung von Inhalt und visuellen Layout Informationen. Vorrangiges Ziel der Darwin Information Typing Architecture ist die 1:1 Wiederverwendung (Reuse) von Mini-Dokumentationen in verschiedenen Kontexten.

DITA baut auf den bewährten Erfahrungen im Bereich des Datenbank-Design, der Objektorientierten Programmierung 🇩🇪 und der Technischen Dokumentation auf. Vor der Einarbeitung in das DITA Konzept sollten Strukturierungsfähigkeiten mit hierarisch orientierten Techniken wie z.B. dem Mindmapping trainiert werden. DITA konforme Strukturierung erfordert einen nicht unerheblichen Einarbeitungsaufwand. DITA ist ähnlich dem OpenOffice.org ODF Office-Formaten ein OASIS Standard 🇩🇪 .

Charakteristika

Aus Ersteller-Sicht besteht eine DITA-konforme Dokumentation aus einer losen Vielzahl von Schritt-für-Schritt Anleitungen, Glossar-Einträgen und Referenz-Dokumenten. Diese Standard Topic-Typen werden je nach Aufgabenstellung und Zielgruppe zu einer Dokumentation zusammengestellt. Die Vielzahl dieser Topic-XML-Dateien stellt hohe Anforderungen an eine geeignetete Dateiverwaltung und könnte im Idealfall mit einem Content Management System (CMS) wie z.B. Archiv/TYPO3 oder einer Versionsverwaltung wie z.B. [Archiv/CVS:CVS] oder Subversion umgesetzt werden. Die Erstellung, Transformation und Verwaltung der DITA Dateien würden in diesem Idealfall kompakt innerhalb eines CMS implementiert sein.

Die Zielgruppe dagegen sieht die inhaltlich zusammengestellte Dokumentation in den meisten Fällen in einer hierarchischen Ordnung abhängig von den unterschiedlichsten Ausgabeformaten wie z.B. PDF und HTML.

Die kleinste Informationseinheit der DITA Specifikation ist ein Topic. Von seiner Definition her ist ein Topic ein autonomer Sachverhalt, welcher je nach Kontext in einem Dokumentationsgebilde angeordnet wird. Vergleiche mit einer Informationsflocke (flake) drängen sich in diesem Zusammenhang auf. Im DITA Standard werden drei Grundtypen von Sachverhalten angeboten, welche in einer technischen Dokumentation immer wieder vorkommen:

  • Tasks: Schritt-für-Schritt Anleitungen.

  • Concept: für Hintergrundinformationen.

  • Reference: für die Aufführung von Kommandos und anderen standardisierten Informationen.

A topic is a unit of information with a title and some form of content, short enough to be specific to a single subject or answer a single question, but long enough to make sense on its own and be authored as a unit. Quelle: OASIS Architectural Specification 1_1 Chapter 3 DITA markup 🇬🇧

Es gibt somit keine Beschränkung für den Umfang eines DITA Topics. Allerdings sollte bei Topic's ab drei Sätzen immer die Frage auftauchen, ob im diesem Fall aus Versehen zwei Topics miteinander vermischt werden. Zwei miteinander vermischte Topics lassen sich schwerer wiederverwenden.

Jedes Topic steht für sich allein und ist ohne zusätzliche Kontextinformation verständlich. Für die Erstellung der zielgruppenorientierten Dokumentation werden Verweise zu den Topics mittels sogenannter DITA-Maps listenartig angeordnet.

Sollten diese Grundtypen den eigenen Anforderungen nicht genügen, können aufbauend auf den Grundtypen durch eine sogenannte Specialisation eigene Topic-Typen erstellt werden (fortgeschritten).

Generell gibt es in einer topic-orientierten Auflistung keine Wertungen. Listeneinträge an erster Stelle sind damit nicht wichtiger als Listeneinträge an letzter Stelle. Diese Gleichbehandlung lässt sich sehr gut mit dem Mindmapping trainieren und sollte vor der Arbeit (u.a.) mit DITA persönlich verinnerlicht sein.

Einstieg

Zum Einlesen empfiehlt sich die Lektüre der ditaref-book.chm Dokumentation. Diese CHM-Datei befindet sich nach dem Entpacken des DITA Open Tool Kit im Pfad ~/doc/ditaref-book.chm Die CHM-Dateien lassen sich unter Linux mit verschiedenen CHM Betrachtern öffnen.

Als Einstieg in die DITA-konforme Dokumentation sollte ein bestens bekanntes Thema gewählt werden. In der Softwaredokumentation empfiehlt sich eine Dokumentation über den "Datei > Drucken..." oder den "Bearbeiten → ..." Dialog zu erstellen. Diese Menü-Einträge tauchen in den meisten Softwarelösungen auf und sind damit sehr gut wiederverwendbar.

Als Vorarbeit für die Erstellung einer umfangreichen DITA konformen Dokumentation wird die Zielgruppe bestimmt. Dafür bieten sich sogenannte Use Cases an. In einer Art Brainstorming werden relevante Schlüsselwörter gesammelt bzw. später hinzugefügt. Hierbei ist Mut zur Lücke das Vorgehensprinzip. Danach werden diese zielgruppenrelevanten Schlüsselwörter entsprechend den Topic-Typ-Vorgaben (z.B. task, concept usw.) beschrieben und mit Metadaten z.B. Computeranfänger, Profi, KDE, GNOME, Xfce, usw. versehen. Zur Verwaltung einer Vielzahl von Topics sind die Topics bzw. deren Metadaten zwingend von einer Desktopsuche (Software) zu indexieren. Um die Verwaltung der Dita-Dateien zu verbessern, empfiehlt es sich einheitliche Metadaten vorzuschreiben.

Nun wird für die betreffende Zielgruppe eine DITA-Map angelegt. Über die Indexliste der Metadaten werden die passenden Topics herausgefiltert. Diese sind dann dem voraussichtlichen Lesefluß des Zielpublikum entsprechend listenartig anzuordnen.

Um eine universelle Wiederverwendung von Topics zu gewährleisten, ist bei der Zusammenstellung auf eine strikte Trennung von Wie- (=Schritt-für-Schritt) und Was- (=Hintergrundinformationen) Informationen zu achten. Diese strikte Vorgehensweise ermöglicht die Zusammenstellung von zielgruppengerechter Dokumentation.

Während der Herausbildung der inhaltlichen Struktur werden mit einem Transformationstool (z.B. dem DITA Open Tool Kit) automatisch visuelle Layoutinformationen hinzugefügt. Beispiele für Ausgabeformate sind z.B. PDF oder HTML.

Eine ausführliche Beschreibung ist im OASIS DITA DOC Archiv 🇬🇧 zu finden.

Im wiki.ubuntuusers.de werden verschiedene Includes Makros verwendet um häufig wiederkehrende Hinweise und Warnungen wiederzuverwenden. Die Include-Funktion bietet ähnliche Funktionalität wie das Dita content inclusion (conref) Attribut. Weitere Informationen sind unter DITA Version 1.1 Architectural Specification S. 40 unten ca. 3MB PDF ⮷ und DITA Version 1.1 Language Specification S. 478 unten ca. 13MB PDF ⮷ zu finden.

⚓︎

Grundinstallation

Die folgende Anleitung zum Einrichten einer DITA Publishing Umgebung sollte ähnlich auch unter anderen Linux-Distributionen funktionieren. S.a. Andere Distributionen Folgende Pakete müssen (unter Ubuntu 6.06 LTS Dapper Drake) installiert sein. Die Bezeichnungen für die Java 5 bzw. Java 1.5 Pakete neuerer Ubuntu-Versionen können davon abweichen [1]:

  • sun-java5-jre (multiverse [2])

  • sun-java5-jdk (multiverse)

  • CHM-Betrachter (Auswahl)

    • gnochm für Gnome optimiert

    • chmsee für Gnome optimiert

    • kchmviewer für KDE optimiert

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

    • fbreader allgemeiner e-book Reader

Alternativ kann auch die Sun Java Runtime Environment - JRE Version 6 bzw. 1.6 und aktueller verwendet werden. Ähnlich das Sun Java Development Kit - JDK.

optional:

  • bzr-gtk (universe) Vorgefertigte Pakete sind unter Ubuntu seit 6.10 Edgy verfügbar. S.a. Downloads Für Dapper muss wahrscheinlich das Olive 🇬🇧 -Plugin in Bazaar eingebunden werden. Umfangreiche Dokumentation kann hier 🇬🇧 gefunden werden.

  • Kate Unter einem Standard Gnome Ubuntu wird die komplette KDE Umgebung nachinstalliert.

Der XMLmind Editor funktioniert ausschließlich mit der offiziellen Version von Sun Java Microsystem. Mit dem GNU Compiler for Java 🇩🇪 Version 1.4 kommt es zu Problemen beim Drag & Drop zwischen dem Editor und dem Dateimanager.

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

java -version 

Sollte jetzt als Ausgabe erscheinen:

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.

... sind einige Einstellungen zu korrigieren. Unter Ubuntu 6.06 LTS Dapper Drake sind die Java Bibliotheken im Pfad /usr/lib/jvm/ abgelegt. Bei der Installation des Sun Java Runtime Environment wird meist ein Menü-Eintrag zu einem sogenannten Sun Java Plugin Control Panel angelegt. Dort finden sich über den Reiter Java Application Runtime Settings auch Informationen über die aktuellen Dateipfade der Java Bibliotheken. Sollte dort ein Ordner

  • /java-1.4.2-gcj-4.1-1.4.2.0/ aufgeführt sein,

sind die Pakete

  • gij-4.1 und

  • java-gcj-compat zu entfernen. [1]

Dabei ist zu beachten, dass nach dem Entfernen dieser Pakete eventuell andere Java-Anwendungen nicht mehr funktionieren werden. Insbesondere eine bestehende Eclipse-Version aus den Ubuntu-Softwarequellen wird in diesem Fall nicht mehr funktionieren. Eventuell ist eine Ubuntu-Installation in einer Virtuellen Maschine zu überdenken. Dazu sind aber mindestens 1 GB Arbeitsspeicher und ca. 10 GB zusätzlicher Festplattenspeicher notwendig (s.a. VirtualBox und Archiv/VMware).

Sollte als Ausgabe erscheinen:

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)

wird der XMLmindEditor von Pixware ordnungsgemäß funktionieren.

Editoren

Vom Prinzip her lässt sich jeder XML-Editor verwenden. Die DITA DTDs 🇩🇪 lassen sich hier 🇬🇧 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 zu ca. 80 % 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 XMLmind XML Editor 🇬🇧 in der Personal- (früher Standard-) Version heruntergeladen werden. Die heruntergeladene xxe-perso-X_X_X.tar.gz Datei wird in den Ordner ~/00-personal-dita-publishing-environment/helper-applications/Pixware-XMLmindEditor entpackt [3]. Gestartet wird der Editor mit der Datei ~/00-personal-dita-publishing-environment/helper-applications/Pixware-XMLmindEditor/xxe-perso-X_X_X/bin/xxe

Alternativ empfiehlt sich das Anlegen der Starterverknüpfung [4] auf die Datei ~/00-personal-dita-publishing-environment/helper-applications/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. Gegebenenfalls kann der Editor natürlich auch unter ressourcenarmen Fenstermanagern wie z.B. Fluxbox benutzt werden. Eine weitere Möglichkeit die Performance des Editors zu erhöhen, besteht in der Deaktivierung der Rechtschreibprüfung unter "Options → Preferences → Tools → (englischen) Spellchecker". Nach dem erstmaligen Start vom XMLmindEditor ist per "Options → Install Add-ons..." die DITA DTD-Konfiguration herunterzuladen. Dafür ist eine bestehende Internetverbindung notwendig.

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.

Inmedius DITA Storm

DITA Storm 🇬🇧 ist ein browser-basierter DITA XML Editor und kann hier 🇬🇧 online benutzt werden. Dazu ist JavaScript zu aktivieren. Zur Offlinebearbeitung kann dieser Editor auch hier 🇬🇧 heruntergeladen werden. Eine Anleitung für die Integration in eine Webseite oder CMS kann hier 🇬🇧 gefunden werden.

Eclipse Authoring Entwicklungsumgebung

Allgemeine Hinweise

Die Eclipse IDE belegt relativ viel Systemressourcen. Ein Arbeitsspeicher von mindestens 265 MB wird empfohlen. S.a. Verwaltung der DITA-Dateien

Installation

Die Installationsarten sind dem Eclipse-Artikel zu entnehmen.

Bei der Installation aus den Ubuntu-Quellen wird das Paket ant mitinstalliert. Die Wechselwirkungen mit der Ant-Version in dem DITA-OT1.4_fullpackage_bin.tar.gz Paket wurde nicht getestet. Der Pixware XMLmindEditor funktioniert nicht mit dem GNU Compiler for Java (s.o.). In dem Fall muss ein Eclipse-Paket selbst kompiliert werden.

EasyEclipse Distro Bälle

Die EasyEclipse 🇬🇧 "Distro-Bälle" enthalten 🇬🇧 eine Sun Java Runtime Environment. Die Wechselwirkungen der eingepackten Sun Java Version in diesen EasyEclipse Distrobällen mit einer schon lokal vorhandenen Sun Java Installation aus den Ubuntu Softwarequellen wurde nicht getestet. Linux besitzt ein durchdachtes Paketmanagement und deckt damit auch die Zielstellung des Easy Eclipse Paketes durch die Erstellung von Metapaketen ab.

Unabhängig davon bietet das Easy Eclipse Distribution-Plugin Chart 🇬🇧 eine gute Übersicht, um im Eclipse Ökosystem 🇬🇧 die richtige Auswahl der Komponenten zu finden. Für den Einsatz in einem Produktivsystem sollte aber eine native Eclipse-Installation mit den benötigten Sun Java-Komponenten bevorzugt werden.

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.com 🇬🇧 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 erfordert zwingend eine vorhandene Java 1.5 bzw. 5 und höher JDK-Entwicklungsumgebung und kann von der entsprechenden SourceForge Projektseite 🇬🇧 heruntergeladen werden. Desweiteren kann das Kit ohne administrative Rechte benutzt werden.

Hinweis:

Eine vorgefertigte Ordnerstruktur mit angepassten Transformations-Starter-Skripten kann hier ⮷ als Zip-Archiv heruntergeladen werden. Nach dem Entpacken [3] sollten die Ordnerstrukturen ~/00-personal-dita-publishing-environment/ und ~/00-personal-folder-misc/ vorhanden sein.

Die nachfolgende Beschreibung bezieht sich auf das FullPackage DITA-OT1.4_fullpackage_bin.tar.gz. Wichtig ist das FullPackage direkt im Homeverzeichnis zu entpacken. So befindet sich dann z.B. der Ant-Ordner im Pfad ~/ant/. Wird dieser Dateipfad nicht verwendet, wird die automatische Verwendung der Umgebungsvariablen wie nachfolgend beschrieben nicht funktionieren. Um Benutzerdateien nicht mit den Dateien des DITA Open Tool Kits zu vermischen, empfiehlt sich die Ablage von Benutzerdateien in ~/00-personal-folder-misc.

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

./startcmd.sh 

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

Überprüfung der DITA Open Tool Kit-Installation

Um die Installation zu überprüfen, wechselt man im Terminal [6] in den DITA Open Tool Kit-Ordner (/home/dita-account/) und startet den Transformationsprozess mit:

ant samples.web -f build_demo.xml 

Dadurch wird eine einfache Transformation in HTML durchgeführt.

Mit

ant all -f build_demo.xml 

werden alle verfügbaren Transformationen durchgeführt.

Mit

ant -f build_demo.xml 

ist es möglich interaktiv Grundeinstellungen vorzunehmen.

Der Transformationsprozess wird gestartet

Buildfile: build_demo.xml

und sollte im Normalfall mit

BUILD SUCCESSFUL
Total time: X minutes X seconds

enden. Während diese Transformationsprozesses werden die DITA Quelldateien aus dem Ordner ~/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 ~/out/ abgelegt.

Dokumentationen produzieren

Eine vorgefertigte Ordnerstruktur für eine Personal DITA Publishing Environment - PDPE mit angepassten Transformations-Starter-Scripts des DITA Open Tool Kits kann hier 🇬🇧 heruntergeladen werden.

Ablage der DITA Dateien

Lone-DITA 🇬🇧 bietet eine sehr gute DITA Schritt-für-Schritt Anleitung anhand vom XMLmindEditor. Weitere Informationen finden sich natürlich auch in der mitgelieferten Software-Dokumentation vom XMLMindEditor.

Nach der Zusammenstellung der beispielhaften beginners-tutorial.ditamap mit den relevanten Tasks, Concepts, Referenzen usw. wird die Transformation in ein Ausgabeformat durchgeführt.

Einfache Transformation mit Hilfe der dost.jar Datei

Diese einfache Transformation eignet sich gut dafür erstellte Ditamaps im Ausgabe Layout zu testen. Damit ist eine Erfolgskontrolle bei der Erstellung der dita konformen Dokumentation möglich. 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 /home/dita-account/startcmd.sh gestartet und z.B. die XHTML Transformation einer Ditamap wie folgt eingeleitet:

java -jar lib/dost.jar /i:/Dateipfad/zur/hello_world.ditamap /transtype:xhtml 

oder

java -jar lib/dost.jar /i:/home/dita-account/00-personal-dita-publishing-environment/ditamaps-and-topic-subdirectories/beginners-tutorial.ditamap /transtype:xhtml 

/home/dita-account/ kann nicht durch eine Tilde ~ ersetzt werden! Die Ausgabedateien sind standardmäßig im /home/dita-account/out Ordner zu finden.

Weitere Transformationstypen (transtype's) sind zum derzeitigen Stand: docbook, eclipsehelp, xhtml, eclipsecontent, javahelp, htmlhelp, pdf, troff, wordrtf

Ausführlichere Informationen können hier 🇬🇧 gefunden werden.

Angepasste Transformation

Die nachfolgende Anleitung geht davon aus, dass die DITA Dateien im Pfad ~/00-personal-dita-publishing-environment/ditamaps-and-topic-subdirectories abgelegt werden. Wichtig ist dabei 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, wird die Transformation der Dita-Dateien fehlschlagen.

Im Ordner ~/ant/ befinden sich verschiedene Transformations-Starterskripte:

  • template_docbook.xml

  • template_eclipsehelp.xml

  • template_htmlhelp.xml

  • template_javahelp.xml

  • template_pdf.xml

  • template_wordrtf.xml

  • template_xhtml.xml

Mit Hilfe dieser Vorlagen kann eine entsprechende Transformation eingeleitet werden. Die Transformation an sich kann an die eigene Bedürfnisse angepasst werden. Siehe dazu auch die entsprechenden Anleitungen im Lone-DITA-Tutorial 🇬🇧 .

Als Beispiel wird nachfolgend die Anpassung des template_xhtml.xml-Starterskripts erläutert. Das Starterskript wurde umbenannt und befindet sich nun im Ordner ~/00-personal-dita-publishing-environment/transformation-starter-scripts/dita2xhtml-starter-script.xml.

XHTML-Ausgabe bauen

Dazu wird in der Eclipse IDE oder im XMLmindEditor die Datei ~/ant/template_xhtml.xml geöffnet. Dann wird diese Datei als dita2xhtml-starter-script.xml im Ordner ~/00-personal-dita-publishing-environment/transformation-starter-scripts/ abgespeichert.

An der Datei dita2xhtml-starter-script.xml werden nun folgende Änderungen an den Dateipfaden /home/dita-account/ u.ä. vorgenommen. Dabei wird der Schrägstrich durch den Textstring ${file.separator} ersetzt.

project >
basedir .
default @DELIVERABLE.NAME@2xhtml
name @PROJECT.NAME@_xhtml

project > property
name dita.dir
value ${file.separator}home${file.separator}dita-account

project > import
file ${file.separator}home${file.separator}dita-account${file.separator}integrator.xml

project > target
depends integrate
name @DELIVERABLE.NAME@2xhtml

project > target > ant
antfile${file.separator}home${file.separator}dita-account${file.separator}build.xml
target init

project > target > ant > property
name args.input
value ${file.separator}home${file.separator}dita-account${file.separator}00-personal-dita-publishing-environment${file.separator}ditamaps-and-topic-subdirectories${file.separator}beginners-tutorial.ditamap

project > target > ant > property
name output.dir
value ${file.separator}home${file.separator}dita-account${file.separator}00-personal-dita-publishing-environment${file.separator}transformation-results${file.separator}xhtml

project > target > ant > property
name transtype
value xhtml

dita2xhtml-starter-script.xml speichern.

Das DITA Open Tool Kit starten:

./startcmd.sh 

und mit

ant -f ~/00-personal-dita-publishing-environment/transformation-starter-scripts/dita2xhtml-starter-script.xml 

die Transformation starten

Um diese Befehle zusammenzufassen, wird von der Datei ~/startcmd.sh eine Sicherheitskopie erstellt. Danach wird die im Editor geöffnet und an vorletzter Stelle als letzte Anweisung den zuvor manuell eingegebenen Befehl einzufügen:

...
ant -f ~/00-personal-dita-publishing-environment/transformation-starter-scripts/dita2xhtml-starter-script.xml
bash

In Zukunft ist es nur noch nötig:

  • darauf zu achten, dass DITA-Maps immer im ~/00-personal-dita-publishing-environment/ditamaps-and-topic-subdirectories Pfad abgelegt werden.

  • den Namen der zusammengestellten DITA-Map vor dem Transformieren (Build) in der ~/00-personal-dita-publishing-environment/ditamaps-and-topic-subdirectories/new.ditamap anzupassen.

  • das Starten des ~/startcmd.sh-Skriptes startet gleichzeitig das DITA Open Tool Kit und den XHTML Build-Prozess für die entsprechende DITA-Map.

Einarbeitung in das DITA Fachgebiet

Zum Einlesen empfiehlt sich die Lektüre der ditaref-book.chm Dokumentation. Diese CHM Datei befindet sich nach dem Entpacken des DITA Open Tool Kit im Pfad ~/doc/ditaref-book.chm Die CHM-Dateien lassen sich unter Linux mit der xchm Anwendung betrachten.

Plugins

Das Dita Open Tool kann durch verschiedene Plugins 🇬🇧 erweitert werden. Das docbook2dita Plugin z.B. erlaubt die Transformation von DocBook Dateien in das Dita Format.

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-java5-jdk (multiverse) und deren abhängige Paketen müssen nachinstalliert werden (ca. 15 MB) [1] [2].

⚓︎

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 von ActiveState 🇬🇧 ist ein kostenloser Open Source Cross Plattform Editor. Er 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 eine Open Source Version 🇬🇧 des Komodo Edit Editors eingearbeitet. Komodo Edit basiert auf Mozilla Code und ist somit in XUL 🇩🇪 umgesetzt. Drag&Drop zwischen dem ActiveState KomodoEditor und dem Pixware XMLMindEditor ist möglich. Dazu ist der Tab der geöffneten Dita Datei im Komodo Edit mit der Maus anzufassen und in die Eimer der XMLmindEditor ditamap fallen zulassen.

KDE Kate Editor

Kate bietet eine graphische Oberfläche für das grep-Tool. Der dazugehörige Fußzeilen-Reiter kann mittels "Window → Tool Views → Show Find in Files" angezeigt werden. Über den Fußzeilen-Reitern unten rechts befindet sich eine schmale gestrichelte Trennlinie. Diese Trennlinie wird mit dem Mauszeiger angefasst und nach oben aufgezogen. Damit sind dann die Eingabefelder für die Globale grep-Suche sichtbar. Nach der Eingabe der Suchbegriffe und beendeten Suchvorgang werden im unteren Feld die Suchergebnisse angezeigt. Diese Dateien müssen per Doppelklick geöffnet werden. Erst nach dem Öffnen der gefunden Dateien erscheinen die Dateien auf der linken Seite im File System Browser. Nach Betätigen des linken Seiten-Reiters "File System Browser" lassen sich die aufgeführten Dateien per Drag & Drop in die Eimer einer *.ditamap des Pixware XMLmindEditors einfügen.

Eclipse IDE

Dazu ist in Eclipse ein Projekt zu erstellen und danach ist innerhalb von Eclipse der komplette /ditamaps-and-topic-subdirectories/-Ordner mit allen DITA-Dateien in den Ordner ~/00-personal-dita-publishing-environment/ditamaps-and-topic-subdirectories/full-text-search-clipboard/ zu importieren. Dazu wird "File → Import → Filesystem" etc. benutzt.

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.

Eclipse bietet eine Unmenge an Erweiterungen an. Eventuell befindet sich im Eclipseplugincentral.com-Archiv 🇬🇧 auch ein spezielles Suchwerkzeug für die o.a. Aufgabe.

Versionsverwaltungssoftware

Auch der Einsatz einer Versionsverwaltung wie z.B. CVS, Subversion oder auch Archiv/Bazaar kann zur Verwaltung der DITA-Dateien hilfreich sein.

Die Desktopsuchen Archiv/Beagle, Catfish und Tracker sind für diese Aufgabe wahrscheinlich nicht geeignet. Strigi scheint allerdings in der Lage zu sein XML Dateien im Volltext durchsuchen zu können.

Literaturempfehlungen

Einsteiger

Fortgeschritten

DITA Einstieg

  • dita-ssp-Hintergrundwissen Der aktuelle uu.de Artikel wird derzeit überarbeitet.

  • dita-ssp Mit Veröffentlichung der Version 1.5 des Dita Open Tool Kits wird dieser Baustellenartikel den uu.de Mods zur Begutachtung übergeben.

  • Minimalismus Beschreibung des Minimalismus aus der Sichtweise der Organisation für die Verbesserung von strukturierten Informationsstandards (OASIS). Dieser Textteil wird nach Veröffentlichung des Dita Open Tool Kits in der Version 1.5 in den aktuellen Dita Hintergrund Artikel aufgenommen.

  • PDPE 🇬🇧 - Vorgefertigte Ordnerstruktur für eine Personal DITA Publishing Environment mit angepassten Transformations-Starter-Scripts des DITA Open Tool Kits

  • OASIS DITA Dokumente 🇬🇧 - Konzeptionelle Beschreibung (architectural specification) und Beschreibung der Auszeichnung/Tags (language specification)

  • OASIS DITA Technical Committee (TC) 🇬🇧

  • Lone-DITA, A DITA community for small documentation teams 🇬🇧 - Sehr gute DITA Schritt-für-Schritt Anleitung anhand vom XMLmindEditor. Die PDF Datei wurde aus DITA Dateien generiert. (teilweise auf MS Windows XP bezogen). Momentan offline (Juni 2008). Kann alternativ hier ⮷ bzw. Beispieldateien hier ⮷ heruntergeladen werden.

  • Yahoo DITA Users Discussion Group 🇬🇧 - Sehr aktiv und von Fachleuten besucht

  • dita.xml.org 🇬🇧 Thematisches DITA Portal

  • Adobe Systems Speaks Out on DITA: 🇬🇧 Internal use of FrameMaker, CMS, and DITA

  • Adobe FrameMaker Online Hilfe 🇬🇧 - Kapitel: Structured authoring using DITA. Adobe FrameMaker 8 versucht Layout- und strukturierte XML Authoring Funktionen unter einer gemeinsamen Benutzungsoberfläche zur Verfügung zu stellen.

  • Adobe Technical Communication Suite 🇩🇪

  • oXygen XML Editor and XSLT Debugger 🇬🇧 plattformunabhängig. Besitzt "Finden/Ersetzen in Dateien"-Funktion und kann XML Dateien strukturiert anzeigen. Diese Funktion ist äußerst wichtig für die Verwaltung von Dita Dateien und die Zusammenstellung von Ditamaps. Erfordert zwingend Sun Java Runtime. Sun JRE 1.6 update 02 enthält einen Bug beim "Datei öffnen"-Dialog und sollte nicht verwendet werden.

  • DITA Open Tool Kit 🇬🇧 - SourceForge Projektseite

  • IBM Task Modeler - Ein Eclipse Plugin um Modelle für das Verhalten der Zielgruppe einer Software zu analysieren und zu erstellen. Zielstellung ist die Benutzer zentrierte Erstellung einer DITA konformen Dokumentation.

  • DITA Open Toolkit Online Hilfe 🇬🇧 im Eclipse-Help Format (leicht veraltet)

  • Erstellung eines lokalen Eclipse Help Infocenters 🇬🇧 - Modifizierung einer lokalen Eclipse Installation zur Anzeige von transformierten EclipseHelp Dateien.

  • Scribus besitzt leider derzeit (noch) keine Möglichkeiten für das XML strukturierte Authoring und soll eine Alternative zu Adobe InDesign werden. Adobe InDesign besitzt Möglichkeiten zur Bearbeitung von XML Tags bzw. Import von XML DTDs. Siehe auch DITA 2 InDesign Plug-In 🇬🇧

Fortgeschritten


Diese Revision wurde am 12. Februar 2020 19:40 von Heinrich_Schwietering erstellt.
Die folgenden Schlagworte wurden dem Artikel zugewiesen: Bildung