FlexDoc/XML - Generator

Input XML

XML files are the main sources of the data processed by FlexDoc/XML templates, by which the documentation is generated.

Additional data can be injected via template parameters.

Specifying Input XML File(s)

The input XML files are specified either:

• In the «XML File(s)» field of the Generator Dialog
• As free arguments on the generator command line

Any number of input XML files can be specified, by which you want to generate the documentation.

Each such a specification must be either:

• Local file pathname or pathname pattern
• URL (e.g. http://www.w3.org/2001/XMLSchema.xsd)

At that:

• Multiple file specifications must be separated with spaces.
• When a file specification contains spaces itself, it must be enclosed in double quotes.
• You can combine any specification types together.
• The "pathname pattern" is an Ant-style pattern for local file pathnames. See: Using file pathname patterns.
• In case of URL, the generator will try to download such a file directly from the Internet (or elsewhere). This, however, can be redirected using an XML catalog.

XML File Pathname with Spaces

When some of your XML schema file pathnames contain spaces, to specify them to the generator, you need to enclose every such a pathname in double quotes. For example:

"c:\My XML Projects\schemas\products.xsd"

This should be done both in the Generator Dialog and on the generator command line.

Using File Pathname Patterns

When you need to process at once so many input XML files that it is impractical to list all of them as generator arguments, you can use Ant-style file pathname patterns.

Each pathname pattern looks similar to a normal file pathname besides that it may contain some wildcard characters with a special interpretation. These are the following:

Wildcard	Description
?	matches one character in a real file name
*	matches zero or more characters
**	when used as the name of a directory, it matches zero or more sub-directories at any depth

File pathname patterns may be both absolute and relative ones, may contain spaces, etc. Basically, they should be specified the same as the ordinary file pathnames.

Example Patterns:

Pattern	Description
*.xsd	matches all XSD files in the current directory
c:\schemas\*.xsd	matches all XSD files in the directory c:\schemas\
c:\schemas\**\*.xsd	matches all XSD files in the directory c:\schemas\ and all its subdirectories
c:\**\schemas\*.xsd	matches all XSD files found in any directory with the name 'schema' at any depth
../**/*.xsd	matches all XSD files found in the parent directory of the current one and all its subdirectories
*.x??	matches all files in the current directory, whose name extension consists of 3 letters starting with 'x'
*.x*	matches all files in the current directory, whose name extension starts with 'x'

The name-separator may be either slash ('\' or '/') independent on the system.

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 uses XML Catalogs for two purposes:

1. 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:

   • Designing Templates | Defining XML Type | Assigning XML Schemas | xsd.catalogs property
   • FlexDoc/XML | XSDDoc | Templates | XML Type
   • Installation / Configuration Files | Default XML Catalog
2. To resolve the locations of the XML and DTD files referenced from other data-source XML files processed by the generator.

   In that case, the necessary XML catalog(s) must be specified along with the input XML files.

Assigning XML Catalog(s)

The XML catalogs to be used to load all necessary input XML files can be specified both in the generator GUI and on the generator Java command line:

• To specify XML catalogs in the Generator Dialog, click the «Catalog» button. The following dialog will appear:

  

  Here, you can add one or more XML Catalog files, which may be both local file pathnames and absolute URLs. The «Include default XML catalog» check-box allows you to add also the default XML catalog.
• Alternatively, you can specify all your XML catalogs on the generator Java command line using the -xmlcatalog option, e.g.:

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

  To specify multiple XML catalogs, use this option several times for each file.

All specified XML catalogs will be loaded before the data-source XML files and further used to resolve (or redirect) both the initially specified XML file URIs and any external identifiers or URI references found within the XML files being processed.

When multiple XML catalogs are used, the order in which they are specified (on the command line or in the GUI) may be important! The same URI may have different resolutions according to different catalogs, but the one will be used, which was found in the catalog specified the first.