Eine Software erschließt sich für den Anwender erst durch ein Handbuch und/oder eine Online-Hilfe. In diesem Artikel soll gezeigt werden, wie auf der Grundlage von XML und unter Einsatz von XSLT und Python eine medienneutrale Benutzerdokumentation erstellt werden kann.
XML ist in aller Munde - warum sollte man dann nicht auch XML für die Benutzerdokumentation verwenden? Am Beispiel Cross-Media-Publishing möchte ich Ihnen die Vorteile von XML bei der Erstellung von Benutzerdokumentationen aufzeigen. Grundlage bildet dafür eine bei der Firma HaCon Ingenieurgesellschaft mbH entwickelte Lösung, die aus einem XML-Dokument generisch mittels XSLT und Python [1] eine HTML-basierte Online-Hilfe und über Adobe FrameMaker Version 7 [2] ein Handbuch im PDF-Format erzeugt. Die Lösung ist firmenspezifisch anpassbar und durch den Einsatz der im Folgenden vorgestellten Technologien beliebig erweiterbar. So lassen sich Benutzerdokumentationen kostengünstig und mit gleich bleibender Qualität erstellen. Gerade für Unternehmen, die nicht das Geld für teure Redaktionssysteme ausgeben wollen oder können, eignet sich die hier beschriebene Lösung, denn sie basiert, abgesehen von Adobes FrameMaker, auf Open Source-Technologien (Python) und offenen Standards (XML, HTML, XSLT, CSS).
Warum XML für die Benutzerdokumentation?
Für den Druck eines Handbuchs wird normalerweise ein DTP-Programm benötigt, für die Online-Hilfe ein HTML-Editor - der Autor muss beide Anwendungen kennen und beherrschen und sich auf die medienspezifischen Unterschiede im Detail einstellen. Dies lässt sich vermeiden, indem man Inhalte über ein medienneutrales Format wie XML publiziert. So lassen sich die Aufgaben in der Benutzerdokumentation klarer voneinander trennen: Der Autor erstellt dann wie gewohnt den Inhalt und ein Grafiker kann an dessen Präsentation arbeiten, indem er die Layoutvorlagen für das gewünschte Medium gestaltet (Trennung von Layout und Inhalt).
Ein Vorteil von XML ist, dass es sich in seiner Struktur durch ein Schema (DTD
oder XML Schema) beschreiben lässt: Durch ein aufgabenspezifisches Schema wird
gewährleistet, dass die Benutzerdokumentation in festgelegten Strukturen erstellt
wird. Eine gleich bleibende Qualität ist somit gesichert - ein gewichtiges Argument
für kundengerechte Benutzerdokumentation! Anstatt Schemata in Eigenregie zu entwickeln
oder von einem externen Dienstleister einzukaufen, lassen sich natürlich auch
bereits entwickelte Schemata, wie z.B. Docbook [3] oder der in der Luftfahrt eingesetzte
AECMA-Standard [4] verwenden - allerdings muss man dann auch deren Komplexität
in Kauf nehmen! Egal welches Schema verwendet wird, ein paar Eigenheiten müssen
für eine medienneutrale Anwendung berücksichtigt werden: So sollte das Schema
optionale medienspezifische Elemente und Attribute enthalten, um so z.B. durch
definierte Filterfunktionen Inhalte medienspezifisch ein- oder ausblenden zu können.
Als Beispiel wäre hier die nur im Handbuch lesbare Installationsanleitung zu nennen,
da eine Online-Hilfe in den meisten Fällen erst über ein installiertes Programm
nutzbar ist. Genauso dürfen wichtige Inhaltselemente in einer Benutzerdokumentation
nicht fehlen. So sind z.B. Abschnitte, Handlungsanweisungen, Erklärungen, Hinweise,
Querverweise, Fachbegriffe usw. zur inhaltlichen Strukturierung unerlässlich.
XML ist aber noch weitaus leistungsfähiger: XML-Elemente lassen sich durch selbst definierte XML-Attribute ergänzen und dann durch geeignete Parser filtern oder ergänzen. Mit diesem Mechanismus werden in unserer Benutzerdokumentation erklärungsbedürftige Fachbegriffe über einen im XML-Attribut eingetragenen Datenbankschlüssel mit der korrespondierenden Terminologie-Datenbank verknüpft. Ein Python-Programm extrahiert anhand des Schlüssels die in der Datenbank gespeicherten Definitionen und fügt Sie als Attributtext zum Element hinzu oder erstellt für das Handbuch einen gesonderten Glossareintrag (Begriff/Definition) in der Glossar-Dokumentenvorlage.
<table border="0" width="100%" bgcolor="#0854FF" cellpadding="5" cellspacing="0">
<tr>
<td>
<table border="0" width="100%" bgcolor="#FFFFFF" cellpadding="5" cellspacing="0">
<tr valign="middle">
<td height="10">
Flexibilität mit Python</td>
</tr>
<tr>
<td>Wer als Autor auf Standardwerkzeuge wie DTP-Programm, Textverarbeitung
oder Grafikprogramm setzt, der stößt in vielen Fällen schnell an deren
Grenzen. So kann z.B. der Auftrag, mal eben das Dateiformat oder die
Bildgröße von 500 Grafiken zu ändern, schnell die weitere Produktion
lahm legen. Solche Aufgaben erfordern den Einsatz eines programmierbaren
Werkzeugs. Skriptsprachen wie Perl, PHP, Python oder Ruby sind durch
ihre einfache Syntax und den umfangreichen Standardbibliotheken für
die alltäglichen Probleme gewappnet. Der Autor des Artikels hat sich
für die Programmiersprache Python [1] entschieden. Neben der klaren
und kompakten Syntax, ist Python mit einer umfassenden und erweiterbaren
Standardbibliothek ausgestattet, objektorientiert programmierbar und
lässt sich plattformübergreifend einsetzen. So kann ein Autor über
Python beispielsweise:
- dateiübergreifend mit regulären Ausdrücken beliebige Texte ersetzen,
- automatisch Fachbegriffe extrahieren und kontrollieren (Terminologiekontrolle),
- XML-Dokumente über standardisierte Schnittstellen (DOM, SAX) bearbeiten,
- über Datenbankschnittstellen beliebige Daten abfragen, ändern oder löschen (Database Publishing),
- automatisch Bilder oder Texte in andere Formate konvertieren oder
- eigene Agenten zur automatischen Informationsbeschaffung programmieren.
Literatur zum Thema Python gibt
es reichlich, allerdings werden in den vom Autor gelesen Büchern andere
Einsatzfelder als die Benutzerdokumentation bedient - diese Brücke
muss der interessierte Leser derzeit noch selber bauen. </td>
</tr>
</table>
</td>
</tr>
</table>
Welche Technologie übernimmt welche Aufgabe?
XML ist auch die Grundlage für alle weiteren verwendeten Technologien. Mit Hilfe von Adobe FrameMaker 7 werden einerseits die strukturierten Dokumente erstellt und zu gültigen XML-Dokumenten für die Online-Hilfe-Konvertierung exportiert. Andererseits lassen sich XML-Dokumente über die integrierten DTP-Funktionen als Handbuch formatieren. Für die lesegerechte Darstellung existieren eine FrameMaker-Layoutvorlage für das Handbuch und für die Online-Hilfe ein Cascading Style Sheet. XSLT konvertiert das aus FrameMaker exportierte XML-Dokument zu einem für Online-Hilfen geeigneten Ausgabeformat (HTML). Python erfüllt übergreifende Funktionen, um z.B. eine große HTML-Datei in einzelne lesegerechte HTML-Dateien aufzuteilen und anschließend dateiübergreifend zu verlinken sowie um bestimmte Informationen aus einer Datenbank zu extrahieren und dem XML-Dokument hinzuzufügen (Glossar). Die Online-Hilfe wird direkt im Browser gelesen oder über einen Hilfe-Compiler in eine eigenständige Online-Hilfe umgewandelt.
Abb. 1: Das Zusammenspiel der Tools
Ein XML-Dokument erstellen
Ein XML-Dokument lässt sich am besten über einen XML-Editor erstellen. Der verwendete XML-Editor sollte aber in Verbindung mit einem Schema arbeiten. Das heißt, der Autor darf bei der Erstellung ausschließlich Elemente und Attribute einfügen, die in dem aktuellen Inhaltskontext gemäß des Schemas erlaubt sind. Sonst entstehen nicht die für die Benutzerdokumentation so wichtigen gleichbleibenden Inhaltsstrukturen. Genauso ist eine Strukturansicht sinnvoll, die dem Autor die Dokumentenstruktur hierarchisch anzeigt. Unterschiedliche Dokumentansichten (Textmodus, Strukturmodus) erleichtern dem Autor den Umgang mit strukturierten Dokumenten.
In der Technischen Dokumentation hat sich Adobes FrameMaker als Standardwerkzeug etabliert (auf der Firmen-Homepage stellt Adobe entsprechende Lösungen vor [2]). Seit der Version 7 wird von Adobe keine getrennte SGML-Version ausgeliefert, sondern FrameMaker 7 beherrscht von Haus aus XML. Wer den FrameMaker bereits für die Handbucherstellung verwendet, braucht keinen weiteren XML-Editor wie z.B. Altovas xmlspy [5], da FrameMaker vergleichbare Editierfunktionen anbietet und ebenso standardisiertes XML erzeugt.
Für strukturierte Dokumentenerstellung werden im FrameMaker mehrere Dateien benötigt:
- Eine Projektdatei für die strukturierte Arbeitsumgebung,
- eine Schreib/Leseregeln-Datei (Read/Write Rules) für den XML-Import/-Export,
- eine EDD-Datei (Element Definition Document) für die Strukturinformation, die Formatierungen sowie zusätzlichen Produktionsregeln für das Handbuch,
- eine daraus abgeleitete XML-DTD-Datei für den XML-Import/-Export und
- eine Layoutvorlagen-Datei für die Druckdarstellung.
Der Autor erstellt das XML-Dokument über die folgenden drei Arbeitschritte: Zuerst ein leeres FrameMaker-Dokument anlegen, dann das Dokument über die EDD strukturieren und über die Layoutvorlage formatieren und anschließend den Inhalt über die integrierten Werkzeuge erstellen. Das fertige Dokument wird abschließend über die XML-Exportfunktion in ein gültiges XML-Dokument für die Online-Hilfe umgewandelt. Für den XML-Export werden die definierten Schreib-/Leseregeln verwendet.
FrameMaker stellt dem Autor zusätzliche Werkzeuge zur Verfügung, um einfach und sicher gültige XML-Dokumente erstellen zu können. Er kann kontextabhängig aus dem Elementkatalog Elemente und Attribute in das Dokument einfügen (siehe Abb. 2). Über die EDD-Produktionsregeln werden bestimmte Elemente und Attribute automatisch in das Dokument eingefügt oder kontextabhängig formatiert, um die Erstellung von komplexen Dokumenten zu vereinfachen. Die Struktur des Dokuments wird über eine im separaten Fenster angezeigte Strukturansicht grafisch dargestellt (siehe Abb. 3). Strukturverletzungen werden dabei rot dargestellt, so kann der Autor direkt während des Erstellungsvorgangs die Integrität der eingefügten Elemente und Attribute gegenüber dem Schema (EDD/DTD) validieren. Die Elementnamen (Tags) und die Elementgrenzen lassen sich in der Dokumentenansicht ein- oder ausblenden. Eine abschließende Dokumenten-Validierung übernimmt der integrierte Parser auf Wunsch.
Abb. 2: Kontextabhängiges Editieren
Abb. 3: Die Dokumentenstruktur in der Strukturansicht
Vom XML-Dokument zum Handbuch
Für den professionellen Handbuch-Druck eignen sich alle DTP-Programme, die XML importieren und darstellen können oder wie FrameMaker gleich eine strukturierte Arbeitsumgebung und ausgefeilte Layoutfunktionen bereitstellen. Natürlich lassen sich für eine reine Druckausgabe geeignete Formate (z.B. PDF) über XSL:FO [6] und einen Layout-Prozessor wie FOP [7] erzeugen, aber ein DTP-Programm bietet direkte WYSIWYG-Unterstützung für die Layout-Bearbeitung - so lassen sich flexibel Texte und Grafiken direkt auf dem Bildschirm gestalten. Bei entsprechend gestalteten Layoutvorlagen braucht sich ein Autor auch nicht mehr um eine Seitennummerierung, Kopf- und Fußzeilen oder ein Inhaltsverzeichnis zu kümmern - alle Formatierungen, die ein XML-Dokument zum professionelles Handbuch werden lassen, sind in der Layout-Vorlage definiert und lassen sich mit den integrierten DTP-Funktionen jederzeit nachbearbeiten.
Ein XML-Dokument muss mit FrameMaker in eine existierende strukturierte Arbeitsumgebung importiert werden, es sei denn, es wurde bereits mit FrameMaker erstellt. Die Schreib-/Leseregeln bilden die Brücke zwischen extern vorliegenden XML-Dokumenten einerseits und interner Dokumenten-Darstellung in FrameMaker andererseits. Die in der Layoutvorlage definierten Seitenlayouts und Absatz- und Zeichenformate stellen die XML-Elemente druckspezifisch dar. Wenn das XML-Dokument fertig importiert und formatiert ist, lässt es sich durch Inhaltsverzeichnis und Index inklusive der druckspezifischen Angaben (wie z.B. Seitenzahlen) ergänzen und abschließend, über den im Lieferumfang enthaltenen Acrobat Distiller, komplett als PDF-Datei exportieren.
Vom XML-Dokument zur Online-Hilfe
Das fertige XML-Dokument wird über XSLT und Python in eine Online-Hilfe konvertiert. Diese Konvertierung läuft automatisch ab. Zuerst wird über XSLT das medienneutrale XML in das Ausgabeformat HTML konvertiert, das später über ein Cascading Stylesheet (CSS) medienspezifisch formatiert wird. Für die XML-Transfomation eigenen sich alle XSLT-Prozessoren, die XSLT 1.0 [8] unterstützen. Wir verwenden Apache Xalan [9], der sich auch über das Python-Pyana-Modul [10] steuern lässt.
Über XSLT werden aus dem XML-Dokument drei Dateien erzeugt:
- eine HTML-Datei, die den Inhalt enthält,
- ein hierarchisches Inhaltsverzeichnis, das durch rekursive XSLT-Regeln erzeugt wird (siehe Listing 1)und
- ein Index, der die im XML-Dokument enthaltenen Indexelemente auflistet, um eine Stichwortsuche zu ermöglichen.
Das Inhaltsverzeichnis und der Index sind vom Format des später verwendeten Hilfe-Compilers abhängig. Bei einem großen XML-Dokument (wie es üblicherweise bei Benutzerdokumentationen vorkommt) entsteht eine entsprechend große HTML-Datei, die für eine HTML-basierte Online-Hilfe in dieser Form nicht geeignet ist. Ein Python-Programm (siehe Listing 2) teilt jedoch über in XSLT definierte Markierungen den Inhalt in einzelne HTML-Dateien auf, um dem Medium Online-Hilfe gerecht zu werden. Welche Inhaltsabschnitte markiert werden, kann der Autor frei definieren. Allerdings verlieren dann alle in der ursprünglichen HTML-Datei enthaltenen Hyperlinks ihre Gültigkeit, weil der Hyperlink nun auf einen Inhalt verweist, der in einer anderen Datei steht. Deswegen werden auch alle Hyperlinks durch das Python-Programm aktualisiert. Wenn ein Hyperlink gefunden wird, der auf einen Inhalt referenziert, denn es gar nicht (oder nicht mehr) gibt, dann wird der falsche Hyperlink in eine Fehlerliste eingetragen (Link-Checker). Der Autor korrigiert dann den Querverweis im XML-Dokument und startete die Konvertierung neu. Das Python-Programm erzeugt abschließend eine Projektdatei für den Hilfe-Compiler und aktualisiert das Inhaltsverzeichnis und den Index um die erzeugten Dateinamen.
Listing 1 <?xml version="1.0" encoding="UTF-8" ?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="html" indent="no" />
<!-- Generierung HTML Inhaltsverzeichnis -->
<xsl:output method="html" />
<xsl:template match="/">
<HTML>
<head></head>
<body>
<xsl:apply-templates select="document"/>
</body>
</HTML>
</xsl:template>
<xsl:template match="document">
<!-- fuer alle Kapitel -->
<xsl:for-each select="chapter">
<h2><a href="#{head/@Id}" ><xsl:value-of select="head"/></a></h2>
<!-- fuer alle Abschnitte -->
<ul>
<xsl:apply-templates select="section"/>
</ul>
</xsl:for-each>
</xsl:template>
<xsl:template match="section">
<li>
<!-- fuer alle Ueberschriften -->
<xsl:for-each select="head">
<a href="#{./@Id}" ><xsl:value-of select="."/></a>
</xsl:for-each>
<xsl:choose>
<!-- FALLS weitere Unterabschnitte DANN Rekursion -->
<xsl:when test="./section">
<ul>
<xsl:apply-templates select="section"/>
</ul>
</xsl:when>
</xsl:choose>
</li>
</xsl:template>
</xsl:stylesheet>
Listing 2 import re, string, sys
''' Dieses Skript teilt eine grosse HTML-Datei an vorgegebenen Trennmarken
in kleine Dateien auf. Aufruf: python cut.py %1 %2
wobei:
%1 = Dateiname der zu splittenden Eingabedatei
%2 = Angabe der Trennmarke als regulaerer Ausdruck z.B. :
<!--cut--> als HTML-Kommentar
'''
def cut_string(string, pattern):
# Funktion: teilt Sting an Trennmarken auf und fuegt den Teilstring der Rueckgabeliste zu
# Uebergabeparameter: string = Uebergabestring, der aufgeteilt wird
# Uebergabeparameter: pattern = regulaerer Ausdruck, der die Trennmarkierung beschreibt
# Rueckgabe: stringlist = Liste des aufgeteilten Strings
count = 0
lastpos = 0
stringlist = []
beginfile = re.compile(pattern, re.I|re.M)
all = beginfile.findall(string)
for elements in all:
newpos = beginfile.search(string, lastpos)
stringlist.append(string[lastpos:newpos.start()])
lastpos = newpos.end()
count += 1
# das Stringende anfuegen:
newpos = beginfile.search(string, lastpos)
stringlist.append(string[lastpos:])
return stringlist
if __name__ == "__main__":
count = 0
# Uebergabeparameter infile = zu splittende Eingabedatei
infile = open(sys.argv[1] ,'r').read()
# Uebergabeparameter cutpoint = regulaerer Ausdruck fuer Trennmarken in Eingabedatei
cutpoint = sys.argv[2]
for items in cut_string(infile , cutpoint):
outfiles = open(str(count)+'.html','w')
outfiles.write(items)
outfiles.close()
count +=1
Über eine XML-Konfigurationsdatei lässt sich das Python-Programm flexibel an anderen Anforderungen anpassen. Die Konfigurationsdatei enthält alle projektabhängigen Parameter (Dateipfade, Dateiendungen usw.) und Vorlagen für den Kopf und den Fuß der einzelnen HTML-Dateien. Im HTML-Kopf stehen z.B die Navigationselemente (
Vor und
Zurück), um später dem Leser einen linearen Lesefluss (Blättern) innerhalb der Online-Hilfe zu ermöglichen. Im HTML-Fuß stehen z.B. Logos oder das Impressum der Firma.
Medienformate: Online und Print
Elektronische Medien (Online-Hilfen) sind anders aufgebaut als Print-Medien (Handbücher): In einem Print-Medium werden die einzelnen Inhalte in eine lineare Form gebracht und durch eine hierarchische Gliederung, einen Advanced Organizer, einen alphabetischen Index und eventuell ein Register für den Leser organisiert. Ergänzende Inhalte werden durch Querverweise miteinander verbunden oder als Fußnote notiert. Der Leser kann interessante Seiten mit Lesezeichen versehen, mit dem Textmarker wichtige Stellen markieren und einzelne Inhalte durch eigene schriftliche Anmerkungen ergänzen.
In einer Online-Hilfe steht hingegen die Interaktion im Vordergrund: Bei kontextsensitiven Online-Hilfen werden die relevanten Inhalte über die Anwendung aufgerufen, wie z.B. bei Windows-Systemen über die berühmte
F1-Funktionstaste. Zusatzinformationen lassen sich so gestalten, dass diese dem Leser erst durch einen Mausklick angezeigt werden: So kann in der Online-Hilfe ein Glossar gleich im Text mitgeführt werden, indem bei erklärungsbedürftigen Begriffen dem Leser per Mausklick in einem Popup-Fenster eine Definition angeboten wird. Der Lesefokus bleibt dabei auf dem betroffenen Inhalt. Um die Online-Hilfe aber auch ohne konkreten Programmbezug - also eher konzeptionell zu nutzen - bieten sich zusätzliche Navigationselemente an, wie z.B.:
- ein verlinktes Inhaltsverzeichnis,
- ein verlinkter Index,
- Vor- und Zurück-Schaltflächen, um in der Online-Hilfe linear zu blättern,
- thematische Links,
- eine History-Liste, die bereits besuchten Seiten anzeigt und
- eine Suchen-Funktion, über die sich beliebige Textstellen auffinden lassen.
Um beiden Medientypen gerecht zu werden, sollten das medienneutrale XML-Dokument immer aus thematisch abgeschlossenen, hierarchisch angeordneten Informationsabschnitten bestehen, die nur durch einen Querverweis auf andere Inhalte verweisen und nicht durch Formulierungen wie z.B. wie schon auf Seite x erwähnt oder, auf der nächsten Seite, denn wo ist in der Online-Hilfe die nächste Seite? Die unterschiedliche Informationsdichte pro Blatt oder Bildschirmseite legt der Autor über Layoutvorlagen fest. Durch selbst definierte XML-Attribute lassen sich Inhalte für das jeweilige Ausgabeformat ein- oder ausschalten (filtern).
Was die Zukunft bringen könnte
Der Einsatz von XML öffnet im Bereich Dokumentation die Tür für weitere denkbare Anwendungen zusätzlich zum Cross-Media-Publishing: So könnten zukünftig XML-Dokumente oder sogar einzelne XML-Strukturen in einem nativen XML-Datenbanksystem gespeichert und so beliebig oft wiederverwendet werden. Damit die einzelnen Inhalte jederzeit wieder auffindbar wären, würden Sie über RDF-basierte Metainformationen wie z.B. Dublin Core [11] ausgezeichnet. Ein Applikationsserver wie z.B. Zope [12] würde den Zugriff (Workflow, Rechte) der Autoren auf das XML-Datenbanksystem regeln und eine webbasierte Benutzeroberfläche zur Verfügung stellen. So entstünde nach und nach ein individuell anpassbares Redaktionssystem, das dem Autor seine täglichen Arbeit wesentlich erleichtert.
Christian Kopecki (christian.kopecki@hacon.de) arbeitet als Technischer Redakteur bei der Firma HaCon Ingenieurgesellschaft mbH in Hannover. Zu seinen Aufgabenbereichen zählen neben der Benutzerdokumentation auch die Entwicklung von Lösungen und Tools rund um die Dokumentation. Links und Literatur
Hat Ihnen dieser Artikel gefallen? Dann abonnieren Sie das Entwickler Magazin direkt über unser
