FlexDoc/XML - Installation / Configuration Files

Installation
Configuration Files
XML Catalogs

1. Installation

To install FlexDoc/XML on Windows, please follow these steps:

Unpack the downloaded archive at some location, which we shall designate as '{flexdoc-xml}'.
Go to {flexdoc-xml}\bin directory.
Edit *.bat files found there to specify the JAVA_HOME variable according to the location of Java 9 (or later) installed on your system.
If you want to run those files from a different location, set also the DFH variable to the absolute pathname of the FlexDoc/XML installation directory (e.g. set DFH=C:\flexdoc-xml-1.12.5).
If you have a license file flexdoc-xml.license (received by e-mail), copy it to {flexdoc-xml}\lib directory. This file should be always near the flexdoc-xml.jar file!

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)

For further details about installation and setting up various things, please see:

2. Configuration Files

Totally, FlexDoc/XML employs five stationary configuration files:

flexdoc.config
flexdoc.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
flexdoc.config	This is the FlexDoc/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 flexdoc.license file. The definitions of macros, which can be used in the `flexdoc.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. Default Location: By default, the main configuration file is `'flexdoc.config'`. It is searched for in the same directory where the FlexDoc/XML Java library `'flexdoc-xml.jar'` is located. If not found, the `'flexdoc.config'` file is created automatically with the default settings. Alternative Location: Can be specified using -flexdocconfig option both on the Template Designer and Generator command line.
flexdoc.license	The FlexDoc/XML license file, which you should receive by e-mail. Default Location: Searched near the FlexDoc/XML Java library file `'flexdoc-xml.jar'` The default license file name is `'flexdoc-xml.license'`. When a file with that name is not found, the generic `'flexdoc.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). Alternative Locations: Can be specified using -license option on the generator or Template Designer command line Can be assigned in the main configuration file (flexdoc.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. 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. 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 FlexDoc/XML resources. This file is crucial for big template applications, like XSDDoc! For more details, please see: XML Catalogs \| Default XML Catalog 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 FlexDoc/XML.

How FlexDoc/XML uses XML Catalogs

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

Furthermore, 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).

FlexDoc/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 FlexDoc/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 FlexDoc/XML resource directory:

{flexdoc-xml}/lib/resources

This is needed because those schemas are used in the definitions of XML Types of some template applications supplied with FlexDoc/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: {flexdoc-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. WSDLDoc) as well as during the generation of some examples.

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

{flexdoc-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:flexdoc-xyz:xml:defaultcatalog

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

-xmlcatalog urn:flexdoc-xyz: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 FlexDoc/XML main configuration file (flexdoc.config), you may always use the -defaultcatalog option as the last resort.