Unpack the downloaded archive.
Copy the DocFlex license file 'docflex-xml.license', which you received by e-mail, into the 'lib' directory. This file must be always near the DocFlex/XML Java library (docflex-xml.jar) file!
Edit generator.bat and designer.bat to specify the 'JRE' variable according to the location of Java 7, Java 6, Java 5 or Java 1.4.x installed on your system.

After that, you can start:

generator.bat (e.g. to generate XML Schema documentation)
designer.bat to launch the Template Designer (and investigate XSDDoc templates or samples)

2. Configuration Files

Totally, DocFlex/XML employs five stationary configuration files (some of which are not used in certain editions):

docflex.config
docflex.license
designer.config
generator.config
catalog.xml

(In addition, there may be any number of XML Type Configuration Files prepared for specific template applications.)

Here are details about each configuration file:

File

Description

docflex.config This is the DocFlex/XML main configuration file. It specifies:

The default template directory. It is used by the template designer as an initial file chooser directory.

The default output directory (used when no output directory is specified to the generator directly with the -d option or can be found in the generator.config file).

The location of the default XML catalog file (see catalog.xml).

The locations of some frequently used XML Type Configuration Files, which need to be loaded reliably (because the default search procedure for an XML Type file in some cases may fail and specifying it all the time with -xmltype option on the command line may be cumbersome).

An alternative location of the docflex.license file.

The definitions of macros, which can be used in the docflex.config itself as well as in all XML Type Configuration Files.

An external system command to open URL (or several such commands for different URL types). This is used to launch an external viewer for the generated output files (see also -launchviewer command line option) as well as to handle any other URL open requests (e.g. from external links within various descriptions shown in the generator GUI or Template Designer).

The main configuration file is used in the read-only mode and never changed.

Editions:

Used in all editions of DocFlex/XML.

Default Location:

By default, the main configuration file is 'docflex.config'. It is searched for in the same directory where the DocFlex/XML Java library 'docflex-xml.jar' is located. If not found, the 'docflex.config' file is created automatically with the default settings.

Alternative Location:

Can be specified using -docflexconfig option both on the Template Designer and Generator command line.

docflex.license The DocFlex/XML license file, which you should receive by e-mail.

Editions:

May be used in both editions of DocFlex/XML (Full Edition and RE).
The default license file name is 'docflex-xml.license'. When a file with that name is not found, the generic 'docflex.license' file will be searched in the same location.

Note: You may copy all your licenses into the same single license file (e.g. in the case of multiple licenses).

Default Location:

Searched near the DocFlex/XML Java library file 'docflex-xml.jar'

Alternative Locations:

Can be specified using -license option on the generator or Template Designer command line

Can be assigned in the main configuration file (docflex.config)

designer.config The Template Designer configuration file. It stores the designer configuration for the recently edited templates. This file is created and maintained automatically.

Editions:

Used only in DocFlex/XML (Full Edition).

Default Location:

config/designer.config -- assigned in the main configuration file

Alternative Location:

Can be specified using -config option on the Template Designer command line.

generator.config The generator configuration file; used by the Generator to obtain all settings not specified directly on the command line.
This file is created and maintained automatically by the generator dialog. It contains:

The last used templates

The values of template parameters

The last used XML files

The list of XML catalog files

The output directory and file name

The output format and its options

When the generator dialog is invoked next time, those settings are restored from the generator config file, so you don't need to re-enter them again. The values of template parameters previously specified for one template will also be loaded into the equally named parameters of other templates.
You can use the generator dialog to quickly prepare a config file with the specific settings you need and, then, provide only this file on the generator command line (using -config option) instead of specifying all those settings directly.

Editions:

Used in all editions of DocFlex/XML.

Default Location:

config/generator.config -- assigned in the main configuration file

Alternative Location:

Can be specified using -config option on the generator command line.

catalog.xml The default XML catalog file; redirects the external locations of some standard XML schemas found in Internet to their local copies stored in DocFlex/XML resources.
This file is crucial for big template applications, like XSDDoc! For more details, please see: XML Catalogs | Default XML Catalog

Editions:

Used in all editions of DocFlex/XML.

Default Location:

lib/resources/catalog.xml -- assigned in the main configuration file

Alternative Location:

Can be specified using -defaultcatalog option both on the Generator and Template Designer command line.

3. XML Catalogs

What is XML Catalog?

Suppose you have an XML file that contains a reference to another XML file. That reference may be specified as a certain external URL. For instance, you have an XML schema containing a line like this:

<xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/xml.xsd"/>

Here, the <xs:import> element tells the XML schema processor to import another XML schema 'xml.xsd' located by the URL http://www.w3.org/2001/xml.xsd, which is found somewhere in Internet (specifically, on the web-site of W3C).

