vishia - Dokumentationsgenerierung mit XML

vishia - Dokumentationsgenerierung mit XML

Inhalt


1 Übersicht

Topic=.XmlDocuGen.overviewNavigation.

ulStyle=list-closely

Im Bild ist der Gesamtzusammenhang der Dokumentengenerierung dargestellt. Auf den wesentlichen Blöcken befinden sich Linkflächen, die zu den einzelnen Teilaspekten führen. Diese Linkflächen sind nachfolgend noch einmal als Liste aufgeführt.

Die Dokumentengenerierung basiert auf einzelnen kommandozeilenorientierten Konvertierungsschritten. Mit der Auswahl der Inputfiles je eines Konvertierungsschrittes wird der Inhalt der zu erzeugenden Dokumente bestimmt. Die einzelnen Konvertierungsschritte können am einfachsten in einem batch-Ablauf (unter Windows ein batchfile) ausgeführt werden. Besser ist es jedoch, das dafür bekannte und verbreitete XML-basierende Maketool ANT aus dem Eclipse-Bereich zu benutzen. Die Generierung der hier sichtbaren Seite ist mit der hier vorgestellten Dokumentengenerierung unter Nutzung von ANT realisiert, kann also als Beispiel dienen.

Die Dokumentengenerierung besteht insgesamt aus den einzelnen Teilen in meist je einem eigenem HTML-File:

2 Motivation

Topic=.XmlDocuGen.conceptualFormulation.

pStyle=standard ulStyle=list-closely

XML ist im Web verbreitet, HTML-Seiten werden oft aus XML-Datenbeständen aufbereitet. Meist wird XML vorrangig mit dem Web in Verbindung gebracht. Dabei sind Anwendungsgebiete von XML viel umfassender. XML ist ein allgemeingültiges Codierungskonzept für Daten. XML ist zu finden bei

  • Datenarchivierung: Nicht nur XML-basierende Datenbanksysteme, mit XML gespeicherte Daten sind tool- und versionsunabhängiger. XML als Basis für die Datencodierung löst mehr und mehr propritäre Datenformate ab, selbst bei Microsoft.

  • Datenaustausch: Auch bei einem Datenaustausch können mit XML toolspezifische Barrieren überwunden werden. XML wird verwendet bei der Codierung der Daten in auszutauschenden Files (Export -> Import) oder auch bei Datenströmen bei Netzwerkverbindungen.

Weil Daten in XML vorliegen, kann eine Dokumentationsgenerierung auf der Basis XML aufbauen. Input-Informationen sind dabei entweder Klartexte oder xhtml-Anteile:

  • Inhalt von Beschreibungsfelder beispielsweise

    • Beschreibung von UML-Modell-Komponenten in einem XMI-File,

    • Artikelbeschreibungen in einem Artikeldatenbestand,

  • Beschreibungstexte in Topics,

  • Textdokumente selbst, beispielsweise Winword-2003 in XML gespeichert, als Input für Weiterverwendung. oder die Daten in ihren Zuordnungen selbst.

  • Auflistung aller Methoden und Attribute von Klassen im UML,

  • Listen Artikel - Stückzahlen im Lager,

  • Parameter und der aktuell eingestellte Wert.

Auch Daten, die nicht in XML vorliegen, können einbezogen werden. Diese Daten werden dazu nach XML konvertiert. Die SBNF-Konvertierung spielt dabei die Schlüsselrolle. Input-Informationen nicht in XML sind beispielsweise

  • Programmcodes, hierbei insbesondere C/C++-Headerfiles. Diese beschreiben Datenstrukturen,

  • Export aus Excel und ähnlichen Programmen im CSV-Format,

  • Topics in Textform.

Damit wird die klassische eigenständige Erstellung einer Dokumentation mit einem Textverarbeitungssystem abgelöst von einer integrierten Dokumentationserstellung aus Datenbeständen, Quellfiles und zugehörigen Beschreibungstexten. Das ist mit einer konsequenten Trennung der Erfassung der eigentlichen Information von der Aufbereitung für ein bestimmtes Dokument verbunden.

Aufgrund der Vielfältigkeit der Codierungsarten der Input-Informationen ist die hier vorgestellte XML-Dokumentengenerierung nicht ein fertiges Tool - das wäre zugeschnitten - sondern wird als Grundprinzip vorgestellt, das der Anwender nach eigenem Ermessen ausbauen kann. Konkret wird eingegangen auf die

  • Konvertierung von Dokumentation aus Headerfiles

  • Dokumentationsgenerierung aus UML-Modellen über XMI

  • Nutzung von Topics

Die HTML-Seiten dieses Internetauftrittes ist zum großen Teil mit der hier vorgestellten Dokumentationsgenerierung erzeugt. Die Dokumentationsquellen werden auch teils für ganz andere Dokumente im Bereich meiner beruflichen Tätigkeit verwendet. Das ist ebenfalls eine Motivation zur Nutzung dieser Dokumentationsgenerierung.

Zu diesem Thema wird voraussichtlich in der Zeitschrift Entwickler Magazin des Software & Support - Verlages Ausgabe 3, ein Artikel von mir erscheinen.

3 Was braucht man - download

Topic=.XmlDocuGen.toolbase.

pStyle=standard ulStyle=list-closely

Folgend ist alles benannt, was als Tools für die Dokumentengenerierung mit XSL notwendig ist. Nicht dabei sind die Anwender-Dateien.

3.1 Betriebssystem, Externe Software

Topic=.XmlDocuGen.toolbase..

pStyle=standard ulStyle=list-closely

Als ausführbares Programm muss auf dem Zielrechner >>Java installiert sein. Die Version 1.4 genügt, höher darf sein.

Um die Steuerung der Generierung über Eclipse-Ant zu nutzen, kann entweder Eclipse komplett installiert sein (ca. 180 MByte), oder nur das Eclipse-Ant-Plugin allein wird auf der Festplatte plaziert (ca. TODO MByte).

Die XML-Verarbeitung in den eigenen Java-Programmen basiert auf jdom. Die offizielle Seite ist http://www.jdom.org, dort kann man sich das Java-Archiv jdom.jar herunterladen. Es steht aber auch auf den vishia-Seiten zur Verfügung: download:_jdom.jar. Die Lizenzbedingungen von jdom.org sind zu beachten. Freie Nutzung ist gestattet.

Das ist der Bedarf an externer Software.

3.2 vishia - Xslt.jar

Topic=.XmlDocuGen.toolbase..

pStyle=standard ulStyle=list-closely

Im Java-Archiv download:_xslt.jar sind wesentliche Java-Programme für die Dokumentengenerierung zu finden. Alle Sources dafür befinden sich im vishia-Java-Bereich. Die wesentlichen Programme (classes mit main) sind:

  • vishia/xslt/Xslt: XSL-Translator. Der Kern wird aus javax.xml genutzt, jdom ist eine Hülle, einigen Eigenschaften sind erweitert und zu einem main-Programm zusammengefasst.

  • vishia/xslt/Xsltpre: Präprozessor für XSL-Scripts. Das ist ein relativ einfaches Programm, dass in xsl-Scripts Ersetzungen für Kurzschreibweisen vornimmt. Solche xsl-Scripts sind hier allesamt mit der Endung .xslp versehen. Sie sind besser les- und pflegbar. Das Programm wandelt nach Standard-xsl.

  • vishia/xml/CorrectHref: Das ist dasjenige wesentliche Programm, dass Hyperlinkzuordnungen vornimmt. Dieses Programm ist exakt auf die hier vorgestellte Dokumentengenerierung zugeschnitten, das Verhalten wird gesteuert vom Steuerfile der Dokumentengenerierung.

  • vishia/stringScan/SBNF2Xml: Der SBNF-Parser.

3.3 XSL-Scripts uns SBNF-Scripts

Topic=.XmlDocuGen.toolbase..

pStyle=standard ulStyle=list-closely

Alle XSL- und SBNF-Scripts und einige batchfiles (für Windows) befinden sich im download:_XmlDocu_xsl. Das sind drei Verzeichnisse, die gemeinsam in ein Anwenderverzeichnis eingeordnet werden sollen, in der auch xslt.jar steht. Eine Umgebungsvariable XML_TOOLBASE soll dorthin zeigen:

 XML_TOOLBASE
  |
  +--xslt.jar
  +--jdom.jar
  |
  +--Sbnf2Xml
  |   +--SBNF-Scripts
  |
  +--XmlDocu_batch
  |   +--batchfiles (windows)
  |
  +--XmlDocu_xsl
      +--XSL-Scripts

