FlexDoc/XML, Version 1.13

Release Notes

Table Of Contents

About FlexDoc/XML

FlexDoc/XML is a software system for development and execution of high-quality documentation/report generators from any data stored in XML files.

The actual documentation/report generators are programmed in the form of special templates using a graphic Template Designer that represents the templates visually in a form resembling the output they generate. Further, the templates are interpreted by a Template Processor, which takes on input the XML files and produces by them the result documentation.

FlexDoc/XML includes ready-to-use template applications that implement some very advanced professional documentation generators in the field of XML:

It also includes diagramming plugins to generate graphical representations (i.e. charts, diagrams) of various things described in XML files, which can be inserted automatically into the documentation generated by particular template applications. There are currently three such plugins: Finally, FlexDoc/XML supports the integration of all that functionality with Apache Ant and Maven build systems.

Since all those things are not needed to everyone, the FlexDoc/XML software is not covered by a single license. Rather, it is broken into several logical products, which are licensed separately.

Below is the summary of all most important features (functionality) included in FlexDoc/XML as well as how they are licensed.

Core Components

Component Description Licensing
Template Processor
(Generator) 		Provides the Runtime Environment to execute template applications. This includes:
  • Template Interpreter
  • Output generators in HTML, RTF and TXT formats
  • Generator GUI
  • The support of XML Catalogs for input XML files
Notes:
  • The generator is basically free, except the possibility: which is available only under a Trial/Full license for "FlexDoc/XML SDK".
  • When any trial license is involved in the generation (e.g. for "FlexDoc/XML SDK", a template application or diagramming plugin), all generated output documents will be specifically distorted by replacing some letters with shade ('░') characters (as well as contain special messages). Such documents may be used only for evaluation of this software. Any other usage is prohibited!

    If you replace the trial license with the full one (or do not use that feature at all), no distortion will happen.
Free License (activated by default) or Trial/Full License for FlexDoc/XML SDK
Template Designer Provides a high-quality GUI to design templates. This is the only way to create/modify templates. In effect, the Template Designer both visualizes the template language and gives you access to most of FlexDoc.XYZ features.

Notes:

  • Under the Demo License, the Template Designer will work only in demo mode. You will be able to investigate some functionality, but unable to save any created/modified templates.
  • Trial templates – those created/modified the last time during the trial of "FlexDoc/XML SDK" – can be executed only in the presence of that license (trial or full).
Demo License (activated by default) or Trial/Full License for FlexDoc/XML SDK

Template Applications

Application Description Licensing
XMLDoc A simple template set that allows you to compile any number of generic XML files into a web-ready HTML or printable RTF documentation with the optional inclusion of a namespace binding report that shows which namespace prefixes are bound to which namespace URIs and where.

For more details, see Docs | FlexDoc/XML | Samples | XMLDoc. 		free
XSDDoc A template application that implements very powerful XML Schema Documentation Generator able to produce both multi-framed Javadoc-like HTML and printable RTF documentation.

For more details, see {flexdoc-xml}/templates/XSDDoc/README.html, Docs | FlexDoc/XML | XSDDoc. 		Demo License (activated by default) or Trial/Full License for XSDDoc
WSDLDoc A similar template application that implements even more powerful documentation generator for WSDL, XML schemas (XSD) and all interconnections between them.

For more details, see {flexdoc-xml}/templates/WSDLDoc/README.html, Docs | FlexDoc/XML | WSDLDoc. 		Demo License (activated by default) or Trial/Full License for WSDLDoc

Diagramming Plugins

Plugin Description Licensing
DiagramKit Implements FlexDoc/XML native diagramming engine. It creates beautiful XSD diagrams that can be generated simultaneously along with (and inserted into) the documentation generated by XSDDoc or WSDLDoc (with the support of all possible hyperlinks).

For further information, please see: 		Demo License (activated by default) or Trial/Full License for DiagramKit
XMLSpy Integration Allows you to insert automatically the XSD diagrams produced by Altova XMLSpy into the documentation generated by XSDDoc or WSDLDoc (with the full support of diagram hyperlinks).

For more information, see: 		Demo License (activated by default) or Trial/Full License for XMLSpy Integration
Oxygen XML Integration Allows you to insert automatically the XSD diagrams produced by Oxygen XML Editor into the documentation generated by XSDDoc or WSDLDoc (with the full support of diagram hyperlinks).