Suppose that you have both XML schemas on your local drive. You want to process them without changing anything in the schema sources and, yet, without loading anything from the Internet. How can you do that?

Another situation may happen when an XML file (or any other file) is referred by a certain opaque URI (or system identifier), like the following string:

urn:oasis:names:tc:dita:xsd:xml.xsd:1.1

Such an URI does somehow identify the file. But, it provides no clue where that file can be found. How can it be processed then?

XML catalogs provide a solution for such problems. Basically, an XML catalog is a special XML file that maps some external identifiers or URIs to other URIs, which may provide more information on how the physical files can be found. Here is an example of XML catalog (click on the link):

http://docs.oasis-open.org/dita/v1.1/OS/schema/catalog.xml

Using XML catalog, you can specify that a file originally found by a remote URL should be actually taken from a certain location on your system or a certain opaque URI must be translated into another local file.

Of course, that idea is simple and probably was implemented many times! Indeed, several XML catalog formats exist now. One of them – OASIS XML Catalogs v1.1 – is apparently the most prominent standard, which is used by DocFlex/XML.

How DocFlex/XML uses XML Catalogs

DocFlex/XML supports OASIS XML Catalogs v1.1 using 'org.apache.xerces.util.XMLCatalogResolver' class included in Apache Xerces2 (see Apache Xerces2 | Using XML Catalogs).

When the locations of OASIS XML Catalog files are specified, they are passed to the instance of XMLCatalogResolver, which is registered on the Apache XML parser used to read XML files. After that, the DTD references specified in the XML files will be automatically resolved according to the catalog mappings.

What is more, the prepared instance of XMLCatalogResolver will be used also by the 'resolveURI()' function available in FlexQuery-expressions. This function plays a key role within the templates when loading and processing of the XML files referenced from other XML files. (For instance, it is used in XSDDoc templates to process XML schema <xs:import> elements).

DocFlex/XML uses XML Catalogs for two purposes:

To resolve the locations of the XSD and DTD files that provide the datatype information for XML Types -- the descriptions of specific xml-file data sources, on which particular template applications are based.
For further information about this, please see:
To resolve the locations of the XML and DTD files referenced from other data-source XML files processed by the generator.
In this case, the necessary XML catalog(s) must be specified with -xmlcatalog option on the generator command-line or in the generator GUI (see Assigning XML Catalog(s)).

Default XML Catalog

The default XML catalog has been introduced (since DocFlex/XML v1.8.5), to substitute dynamically the canonical locations of some standard XML schemas (like http://www.w3.org/2001/XMLSchema.xsd) found in Internet with their local copies stored in the DocFlex/XML resource directory:

{docflex-xml}/lib/resources

This is needed because those schemas are used in the definitions of XML Types of some template applications supplied with DocFlex/XML (e.g. see XSDDoc | Templates | XML Type). Therefore, they need to be loaded quickly and reliably.

Previously, those XML schemas were also held locally along with the XSDDoc templates in the directory: {docflex-xml}/templates/XSDDoc/xmltype/. But now, they have been moved in a more central location so as to reuse them in other template applications (e.g. in the coming WSDLDoc) as well as during the generation of some examples.

The location of the default XML catalog is specified in docflex.config. By default, it is the file:

{docflex-xml}/lib/resources/catalog.xml

However, that location can be overridden with -defaultcatalog option both on the Generator and Template Designer command line.

The default XML catalog is not activated automatically whenever some XML catalogs might be used (see above). Instead, like all other XML catalogs, it must be selected explicitly (e.g. with -xmlcatalog option or xsd.catalogs property). The difference is that it can be specified not only with a physical URL or pathname (leading to the catalog file itself), but using the following abstract URI:

urn:docflex-com:xml:defaultcatalog

That URI is recognized by DocFlex/XML simply as the “default XML catalog” (whose actual file is specified as such in docflex.config). This makes possible to select the default XML catalog independently on where it is actually located. For example:

-xmlcatalog urn:docflex-com:xml:defaultcatalog

In fact, the alternative possibility to specify the default XML catalog file using -defaultcatalog command line option is provided because the default XML catalog is extremely important for big template applications like XSDDoc.
For instance, the "xsddoc" XML Type, on which XSDDoc templates are based, itself is based on the XML Schema for XML schemas: http://www.w3.org/2001/XMLSchema.xsd. If that schema cannot be loaded, the XML Type won't be initialized and XSDDoc won't work; nor even can it be edited in the Template Designer!
So, if something is wrong with your DocFlex/XML main configuration file (docflex.config), you may always use the -defaultcatalog option as the last resort.