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 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.

Running on macOS

  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.

    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.
    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.

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.

Licensing of Diagramming Plugins

Diagramming plugins are 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!

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

FlexDoc/XML currently includes a single diagramming plugins able to generate component diagrams: FlexDoc/XML DiagramKit

How to generate diagrams with 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-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.

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 integrate with Ant/Maven?

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