Folgende Scripts spielen eine wesentliche Rolle:

  • Sbnf2Xml/DocuGenCtrl.sbnf: Das ist das SBNF-Script, mit dem der textuelle Dokumentengenerierungs-Steuerfile in ein XML-File gewandelt wird. Das Script kann der Anwender erweitern mit speziellen Generierungsaufrufen. Bei Syntaxproblemen sollte hier nachgeschaut werden.

  • XmlDocu_xsl/GenDocuCtrl2Xsl.xslp: Dieses Script verwandelt den mit DocuGenCtrl.sbnf erzeugten XML-File in ein XSL-Script für die Anwendergenerierung des NAME.pre1.xml. Es ist essentiell für die Anpassung der Dokumentengenerierung an Anwenderwünsche. Die speziellen Konvertierungen werden aber durch importierte Scripts realisiert. Damit entsteht eine Unabhängigkeit der Quellenpflege der allegemeinen Konvertierung mit den special.xsl.

  • XmlDocu_xsl/GenDocuCtrl2Ant.xslp: Dieses Script verwandelt den mit DocuGenCtrl.sbnf erzeugten XML-File in ein Eclipse-Ant-Steuerfile. Damit werden alle Konvertierungen aufgerufen. Wenn der Anwender eine spezielle Konvertierung braucht, dann muss er dieses Script ergänzen.

  • Sbnf2Xml/AsciiTopics.sbnf: Mit diesem SBNF-Script ist es möglich, flach-textuell vorgegebene Topics nach XML zu konvertieren.

  • XmlDocu_xsl/TopicXhtml.xsl: Das ist ein fast immer zu importierendes Script, das Texttopics in XHTML wandelt.

  • Sbnf2Xml/Cheader.sbnf: Dieses SBNF-Script parsed Headerfiles, die damit erzeugte XML-Darstellung des Inhaltes lässt sich für viele Konvertierungen nutzen auch außerhalb der Dokumentengenerierung.

  • XmlDocu_xsl/HeaderXml2UmlXml.xsl: Dieses File konvertiert einen geparsten Headerfile in ein Format, das dem UML-Format (aus XML erzeugt) entspricht. Damit sind die Inputs aus Headerfiles und UML-Modellen für die Dokumentengenerierung strukturidentisch.

  • XmlDocu_xsl/UmlDocu.xslp: Das ist ein in der Dokumentengenerierung importiertes XSL-File für die Darstellung von Inhalten aus UML-Modellen und Headerfiles.

  • XmlDocu_xsl/Pre2Xhtml.xsl: Dieses Script verwandelt den XhtmlPre-XML-File nach HTML bzw. XHTML. Derzeit wird nach reinem HTML konvertiert.

  • XmlDocu_xsl/HtmlFormatStd.xml: Dieses file enthält CSS-Definitionen für HTML-Files.

  • XmlDocu_xsl/Pre2Word.xsl: Dieses Script verwandelt den XhtmlPre-XML-File nach Word2003-XML.

  • XmlDocu_xsl/WordFormatStd.xml: Dieses file enthält Formatvorlagen für Word, die Namen sind die selben wie die class-Namen im benachbarten HtmlFormatStd.xml.

4 Begriffe

Topic=.XmlDocuGen.terms.

pStyle=standard ulStyle=list-wide

Folgend sind einige Begriffe genannt, die hier eigenständig dargestellt die Begriffswelt der XML-Dokumentengenerierung bezeichnen soll. Die Reihenfolge ist so gewählt, dass zuerst allgemeine Begriffe stehen. Die Aufstellung ist bisher noch sehr lückenhaft (TODO):

Allgemeine Begriffe:

  • Dokumentation und Dokument: Eine Dokumentation ist eine Darstellung eines Sachverhaltes in lesbarer Form. Eine einzelne Datei soll dagegen als Dokument bezeichnet werden. Der Begriff Dokument taucht auch in XML-Prinzipdarstellungen auf. Ein XML-Baum befindet sich in einem Dokument, gemeint ist hier die XML-Datei als solche. Als Dokument wird allgemein auch ein amtlicher Nachweis bezeichnet. Der Unterschied zwischen Dokumentation und Dokument ist also eher quantitativ geprägt. Hier wird von Dokumentationsgenerierung gesprochen, weil aus vielen Files mehrere Dokumente entstehen.

  • End-Anwender: Damit ist derjenige Nutzer der Dokumentengenerierung gemeint, der Inhalte von Dokumenten kennt, deren Gestaltung bestimmen will, dabei über Grundkenntnisse etwa auch in Winword und über Computernutzung beherrscht, aber nicht XSL programmieren will und nicht Detailprobleme der XML-Datendarstellung beherrschen will.

  • Anwender-Aufbereitung: Die Dokumentengenerierung kann entsprechend der Anwendung aufbereitet werden, damit sind verschiedenste Input-Daten und verschiedenste Möglichkeiten deren Darstellung beherrschbar. Die Anwender-Aufbereitung kann jeder Anwender selbst tun, wenn er die Technik des XML einschließlich XSL und weitergehende Kenntnisse von Computer-Systemsoftware beherrscht. In etwa entspricht das dem Berufsbild des Informatikers.

Technische Begriffe:

  • Label: In bezug auf Hyperlinks: Bezeichnung entweder des dokumentinternen Ankers oder die Bezeichnung, die für die Hyperlinkzuordnung benutzt wird.