vishia - Steuerung der Dokumentengenerierung

Topic=.DocuGenCtrl.Syntax..

ulStyle=list-closely

 NAME.pre.xml:
    [exec] WARNING: ERROR argument -i is obligat.

Obige ANT-Meldung weist darauf hin, dass im Document-Block kein input angegeben ist:

 Document "vishia - Object_Jc - Basis aller Daten" ident=Object_Jc
 {
   input: Object_Jc.topic.txt;

TODO

Topic=.DocuGenCtrl.GenAnt.xml..

ulStyle=list-closely

Im folgenden ist kurz das Prinzip von ANT dargestellt.

Im XML-Steuerfile für ANT gibt es <target>, Ziele. Ein Ziel ist die Generierung von irgendetwas. Innerhalb des <target>-Blockes stehen Anweisungen.

• Es gibt solche grundlegenden Anweisungen wie <mkdir> oder <copy>, wobei diese Befehle schon recht intelligent realisiert sind. <copy> erzeugt automatisch notwendige Zielverzeichnisse, es können File-Gruppen angegeben werden usw.

• Als Anweisungen lassen sich über <exec> beliebige Kommandozeilen-Aufrufe realisieren.

• Mit <java> lassen sich direkt java-Klassen aufrufen. Dabei wird nicht wie aus Kommandozeilen gewohnt main aufgerufen, sondern aus einer von org.apache.eclipse.ant.Task vererbeten Klasse wird execute() gerufen. Da ANT selbst in Java geschrieben ist, erfolgt die Verzweigung unmittelbar in der JVM.

• <antcall> ruft unmittelbar ein anderes <target> auf.

Um ein Ziel <target> zu erreichen, müssen gegebenenfalls andere Ziele bereits zuvor erreicht worden sein. Das wird innerhalb des <target...> mit depends ausgedrückt. Dabei hat ANT die Eigenschaft, jedes Ziel nur einmal erreichen zu wollen, ist es geschafft, dann ist es da. Ein abhängiges Ziel ist eine notwendigerweise zuvor auszuführende Konvertierung. Was da ist, ist schon da und braucht nicht noch einmal ausgeführt zu werden. Das verringert die Planung bei komplexen Abhängigkeiten und spart Zeit für unnötige doppelte Konvertierungen.

Innerhalb von ANT kann günstig festgestellt werden, ob ein File oder mehrere (Quell-)Files vom Zeitstempel her jüngeren Datums sind als ein (Ziel-)File. Das ist die von Makern gewohnte Leistungseigenschaft. Bei ANT kann sie aber besser bestimmt angegeben werden. Die meisten Maker unterscheiden nur pauschal zwischen Quell- und Zielfiles.

In ANT gibt es eingeschränkt solche Dinge wie Variablen und if-Anweisungen. Das ist gewollt. Es gibt Erweiterungen von ANT, die hier Abhilfe stellen, das ist aber nicht unbedingt zweckvoll. Bei der Ant-Strategie fällt auf, dass es keine Subroutinen-Aufrufe mit Parametern gibt. Jedes <target> wird nur einmal ausgeführt. Wird es mehrmals dediziert gerufen, evtl. mit verschiedenen Parametern, wird es dennoch nur einmal ausgeführt. Damit ist ein <antcall> untauglich für mehrmalige Verwendung.

Für nicht umfangreiche aber komplexe Fälle sollte ein ANT-XML-Script per Hand geschrieben werden. Die Anleitung gibt genügend Muster vor. Für immer wiederkehrende Fälle ist es aber geboten, das ANT.xml-Script zu generieren. Für die Dokumentengenerierung enthält der Generier-Steuerfile alle Informationen für das ANT-Script. Dieses kann aus einfachen Input-Daten dabei auch sehr komplex werden, wenn eine umfangreiche Aufbereitung von XML-Daten aus Quellen (andere XML-Formate, textuelle Quellen) notwendig sind. Dabei muss das Script zum Generieren des ANT-Scriptes diese Fälle kennen, um die richtigen Generieralgorithmen zu generieren. Der Anwender der Dokumentengenerierung braucht dann nur wenig spezielles anzugeben.

Topic=.DocuGenCtrl.GenAnt.xml..

ulStyle=list-closely

Das Steuerfile enthält folgende für ANT.xml wesentliche Blöcke:

Im importXsl-Block werden alle zusätzlichen XSL-Scripte benannt. Diese werden bei der XhtmlPre-Übersetzung importiert und unterstützen eine anwenderangepasste Generierung:

 importXsl
 ( XmlDocu_xsl:TopicXhtml.xsl
 , XmlDocu_xsl:HeaderDocu.xslp
 );

Im Beispiel ist die Unterstützung von Topics und Konvertierungen aus Headerfiles angegeben. Hierbei wird berücksichtigt, dass XSL-Scripts mit Xsltpre vorverarbeitet werden könnten, mit Angabe der Extension xslp. Vor dem : steht eine Verzeichnisangabe eines Pfades, der sich auf das Verzeichnis laut Umgebungsvariable XML_TOOLBASE bezieht.

Mit prepXml werden die aufbereitenden (prepare) XML-Konvertierungen benannt. Beispiel:

 prepXml: Topics.topic.txt          ->TextTopic2Xml  ->Topics_TEST.xml;
 prepXml: DocuGenCtrl.topic.txt     ->TextTopic2Xml;
 prepXml: ../../src/Example.h       ->Header2Xml     ->Example.h.xml;

In diesem Beispiel sind 3 Files aufgeführt, die präpariert werden sollen. Nach dem -> ist jeweils der Translator und das Outputfile benannt. Das Outputfile kann weggelassen werden, dann wird das Outputfile unter dem Namen des Inputfiles mit angehängtem .xml gespeichert. Dieses Verhalten hängt allerdings von der Gestaltung des Translator ab.

Als Translator sind nur bestimmte Angaben möglich. Die möglichen Translators müssen im Generierfile berücksichtigt werden. Das ist pro Translator etwa ein Block im Umfang einer Bildschirmseite. Der Anwender kann hier ergänzen. Weitere Translators werden benötigt, wenn andere Konvertierungen notwendig sind als bisher vorgesehen.

Es kann ein oder mehrere Dokumente angegeben werden:

 Document "Dokumentationsgenerierung mit XML - Übersicht" ident=XmlDocuGen
 {
   input: XmlDocuGen.topic.txt;
   input: ./xmlDocuGenPicture.xml;
   inset: label = topic(Special/path);
   chapter "Übersicht" (id=XmlDocuGen_Overview)
   { picture("Übersicht Ablauf der Dokumentengenerierung", imgMap="XML_DocuGen_1");
     topic(XmlDocuGen/overviewNavigation/*, ulStyle="list-closely");
   }
   chapter "Motivation" (id=XmlDocuGen)
   { topic(XmlDocuGen/conceptualFormulation/*);
   }
 }

Alle unter input: aufgeführten Files werden als Inputfiles (Eingangsquellen) benutzt. Dabei wird eine vorige Aufbereitung der Eingangsquellen berücksichtigt, entsprechend den Angaben bei prepXml: oben. Der Aufruf der Aufbereitung wird im ant.xml-File organisiert, für den XSL-Translatorschritt wird der daraus resultierende Output aus dem ../tmp..-Verzeichnis benutzt.

Der Eintrag inset: weist einem Label eines Platzhalters in einem beliebigen Text des Dokumentes den Inhalt eines Topics zu. Damit ist es möglich, innerhalb von Topics oder anderen Textbestandteilen des Dokumentes nicht nur den dort stehenden Text wiederzugeben sondern ihn mit dokumentenspezifischen Inhalt zu mischen, wenn dies an entsprechenden Textstellen vorgesehen ist. Das ist eine generelle zweite Möglichkeit der Inhaltsbestimmung. Siehe auch inset-Technologie.

Hierbei sind insbesondere die input:-Angaben wichtig. Die Kapitelgliederung (chapter) ist dagegen für ANT.xml nicht wichtig.

Mit diesen Informationen ist im ANT.xml niederlegbar:

• die Aufbereitungen von XML-Inputs (je ein <target>),

• die Aufbereitung von XSL-Scripts mit Xsltpre

• die Generierung des Dokumentes selbst als HTML-Output, zusätzlich aufgrund einer Aufrufparameterangabe auch andere Outputformate wie word.xml,

• die Generierung des XhtmlPre.xml des jeweiligen Dokumentes, hierbei ist die Benennung der input. bei den Dokumenten wichtig.

• Die Steuerung der Generierung aller Dokumente.

Mit ANT wird erreicht, dass eine Generierung nur aufgerufen wird, wenn die betreffenden Quellen neuer sind als der zuvor erzeugte Output. Eine Gesamtgenerierung wird erreicht, wenn der Output zuvor manuell gelöscht wird.

Topic=.DocuGenCtrl.GenAnt.xml...

ulStyle=list-closely

Im Script GenDocuCtrl2Ant.xslp wird aus dem DocuGenCtrl.xml folgende Bestandteile im ANT.xml hergestellt:

 <?xml version="1.0" encoding="ISO-8859-1"?>
 <!-- Generated by GenDocuCtrl2Ant.xslp -->
 <project name="GenDocuGen" default="GenDocuGen" basedir=".">
 <property environment="env" />
 <property name="tmp" value="../tmp" />
 <import file="${env.XML_TOOLBASE}/XmlDocu_xsl/GenDocu.ant.xml"/>
 	<target name="GenDocuGen" description="The whole documentation of this folder"
 	   depends="XmlDocuGen.html,DocuGenCtrl.html,Topics.html,WikiFormat.html,XslHints.html,xyz.html,copy.special.xsl">
   </target>

Das ist der Kopf des ANT.xml. Hier ist die Voreinstellung des ../tmp hart codiert. Sie lässt sich ändern durch Anpassung des GenDocuCtrl2Ant.xslp. Das erste <target> ist das Defaulttarget und zählt in depends alle Dokumente auf, die in dem DocuGenCtrl-File vorgefunden werden.

 <target name="XmlDocuGen.html" depends="isUptodate_XmlDocuGen.html" unless="isUptodate_XmlDocuGen.html" >
   <echo message="generating HTML" />
       <antcall target="gen_XmlDocuGen.html" />
 </target>
 <target name="isUptodate_XmlDocuGen.html"> 	  <uptodate property="isUptodate_XmlDocuGen.html" targetfile="../html/XmlDocuGen.html">
     <srcfiles file="${curDir}/XmlDocuGen.genctrl.txt" /> 	    <srcfiles file="${curDir}/XmlDocuGen.topic.txt" /> 	    <srcfiles file="${curDir}/./xmlDocuGenPicture.xml" /> 	    <srcfiles file="${env.XML_TOOLBASE}/XmlDocu_xsl/GenDocuCtrl2Xsl.xslp" /> 	  </uptodate>
 </target>
 <target name="gen_XmlDocuGen.html" depends="tmpdir,XmlDocuGen.pre.xml">
   <exec dir="${curDir}" executable= "java" failonerror="true">
     <arg line ="-cp ${env.XML_TOOLBASE}/xslt.jar;${env.XML_TOOLBASE}/jdom.jar vishia.xslt.Xslt" />
 	  <arg line="-i${tmp}/XmlDocuGen.pre.xml" />
 	  <arg line="-i${env.XML_TOOLBASE}/XmlDocu_xsl/HtmlFormatStd.xml" />
 	  <arg line="-t${env.XML_TOOLBASE}/XmlDocu_xsl/Pre2Xhtml.xsl" />
 	  <arg line="-w+ -y../html/XmlDocuGen.html" />
  	</exec>
 </target>

Dieser Block wird pro Dokument erzeugt. Er ist hier leicht gekürzt dargestellt. Wichtig ist, dass sowohl für den <uptodate>-Test als auch als Input für den Aufruf der Konvertierung zu html die unter input: aufgeführten Files des jeweiligen Dokumentes benutzt werden. Hier ist hart codiert, dass der Output nach ../html geschrieben wird. Die Nutzung des HtmlFormatStd.xml ist ebenfalls hart codiert, auch die Abhängigkeit von bestimmten Tool-Files. Diese Informationen lassen sich entweder anpassen oder auch mit kleinen Erweiterungen über das DocuGenCtrl.genctrl.txt-Steuerfile vorgebbar gestalten. Dafür muss das DocuGenCtrl.sbnf erweitert werden (meist ist eine Abwärtskompatibilität möglich und sinnvoll), und das GenDocuCtrl2Ant.xslp muss natürlich entsprechend erweitert werden. Auch das lässt sich abwärtskompatibel realisieren. Wenn beispielsweise keine Angaben für eine andere Wahl für HtmlFormatStd.xml vorliegen (Abfrage im Xsl über <xsl:choose>...<xsl:otherwise>), dann wird eben die Voreinstellung benutzt.

Die Erzeugung des HTML einschließlich des abhängigen Aufrufes von XmlDocuGen.pre.xml hängen von der Neuwertigkeit der Input-Dokumente ab. Sind diese nicht neuerer, dann wird auch das als Konvertierungs-Zwischenschritt notwendige XmlDocuGen.pre.xml nicht gerufen. Damit wird erreicht, dass das Vorhandensein dieses Zwischen-Formates nicht getestet wird. Damit braucht ein Inhalt im ../tmp-Verzeichnis nicht exisitieren.

Folgender Block wird zur Erzeugung des XhtmlPre-Formates generiert (leicht gekürzte Darstellung):

 <target name="XmlDocuGen.pre.xml"
   depends="XmlDocuGen.topic.txt.xml,
            GenDocuCtrl2Xsl.xsl,
            copy.special.xsl,
            isUptodate_XmlDocuGen.pre.xml"
   unless="isUptodate_XmlDocuGen.pre.xml"
 >
   <exec dir="${curDir}" executable= "cmd.exe" failonerror="true">
 	  <arg line ="/c ${env.XML_TOOLBASE}\xt.exe ${tmp}/XmlDocuGen.genctrl.xml ${env.XML_TOOLBASE}/XmlDocu_xsl/gen/GenDocuCtrl2Xsl.xsl ${tmp}/XmlDocuGen.genctrl.xsl document=XmlDocuGen"/>
  	</exec>
   <exec dir="${curDir}" executable= "java" failonerror="true">
     <arg line ="-cp ${env.XML_TOOLBASE}/xslt.jar;${env.XML_TOOLBASE}/jdom.jar vishia.xslt.Xslt" /> 	    <arg line ="-i${tmp}/XmlDocuGen.topic.txt.xml" /> 	    <arg line ="-i./xmlDocuGenPicture.xml" />
 	  <arg line ="-t${tmp}/XmlDocuGen.genctrl.xsl" />
 	  <arg line ="-w+ -y${tmp}/XmlDocuGen.pre1.xml" />
  	</exec>
   <exec dir="${curDir}" executable="java" failonerror="true">
     <arg line ="-cp ${env.XML_TOOLBASE}/xslt.jar;${env.XML_TOOLBASE}/jdom.jar vishia.xml.CorrectHref" />
 	  <arg line ="-i${tmp}/XmlDocuGen.pre1.xml" />
 	  <arg line ="-c${tmp}/XmlDocuGen.genctrl.xml" />
 	  <arg line ="-y${tmp}/XmlDocuGen.pre.xml" />
  	</exec>
 </target>
 <target name="isUptodate_XmlDocuGen.pre.xml" > 	  <uptodate property="isUptodate_XmlDocuGen.pre.xml" targetfile="${tmp}/XmlDocuGen.pre.xml">
     <srcfiles file="${curDir}/XmlDocuGen.genctrl.txt" /> 	    <srcfiles file="${curDir}/XmlDocuGen.topic.txt" /> 	    <srcfiles file="${curDir}/./xmlDocuGenPicture.xml" /> 	    <srcfiles file="${env.XML_TOOLBASE}/XmlDocu_xsl/GenDocuCtrl2Xsl.xslp" /> 	  </uptodate>
 </target>

Hier erfolgt nochmals ein Test auf Neuartigkeit der Quellfiles. Damit wird eine Generierung für den Fall unterdrückt, dass keine neuen Inputs vorliegen, das XhtmlPre vorliegt, aber nur das HTML generiert werden muss beispielsweise weil Pre2Xhtml.xsl geändert wurde. Damit wird insbesondere für Testfälle der Scriptentwicklung Zeit gespart.

Ansonsten besteht diese Generierung aus drei Stufen:

• Generierung des xsl-Scriptes für die XhtmlPre-Erzeugung aus dem vorliegenden genctrl.xml-Format. Das ist das selbe File, das als Zwischenschritt auch für die Generierung dieses ANT-Scriptes verwendet wurde.

• Generierung des XhtmlPre selbst.

• Korrektur von Hyperlinks mittels CorrectHref. Als Input wird wieder das genctrl.xml verwendet. Diesmal spielt aber der Part der HyperlinkAssociation die entscheidende Rolle.

Im ANT.xml finden sich dann weiterhin alle XML-aufbereitungs-<target>, beispielsweise für:

 <target name="WikiStyle.topic.txt.xml" depends="isUptodate_WikiStyle.topic.txt.xml" unless="isUptodate_WikiStyle.topic.txt.xml" >
   <echo message="update with SBNF_EXE" />
   <exec dir="${curDir}" executable= "java" failonerror="true">
 	  <arg line ="-cp ${env.XML_TOOLBASE}/xslt.jar;${env.XML_TOOLBASE}/jdom.jar vishia.stringScan.SBNF2Xml"/>
 	  <arg line ="--rlevel:334 --report:${tmp}/WikiStyle.topic.txt.xml.rpt"/>
 	  <arg line ="-iWikiStyle.topic.txt -s${env.XML_TOOLBASE}/Sbnf2Xml/AsciiTopics.sbnf -y${tmp}/WikiStyle.topic.txt.xml"/>
  	</exec>
 </target>
 <target name="isUptodate_WikiStyle.topic.txt.xml" > 	  <uptodate property="isUptodate_WikiStyle.topic.txt.xml" targetfile="${tmp}/WikiStyle.topic.txt.xml"> 	    <srcfiles file="${curDir}/WikiStyle.topic.txt" /> 	    <srcfiles file="${env.XML_TOOLBASE}/Sbnf2Xml/AsciiTopics.sbnf" /> 	  </uptodate>
 </target>

Hier wird ein textueller Topicfile in Xml gewandelt, weil im DocuGenCtrl-File dies unter prepXml: angegeben wurde. Es erfolgt hier ebenfalls ein <uptodate>-Test, eigentlich nur um Konvertierungszeit zu sparen.

Der ANT.xml-File enthält noch ein Block für das Kopieren spezieller XSL-Scripts bzw. deren Aufbereitung mit xsltpre:

 <target name="copy.special.xsl" depends="HeaderDocu.xslp,dummyTarget">
   <echo message="copy *.xsl" />
   <copy todir="${curDir}/${tmp}" >
     <fileset dir="${env.XML_TOOLBASE}/XmlDocu_xsl" includes="TopicXhtml.xsl" />
   </copy>
 </target>
 <target name="HeaderDocu.xslp" depends="isUptodate_HeaderDocu.xslp" unless="isUptodate_HeaderDocu.xslp">
   <exec dir="${curDir}" executable= "cmd.exe" failonerror="true">
 	  <arg line ="/c call java -cp %XML_TOOLBASE%/xslt.jar;%XML_TOOLBASE%/jdom.jar vishia.xslt.Xsltpre --report:${tmp}/xsltpre.rpt --rlevel:324 -i${env.XML_TOOLBASE}/XmlDocu_xsl/HeaderDocu.xslp -o${tmp}/HeaderDocu.xsl"/>
  	</exec>
 </target>
 <target name="isUptodate_HeaderDocu.xslp">
   <uptodate property="isUptodate_HeaderDocu.xslp" targetfile="${tmp}/HeaderDocu.xsl" >
     <srcfiles file="${env.XML_TOOLBASE}/XmlDocu_xsl/HeaderDocu.xslp" />
   </uptodate>
 </target>

und noch einige zusätzliche feste <target> mit Hilfsfunktionalität wie

 <target name="prepareHtmlOutput">
   <echo message="prepareHtmlOutput" />
   <mkdir dir="../html" />
 </target>

Die gesamte Generierung dieser Inhalte wird mit dem ../XmlDocu_xsl/GenDocuCtrl2Ant.xslp gesteuert und ist dort anpassbar.

Topic=.DocuGenCtrl.GenAnt.xml...

ulStyle=list-closely

TODO