FlexDoc/XML - XSDDoc - Templates

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 XML Type Configuration File, a special plain text file found in the XSDDoc template set directory:
{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;xmltype/xhtml.xsd;xmltype/CustomElements.xsd
xsddoc.xsd.catalogs = urn:flexdoc-xyz: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.name = %IMAGE_PROVIDER%
xsddoc.imageProvider.classPath = %IMAGE_PROVIDER_CLASSPATH%
And here is the meaning of each line:

Line Explanation
1 The XML Type full name
2 A short description of the XML Type
3 This setting is most important for the whole XML Type definition. It specifies one or several XML schema files that provide the datatype information about all data-source XML files possible to process by any template set based on that XML Type.

In the case of XSDDoc, these are:

  • http://www.w3.org/2001/XMLSchema.xsd

    It is the URL of the XML schema for XML Schemas, its default location. However, it is redirected using the Default XML Catalog (see line 4) to the file provided in the FlexDoc/XML resources:

    {flexdoc-xml}/lib/resources/www_w3_org/2001/XMLSchema.xsd
  • xmltype/xhtml.xsd

    The relative path to a little XML schema provided along with the XSDDoc templates to describe some basic structure of XHTML files. XSDDoc processes XHTML files, when you need to provide some large HTML-formatted general description to be placed in the documentation overview. For more details, please see the parameter: Literal Input | General Description | File

  • xmltype/CustomElements.xsd

    Another support XML schema that defines custom elements used in XSDDoc templates.

See Also: 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:flexdoc-xyz:xml:defaultcatalog
denotes the Default XML Catalog, which redirects the Internet locations of all necessary files to their local copies held in FlexDoc/XML resources: {flexdoc-xml}/lib/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 you to program in templates the searching and iterating elements not only by their XML names (directly found in XML files), but also by the element types associated with the elements according to the XML schemas.

See Also: Defining XML Type | Assigning XML Schemas | xsd.includeAbstractTypes

6-9 These lines specify all namespace prefixes used in XSDDoc templates.

Templates, like the XML files/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.

See Also: 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).

That is needed to be able to program in templates the processing of entire XML file content, for instance, to fully reproduce it in the generated documentation together with the special formatting and hyperlinks.

See Also: Defining XML Type | Pseudo-elements

11 Indicates that any 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, as the template's root element, from which the processing of the template starts. That allows XSDDoc to process/document any number of XML schemas at once.

See Also: Defining XML Type | Pseudo-elements | #DOCUMENTS
12 Specify the name of the Element Image Provider.
Here “elements” mean not XML schema element components, but rather elements of the XML document that describes the schema (that is the XSD file), and “images” are diagrams, which depict content models of XML schema components defined by some of those elements (such as <xs:element>, <xs:complexType> and <xs:group>).
«Element Image Provider» is actually a more technical name for diagramming plugin, whose job is to generate those diagrams. FlexDoc/XML currently includes a single diagramming plugin:
FlexDoc/XML DiagramKit
Since diagramming plugin is interchangeable, its name is specified not directly, but via 'IMAGE_PROVIDER' macro. That allows you to select a particular diagramming plugin externally on the Java command line of both Generator and Template Designer.

See Also:

13 Specify the file path, where any additional Java classes necessary for running the Element Image Provider can be found.

This setting is particularly important when FlexDoc/XML runs in non-modular mode (e.g. from Maven).

This 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 FlexDoc.XYZ, which is able to process in similar way not only XML-files, but any other data-sources provided via some Java APIs. For example, see FlexDoc/Javadoc.