FlexDoc/XML - XSDDoc - FAQ

Running XSDDoc

How to run XSDDoc?

Running on Windows

  1. Download the FlexDoc/XML archive from the downloads page.
  2. Unpack it in some directory, e.g.:

    C:\flexdoc-xml

    which we shall refer as '{flexdoc-xml}'.

  3. Edit:

    {flexdoc-xml}/bin/generator.bat

    to specify the 'JAVA_HOME' variable according to the location of Java 9 (or later) installed on your system.

    See also: FlexDoc/XML | Overview | Technical Requirements | Where to get Java / JavaFX?

  4. Run that generator.bat. You will see the Generator Dialog like shown on this screenshot:

  5. In the «Template» field, select
  6. In the «XML File(s)» field, specify one or many XSD files, by which you want to generate the documentation.

    This field must contain one or several file specifications, which may be either:
    • local file pathname or pathname pattern
    • URL (e.g. http://www.w3.org/2001/XMLSchema.xsd)
    Notes:
    • Multiple file specifications must be separated with spaces.
    • When a file specification contains spaces itself, it must be enclosed in double quotes.
    • You can combine any specification types together.
    • The "pathname pattern" is an Ant-style pattern for local file pathnames. See: FlexDoc/XML | Documentation | Running Generator | ... | Using file pathname patterns.
    • In case of URL, the generator will try to download such a file directly from the Internet (or elsewhere). This, however, can be redirected using an XML catalog.
  7. In the «Output format» field, select HTML or RTF format.

    RTF will work only with SingleDoc.tpl template!

  8. Click «Run» button to start the generation.

    If you have not installed any licenses, you will see this dialog:

    Just click OK to continue.

    This message notifies you, that everything will work in demo mode. It means that XSDDoc will process all your input XSD files, however fully document only limited number of components. If those limits are not reached, you will get the complete documentation. Otherwise, some content will be omitted and the message included saying which limits were exceeded.

    Once all source XSD files have been loaded, the generator enters into the estimation phase. Lots of processing is being done during that, however, you will see only "Scanning data source, please wait..." message on the progress bar. On large input data this phase may take some time. Please wait! After that, the generator passes into the generation phase. The progress bar will show what's being generated. You can stop the generator at any time during any phase by clicking «Cancel» button.

Running on macOS

Notes:
  • FlexDoc/XML was tested on macOS Catalina (10.15)
  • For everything to work, you need to have Java 9 (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.
  1. Unpack the downloaded FlexDoc/XML archive at some location (e.g. on Desktop), which we shall designate as '{flexdoc-xml}'.
  2. 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. To be able to run it, first you need to assign it with the executable privilege as follows:

    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, you can run generator.command from the Finder just by clicking twice on it.

    When you run generator.command, the Generator Dialog should show up like on this screenshot:

  3. Anything else is the same as in case of Windows.

Running on Linux

  1. Unpack the downloaded FlexDoc/XML archive at some location, which we shall designate as '{flexdoc-xml}'.
  2. Go to {flexdoc-xml}/bin/linux directory. The doc-generator (Template Processor) is launched by generator.sh shell script file.

    Edit generator.sh to specify the JAVA_HOME variable according to the location of Java 8.x (or later) installed on your system. Edit also the file "Permission" properties to allow it to be executed by Linux.

    Run that generator.sh. You will see the Generator Dialog like shown on this screenshot:

  3. Anything else is the same as in case of Windows.

How to generate HTML documentation?

Framed HTML

To generate multi-file framed HTML (Javadoc-like) XML Schema documentation:
  1. Start the generator (run generator.bat / generator.sh / generator.command according to your OS). The Generator Dialog should appear.
  2. In «Template» field, select FramedDoc.tpl template: {flexdoc-xml}/templates/XSDDoc/FramedDoc.tpl.
  3. Click «Params» button, if you need to specify/edit parameters of that template.

    The following are the template parameters specific to framed HTML documentation. Click on the screenshot to see the corresponding parameter description:

  4. In «XML File(s)» field, specify one or many input XML schema (XSD) files.
  5. In «Output Format» field, select HTML output format. Click «Options» button, if you need to specify/edit HTML options.
  6. Click «Run» button to start the generation.

Single File HTML

Sometimes you may want to generate your entire XML Schema documentation as a single HTML file (including diagrams, images and anything else). That's easy to do:
  1. Start the generator (run generator.bat / generator.sh / generator.command according to your OS). The Generator Dialog should appear.
  2. In «Template» field, select SingleDoc.tpl template: {flexdoc-xml}/templates/XSDDoc/SingleDoc.tpl.
  3. Click «Params» button, if you need to specify/edit parameters of that template.
  4. In «XML File(s)» field, specify one or many input XML schema (XSD) files.
  5. In «Output Format» field, select HTML output format. Click «Options» button, if you need to specify/edit HTML options.
  6. Click «Run» button to start the generation.

How to generate RTF documentation?

To generate single-file RTF documentation for your XML schema(s):
  1. Start the generator (run generator.bat). The Generator Dialog should appear.
  2. In «Template» field, select SingleDoc.tpl template: {flexdoc-xml}/templates/XSDDoc/SingleDoc.tpl.
  3. Click «Params» button, if you need to specify/edit parameters of that template.

    The following are the template parameters specific to RTF documentation. Click on the screenshot to see the corresponding parameter description:

  4. In «XML File(s)» field, specify one or many input XML schema (XSD) files.
  5. In «Output Format» field, select RTF output format. Click «Options» button, if you need to specify/edit RTF options.
  6. Click «Run» button to start the generation.

How to include diagrams?

XSD component diagrams are generated by a special diagramming plugin. Diagrams can be automatically inserted in both HTML and RTF documentation. In case of HTML, numerous diagram hyperlinks are generated as well.

Diagramming plugins are particular implementations of Element Image Provider. Since FlexDoc/XML itself is mostly about data-mining in XML files and generating some human-readable texts from the found results, it has little intersection with diagramming. So, generation of any diagrams needs to be implemented separately for every particular documentation task, where they are required. Since the latter is the job of a particular template application, the diagramming plugin serves as its functional extension and both need to interact.

For further details, please see: FlexDoc/XML | Features | Diagramming Plugins

FlexDoc/XML currently includes three different diagramming plugins able to generate component diagrams:

Licensing of Diagramming Plugins

Each diagramming plugin is licensed separately. However, in demo mode any of them will work together with XSDDoc and generate a limited number of complete and undistorted diagrams. So, you can try how they work immediately. Just downloads FlexDoc/XML and run XSDDoc!

How to include diagrams generated by 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.

All diagrams visible in all XSDDoc examples have been generated by DiagramKit:

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 must 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 the downloads page 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-14_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.

Related Template Parameters:

The following are the template parameters that control running of DiagramKit (i.e. what diagrams it generates). Note that the “DiagramKit” parameter group is enabled only when the DiagramKit plugin is active. Click on the screenshot to see the corresponding parameter description:

See Also:

How to include diagrams generated by XMLSpy?

If you have a license for Altova XMLSpy (http://www.altova.com/xmlspy/), you can turn it into a diagramming engine for FlexDoc/XML using XMLSpy Integration.

Here is how to get it work:

  1. Go to the subdirectory:

    {flexdoc-xml}/integrations/XMLSpy/

    where '{flexdoc-xml}' denotes the directory where you installed FlexDoc/XML.
  2. Find generator.bat in that directory and edit it to specify:
    • Java location (e.g. C:\Program Files\Java\jdk-14)
    • XMLSpy installation directory (e.g. C:\Program Files\Altova\XMLSpy2020)
    For more details about this, please read the README file found in the same directory: {flexdoc-xml}/integrations/XMLSpy/README.html
  3. Run that generator.bat.
  4. Everything else is the same as described in How to run XSDDoc.

Related Template Parameters:

The following are the template parameters that control XMLSpy Integration. Note that the “XMLSpy Integration” parameter group is enabled only when the XMLSpy Integration plugin is active. Click on the screenshot to see the corresponding parameter description:

See Also:

FlexDoc/XML | Integrations | XMLSpy

How to include diagrams generated by Oxygen XML?

If you have a license for Oxygen XML Editor (http://www.oxygenxml.com), you can turn it into a diagramming engine for FlexDoc/XML using OxygenXML Integration.

Here is how to get it work:

  1. Go to the subdirectory:

    {flexdoc-xml}/integrations/OxygenXML/

    here '{flexdoc-xml}' denotes the directory where you installed FlexDoc/XML.
  2. Find generator.bat in that directory and edit it to specify:
    • Java location (e.g. C:\Program Files\Java\jdk-14)
    • Oxygen XML installation directory (e.g. C:\Program Files\Oxygen XML Editor 21)
    For more details about this, please read the README file found in the same directory: {flexdoc-xml}/integrations/OxygenXML/README.html
  3. Run that generator.bat.
  4. Everything else is the same as described in How to run XSDDoc.

Related Template Parameters:

The following are the template parameters that control OxygenXML Integration. Note that the “OxygenXML Integration” parameter group is enabled only when the OxygenXML Integration plugin is active. Click on the screenshot to see the corresponding parameter description:

See Also:

FlexDoc/XML | Integrations | Oxygen XML

How to integrate with Ant/Maven?

A demo about that you can find in your FlexDoc/XML installation:
{flexdoc-xml}/integrations/ant/
{flexdoc-xml}/integrations/maven/
See Also: