Products         Downloads         Licensing         Shop         Customers         Support    

 DocFlex Technology
Overview
Features
Documentation
 DocFlex/XML
Overview
Features
Documentation
XSDDoc
Features
Organization
Examples
Templates
Subtemplates
Parameters
FAQ
WSDLDoc
Integrations
Bundles
 DocFlex/Javadoc
Overview
Documentation
Basic Templates
JavadocPro
Examples
Tutorials
 DocFlex/Together
Overview
Examples
Basic Templates
Documentation
Tutorials
 Try
Downloads
Registration
Trial License
 Use
Licensing
Shop
Support
 Company
News
Products
Customers
About Us
Imprint
Legal
Contact
Links
 

DocFlex/XML - XSDDoc - Templates

  1. Overview
  2. XML Type
  3. Main Templates
  4. Subtemplates
  5. Template Parameters

1.  Overview

The “XSDDoc” template set includes two main templates, which effectively provide two different documentation generators:
  1. FramedDoc.tpl to generate framed HTML documentation
  2. PlainDoc.tpl to generate single file documentation
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.8.1) consists of 71 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
14
15
16
17
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%
xsddoc.imageProvider.XMLSpy.classPath = %XMLSPY_CLASSPATH%
xsddoc.imageProvider.XMLSpy.libPath = %XMLSPY_LIBPATH%
xsddoc.imageProvider.OxygenXML.command = %OXYGENXML_COMMAND%
xsddoc.imageProvider.OxygenXML.config = %OXYGENXML_CONFIG%
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:

13 XMLSpy Integration parameter: 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 passed via 'XMLSPY_VERSION' macro, which can be specified on the command line.

See also:

14 XMLSpy Integration parameter: The Java classpath to XMLSpy Java API. It is passed via 'XMLSPY_CLASSPATH' macro, which can be specified on the command line.

For more details, please see: DocFlex/XML | Integrations | XMLSpy | Setting Details | XMLSpy API Java Class Path

15 XMLSpy Integration parameter: The pathname of the directory containing a non-Java implementation of XMLSpy API (this is a Windows DLL that provides a bridge between Java and XMLSpy's Windows native code). It is passed via 'XMLSPY_LIBPATH' macro, which can be specified on the command line.

For more details, please see: DocFlex/XML | Integrations | XMLSpy | Setting Details | XMLSpy API Library Path

16 OxygenXML Integration parameter: Specify the OS command to call OxygenXML's own XML schema doc-generator. It is passed via 'OXYGENXML_COMMAND' macro specified on the command line.

For more details, please see: DocFlex/XML | Integrations | Oxygen XML | Setting Details | OS command to run OxygenXML's own DocGen

17 OxygenXML Integration parameter: Specify an alternative pattern file for the settings file passed to OxygenXML's XML schema doc-generator. This may be needed in case when that settings file substantially changes in the future OxygenXML version, so that one used now by the integration (and stored in resources) will not be adequate for this.

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:
  1. First, the “Template Init Expression” specified in the template properties is processed:

  2. 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:
    3. OxygenXML.tpl, which is a part of the OxygenXML Integration. This template is called only when the OxygenXML Integration is installed and enabled. See also:

  3. 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.

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

  5. 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, OxygenXML.tpl

4.  Subtemplates

Subtemplates by directory:

5.  Template Parameters

See: DocFlex/XML | XSDDoc | Templates | Parameters

Copyright© 2003-2014 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.