parson AGDITA-Inhalte auf Knopfdruck veröffentlichen: das DITA Open Toolkit
Zugehörige parson-Leistung: DITA-XML für Technische Dokumentation
Sie schreiben Technische Dokumentation in DITA-XML und veröffentlichen aus diesem Format? Das klingt einfach: Ein Knopfdruck und wie von Zauberhand entsteht aus einem XML-Autorenwerkzeug oder einer Webanwendung heraus ein PDF, eine HTML-Dokumentation oder eine Webhelp. Aber ist es wirklich so einfach? Was geschieht unter der Oberfläche? Und was ist, wenn Sie Ihre Ausgabeformate anpassen wollen?
Das DITA Open Toolkit (DITA-OT) ist die Antwort. In diesem Artikel stellen wir Ihnen dieses kleine, aber sehr mächtige Werkzeug vor, das Ihre in DITA-XML geschriebene Dokumentation in das gewünschte Ausgabeformat umwandelt.
DITA-XML und das DITA Open Toolkit
DITA ist ein XML-Standard mit einer definierten Syntax bzw. Elementstruktur, der von zahlreichen XML-Autorenwerkzeugen unterstützt wird, z.B. Oxygen XML Author/Editor. Viele Unternehmen verwenden XML-Autorenwerkzeuge, um Technische Dokumentation zu schreiben, zu bearbeiten und zu prüfen. Zwar kann man DITA-XML auch ohne eine solche Software schreiben; ein XML-Autorenwerkzeug bietet aber so viele nützliche Funktionen wie Autorenunterstützung und automatische Validierung, dass sich dies nicht lohnt.
Der DITA-XML-Standard definiert jedoch nicht, wie die erstellten Inhalte in ein Format übertragen werden, das Anwender:innen, Webportale oder andere Anwendungen erwarten und das gut lesbar ist. Hier kommt das DITA OT ins Spiel.
Was ist das DITA Open Toolkit?
DITA OT ist ein Werkzeugkasten, mit dem DITA-Inhalte in die gewünschten Ausgabeformate verwandelt werden können. Außerdem liefert das DITA OT eine Umsetzung der DITA-Architektur in Form von Document Type Definitions (DTDs), XML Schemas (XSD) oder Relax NG (RNG). Diese Schemas leiten die Autor:innen und stellen sicher, dass ihre Inhalte DITA-konform sind.
Viele Autorenwerkzeuge und Content-Delivery-Portale bieten standardmäßig eine Unterstützung für das DITA OT. Sie können also mit dem DITA OT Ihre Ausgabeformate und ggf. die Schemas individuell anpassen und dann das DITA OT mit Ihren individuellen Anpassungen im Autorenwerkzeug und ggf. einem Content-Delivery-Portal integrieren. Hier sind die wichtigsten Eigenschaften des DITA OT:
- Kostenlos und herstellerunabhängig. Das DITA-OT kann überall und von jedem genutzt werden.
- Open Source. Das DITA OT wird von einer kleinen, unabhängigen Gruppe sowie der größeren Community auf GitHub gepflegt und weiterentwickelt.
- Unterstützt verschiedene Ausgabeformate, z.B. HTML, PDF, Markdown, Webhelp.
- Enthält die Basistechnologien Java, ANT und XSLT. PDF kann über den kostenlosen XSL-FO-Prozessor Apache FOP standardmäßig erstellt werden.
- Erweiterbar. Neue oder angepasste Ausgabeformte sowie angepasste Schemas können über den Plugin-Mechanismus des DITA-OT integriert werden.
DITA OT als Kommandozeilenwerkzeug
Das DITA OT ist ein reines Kommandozeilenwerkzeug. Sie können es aufrufen, bedienen und Ausgabeformate erzeugen, ohne ein XML-Autorenwerkzeug zu verwenden – auch wenn in diesem Fall entsprechende Komfortfunktionen fehlen. Einzige Voraussetzung ist eine vorhandene Java Runtime Environment.
DITA OT in XML-Autorenwerkzeugen wie Oxygen integrieren
Eins der am weitesten verbreiteten DITA-Tools ist Oxygen XML Author bzw. Oxygen XML Editor. Die Software verfügt standardmäßig über ein DITA-Framework mit integriertem DITA OT, sodass Sie Ihre DITA-Dokumente direkt in der Oxygen-Umgebung erstellen und veröffentlichen können.
Für die verschiedenen Ausgabeformate bietet Oxygen sogenannte Transformationsszenarien, mit denen Sie die Ausgabe von DITA-Inhalten an die Anforderungen eines Projekts anpassen können. Transformationsszenarien können direkt in Oxygen mit Hilfe verschiedener Parameter und Stylesheets konfiguriert werden. Es gibt aber auch einen Transformationstyp, der auf die Plugins im DITA OT zugreift. Neben den Standardausgabeformaten des DITA OT liefert Oxygen dazu auch eine Reihe eigener Formate, z.B. eine WebHelp.
Manche proprietäre Autorenwerkzeuge oder Redaktionssysteme verfügen über eigene Publikationsprozesse (Pipelines) für DITA nach PDF, z.B. Adobe FrameMaker, IXIA CCMS oder Tridion Docs. Da diese Werkzeuge kostenpflichtig und die Pipelines speziell für dieses Tool konzipiert sind, haben sie nicht den Verbreitungsgrad wie das DITA OT.
Wie passe ich die Ausgabeformate des DITA OT an?
Je nach Transformationstyp und Anwendungsfall erfolgt die Anpassung der Ausgabeformate direkt in Oxygen oder im entsprechenden Plugin des DITA OT. Dies ist z.B. dann sinnvoll, wenn das DITA OT auch außerhalb von Oxygen verwendet werden soll.
Wenn Sie Ihre Ausgabeformate im DITA OT anpassen möchten, müssen Sie separate Plugins konfigurieren. Innerhalb dieser Plugins können Sie Formate und Layout Ihres Ausgabeformats anpassen, z.B. Farben, Spaltenbreiten, Schriftgröße oder Abstände in PDF oder HTML. Je nach Format benötigen Sie dafür Kenntnisse in XSLT, XSL-FO oder CSS.
Ein solches Plugin macht Sie systemunabhängig. Nach dem Einbinden in das DITA OT können Sie das entsprechende Ausgabeformat direkt erzeugen.
DITA-Architektur mit dem DITA Open Toolkit anpassen
Der DITA-Standard liefert Elemente und Strukturen für Topic-basiertes Schreiben und Unterstützung für semantische Elemente und Topic-Typen aus verschiedenen Fachdomänen. Oft sind Autor:innnen mit der Auswahl der richtigen Strukturelemente und Auszeichnungselemente überfordert, da es so viele Wahlmöglichkeiten gibt. Sie können jedoch die Anzahl verfügbarer Möglichkeiten in DITA einschränken oder neue Elemente und Attribute definieren.
Auch dieser Anwendungsfall wird im DITA OT mithilfe von Plugins realisiert. Zunächst entscheiden Sie sich für eine dieser technischen Ausprägungen der DITA-Dokumentendefinition:
- DTD bietet die breiteste Toolunterstützung, ist aber etwas umständlich anzupassen.
- Relax NG ist die normative Grammatik des DITA-Standards und relativ einfach zu erlernen, wird aber immer noch von vielen Tools nicht unterstützt.
- XML Schema ist ähnlich einfach wie Relax NG, wird aber ab DITA 2.0 nicht mehr unterstützt.
Anschließend legen Sie für Ihre angepassten Schemas ähnlich wie bei den Ausgabeformaten ein eigenes Plugin an und überschreiben in diesem die Standardschemas. Die größte Herausforderung besteht dabei darin, die komplexe DITA-Architektur zu verstehen und nicht versehentlich zu zerstören.
Beispiel für die Implementierung eines DITA-OT-Plugins
parson hat bereits zahlreiche Unternehmen bei der Erstellung und Implementierung eigener DITA-OT-Plugins unterstützt. Diese Projekte umfassen oft nicht nur die initiale Einrichtung, sondern auch die ständige Anpassung, etwa bei Layout- oder CI-Änderungen, technischen Updates oder Erweiterungen der Funktionalitäten. Ein Beispiel ist der Halbleiterhersteller Nexperia, der seine Dokumentation in DITA-XML schreibt und seine Datenblätter als PDF publiziert.
Weitere Informationen finden Sie in unserer Projektreferenz.
Wir sind Expert:innen für DITA-XML und das DITA OT
Sie möchten DITA-XML für die Technische Dokumentation verwenden oder benötigen Plugins für das DITA Open Toolkit? Wir finden Ihre individuelle DITA-Lösung!
Neuen Kommentar hinzufügen