# readme - zbnfjax

Inhalt

- 1 Sources and make
- 2 Which other tools and sources are needed ?
- 3 Usage

- 3.1 Environment, call
- 3.2 The file-locations to use, adaptions

- 4 Content description

- 4.1 batch
- 4.2 batch_template
- 4.3 make
- 4.4 XmlDocu_xsl
- 4.5 xsl
- 4.6 Jars

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.

## 1 Sources and make

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.

## 2 Which other tools and sources are needed ?

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.

## 3 Usage

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.

### 3.1 Environment, call

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:

`cmd` | description, arguments
`call "cmdsh" "args"` | 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"
`genDocu ctrlfile` | The documentation generation is invoked.
`javacjar` | Java-compilation and building a jar file.
`java class args` | Java is invoked with the classpath defined in zbnfjax. `class` is the path to the Main-class. All Arguments should supplied in the second arg in "".
`zbnf2Xml args` | The call of the java-programm org.vishia.zbnf.Zbnf2Xml is invoked.
`zmake args` | The call of Zmake is invoked.
`CHeader2JavaByteCoding args` | The call of CHeader2JavaByteCoding is invoked.
`Header2Reflection args` | The call of Header2Reflection is invoked. To support a lot of inputfiles, all inputfiles may be accumulated in a environment variable `INPUT` in form `-i:PATHFILE` separated with spaces. Than this calling arguments should not be given in the argument line.

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.

### 3.2 The file-locations to use, adaptions

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/*
| `zbnfjax`-folder from this download, copied, ready to use
    D:\batch
| - |
    setZBNFJAX_HOME.bat
    zbnfjax.bat
| In directory `zbnfjax/batch_template` from this download, copied and adapted. The PATH-Variabe of the system should point to this location. If the pathes of all components are used like shown here, no adaption is necessary.
- |
    /usr/bin
    zbnfjax
| In directory `zbnfjax/batch_template` from this download, copied and adapted, the PATH-Variabe of the system points to this location. If the pathes of all components are used like shown here, no adaption is necessary.
    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: `jdom-1.1.1.zip`. Inside this zip-file only the `jdom/build/jdom.jar` is extracted and copied.
    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 `usr/share/JavaVersion/jdk1.6.0_17`. The `usr/share/java` is a soft link to this directory. Under Windows the Java-version is used with its immediate path. Note: There may be several versions of Java used on a PC for other applications too. Than a immediate path to the selected Java-version should be set in the environment variables of `zbnfjax` respectively `setZBNFJAX_HOME.bat`. Any system variables should not be changed.
    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 `org.apache.ant_1.6.5` was used yet.

## 4 Content description

Topic:.readme_zbnfjax..

The folder contains the folders and files:

### 4.1 batch

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.

### 4.2 batch_template

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.

### 4.3 make

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.

### 4.4 XmlDocu_xsl

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.

### 4.5 xsl

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.

### 4.6 Jars

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.