Inhalt
Topic:.readme_zbnfjax.
The zbnfjax-folder contain jar and scripts to work with ZBNF and XML. Some examples are explained, see ../readme_ZBNF.html. The zbnfjax is a complexly ready to use folder for some applications such as Zmake and Documentation generation.
XSL-Scripts, ZBNF-Scripts. Batches and the Zmake.jar for Zmake, the standard Zmake-System is supplied here.
XSL-Scripts, ZBNF-Scripts, Batches and the Xslt.jar for XML-Documentation-Generation.
XSL-Scripts, ZBNF-Scripts, Batches for conversion to XMI from Headerfiles and Java-Files. The XMI-File presents an UML-Model and it can be inputted to any UML-Tool.
Xslt.jar for free XSL-Translation using mulitple inputs and Wikiformat-Conversion.
Topic:.readme_zbnfjax..
All Java-Sources, which are sources of the ready-to-use jar-Files in the zbnfjax-folder, are supplied in ../srcJava_...-Folders. The Java sources are separated in additional folders because the independence of the sources shall be emphasized.
The makefiles uses only specific srcJava_...-Folders. The sources are also located in www.vishia.org/Java, maybe there in newer revisions.
The Javadoc of this sources are visible at www.vishia.orgJava/docuSrcJavaPublic or www.vishia.orgJava/docuSrcJavaSrc. It is possible to generate the Javadoc locally at the users filespace: Starting ../make/genjavadoc_Zbnf.bat generates it in a parallel folder to ZBNF. The generated javadoc isn't a part of the download because the file space is greater
as all others.
All batch-Files for generating the jar-Files located in zbnfjax are given in the ../make-directory. The javac-Compiler and the jar-Builder are used and should be present while making. The compiling process is contained
in the file make/makeJavacJar.bat. This file should be adapted to find the Java-Develop-Environment (see comments there). The batchfiles are given only for
windows-environment yet. Shell scripts for Linux should be adequately.
All together are supplied in the download http://sourceforge.net/projects/zbnf.
The sources are self-documenting so far as well. Some additional explanations are provided at several pages of www.vishia.org, some links are given in the examples to the vishia-page in internet.
Topic:.readme_zbnfjax..
The XSLT-translation uses the SAXON-XSLT. The zbnfjax is tested with the last version of Saxon-B, available under http://saxon.sourceforge.net in chapter Older Products as open-source-product. Saxonica has changed its licence conditions. In the past the Saxon-B was open-source, but Saxon-SA
was the commercial product including Xschema and others. The newer versions knows three levels of licence: The open-source
Home Edition, a low-cost Professional Edition and a Enterprise-Edition. The new Home-Edition doesn't support the <saxon:call-template ... instruction, which is used in the Xslt-Scripts. Therefore the last Saxon-B is proper for using zbnfjax in open-source-conditions.
But it is recommended to use the newer Saxon's commercial editions if further support of saxon may be need. See http://www.saxonica.com.
The JDOM-Java-Sources or the jdom.jar, which are available as open source under http://www.jdom.org.
For using ANT, either an eclipse installation can be used (http://www.eclipse.org) or the original from Apache can be used, see http://ant.apache.org.
Topic:.readme_zbnfjax..
All possibilities of usage are command-line-oriented. It means, no GUI (Graphical User Interface) is present. The invoking is controled from scripts. The examples show that.
Topic:.readme_zbnfjax...
There are some different file locations for the several tasks:
Java environment (JDK)
ANT
SAXON and JDOM Jars
The zbnfjax-directory
temporary directories
This file-locations may be non-uniform in several installations. But a call of a tool seen from user level should be uniformly. Therefore some environment variables are set in only one file, which should be adapted depending from the file locations. All other batch- or shell-script files are independently of the file locations of all tools.
For running under Windows, the file setZBNFJAX_HOME.bat is called on start of all other batches. This file sets the environment variables. The file is located in ZBNF/zbnfjax/batch_template/setZBNFJAX_HOME.bat. This file is the template. The user should copy it in a directory, which is obtainable bei the PATH of the system. So a non-path-specified call of
call setZBNFJAX_HOME.bat
sets the environment variables in the current command process. In the test environment a directory D:\batch was created and added to the system-PATH-Variable of windows. This directory is used as destination for setZBNFJAX_HOME.bat.
The adequate procedure isn't applicable under Unix/Linux. In Unix-systems the setting of environment variables are effected only for sub-shells, never in the parent shell. So it isn't able to call a script to set the variables and use its value outside. Therefore the call of the XML- and convertion-tools are modified:
The user calls
zbnfjax cmd args
The shell-script-file zbnfjax is contained in ZBNF/zbnfjax/batch_template/zbnfjax. From there it should be copied in a PATH-obtainable directory and adapted there. Under Linux the location /usr/bin may be adequate, because it should be present in any situation. The name zbnfjax means ZBNF JAva Xml and may be sufficiently different to other files at this level. This shell-script should be called at user level. The zbnfjax-specific
actions are called inside this script dependent of the cmd. The following settings of cmd are able:
|
|
description, arguments |
|
|
The named cmd-shell-script is executed, all Arguments should supplied in the second arg in "". The path to the script should be given as relativ full qualified path. Typically it is located in the same directory, than write "./script" |
|
|
The documentation generation is invoked. |
|
|
Java-compilation and building a jar file. |
|
|
Java is invoked with the classpath defined in zbnfjax. |
|
|
The call of the java-programm org.vishia.zbnf.Zbnf2Xml is invoked. |
|
|
The call of Zmake is invoked. |
|
|
The call of CHeader2JavaByteCoding is invoked. |
|
|
The call of Header2Reflection is invoked. To support a lot of inputfiles, all inputfiles may be accumulated in a environment
variable |
The variants of second parameter calls the named script under $ZBNFJAX_HOME/unixscript/name internally.
The same procedure is able to use under Windows too. The batch-file zbnfjax.bat is used.
Topic:.readme_zbnfjax...
The zbnfjax-folder should be copied from the download in commonly directories to offer to use. Some further tools are necessary. The
next table shows, where this parts are stored in the file tree. It is an example and suggestion for unified using.
|
Path Windows |
Path Linux |
Folder/Files |
Actions, Explaination |
D:\Progs |
/usr/share/vishia |
zbnfjax/* |
|
D:\batch |
- |
setZBNFJAX_HOME.bat zbnfjax.bat |
In directory |
|
- |
/usr/bin |
zbnfjax |
In directory |
D:\Progs\XML_Tools |
/usr/share/ XML_Tools |
saxon9.jar saxon9_jdom.jar |
It is the last SAXON-B version downloaded from http://saxon.sourceforge.net. Only this files are need here. |
D:\Progs\XML_Tools |
/usr/share/ XML_Tools |
jdom.jar |
Downloaded from http://www.jdom.org: |
D:\Progs\jdk1.6.0 |
/usr/share/java |
bin/*, jre/*, ... |
This is the Java-EE-SDK downloaded from Sun. Under linux the Software is unpacked in a parallel directory like |
D:\Progs\XML_Tools |
/usr/share/ eclipse/plugins |
org.apache.ant_1.6... |
Any ANT-version greater or equal 1.6 should be present. Under Linux the last eclipse version is downloaded from http://www.eclipse.org. It contains ANT. Under Windows Eclipse may be present too, but for non-eclipse users ANT was copied at the shown location.
The version |
Topic:.readme_zbnfjax..
The folder contains the folders and files:
Topic:.readme_zbnfjax..batch.
CHeader2JavaByteCoding.bat: Windows-batch-file to execute conversion from a C-headerfile to a Java-source-file to support structural access to data
in a Java-byte[]array. See ../examples_XML/ByteDataAccessJava/readme.html and www.vishia.org/Java/indexByteDataAccess.html.
cmdDocuGctr.bat: Windows-batch-file to execute the documentation generation. See ../examples_XML/DocuGenerationViaXML/readme.html and www.vishia.org/XmlDocu/index.html.
Topic:.readme_zbnfjax..batch_template.
setZBNFJAX_HOME.bat: Windows-batch-file to set environment variables before starting other actions. This file should be copied in a directory,
which is obtainable by the systems PATH. Its content is to be adapted to your system environment, regarding the path to Java
and the neccesary downloads from SAXON and JDOM.
Topic:.readme_zbnfjax...
This folder contains a makefile makeXsl_fromXslp.bat, which generates the *.xsl-files from the *.xslp into a gen-subdirectory. It uses Zmake. Because most of the scripts converts the xslp to xsl temporary, this make should be a phase-out-model.
But it is used any times yet.
Topic:.readme_zbnfjax...
This folder contains the special Scripts for documentation generation (../examples_XML/DocuGenerationViaXML/readme.html):
htmlstd.css: Standard css-file, this file will be copied in the destination folder while generating HTML-output.
XmlDocu_xsl_RevNotes.txt: This file contains some revision notes to versions, but not all. Its using should be improved. It should be that file, which
contains all revision notes, bug reports and requirements to the documentation generation.
HtmlFormatStd.xml deprecated. It was used instead htmlstd.css in the past.
WordFormatStd.xml This file contains the style sheets for MS-Word documents for all known and used styles. The content of this file will be
copied in a word.xml-file while generating a MS-Word document. The appearance of the text is defined in a standard well form. If a word.xml will be copied into an existing word document with the same named style sheets, the existing appearance of the word document
will be used. But the word.xml-file have to be contain any style sheet with the required name.
FreemindTopic.xsl: It is the xsl-script to transform from topics in a freemind file (see http://freemind.sourceforge.net/wiki/index.php/Main_Page. to Xhtml-elements, which are used to compose a document. This xsl-file can be included in the control script of the documentation
generation (DocuGenCtrl). It is used in te phase of preparing the XhtmlPre-Format.
Pre2Word.xsl: It is the xsl-script to transform from the XhtmlPre-Format to a Microsoft-Word.xml-Format. The word.xml-output file can be opened with MS-Word directly, or it can be inserted in an existing word document.
Pre2Xhtml.xsl: It is the xsl-script to transform from the XhtmlPre-Format to a HTML output.
TopixXhtml.xsl: This xsl-script converts the parsed TextTopics to Xhtml-Elements. It is used adequate to FreemindTopic.xsl to compose a document from TextTopic-Sources.
XmiSample.xsl: It is only a xsl_script to check using XMI-files.
Xschema2PreHtml.xsl: This script converts xschema-Files to Xhtml for documentation generation.
DocuGenCtrl2Ant.xslp: This xsl-Script is used to generate a ANT.xml-File to control the flow of the documentation generation with Apache-ANT. The input is the parsed GenCtrl-File (parsed with DocuGenCtrl.zbnf).
DocuGenCtrl2Xsl.xslp: This xsl-Script converts the content of the parsed GenCtrl-File to a xsl-File, which controls the composition of the document.
The generated XML-File is a xsl-File, which is used to prepare the XhtmlPre-Format from all inputs (two-stage operation).
HeaderDocu.xslp: This xsl-script converts parsed Headerfiles (parsed with ../zbnf/Cheader.zbnf) to Xhtml-elements, which are used to compose a document. This xsl-file can be included in the control script of the documentation
generation (DocuGenCtrl). It is used in te phase of preparing the XhtmlPre-Format.
RequCrossRef.xslp: This xsl-script is used inside a CorrectHref-preparation to produce Xhtml-elements for texts, which shows cross references in a document. The appearance of cross references
in the text may be adapted here. The input of the XSL-translation are an internal produced XML-tree.
XmiDocu.xslp: This xsl-script converts informations from a XMI-file (from an UML-model) to Xhtml-elements, which are used to compose a document. This xsl-file can be included in the control script of the
documentation generation (DocuGenCtrl). It is used in te phase of preparing the XhtmlPre-Format.
AsciiTopics.zbnf: This is a ZBNF-syntax to parse TextTopics.
DocuGenCtrl.zbnf: This is a ZBNF-syntax to parse the textual given documentation control file. The parser output is used as input for the
xsl-scripts DocuGenCtrl2Ant.xslp and DocuGenCtrl2Xsl.xslp and for CorrectHref-preparation too.
The scripts can be adapted, if the appearance of a generated document should be changed. At example the styling of chapters of a document which shows XMI-input may be changed. It may be possible to copy the scripts under an alternate name and change it. A user can create its own style.
Topic:.readme_zbnfjax...
This folder contains commonly xsl-scripts, especially for Zmake.
CheaderTypes.xsl: This xsl-scripts works with inputs from header-files, parsed with ../zbnf/Cheader.zbnf. All types contained in the header are dissolved. Any type is outputed only one time. It is a intermediate step to create
a XMI-file from header-files.
Java2xmiTypes.xsl: This xsl-scripts works with inputs from Java-files, parsed with ../zbnf/Java2C.zbnf. All types contained in the Java-file are dissolved. Any type is outputed only one time. It is a intermediate step to create
a XMI-file from Java-files.
Cheader2ByteDataAccess_Java.xslp: This xsl-scripts works with inputs from header-files, parsed with ../zbnf/Cheader.zbnf. It controls the creation of a Java-file, which controls a byte-data-access using the superclass javadoc-src:_org/vishia/byteData/ByteDataAccess. See ../examples_XML/ByteDataAccessJava/readme.html or Cheader2ByteDataAccess.
Cheader2Xmi.xslp: Xsl-script to generate XMI from headers. See ../examples_XML/Header2XMI/readme.html or Cheader2XMI.
Java2Xmi.xslp: Xsl-script to generate XMI from Java sources. See ../examples_XML/Java2XMI/readme.html or Java2XMI.
ZmakeStd.xslp: The xsl-script which produces ANT.xml to run Zmake. This script contains all Zmake-standard-possibilities. The input for the XSL-translation is a parsed Zmake-Script, see next.
This xsl-file is included in the documentation generation too. It means, that all opportunities of Zmake can use within the
documentation generation. A twice scripting is prevent.
Topic:.readme_zbnfjax...
zbnf.jar: This is the ZBNF-parser-executable. No other tools are needed.
header2Reflection.jar: To run ../examples_ZBNF_core/Header2Reflection/readme.html this jar and zbnf.jar are needed in the classpath.
zmake.jar: This jar contains the org.vishia.zbnf.Zmake-class to run Zmake. Secondly some classes under org.vishia.ant are present. Third the org.vishia.xmlSimple.Xsltpre-class is included here, because it is necessary to run Zmake. This class is also contained in xslt.jar, because it is need in both independently.
xslt.jar: To run the vishia-XSLT-Translator. The SAXON- and JDOM jars should be present in the class path too to run the translator.