Products         News         Downloads         Licensing         Shop         Support    

 DocFlex Technology
Overview
Features
Documentation
 DocFlex/XML
Overview
Features
Documentation
XSDDoc
Templates
Parameter Tree
Examples
FAQ
WSDLDoc
DiagramKit
Integrations
 DocFlex/Javadoc
Overview
Documentation
JavadocClassic
Tutorials
 DocFlex/Together
Overview
Examples
Basic Templates
Documentation
Tutorials
 Try
Downloads
Registration
Trial License
 Use
Licensing
Shop
Support
 Company
News
Products
Customers
About Us
Imprint
Legal
Contact
Links
 

DocFlex/XML - XSDDoc - Frequently Asked Questions

Running XSDDoc

How to run XSDDoc?

Running on Windows

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

    C:\docflex-xml

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

  3. Edit:

    {docflex-xml}/bin/generator.bat

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

    If you don't have the necessary Java version installed on your system, you can freely download and install the most recent version of Java Runtime Environment (JRE) from Java Technology web-site: http://www.oracle.com/technetwork/java/

  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: DocFlex/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. Diagrams will be generated by DiagramKit too, as many as it's allowed by XSDDoc demo limits. 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:
  • DocFlex/XML was tested on macOS Mojave (10.14)
  • For everything to work, you need to have Java installed on your Mac (so that 'java' command is available in the Terminal). You can download Java for Mac from the Oracle website: http://www.oracle.com/technetwork/java/
  1. Unpack the downloaded DocFlex/XML archive at some location (e.g. on Desktop), which we shall designate as {docflex-xml}.
  2. Go to {docflex-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 running 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 DocFlex/XML archive at some location, which we shall designate as {docflex-xml}.
  2. Go to {docflex-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: {docflex-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: {docflex-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: {docflex-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 DocFlex/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: DocFlex/XML | Features | Diagramming Plugins

DocFlex/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 DocFlex/XML and run XSDDoc!

How to include diagrams generated by DiagramKit?

DiagramKit is DocFlex/XML native diagramming engine (independent on any third-party software). It creates beautiful component diagrams, which can be generated/inserted simultaneously along with the documentation generated by XSDDoc (with the support of all possible hyperlinks).

All diagrams visible in all XSDDoc examples were generated by DiagramKit:

DiagramKit is the default DocFlex/XML diagramming plugin and will be active immediately when you run XSDDoc. However, it is covered by a separate license.

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 DocFlex/XML using XMLSpy Integration.

Here is how to get it work:

  1. Go to the subdirectory:

    {docflex-xml}/integrations/XMLSpy/

    where '{docflex-xml}' denotes the directory where you installed DocFlex/XML.
  2. Find generator.bat in that directory and edit it to specify:
    • Java location (e.g. c:\Program Files\Java\jre8)
    • XMLSpy installation directory (e.g. c:\Program Files\Altova\XMLSpy2018)
    For more details about this, please read the README file found in the same directory: {docflex-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:

DocFlex/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 DocFlex/XML using OxygenXML Integration.

Here is how to get it work:

  1. Go to the subdirectory:

    {docflex-xml}/integrations/OxygenXML/

    here '{docflex-xml}' denotes the directory where you installed DocFlex/XML.
  2. Find generator.bat in that directory and edit it to specify:
    • Java location (e.g. c:\Program Files\Java\jre8)
    • Oxygen XML installation directory (e.g. c:\Program Files\Oxygen XML Editor 18)
    For more details about this, please read the README file found in the same directory: {docflex-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:

DocFlex/XML | Integrations | Oxygen XML

How to integrate with Ant/Maven?

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

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