For more information, see: 		Demo License (activated by default) or Trial/Full License for OxygenXML Integration

Full Licenses

Notes:

License Description Note
FlexDoc/XML SDK You need this license if you want to heavily customize the documentation generated by any ready template applications (e.g. change some colors, fonts, layouts, look & feel, add new functionality etc.) or create your own ones. In particular, this license covers: template applications and diagramming plugins are not covered by this license
FlexDoc/XML XSDDoc Unlocks all functionality implemented in XSDDoc templates. In particular, you will be able to: Although these licenses cover the automatic insertion of XSD diagrams in the generated documentation (i.e. programming of that in templates), the generation of diagrams themselves is not covered by them. For that you need a license for one of the diagramming plugins (see below).
FlexDoc/XML WSDLDoc Unlocks all functionality implemented in WSDLDoc templates. In particular, you will be able to:
FlexDoc/XML DiagramKit Unlocks all functionality implemented in DiagramKit. Allows you to generate XSD diagrams and automatically insert them into documentation generated by XSDDoc/WSDLDoc (with the support of all possible diagram hyperlinks).
FlexDoc/XML XMLSpy
Integration 		Covers XMLSpy Integration that allows you automatically to insert the XSD diagrams produced by Altova XMLSpy into the documentation generated by XSDDoc/WSDLDoc. To run the integration, you need to have XMLSpy already licensed/installed on your system
FlexDoc/XML OxygenXML
Integration 		Covers OxygenXML Integration that allows you automatically to insert the XSD diagrams produced by Oxygen XML Editor into the documentation generated by XSDDoc/WSDLDoc. To run the integration, you need to have Oxygen XML Editor already licensed/installed on your system

Package Contents

File / Directory Description
LICENSE.html FlexDoc Software License
README.html this file
CHANGES.html change log of FlexDoc/XML
docs/ FlexDoc/XML & FlexDoc.XYZ Documentation – an HTML copy of all descriptions/documentation published on the product web-site (on the moment of the release). It may be useful when you cannot access the online pages or they changed too much since this release.
bin/*.bat Files prepared for Windows Installation:
bin/designer.bat
bin/generator.bat
bin/linux/ Files prepared for Linux Installation:
bin/linux/designer.sh
bin/linux/generator.sh
bin/linux/flexdoc.config
  • FlexDoc main configuration file prepared for Linux
bin/macOS/ Files prepared for macOS Installation:
bin/macOS/designer.command
bin/macOS/generator.command
bin/macOS/flexdoc.config
  • FlexDoc main configuration file prepared for macOS
lib/ Runtime Environment:
lib/flexdoc-xml.jar
  • FlexDoc/XML main Java module
lib/flexdoc-xml-diagramkit.jar
lib/flexdoc-xml-xmlspy.jar
lib/flexdoc-xml-oxygenxml.jar
lib/flexdoc.config
  • FlexDoc main configuration file prepared for Windows Installation. This file contains locations of other configuration files and various important settings.
lib/xercesImpl.jar
lib/resources/ Runtime Environment Resources:
lib/resources/catalog.xml
  • Default XML catalog
lib/resources/www_w3_org/
lib/resources/schemas_xmlsoap_org/
config/ Configuration files (created and updated dynamically):
config/designer.config
config/generator.config
  • Template Processor configuration file prepared to run a demo (normally, it is maintained automatically by the Generator GUI)
templates/ bundled template applications
templates/XMLDoc/ "XML File Documenter" (XMLDoc) template set:
templates/XMLDoc/SingleDoc.tpl
  • The template to generate single-file documentation (in HTML or RTF format).
templates/XMLDoc/FramedDoc.tpl
  • The template to generate framed HTML documentation.
templates/XMLDoc/xmldoc.xmltype
  • The configuration file that defines the 'xmldoc' XML type, on which all XMLDoc templates are based.
templates/XSDDoc/ "XML Schema Documentation Generator" (XSDDoc) template set. For more details, see: {flexdoc-xml}/templates/XSDDoc/README.html
templates/WSDLDoc/ "WSDL/XSD Documentation Generator" (WSDLDoc) template set. For more details, see: {flexdoc-xml}/templates/WSDLDoc/README.html
DiagramKit/ DiagramKit support files. For more details, see: {flexdoc-xml}/DiagramKit/README.html
integrations/ The support files for integrations of FlexDoc/XML with other software systems
integrations/ant/ Ant example files:
integrations/ant/build.xml
integrations/ant/make.bat
  • Windows batch file to run Ant
integrations/ant/make.command
  • macOS shell script to run Ant
integrations/ant/make.sh
  • Linux shell script to run Ant
integrations/maven/ Maven plugin for FlexDoc/XML. For more details, see: {flexdoc-xml}/integrations/maven/index.html
integrations/XMLSpy/ XMLSpy Integration support files. For more details, see: {flexdoc-xml}/integrations/XMLSpy/README.html
integrations/OxygenXML/ OxygenXML Integration support files. For more details, see: {flexdoc-xml}/integrations/OxygenXML/README.html
samples/ Demo samples:
samples/sales/
  • "Sales Report" – template sample
samples/personal/
  • "Alternative to XSLT" – template sample
samples/HumanEvolution/
  • "XML Schema of Human Evolution" – a demo XML schema that shows in every detail how to use XHTML and insert images in XML schema annotations. To see what a documentation it produces, just run this schema with either XSDDoc/FramedDoc.tpl (for framed HTML) or XSDDoc/SingleDoc.tpl (for RTF) template.

Technical Requirements

FlexDoc/XML is a pure Java application. It will work anywhere, where Java SE version 11 (or later) can be installed.

Specifically, the software includes MS Windows batch files, Linux and macOS shell script files to run FlexDoc/XML immediately on those operating systems. See Windows Installation, Linux Installation and macOS Installation respectively.

To parse XML files, DTDs and XML Schemas, FlexDoc/XML uses Apache Xerces2 Java Parser version 2.12.0, which is included in FlexDoc/XML installation.

In the case of any questions concerning this library, please refer to the Apache Xerces home page: http://xerces.apache.org.

DiagramKit is implemented with the use JavaFX – the newest Java graphics/GUI platform. You are not required to use DiagramKit, but if you do, all JavaFX dependencies must be resolved. That can be done either
Before Java 11, JavaFX was a part of the standard Java SE. So, no problem existed with those JavaFX dependencies, and FlexDoc/XML+DiagramKit could be run immediately with any new Java version.

But since Java 11, Oracle moved JavaFX into a separate project found at openjfx.io. Now those, who need JavaFX, should download JavaFX SDK separately from there, install it and specify all JavaFX dependencies in their Java application according to that installation. That, of course, is too complicated for many ordinary users, and breaks down the whole idea of using some generic JRE preinstalled on user's computer (independently on FlexDoc/XML).

However, as a compensation for all that perturbation (and actually as its goal), since Java 11, anyone could build their own custom JRE (called «runtime image») that would include in itself any 3rd party modules necessary to run a given application on a particular computer platform. That's what we did (see below).

Where to get Java / JavaFX?

You can freely download Java from:

Installation

Windows Installation

To install FlexDoc/XML on Windows, please follow these steps:
  1. Unpack the downloaded archive at some location, which we shall designate as '{flexdoc-xml}'.
  2. Go to {flexdoc-xml}\bin directory.

    Edit *.bat files to specify the JAVA_HOME variable according to the location of Java 11 (or later) installed on your system.

  3. If you want to run those files from a different location, set also the DFH variable to the absolute pathname of the FlexDoc/XML installation directory (e.g. set DFH=C:\flexdoc-xml-1.13).
  4. If you have a license file 'flexdoc-xml.license' (received by e-mail), copy it to {flexdoc-xml}\lib directory. This file should be always near the flexdoc-xml.jar file!
Now, everything must be ready. You can start designer.bat to launch Template Designer or generator.bat to run the template applications or samples.

Linux Installation

To install FlexDoc/XML on Linux, please follow these steps:
  1. Unpack the downloaded archive at some location, which we shall designate as '{flexdoc-xml}'.
  2. If you have a license file 'flexdoc-xml.license' (received by e-mail), copy it to {flexdoc-xml}/lib directory.
  3. Go to {flexdoc-xml}/bin/linux directory.

    For each *.sh shell script file:

  4. Now, everything must be ready. Just run designer.sh or generator.sh!

macOS Installation

For everything to work, you need to have Java 11 (or later) installed on your Mac (so that 'java' command is available in the Terminal). Alternatively, you can download and use FlexDoc JRE for macOS available on our website: https://www.flexdoc.xyz/downloads/

To install FlexDoc/XML on macOS, please follow these steps:
  1. Unpack the downloaded archive at some location (e.g. on Desktop), which we shall designate as '{flexdoc-xml}'.
  2. If you have a license file 'flexdoc-xml.license' (received by e-mail), copy it to {flexdoc-xml}/lib directory.
  3. Go to {flexdoc-xml}/bin/macOS directory (open it with the Finder).

    The doc-generator (Template Processor) is launched by generator.command shell script file.

    Because of security control, all macOS shell script files found in the downloaded FlexDoc/XML archive cannot be executed straight. However, that is easy to overcome as described below for generator.command file:
    1. First, open generator.command with TextEdit (confirm in the warning box that it is OK to open it). Then, simply resave that file via File | Save menu. With that procedure, you will sign generator.command as its “owner/creator”, which is a precondition to be able running it.
    2. On top of that, you will need also to assign generator.command with the executable privilege. Run the Terminal and type in it 'chmod u+x' followed by a space and the full pathname of the script file (instead of typing it, just drag generator.command from the Finder into the Terminal window). Then, press Enter.
    Now at last, you can run generator.command from the Finder just by clicking twice on it.

  4. All the same is with designer.command that runs the Template Designer.

Demo Samples

All provided samples are fully described in the documentation (see Docs | FlexDoc/XML | Samples). To run a sample, you just need to:
  1. Start Template Designer (run designer.bat)
  2. Load a sample template
  3. Invoke generator dialog
  4. Choose the appropriate XML file(s)
  5. Click <Run> button
Please note, some of the sample templates can process only corresponding XML files. This table shows which XML files should be used with particular template:

Sample XML File Template
Sales Report samples/sales/sales.xml samples/sales/sales.tpl
Alternative to XSLT samples/personal/personal.xml samples/personal/personal.tpl
XML Schema of Human Evolution samples/HumanEvolution/HumanEvolution.xsd Run with both templates/XSDDoc/FramedDoc.tpl (HTML output) and templates/XSDDoc/SingleDoc.tpl (RTF output). This will look fun!

Tips

How to run XSDDoc

Please see: {flexdoc-xml}/templates/XSDDoc/README.html | Running XSDDoc

How to run WSDLDoc

Please see: {flexdoc-xml}/templates/WSDLDoc/README.html | Running WSDLDoc

How to include XSD diagrams

Diagrams can be generated and automatically included in the documentation using one of the diagramming plugins:

Using DiagramKit

DiagramKit is the native diagramming engine of FlexDoc/XML. It works synchronously with the Template Processor and generates beautiful XSD component diagrams (with the support of all possible hyperlinks), which are immediately inserted in the documentation output produced by XSDDoc / WSDLDoc.

DiagramKit is implemented entirely in Java with the use of JavaFX. Unfortunately, since Java 11, JavaFX is not included in the standard Java SE and needs to be either The latter possibility is described below.

Once you have downloaded FlexDoc/XML archive and unpacked it at some location (which we shall designate as '{flexdoc-xml}'), do the following:

  1. Go to https://www.flexdoc.xyz/downloads/ once again and download from there (according to your OS):

    “FlexDoc JRE (OpenJDK+JavaFX) to run FlexDoc/XML+DiagramKit”

    In case of Windows, you should get this archive:

    flexdoc-jre-17_windows.zip

    Unpack that archive into {flexdoc-xml}. You will have a folder:

    {flexdoc-xml}/jre

    That will be your Java to run FlexDoc/XML. You don't need to install anything else!
  2. Go to:

    {flexdoc-xml}/DiagramKit/

    Now, you can immediately run generator.bat and designer.bat found there to starts the Template Processor / Template Designer with DiagramKit activated as the diagramming engine.
For further details about running DiagramKit, please see: {flexdoc-xml}/DiagramKit/README.html

Integration with Ant

You can easily integrate FlexDoc/XML (e.g. Template Processor, DiagramKit) with Apache Ant automated build system. For more details, please see:

Integration with Maven

You can easily incorporate the generation of documentation from XML files (e.g. running XSDDoc / WSDLDoc) into your Maven build process.

FlexDoc/XML includes a Maven plugin to run the Template Processor from an Apache Maven build. For further details, please see:

For how to run DiagramKit from Maven (that is, to generate XSD/WSDL documentation with diagrams), please see:

Getting Help

Change Log

Please see: {flexdoc-xml}/CHANGES.html

Copyright© 2021 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.