'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!
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.
generator.bat
(e.g. to generate XML Schema documentation)
designer.bat
to launch the
Template Designer
(and investigate XSDDoc templates or
samples)
(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 | ||
---|---|---|---|
![]() |
This is the DocFlex/XML
main configuration file.
It specifies:
The main configuration file is used in the read-only mode and never changed.
|
||
![]() |
The DocFlex/XML license file,
which you should receive by e-mail.
Alternative Locations:
|
||
![]() |
The Template Designer configuration file.
It stores the designer configuration for the recently edited templates.
This file is created and maintained automatically.
|
||
![]() |
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:
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.
|
||
![]() |
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
|
<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.
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:
For further information about this, please see:
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)).
{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.
|