FlexDoc/XML - XSDDoc - Parameter Tree

About XSDDoc parameters

«Diagramming | XMLSpy Integration» parameter group

Parameter Name / Type / Description

XMLSpy Integration

diagramming.XMLSpy : boolean

Enables XMLSpy Integration. When this parameter is unselected (false), XMLSpy won't be called.

Note: The parameter is enabled only when the XMLSpy Integration has been setup. For more details, please see the integration README found in your FlexDoc/XML installation:

See Also:

XMLSpy Version

diagramming.XMLSpy.version : string

Specify the version number of the XMLSpy installed on your system.

The default value of this parameter is obtained from the -m:XMLSPY_VERSION option specified on the generator command line.

Here you can override it and specify a different XMLSpy version number, which will be used only by XSDDoc templates.

Note that the XMLSpy version number is not used by the XMLSpy integration itself. Rather, it is used essentially to calculate the default values of the “Integration | XMLSpy | Workarounds” parameters (which allows you to not bother yourself much about their meanings).

Show XMLSpy

diagramming.XMLSpy.show : boolean

Specify whether XMLSpy application (IDE) should show up, when it is called from FlexDoc to process the XML schemas.

When “Diagramming | XMLSpy Integration | Quit XMLSpy” parameter was unselected (false), the XMLSpy IDE will remain visible even after finishing FlexDoc/XML. So, you can use it and quit by standard means.

Quit XMLSpy

diagramming.XMLSpy.quit : boolean

Specify whether to quit XMLSpy.

Once all XML schemas have been processed and all diagrams generated, XMLSpy is not needed any longer. Then, XSDDoc issues a command to finish the XMLSpy diagramming. What will happen with the running instance of XMLSpy depends on the setting of this parameter:

true (selected)
This is the default mode (and default setting of this parameter).

As soon as the finishing XMLSpy command is issued, the integration calls an XMLSpy API method to quit XMLSpy and waits until it returns. After that, the processing of XSDDoc templates (that is the generation of documentation) continues.

If you run XSDDoc again (e.g. while using the generator GUI) with XMLSpy integration enabled, a new XMLSpy instance will be launched and so on.

One problem with this mode is that on Linux/Wine quitting of XMLSpy may raise an error (or even hang JVM). In that case, you may try to unselect this parameter.

false (unselected)
The running instance of XMLSpy won't be quitted. The processing of XSDDoc templates continues as normally.

If you run XSDDoc from the generator GUI and then run it again (with XMLSpy integration enabled), the same XMLSpy instance will be reused.

When FlexDoc/XML exits (that is the JVM running it), its use of the XMLSpy instance will be released. However, the XMLSpy process itself will remain in memory running. If “Diagramming | XMLSpy Integration | Show XMLSpy” parameter was selected before that, the XMLSpy IDE will be visible still. So, you can use it and quit by standard means.

On Linux/Wine, releasing XMLSpy instance probably doesn't work smoothly again. But then, the Wine itself quits, so you won't see anything. (The full XML schema documentation with the diagrams will be ready at that).

See Also Parameters:

Delete Temporary Docs

diagramming.XMLSpy.deleteTempDocs : boolean

Specify whether to delete all files temporarily generated by XMLSpy.

When this parameter is selected (true), the entire 'xmlspy' subdirectory will be deleted on the finishing of XSDDoc. Otherwise, all original output files generated by XMLSpy will be left.

Diagram Format

diagramming.XMLSpy.diagramFormat : enum {"PNG", "EMF"}

Select the graphics format of the diagrams generated by XMLSpy.

Possible Choices:

All diagrams will be in PNG formats.

This is the default format. It is best for HTML documentation. (However, in RTF/PDF documentation it will work as well.)

The diagrams will be generated in EMF format.

This format is more suitable for printable RTF/PDF documentation. (In case of HTML, the diagrams will be generated in EMF as well, however, whether you can see them will depend on your HTML browser.)

