FlexDoc/XML - XSDDoc - Documentation Structure

  1. Main Blocks
  2. Framed HTML Documentation
  3. Single-File Documentation
  4. Miscellaneous

1. Main Blocks

The documentation generated by the «XSDDoc» template set is built of large independent main blocks of the following types: All those blocks can be organized and linked together in two different ways:
  1. Framed HTML Documentation
  2. Single-File Documentation

Overview Summary

This page/block is generated only once for the entire documentation. It includes: The Overview Summary appears the first in the Detail Frame of framed HTML documentation (when it is started) or on the first page of single-file documentation (RTF).

Related parameters:

Related template: overview.tpl

All Component Summary

This page/block can be generated once. It contains the summary of all XSD components throughout all processed XML schemas.

Related parameters:

Related template: all-components.tpl

Namespace Overview

This page/block can be generated for each documented namespace. It includes:

Related parameters:

Related template: namespace.tpl

Schema Overview

This page/block can be generated for each processed XML schema. It may includes:
Additionally, the complete reproduced XML source of the XML schema (with the values of various attributes hyperlinked to the related pieces of the documentation) can be added at the end of the Schema Overview. The XML source can be generated also in a separate page/file.

The generation of the XML Schema source is controlled by the following parameters:

Related template: schema-source.tpl
Related parameters: Related template: schema.tpl

Component Documentation

This page/block can be generated for each XSD components of the following types: It provides all sorts of details about the given XSD component and its connections with everything else.

Related parameters:

Related templates:
element.tpl, complexType.tpl, simpleType.tpl, group.tpl, attributeGroup.tpl, globalAttribute.tpl

XML Namespace Bindings

This page/block is a special report, which can be generated only once. It lists all
Namespace prefixes are used in the generated documentation as parts of the names of documented XSD components. That allows you to quickly recognize which namespace the component belongs to.

The showing of namespace prefixes in the component names can be disabled, which is controlled by the parameter: Show | Namespace Prefixes

Related parameters: Related template: xmlns-bindings.tpl

2. Framed HTML Documentation

This kind of documentation is generated by the FramedDoc.tpl main template. In that case, the result documentation forms a simply dynamic HTML app. The HTML browser window is divided into three frames as show on the screenshot:

Frame Purpose
Overview Frame Used for primary navigation and contains the items linked to some important pages loaded directly into the Detail Frame as well as the lists of all documented
  • Namespaces
  • XML Schemas
whose items are linked to the corresponding secondary navigation lists targeted to the List Frame.

The exact content of this frame is controlled by the parameter group: Navigation | Overview Frame

Related template: overview-frame.tpl

These are navigation frames, where you can quickly find what you need without disturbing the current view of the detail document.
List Frame Displays one of the secondary navigation lists associated with a particular selection in the Overview Frame.

All items in such lists are linked to corresponding main blocks targeted to the Detail Frame.

The exact content of this frame is controlled by the parameter group: Navigation | List Frame
Detail Frame Used to display the actual information content of the documentation.

Each of the main blocks becomes a separate HTML file (or page) displayed in that frame. Additionally, some general navigation pages/tools are displayed in that frame as well, e.g. Search.

The initial content of the Detail Frame as well as some extra make-up of the detail pages loaded into it (like Navigation Bar) can be customized with the parameter group: Navigation | Detail Frame 		This frame is used to display the actual documentation content

Navigation Lists

These are separate HTML pages displayed in the List Frame on a particular selection in the Overview Frame:

There are following types of such lists:

List Description
All Components The list of all XSD components. It is generated only once and includes:
  • The list heading linked to the All Component Summary page.
  • All global XSD components and local elements defined throughout all documented XML schemas.
Whether this list is actually generated and its exact content is controlled by the parameter group: Navigation | List Frame | All Components

This list is linked from the «All Components» item in the Overview Frame. See the parameter: Navigation | Overview Frame | All Components

Related template: all-components-frame.tpl

Namespace This list is generated for each documented namespace. It includes:
  • The namespace URI in the list heading with the link to the corresponding Namespace Overview page.
  • All XML schemas targeting that namespace.
  • All global XSD components and local elements, which belong to that namespace.
Whether this list is actually generated and its content is controlled by the parameter group: Navigation | List Frame | Namespace

Such lists are linked from the namespace items in the Overview Frame. See the parameter: Navigation | Overview Frame | Namespaces

