[[Vorlage(Archiviert, "Neuer Informationen findet man in den Artikel [:Darwin_Information_Typing_Architecture:] und [:Archiv/DITA_Single_Source_Publishing:]")]] ## [[Vorlage(Getestet, dapper)]] {{{#!vorlage Wissen [:Pakete_installieren: Installation von Programmen] [:Paketquellen_freischalten: Bearbeiten von Paketquellen] [:Packprogramme: Archive entpacken] [:Menüeditor: Programme zum Menü hinzufügen] [:Rechte: Rechte für Dateien und Ordner ändern] [:Shell: Sich im Terminal zurecht finden] }}} {{{#!vorlage Hinweis Dieser Artikel wurde überarbeitet. Siehe Baustellen Beiträge [http://wiki.ubuntuusers.de/Baustelle/dita-ssp-Hintergrundwissen dita-ssp-Hintergrundwissen] und [http://wiki.ubuntuusers.de/Baustelle/dita_ssp 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:Benutzer und Gruppen]. }}} [[Inhaltsverzeichnis(3)]] Die [http://de.wikipedia.org/wiki/DITA Darwin Information Typing Architecture - DITA] {de} 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 [http://de.wikipedia.org/wiki/Objektorientierte_Programmierung Objektorientierten Programmierung] {de} 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 [http://de.wikipedia.org/wiki/OASIS OASIS Standard] {de} . = 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 [#dita-Dateiverwaltung 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 [:Archiv/Subversion: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: [http://docs.oasis-open.org/dita/v1.1/archspec/archspec.pdf OASIS Architectural Specification 1_1 Chapter 3 DITA markup] {en} 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 [#OTKit DITA Open Tool Kit] im Pfad '''~/doc/ditaref-book.chm''' Die CHM-Dateien lassen sich unter Linux mit verschiedenen [#CHM-Viewer 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 [http://docs.oasis-open.org/dita/v1.1/archspec/archspec.pdf OASIS DITA DOC Archiv] {en} zu finden. Im [:Startseite: wiki.ubuntuusers.de] werden verschiedene [:Wiki/Syntax: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 [http://docs.oasis-open.org/dita/v1.1/archspec/archspec.pdf DITA Version 1.1 Architectural Specification S. 40 unten ca. 3MB PDF] {dl} und [http://docs.oasis-open.org/dita/v1.1/langspec/ditaref-type.pdf DITA Version 1.1 Language Specification S. 478 unten ca. 13MB PDF] {dl} zu finden. [[Anker(CHM-Viewer)]] = Grundinstallation = Die folgende Anleitung zum Einrichten einer DITA Publishing Umgebung sollte ähnlich auch unter anderen Linux-Distributionen funktionieren. S.a. [:Archiv/Andere_Distributionen: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 [http://bazaar-vcs.org/Olive Olive] {en} -Plugin in Bazaar eingebunden werden. Umfangreiche Dokumentation kann [http://doc.bazaar-vcs.org/ hier] {en} 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 [http://de.wikipedia.org/wiki/GNU_Compiler_for_Java GNU Compiler for Java] {de} 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: {{{#!vorlage Befehl 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 [http://de.wikipedia.org/wiki/Dtd DTDs] {de} lassen sich [http://docs.oasis-open.org/dita/ hier] {en} 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 [http://www.xmlmind.com/ XMLmind XML Editor] {en} 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 [:Fenstermanager: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:/// 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 == [http://www.ditastorm.com/ DITA Storm] {en} ist ein browser-basierter DITA XML Editor und kann [http://www.ditastorm.com/onlineDitaEditor.html hier] {en} online benutzt werden. Dazu ist JavaScript zu aktivieren. Zur Offlinebearbeitung kann dieser Editor auch [http://www.ditastorm.com/downloadContinue.html hier] {en} heruntergeladen werden. Eine Anleitung für die Integration in eine Webseite oder CMS kann [http://www.ditastorm.com/integration.html hier] {en} 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 [http://www.easyeclipse.org/ EasyEclipse] {en} "Distro-Bälle" [http://www.easyeclipse.org/site/plugins/sun-java-5-linux-x86.html enthalten] {en} 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 [:Metapakete:Metapaketen] ab. Unabhängig davon bietet das [http://www.easyeclipse.org/site/help/plugin-chart.html Easy Eclipse Distribution-Plugin Chart] {en} eine gute Übersicht, um im [http://www.easyeclipse.org/site/about/index.html Eclipse Ökosystem] {en} 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 [http://www.ditainfocenter.com/ Ditainfocenter.com] {en} gefunden werden. [[Anker(OTKit)]] == DITA Open Tool Kit == Mit dem [http://dita-ot.sourceforge.net/ DITA Open Tool Kit] (Open Source) {en} 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 [http://sourceforge.net/projects/dita-ot/ SourceForge Projektseite] {en} heruntergeladen werden. Desweiteren kann das Kit ohne administrative Rechte benutzt werden. {{{#!vorlage Hinweis Eine vorgefertigte Ordnerstruktur mit angepassten Transformations-Starter-Skripten kann [attachment:Darwin Information Typing Architecture/pdpe-vers-0-1.zip:hier] {dl} 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. {{{#!vorlage Befehl ./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: {{{#!vorlage Befehl ant samples.web -f build_demo.xml }}} Dadurch wird eine einfache Transformation in HTML durchgeführt. Mit {{{#!vorlage Befehl ant all -f build_demo.xml }}} werden alle verfügbaren Transformationen durchgeführt. Mit {{{#!vorlage Befehl 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 [http://tech.groups.yahoo.com/group/dita-users/ Yahoo DITA Users Discussion Group] {en} 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 [attachment:Darwin Information Typing Architecture/pdpe-vers-0-1.zip:hier] {en} heruntergeladen werden. ==== Ablage der DITA Dateien ==== [http://www.lone-dita.com/ Lone-DITA] {en} 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: {{{#!vorlage Befehl java -jar lib/dost.jar /i:/Dateipfad/zur/hello_world.ditamap /transtype:xhtml }}} oder {{{#!vorlage Befehl 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 [http://www.ibm.com/developerworks/library/x-tipditajavacmd.html hier] {en} 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''' * Die generierten Dateien müssen noch mit [http://en.wikipedia.org/wiki/Microsoft_Compiled_HTML_Help Microsoft Help Workshop] {en} in das CHM Format kompiliert werden. * '''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 [http://www.lone-dita.com/ Lone-DITA-Tutorial] {en} . 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 |${file.separator}home${file.separator}dita-account${file.separator}DITA-Flocken ||<-3> '''project > '''|| || '''basedir''' || . || || default || @DELIVERABLE.NAME@2xhtml || || name || @PROJECT.NAME@_xhtml || ||<-3> '''project > property ''' || || name || '''dita.dir''' || || value || ${file.separator}home${file.separator}dita-account || ||<-3> '''project > import''' || ||'''file'''|| ${file.separator}home${file.separator}dita-account${file.separator}integrator.xml || ||<-3> '''project > target''' || || depends || integrate || || name || @DELIVERABLE.NAME@2xhtml || ||<-3> '''project > target > ant''' || ||'''antfile'''||${file.separator}home${file.separator}dita-account${file.separator}build.xml|| ||target || init || ||<-3> '''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''' || ||<-3> '''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|| ||<-3> '''project > target > ant > property'''|| || name ||'''transtype'''|| || value || xhtml || '''dita2xhtml-starter-script.xml''' speichern. Das DITA Open Tool Kit starten: {{{#!vorlage Befehl ./startcmd.sh }}} und mit {{{#!vorlage Befehl 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 [http://sourceforge.net/project/showfiles.php?group_id=132728 Plugins] {en} 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]. [[Anker(dita-Dateiverwaltung)]] = 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 == [:Webeditoren: Komodo Edit] von [http://www.activestate.com/ ActiveState] {en} 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 [http://www.openkomodo.com/ Open Source Version] {en} des Komodo Edit Editors eingearbeitet. Komodo Edit basiert auf Mozilla Code und ist somit in [http://de.wikipedia.org/wiki/XUL XUL] {de} 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 [:Shell/grep: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 [http://www.eclipseplugincentral.com/ Eclipseplugincentral.com-Archiv] {en} 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. [:Archiv/Strigi:Strigi] scheint allerdings in der Lage zu sein XML Dateien im Volltext durchsuchen zu können. = Literaturempfehlungen = == Einsteiger == * [http://www.comet.de/ Sissi Closs: Single Source Publishing. Topicorientierte Strukturierung und DITA] {de} * 270 Seiten * Entwickler.Press Verlag * 1. Auflage (1. Dez. 2006) == Fortgeschritten == * [http://www.dita-buch.de/ Johannes Hentrich: DITA - Der neue Standard für Technische Dokumentation] {de} * 350 Seiten * XLcontent Verlag * 1. Auflage (Veröffentlichungstermin offen) = Links = == DITA Einstieg == * [http://wiki.ubuntuusers.de/Baustelle/dita-ssp-Hintergrundwissen dita-ssp-Hintergrundwissen] Der aktuelle uu.de Artikel wird derzeit überarbeitet. * [http://wiki.ubuntuusers.de/Baustelle/dita_ssp dita-ssp] Mit Veröffentlichung der Version 1.5 des Dita Open Tool Kits wird dieser Baustellenartikel den uu.de Mods zur Begutachtung übergeben. * [http://wiki.ubuntuusers.de/Baustelle/Minimalismus 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. * [attachment:Darwin Information Typing Architecture/pdpe-vers-0-1.zip:PDPE] {en} - Vorgefertigte Ordnerstruktur für eine Personal DITA Publishing Environment mit angepassten Transformations-Starter-Scripts des DITA Open Tool Kits * [http://docs.oasis-open.org/dita/ OASIS DITA Dokumente] {en} - Konzeptionelle Beschreibung (''architectural specification'') und Beschreibung der Auszeichnung/Tags (''language specification'') * [http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita OASIS DITA Technical Committee (TC) ] {en} * [http://www.lone-dita.com/ Lone-DITA, A DITA community for small documentation teams] {en} - 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 [http://www.ditausers.org/tutorials/lone-dita/ditaguide.pdf hier] {dl} bzw. Beispieldateien [http://www.ditausers.org/tutorials/lone-dita/tutorial.zip hier] {dl} heruntergeladen werden. * [http://tech.groups.yahoo.com/group/dita-users/ Yahoo DITA Users Discussion Group] {en} - Sehr aktiv und von Fachleuten besucht * [http://dita.xml.org/ dita.xml.org] {en} Thematisches DITA Portal * [http://www.travelthepath.com/adobeinterview.html Adobe Systems Speaks Out on DITA:] {en} Internal use of FrameMaker, CMS, and DITA * [http://help.adobe.com/en_US/FrameMaker/8.0/ Adobe FrameMaker Online Hilfe] {en} - 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. * [http://www.adobe.com/de/products/technicalcommunicationsuite/ Adobe Technical Communication Suite] {de} * [http://www.oxygenxml.com/ oXygen XML Editor and XSLT Debugger] {en} 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. * [http://sourceforge.net/projects/dita-ot/ DITA Open Tool Kit] {en} - SourceForge Projektseite * [http://www.alphaworks.ibm.com/tech/taskmodeler 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. * [http://www.ditainfocenter.com/ DITA Open Toolkit Online Hilfe] {en} im Eclipse-Help Format (leicht veraltet) * [http://dita.xml.org/wiki/setting-up-the-eclipse-help-infocenter-for-publishing-dita-content Erstellung eines lokalen Eclipse Help Infocenters] {en} - 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 [http://blog.reallysi.com/2008/01/call-for-partic.html DITA 2 InDesign Plug-In] {en} == Fortgeschritten == * [http://www.xiruss.org/tutorials/dita-specialization/ DITA Specialisation Tutorial] {en} ---- ## vim:filetype=moin # tag: Bildung