Configuration Properties and Catalog Support

General system configuration is managed through the setting of Configuration Properties. These Configuration properties complement the parameters by providing control over some of the non-comparison specific features.
The configuration property features include:

whether debug information should be produced;
where the catalogs can be located; and
whether the command line output should overwrite an existing output file without asking the user for permission.

A full list of configuration properties for this tool is contained in the Configuration Properties section of the Reference Guide.

This distribution includes the OASIS DTDs and Schema files for DITA 1.1 and 1.2 as well as the Apache XML Commons Resolver to provide support for XML catalog use. This means, that out-of-the-box, the tool will not need to download the DTDs or Schema files for DITA 1.1 or 1.2 but will use its local copy.

Configuration Properties

Configuration properties can be set through both the API (via the ConfigProperties class) or a configuration file (deltaxmlConfig.xml). A sample configuration file (and dtd) is provided in the samples/config directory of this distribution.
A configuration property is constructed from a triple:

name	A string representing the name of the property.
value	A string representing the value of the property.
fixed	A boolean specifying whether this property can be overridden.

The configuration properties file is typically located in the same directory as the product's library (i.e. the directory that contains the deltaxml-dita.jar file or exe/dll files). We refer to this directory as the installation directory for the remainder of this discussion on configuration properties. If the file cannot be found in the installation directory then it is looked for in the user's home directory, and then the current working directory.

It is sometimes useful to be able to specify a property in terms of other properties. For example, it would be possible to specify a property P in terms of a property Q by including the text ${Q} in P's value. Note that Java system properties, such as user.home and user.dir can be referred to in this way (i.e. ${user.home} and ${user.dir} respectively). We also provide an install.dir property, for locating the product's installation directory, when this information is obtainable from the JVM. Some application servers prevent the automatic installation directory detection from working.

A DeltaXML configuration file can specify a 'search path list' to look for additional properties to be set (or overridden - if they have not previously been fixed). Here, the first search path in the list that exists is loaded; all other entries in the search path are ignored. Further, any attempt to reload a previously visited configuration file will finish the configuration file loading process.

Note that the configuration properties that are specified in configuration files, are loaded before any specified through the API.
For example the configuration property com.deltaxml.cmdline.forceOverwrite can be set to true as follows:

XML

<configProperty 
  name="com.deltaxml.cmdline.forceOverwrite" 
  value="true" 
  fixed="false" />

An alternative way of setting these properties for a single Java invocation only is to use a System property setting when invoking the java command. e.g.

Java only

TEXT

-Dcom.deltaxml.cmdline.forceOverwrite=false

Configuring the catalogs

OASIS Catalogs can be used to locate entities (such as DTDs) and URIs.

If you wish to use additional catalogs that are searched before the built-in catalog you need to supply the location(s) using a deltaxmlConfig.xml file. A sample file (and dtd) is provided in the samples/config directory of this distribution. Copy these files into either the installation directory of deltaxml-dita.jar file or into your user home directory and then modify the value of com.deltaxml.ext.catalog.files to the relevant path(s). For example:

TEXT

<configProperty
  name="com.deltaxml.ext.catalog.files"
  value="C:\catalogs\my_catalog.xml;C:\another-catalog.xml" />

If you wish to completely override the built-in catalog, set the xml.catalog.files property instead.

Please note, it is also possible to use the built-in catalog first, and then additional catalogs by using the 'fixed' com.deltaxml.rsc.catalog.files property within the definition of the xml.catalog.files property as follows:

TEXT

<configProperty
  name="xml.catalog.files" 
  value="${com.deltaxml.rsc.catalog.files};C:\catalogs\catalog1.xml" />

An alternative way of setting these properties for a single Java invocation only is to use a System property setting when invoking the java command. e.g.

Java only

TEXT

-Dcom.deltaxml.ext.catalog.files=C:\catalogs\catalog1.xml;D:\catalog2.xml

Catalog Support in an Application Server

Some application servers use classloaders that, for security reasons, limit the ability to dynamically access some resources and access the location of the running code. If this is the case, you will need to set the xml.catalog.files variable even if you wish to use the inbuilt dtds. It should be set to the following, with the relevant path:

TEXT

<configProperty
  name="xml.catalog.files"
  value="jar:file:/path/to/install/directory/deltaxml-dita.jar!/catalog.xml" />