Main templates are those that can be specified for interpretation directly to the generator (i.e. either with -template option on the command line or in the Generator Dialog).

Besides them, there are many other templates (called subtemplates) that are used internally. Those templates work as procedures invoked from the main templates as well as from each other.

The entire “XSDDoc” template set (version 2.5.0) consists of 64 templates.

2. XML Type

To be able to process any XSD files, first, one needs to know their structure. This is provided by the “xsddoc” XML Type, which is defined using a special plain text file (found in the XSDDoc template set):

{docflex-xml}/templates/XSDDoc/xsddoc.xmltype

Here is its full content:

1 2 3 4 5 6 7 8 9 10 11 12 13 xsddoc.name = W3C XML Schema Files xsddoc.doc = Represents any number of W3C XML Schema Definition (XSD) files xsddoc.xsd.files = http://www.w3.org/2001/XMLSchema.xsd xsddoc.xsd.catalogs = urn:docflex-com:xml:defaultcatalog xsddoc.xsd.includeAbstractTypes = true xsddoc.ns.1.prefix = xs xsddoc.ns.1.uri = http://www.w3.org/2001/XMLSchema xsddoc.ns.2.prefix = xhtml xsddoc.ns.2.uri = http://www.w3.org/1999/xhtml xsddoc.pseudo-elements.all = on xsddoc.defaultRootElement = Documents xsddoc.imageProvider.class = %IMAGE_PROVIDER_CLASS% xsddoc.imageProvider.xmlspy.version = %XMLSPY_VERSION%

And here is the meaning of each line:

Line Explanation

1 The XML Type's full name

2 A short description of the XML Type

3 This setting is crucial for the whole XML Type definition! It specifies one or several XML schema files that will provide the datatype information about all data-source XML files possible to process by any template set based on this XML Type.
In this case, it is http://www.w3.org/2001/XMLSchema.xsd (i.e. “XML schema for XML Schemas”) and the possible data-source XML files are any XML schema (XSD) files themselves.
For further details, please see: Defining XML Type | Assigning XML Schemas | xsd.files

4 The URI of an XML catalog that redirects the locations of the XSD files (specified in line 3 as well as any other XML schemas referenced from them) to some other locations, which may be easier to access.
The specified URI ('urn:docflex-com:xml:defaultcatalog') denotes the Default XML Catalog, which redirects the Internet locations of all necessary files to their local copies held in DocFlex/XML resources.

5 Indicates that all global types (i.e. xs:simpleType and xs:complexType) defined in the XML schemas (line 3) should be exposed as abstract element types.
In particular, this allows programing in templates the searching and iterating of elements not only by their names, which can be directly found in the XML files, but also by the element types, which are associated with the elements according to the XML schemas.
For more details about this setting, please see: Defining XML Type | Assigning XML Schemas | xsd.includeAbstractTypes

6-9 These lines specify all namespace prefixes used in XSDDoc templates.
Templates, like XML documents they process, need to deal with namespace URIs, which are typically long character strings. Therefore, some shortcuts are needed to reference to particular namespaces.
For more details, please see: Defining XML Type | Assigning XML Schemas | Declaring Namespaces

10 This setting says that, in addition to normal elements and attributes, all other nodes of an XML document (i.e. DOM) should be exposed as special elements (called pseudo-elements).
This is needed to be able to process with templates the entire content of the XML file, for instance, to fully reproduce it in the generated documentation along with the special formatting and hyperlinks (see schema-overview.tpl and nodeSource.tpl templates).
For more details, please see: Defining XML Type | Pseudo-elements

11 Indicates that all the processing should start from the #DOCUMENTS pseudo-element, which is created by the template interpreter to represent the list of all data-source XML files specified on the generator command-line for processing.
That virtual element will be passed to any main template (specified on the command-line with -template option), as the template's root element, from which the processing of the template starts. This allows XSDDoc to document any number of XML schemas at once.
For more information, please see: Defining XML Type | Pseudo-elements | #DOCUMENTS

