vishia - Dokumentationsgenerierung mit XML

• Quellen der Dokumentation:

  • Grundsätzliches zur Aufbereitung von XML-Informationen

  • Erfassung von textuellen Inhalten in Topics

  • Topics in einfachen Textfiles unter Nutzung der Wikipedia-like Formatierung

  • Konvertierung von Headerfiles nach XML für Softwaredokumentation

  • Dokumentation aus UML-Modellen über XMI-Export

  • Beispiel Stückliste - Artikel

• Steuerung der Generierung

  • Das Format PreXhtml

  • Vorgabe des Dokumenteninhaltes und Generierung des Generierscriptes für PreXhtml

  • Verwendung von Eclipse-ANT zur Generierung

  • Textformatierung - Formatvorlagen und CSS

  • Konvertierung von Textinformationen in Topics

  • Bestandteile für Softwaredokumentation aus Headerfiles (C/C++)

  • Bestandteile für UML-Softwaredokumentation

  • Verlinkung von Dokumenten

• Details der XSLT-Konvertierung

  • Verarbeitung mehrerer Input-XML-Files

  • vishia-XSLT

  • Präprozessor für XSL, Kurzschreibweise in XSL

  • Problem der Leerzeichen /Whitespaces

  • Beautification von output-XML-Files

  • Tips und Tricks der XSL-Konvertierung

• Erzeugung von End-Dokumenten

  • Winword 2003

  • HTML und XHTML

  • Erzeugung von PDF über FO wird derzeit hier nicht unterstützt (das ist ein TODO).

• Bisherige Beschreibung der Dokumentationsgenerierung (im Jahr 2005 entstanden)

• TODO: Wie es steht und was noch zu tun ist.

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

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.

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.

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.