Important: The generation of diagrams in EMF format is possible only since XMLSpy 2009 or later. (Although, XMLSpy itself supported EMF much earlier, they provided the Java API for it only since 2009.) Therefore, if you have an earlier version of XMLSpy and select "EMF" in this parameter, only PNG graphics will be generated instead.



This parameter group is needed to let the integration know some specifics about how the HTML output produced by XMLSpy should be parsed and interpreted.

Note: The default values of these parameters are calculated from the value of the “Diagramming | XMLSpy Integration | XMLSpy Version” parameter. So, in most cases you don't need to change them.


diagramming.XMLSpy.workarounds.api : enum {"old", "2012"}

Specify which version of XMLSpy Java API will be used to communicate with XMLSpy.

Possible Choices:

"early version"
The early version of XMLSpy Java API, which existed all the time since the very start. It is based on the files:
C:\Program Files\Altova\XMLSpy\XMLSpyInterface.jar
This API is currently most stable and should be preferred (particularly on Windows). So it is the default choice.
A new API provided since XMLSpy 2012. It is based on the files found in the directory:
C:\Program Files\Altova\XMLSpy\JavaAPI\
As of the XMLSpy v2012, the problem of this API is that it raises some internal Java exception when quitting XMLSpy. However, that exception is tolerable and can be ignored in most cases.

We don't know the reason why Altova has created another Java API for XMLSpy. But it may be expected that the new API will be given a priority in the next XMLSpy version.

So, if something doesn't work with some new XMLSpy version (since 2012), you may try to switch to this API.

The same we suggest, if you have problem of running the XMLSpy integration on Linux/Wine.

See Also:

Fix Imagemap Coordinates

diagramming.XMLSpy.workarounds.fixCoords : boolean

Specify whether to correct imagemap coordinates generated by XMLSpy.

As of the versions XMLSpy 2004-2011, all rectangle areas contained in the hypertext imagemaps associated with the content model diagrams generated by XMLSpy are shifted slightly to the top and left, which makes every clickable area to appear somewhat displaced from where it should be.

We have found no rational purpose behind this and assumed that it was simply a bug. Therefore, we programmed a correction by adding (+10,+5) to every (x,y) coordinate found in the imagemaps.

Now, this works fine. But since it is likely a bug in XMLSpy, they may fix it some time later. In that case, our correction would actually produce a distortion by itself.

With this parameter, you can disable any corrections. Unselect it (or specify false) to have only the original imagemap coordinates (generated by XMLSpy) used in the result documentation.

Use Namespace Prefixes

diagramming.XMLSpy.workarounds.useNSPrefixes : boolean

This parameter tells the integration whether namespace prefixes may be used in the component names in the HTML documentation generated by XMLSpy.

In the XML schema documentation generated by XMLSpy 2007 and erlier versions (as well as XMLSpy 2008 base), the titles of components from imported schemas may start with the namespace prefixes declared in the main (importing) schema for the target namespaces of the schemas being imported.

Include Attributes

diagramming.XMLSpy.workarounds.includeAttributes : boolean

This parameter tells the integration whether attributes are documented in the HTML output file generated by XMLSpy. Attributes are documented only since XMLSpy 2006

Exclude Attribute Groups

diagramming.XMLSpy.workarounds.includeAttributes : boolean

This parameter informs the integration that the local attributes defined within global attribute groups are not documented in the HTML output file generated by XMLSpy.

This problem occurs in XMLSpy 2006-2007. Although these XMLSpy versions do depict all local attributes on the diagrams and even generates hyperlinks for them, those local attributes that are defined within global attribute groups are actually never documented separately in the HTML output produced by XMLSpy. (So, the diagram hyperlinks to them in fact lead to nowhere!)

To process such an HTML correctly, the integration needs to know about that omission.

Include Redefined Components

diagramming.XMLSpy.workarounds.includeRedefinedComps : boolean

This parameter tells the integration if the redefined (original) components are documented by XMLSpy.

Although all tested XMLSpy versions process redefinitions of XML schema components (those specified within <xs:redefine> elements), XMLSpy 2006 and early versions do not document separately the original components (those being redefined) in the HTML output they generate.

To process such an HTML correctly, the integration needs to know about this.