12 Specify an Element Image Provider class.
Here, “elements” mean not XML schema element components, but elements of the XML document that describes the schema -- that it the XSD file. The “images” are diagrams that depict content models of XML schema components defined by some of those elements (such as <xs:element>, <xs:complexType> and <xs:group>).
The Element Image Provider's job is to generate those diagrams and allows inserting them in the output. In practice, it is a bridge to some other software that generates those diagrams, which means it is an entry point of some of the integrations.
Currently, only one integration supports this: the integration with XMLSpy. But in the near future more similar integrations are planned. That's why the image provider class is specified not directly, but via 'IMAGE_PROVIDER_CLASS' macro. That allows selecting the particular integration on the command line (of both Generator and Template Designer).
For further information, please see: Defining XML Type | Element Image Provider

13 Specify a parameter for the XMLSpy Integration: the version number of the XMLSpy being used. It cannot be obtained via XMLSpy API, yet it is needed in the XSDDoc templates for the integration support. The XMLSpy version number is provided via 'XMLSPY_VERSION' macro, which can be specified on the command line.
See also: XSDDoc | Parameters | Integrations | XMLSpy | XMLSpy Version

The following screenshot shows a part of the tree representation of the element types and their attributes constructed by this XML Type definition (click on the picture to see a more expanded tree view):

The term “DSM Type” (Data Source Model Type) visible on the screenshot is a generalization of the notion of XML Type extended to the whole DocFlex Technology, which is able to process in a similar way not only XML-files, but any other data-sources provided via some Java APIs. For example, see DocFlex/Javadoc.

3. Main Templates

FramedDoc.tpl

FramedDoc.tpl is a main template designed to generate multi-file (Javadoc-like) framed HTML documentation by any number of XML schema files.

Here is how this template looks when open in the Template Designer (click to enlarge):