Related template: namespace-frame.tpl

Schema This list is generated for each documented XML schema. It may include:
  • The XML schema name in the list heading with the link to the corresponding Schema Overview page.
  • All global components defined in that schema
  • All local elements defined in that schema
Whether this list is actually generated and its exact content is controlled by the parameter group: Navigation | List Frame | Schema

Such lists are linked from the schema file items in the Overview Frame. See the parameter: Navigation | Overview Frame | Schemas

Related template: schema-frame.tpl

Detail Header & Navigation Bar

In framed HTML documentation, the detail page may include the header & navigation bar inserted at the top. The navigation bar is added also at the bottom:

The screenshot links lead to the corresponding template parameters that control/specify the respective features.
Related templates: nav-bar.tpl, nav-top.tpl, nav-bottom.tpl

Dynamic Search

XSDDoc supports the dynamic search functionality that works similar to that in modern Javadoc. All identifiers like XSD component names, attributes etc. are indexed.

The dynamic search-box powered by JQuery UI can be embedded into the Navigation Bar at the top and bottom of each detail page as shown on this screenshot (click to view in full size):

The search-box is also available on the special Search Page that shows the search help and index statistics, which lists what exactly is indexed. The Search page hyperlinked from the Navigation Bar and the Overview Frame.
The dynamic search functionality with the Search page is available only in framed HTML documentation.
Whether it is actually generated is controlled by the parameter group: Navigation | Search

Related template: search.tpl

3. Single-File Documentation

This kind of documentation is generated by the SingleDoc.tpl main template.

In that case, all main blocks are packed in a single document, which can be generated in any format supported by FlexDoc/XML (currently HTML and RTF).

The RTF format may be particularly useful for printing or converting it into PDF. The hyperlinks are supplemented with page number references. There are page headers/footers and certain blocks can be started from a new page. That is controlled by the parameter group “Pagination” (available only in SingleDoc.tpl).
The structure of such a single document is sketched out in the box below. The conventions are the following:
Title Page – Generate Details | Title Page = true
Table Of Contents – Generate Details | Table Of Contents = true
Overview Summary – Generate Details | Overview = true
Namespace Summary – Details | Overview | Namespace Summary = true
Schema Summary – Details | Overview | Schema Summary = true
All Component Summary – Generate Details | All Components = true
Namespace Detail 1...∞
Namespace Overview – Generate Details | Namespace = true
Component Details – Generate Details | Components = true
Schema Overview 1...∞ – Generate Details | Schemas = true
XML Source – Details | Schema | XML Source = true
XML Namespace Bindings – Generate Details | XML Namespace Bindings = true

4. Miscellaneous

Names of XML Files

Each source XML document/file (e.g. XSD etc.) loaded for processing is identified further by a certain name. That name is used in the generated documentation to reference that source XML.
In the case of multi-file framed HTML documentation, the XML document names are used also to form the documentation directory structure. All components found in a particular XML document are described inside the folder named after that document.
The XML document name is formed as follows.

Case of File Pathname

If the source XML document was obtained by a local file pathname, the document's name will be just the name of that file (e.g. 'sales.xml'). That is the last name in the pathname's name sequence.

In that case, the settings of this parameter plays no role.

Case of URL

If the source XML document was obtained by a remote URL, the document's name will be the last name in the name sequence of this URL's path part optionally appended with the URL's query part.

For example, for the URL (with the query part highlighted in red):

https://api.translator.com/V2/soap.svc?xsd=xsd0
the name assigned to the corresponding XML document will be this:
soap.svc?xsd=xsd0
For some XML file sources, the URL query part may be the only thing that distinguishes URLs of different XML documents loaded for processing. So, it must be used to identify each XML document as well.

In other cases, the URL query part may contain just some options to the website for how the XML file should be produced, e.g.:

http://DEV/get.resource/wsdl/all?target=Java
which will be the same for all loaded XML files. Such a query part would just pollute all XML document names used in the documentation. So, it must be omitted.
If the URL query part will be included in XML document names is controlled by the parameter: Show | URL Query in File Names

Namespace Prefixes