On the following screenshot you can see an example of the documentation generated with FramedDoc.tpl (directly from the file: http://www.w3.org/2001/XMLSchema.xsd). Click to view the real HTML:

The FramedDoc.tpl template is interpreted as follows:

First, the “Template Init Expression” specified in the template properties is processed:
This, in turn, invokes the execution of “Init” stock-section (click on the screenshot to enlarge):

This stock-section does not generate any output. Rather, it calls from itself two subtemplates for special purposes:
1. init.tpl creates element maps, which are essentially hash-maps. Element maps allow resolving very complicated queries. They are used in almost all templates of XSDDoc template set (including even init.tpl itself) and are critical for their working.
2. xmlspy.tpl, which is a part of the XMLSpy Integration. This template is called only when the XMLSpy Integration is installed and enabled. See also:
  - “Integrations | XMLSpy” parameter
  - DocFlex/XML | Integations | XMLSpy | How Integration Works
Further, the template's root section block is processed (which is the content of the 'FramedDoc.tpl' tab):

It does the following:
1. overview-summary.tpl template is called to generate Overview Summary page for the whole documentation.
2. all-components-summary.tpl template is called to generate All Component Summary page.
3. All namespaces targeted by the XML schemas to be documented are itereated.
  For each namespace:
  1. namespace-overview.tpl template generates Namespace Overview page.
  2. namespace-frame.tpl template generates Namespace Components page.
  3. For all global components and local element components (to be documented separately) that belong to the namespace the following templates are called (depending on the component type):
    to generate the corresponding Component Documentation files.
4. All XML schemas (to be documented) are itereated.
  For each schema:
  1. schema-overview.tpl template generates the Schema Overview page.
  2. schema-frame.tpl template generates Schema Components page.
5. all-components-frame.tpl template is called to generate All Components page.
6. overview-frame.tpl template is called to generate the page shown in the Overview Frame.
7. xmlns-bindings.tpl template is called to generate the XML Namespace Bindings page.
At this point, all document files have been generated. What is left is the HTML frameset file (normally named 'index.html'). That file starts the whole documentation to display particular HTML documents in three frame windows:

For further details about the usage of each frame, see: Documentation Organization | Framed HTML Documentation | Frameset Structure.
The frameset file is generated according to the definition specified in the “Output File | Frameset Structure” tab of the FramedDoc.tpl properties dialog:

The expression specified in the “Source Expression” field (on the right panel) should return the pathname (or URL) of a document to be initially loaded in the given frame.
However, the initial content of the detailFrame may be overridden dynamically by the Javascript, which is inserted in index.html according the “HTML Head Expression”:

This particular Javascript obtains a URL parameter (specified after '?' in the initial URL) passed to index.html. If the parameter exists, the detailFrame will be reloaded according to the new URL found in the parameter. That allows you to construct URLs like this one:
http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/index.html?schemas/XMLSchema_xsd/elements/element.html
which will open the frameset documentation directly on a specified page.
As soon as everything has been generated, the “Template Finish Expression” is processed:

which invokes the execution of “Finish” stock-section (click on the screenshot to enlarge):

Currently, all it does is removing the temporary files produced by XMLSpy (when XMLSpy Integration is enabled).

PlainDoc.tpl

PlainDoc.tpl is a main template designed specifically to generate single file documentation in all supported output formats (which currently include HTML, RTF and TXT).

Here is how this template looks when open in the Template Designer (click to see the full screenshot):

The RTF output it generates is the most important. It delivers an unmatched quality printable RTF documentation. Here are a few pages of such a documentation generated with PlainDoc.tpl (click to enlarge):

...

Calls:

about.tpl, all-components-summary.tpl, attribute.tpl, attributeGroup.tpl, complexType.tpl, element.tpl, group.tpl, init.tpl, localElementExt.tpl, namespace-overview.tpl, overview-summary.tpl, schema-overview.tpl, simpleType.tpl, xmlns-bindings.tpl, xmlspy.tpl

4. Subtemplates

Subtemplates by directory:

[lib]

init.tpl,
about.tpl, overview-frame.tpl,
overview-summary.tpl

[lib/ann]

annotation.tpl, firstSentence.tpl

[lib/attribute]

attribute.tpl,
attributeProfile.tpl,
attributeProfile2.tpl, attributes.tpl,
attributeSummary.tpl

[lib/component]

componentName.tpl,
all-components-frame.tpl,
all-components-summary.tpl,
contentType.tpl,
diagram.tpl,
xmlRep.tpl, complexContentModel.tpl,
simpleContentRep.tpl,
simpleContentDerivation.tpl,
wildcard.tpl,
facet.tpl

[lib/element]

element.tpl,
elementProfile.tpl,
elementProfile2.tpl,
elementBlockAttrInfo.tpl,
elementFinalAttrInfo.tpl, substitutionGroupInfo.tpl,
contentElementList.tpl,
contentElements.tpl,
elementSummary.tpl,
localElementExt.tpl

[lib/groups]

group.tpl,
groupProfile.tpl,
groupProfile2.tpl,
groupSummary.tpl, attributeGroup.tpl,
attributeGroupProfile.tpl,
attributeGroupProfile2.tpl,
attributeGroupSummary.tpl

[lib/images]

[lib/integrations]
xmlspy.tpl

[lib/namespace]

namespace-frame.tpl,
namespace-overview.tpl, namespaceProfile.tpl

[lib/schema]

schema-frame.tpl,
schema-overview.tpl, schemaProfile.tpl

[lib/type]

complexType.tpl,
simpleType.tpl,
typeProfile.tpl,
typeProfile2.tpl,
typeBlockAttrInfo.tpl,
typeFinalAttrInfo.tpl, typeRelatedCompLists.tpl,
typeUsage.tpl,
typeDerivationTree.tpl,
typeDerivationSummary.tpl,
complexTypeSummary.tpl,
simpleTypeSummary.tpl

[lib/xml]

nodeSource.tpl,
sourceNote.tpl, xmlns-bindings.tpl

5. Template Parameters

[this section will be written soon]

Currently see: DocFlex/XML | XSDDoc | Templates | Parameters