As you may know, each XML name is not just a string. Rather, it is a vector of two strings:
{ namespace URI, local name }
The «namespace URI» may be a very long string. Its purpose is to uniquely separate some group of names used in a particular XML vocabulary (that is called a namespace) from any other XML names possibly found in the Internet. Because of that the namespace URI cannot be used in XML documents along with each XML name. That would be too cumbersome. So, the namespace is represented by a much shorter string called namespace prefix, which is added before each local name separated with the colon, e.g.: <xs:schema>. At that, the namespace prefix is a local thing defined only in that XML document using a namespace URI/prefix binding.

For example, here is how the binding of the prefix 'xs' to the namespace URI 'http://www.w3.org/2001/XMLSchema' is defined:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> ... </xs:schema>
Any namespace prefixes used in the output documentation originate from the namespace URI/prefix bindings declared in the source XSD files. For a particular XML name, its namespace prefix is generated according to the binding for the given namespace found nearest to the documentation context where that XML name appears.

That is controlled by the parameter:

Show | Namespace Prefixes
If it is selected (true), the corresponding namespace prefix will be added to each XML name. If this parameter is unselected (true), no namespace prefixes will appear in any XML names across the documentation.
Example:

Suppose you generate a single documentation for two XML schemas: schema1 and schema2 together.

The schema1 targets the namespace identified by the URI 'namespace_uri_1', which is bound to the prefix 'myns'. That schema defines a type component MyType. So, in the documentation parts related to the schema1 that type will be referenced as:

myns:MyType
The schema2 targets a different namespace. However, it also uses the 'MyType' defined in schema1, which it imports. To reference that type, the schema2 binds the URI 'namespace_uri_1' to the prefix 'ns1'. So, MyType will look in it as:
ns1:MyType
So that type will appear in the documentation parts related to the schema2.

However, in both cases, the hyperlinks from the type's name will lead to the same location in the documentation with the MyType's details.

See also: FlexDoc/XML | DiagramKit | FAQ | Diagram Settings | How to show/hide namespace prefixes?

How To Unify Prefixes?

The mishmash of local namespace prefixes in the documentation may be not what you need. After all, namespace prefixes in component names can be helpful to quickly identify which namespace a particular component belongs to, especially when several namespaces are used together.

You can achieve that by using a driver schema. That is the schema that references from itself directly or indirectly (via <xs:import>, <xs:include>, <xs:redefine> directives) all other XML schemas you want to document. Then, you can:

  1. Specify in the driver schema (i.e. directly in the <xs:schema> element) the bindings for those prefixes, with which you want to represent particular namespaces accros the entire documentation.
  2. Specify the driver schema as the only input file for the generator.
  3. Make sure that this template parameter is selected: Show | Namespace Prefixes | Unify
«Driver schema» is a logical concept. In fact, it is not used directly by XSDDoc. It just helps to understand what's going on, to simplify it. That's actually more complicated. XSDDoc is able to document together any number of namespaces, both dependent somehow on each other or not. It is even able to document the same namespace multiple times, for instance, different versions of the same XML schema. And that won't lead to any collisions! Everything will be documented separately and correctly. Yet in the same documentation.

It works as follows. When you start XSDDoc, you specify one or several input XSD files. Some of them may reference others. Some may import other schemas (XSD files) not listed on the command line. Initially, XSDDoc loads all directly specified XML schemas and all those referenced from them (imported, included, redefined) recursively. That bunch of all involved XML schemas is what is supposed to be documented. Then, XSDDoc divides that initial bunch into a few independent domains. A domain is defined so that all XML schemas included in it depend on each other (reference one another somehow directly or indirectly). Obviously, at least one of those schemas in the domain must be one specified directly to the generator (on the command line). That schema is assumed to be the domain's main XSD. There may be several candidates for such a main XSD. In that case, the selected will be one that was loaded first.

The main XSD concept is similar to "driver schema". The difference is that there may be any number of main XSDs. For instance, when you document together different versions of the same XML schema (defining the same namespace), all of them will become main XSDs. So here, each main XSD becomes the source of preferred namespace prefixes for all XSD components defined in its domain. The qualified names of all XSD components (prefix:localName) are determined on the initialization (loading/separation) phase. In that phase, XSDDoc creates special hashed element maps. Further, all documentation is generated mostly by those element maps, rather than directly by the XSD source.

There is a special situation however. Some XSD files may be involved simultaneously in different domains. All of them will define some imported namespace. Such shared XSDs are documented only once. Technically, each of them must have multiple main XSDs, whom they subordinate. However, the selected for such a role will be only one loaded first. That main XSD will provide the preferred namespace bindings for that shared schema.