FlexDoc/XML - XMLDoc

  1. Overview
  2. Examples
  3. Template Summary
  4. XML Type
  5. SingleDoc.tpl
  6. FramedDoc.tpl
  7. Document.tpl
  8. xmlns-bindings.tpl
  9. TOC.tpl
  10. about.tpl

1. Overview

The “XML File Documenter” (or “XMLDoc”) set of templates compiles any number of generic XML files into a nice looking web-ready HTML or printable RTF documentation with the optional inclusion of a namespace binding report.

It may also serve as an example of a very simple and, at the same time, practically useful application of FlexDoc/XML. See templates to learn how it works.

The set includes two main templates (i.e. those to be specified directly in the generator dialog or on the command line with -template option):

  1. SingleDoc.tpl template can be used to generate single file documentation in any output format supported by FlexDoc. See RTF demo and Plain HTML demo.
  2. FramedDoc.tpl template is a variant of the same but designed to generate a framed HTML documentation. See Framed HTML demo.
Besides those main templates, there are few sub-templates, which are called internally from the both main ones. See Template Summary for more details.

2. Examples

The following XML file demo documentation has been generated from three XSL files (XSL is a subset of XML that encodes XSLT scripts) found in Apache Ant software package.

We have chosen those files simply because we use Apache Ant itself (without learning much what those XSLT scripts do).

You can download the whole demo documentation shown on this page by clicking on the file link: xmldoc-demo.zip (26 Kb).

RTF demo

The following pages are from an RTF document generated with SingleDoc.tpl template (click on the screenshot to see the real size page preview):

Plain HTML demo

This is actually the same document as RTF above generated with SingleDoc.tpl template, however, now it is in HTML format (click on the screenshot to see the real HTML):

Framed HTML demo

The following is a framed HTML variant generated with FramedDoc.tpl template (click on the screenshot to see the real HTML):

3. Template Summary

The “XML File Documenter” set of templates is based on a special “xmldoc” XML Type, which is detailed below. The set includes 2 main templates and 4 subtemplates, which are summarized in the following table:

Template Annotation Called From
SingleDoc.tpl generates a single-file documentation from all specified XML files in any supported output format generator
FramedDoc.tpl generates a framed HTML documentation with a separate document for each XML file and table of contents frame generator
Subtemplates
Document.tpl processes a single XML file SingleDoc.tpl, FramedDoc.tpl
xmlns-bindings.tpl generates Namespace Bindings report SingleDoc.tpl, FramedDoc.tpl
TOC.tpl generates summary frame document FramedDoc.tpl
about.tpl prints the about information at the bottom of document SingleDoc.tpl, Document.tpl, xmlns-bindings.tpl

4. XML Type

The XML Type definition used by the “XML File Documenter” templates covers a very general case of XML files. It is not based on any DTD or XSD, but instead enables all kinds of pseudo-elements which represent all possible nodes of an XML document. Here is how that definition looks:
xmldoc.name = Generic XML Files
xmldoc.pseudo-elements.all = true
xmldoc.defaultRootElement = Documents
The following tree represents the DSM Type (Data Source Model Type) constructed by this definition (click on the picture to see the expanded tree):

The last line of the XML Type definition:
xmldoc.defaultRootElement = Documents
says that for any main template based on this type, the generator should open all XML files specified for the processing and pass them to the template as children of an #DOCUMENTS pseudo-element, which will be the template's root element. See <typeId>.defaultRootElement setting for more details.

5. SingleDoc.tpl

This is the first main template included in the “XML File Documenter” template set. This template is able to compile any number of XML files of any possible types into a single document with the table of contents and optional inclusion of Namespace Bindings report (see xmlns-bindings.tpl).

Such documentation can be generated in any supported output format (which may be especially suitable for printing). To specify a necessary destination output format all you need is to select that format in “Output format” combo-box in the generator dialog or using -format option on the generator command line.

See RTF demo and single-file HTML demo documentation generated with this template.

Template organization

This is the screenshot of SingleDoc.tpl template open in Template Designer (click on the picture to see it in natural size):

The template is designed to process all XML files specified for the generator. In according with the “xmldoc” XML Type, the generator will open all those XML files and prepare them as children of an #DOCUMENTS pseudo-element passed to the template as its root element.

The Element Iterator titled “DOC FOR EACH XML FILE” is actually where all XML files are processed by calling Document.tpl subtemplate for each XML file.

Parameter Definitions

The SingleDoc.tpl template accepts a few parameters, which provides some additional data for the generated documentation (such as title) as well as control the template behavior (e.g. sorting of multiple XML files, inclusion of Namespace Bindings report, etc).

The following screenshots show how those parameters are defined:

This is the definition of a single parameter:

And this is how the result Parameter Inspector looks:

6. FramedDoc.tpl

This is the second main template included in the “XML File Documenter” template set. This template is designed to generate a framed HTML documentation with a separate document for each XML file and table of contents frame.

The following demo documentation was generated with FramedDoc.tpl template. This is a framed HTML variant of the same documentation shown in RTF demo (click on the picture to see the real HTML):

Template organization

The FramedDoc.tpl template is a special frameset template. Its main block by itself does not produce any output at all. Instead, it calls other templates which generate separate HTML documents.

The template's main block start with the element iterator section, which iterates by all XML files specified for processing by the generator. The generator opens each XML file and represents it as an #DOCUMENT pseudo-element. Such pseudo-elements are provided as children of another special pseudo-element #DOCUMENTS, which is the one passed to the template as its root element. The iterator contains a call to the Document.tpl template that generates a separate HTML document for each XML file.

The next call template section following the iterator call xmlns-bindings.tpl template which generates the Namespace Bindings report. The last one is a call of TOC.tpl template that generates the table of contents HTML document.

Frameset structure

The only file directly produced by the FramedDoc.tpl template is the HTML frameset document (such as 'index.html') that displays the whole documentation. This frameset HTML is generated by a special frameset structure definition contained in the FramedDoc.tpl template and shown on the following screenshot:

The frameset structure defines frame windows and specifies which HTML document should be initially loaded in each frame. The frame definition shown on the screenshot specifies that the 'detailFrame' frame should be preloaded with the first document produced by the Document.tpl template. That would correspond with the first item in the table of contents produced by TOC.tpl template.

7. Document.tpl

The Document.tpl template is the one that processes a single XML file. It is used only as a subtemplate. That means, this template is not supposed to be specified directly for the generator, rather it is called from within both main templates:
  1. From the SingleDoc.tpl template to document an XML file as part of a single output document
  2. From the FramedDoc.tpl to generate a separate HTML document for each particular XML file
The Document.tpl template works by reproducing the original content of an XML document. In a certain sense, it "understands" the XML document's structure and, then, "retells" it in its own way.

The template consists of the following parts:

Besides this, there is a hypertext target definition specified in the template properties:

This is used to generate a hyperlink to the detail of the particular XML file from the item representing it in the Table of Content (see TOC.tpl template).

The main block

The Document.tpl template receives an XML file to process prepared in the form of #DOCUMENT pseudo-element, which is passed as the template's root element.

Then, the generator starts processing the template's main block shown on the following screenshot (click to see in the full size):

The main block starts from the Area Sections, which generate the title information about the XML file.

Then, the Element Iterator follows which iterates by all direct children of the Document node provided by DOM (specifically, that is the node represented by Java interface org.w3c.dom.Document).

The node associated with the XML file's <!DOCTYPE> statement is processed directly within the iterator's body. All other DOM nodes are processed by “Node” stock-section.

At the very bottom, you can see the Page Footer block. This block contains template components to generate a page footer used in RTF documentation (see RTF demo). That page footer displays the information specific to the given XML document. To make it appear on the pages related to the XML file, the generator produces a separate RTF output section per each call of the Document.tpl template.

“Node” stock-section

Stock-sections are the template parts which behave similar to procedures in ordinary programming languages. Each stock-section can be called from different locations in a template (including from within this stock-section itself).

This particular stock-section processes an XML document's node which may contain other child nodes:

You may notice a place where this stock-section calls itself to process nested nodes – children of the one it received.

“AttrList” stock-section

This stock-section does a very simple work. It prints the list of attributes of an XML element.

The two nested area sections are variants of the same with slightly different text formatting.

8. xmlns-bindings.tpl

This template generates the Namespace Bindings report like the one shown of the following screenshot:

When you are reading certain XML documents, sometimes you may notice that the element tags contained in them are littered with various unknown namespace prefixes. For a big XML document, it may take some efforts to find the location where a particular namespace prefix is defined and to which URI it is bound (especially when that XML document is in the printed form).

The Namespace Bindings report helps to quickly find by a each prefix the namespace URI corresponding to it and the location where that binding is defined.

The xmlns-bindings.tpl template has a very simple structure shown on this screenshot (click to see in normal size):

Basically, the template consists of an Element Iterator that generates a table in which every namespace binding is represented by a row.

Here is how it works.

The template receives as its root element the #DOCUMENTS pseudo-element that represents all XML files. Then, the Element Iterator iterates by the #NAMESPACE pseudo-elements collected according to the following Location Rule (specified in the iterator properties):

* -> child::#DOCUMENT/namespaces^::#NAMESPACE
The left part of the rule is the Location Path which defines the search of the #NAMESPACE elements:
  1. The first step starts from the root #DOCUMENTS element and selects all its children of #DOCUMENT type that represent XML files.
  2. The second step selects all #NAMESPACE pseudo-elements by references obtained from values of namespaces attribute of each #DOCUMENT element. This is specified using link-axis.

9. TOC.tpl

This template is called from FramedDoc.tpl to generate a summary frame document which appears in the left frame (see Framed HTML demo). The template is shown on the following screenshot (click to enlarge):

The template receives #DOCUMENTS root element. The Element Iterator iterates by all XML documents and generates the summary list of XML files.

Each summary item is produced by a data control (shown on the screenshot as rectangle with “xmlName”). This data control prints the name of each particular XML file as well as generates a hyperlink to the XML file's detailed documentation.

The hyperlink is defined in the data control's properties:

When a hyperlink is generated, it is connected to the target using values of keys generated by expressions specified in the hyperlink definition properties (see screenshot). The corresponding target keys are generated using similar expressions defined in the properties of Document.tpl template.

The “detailFrame” is the name of the target frame window where the HTML document referenced by hyperlink is loaded (see frameset structure definition).

10. about.tpl

This template just prints the information about FlexDoc/XML product together with the hyperlinks to this web-site at the bottom of each generated document. You can easily suppress this by disabling the Area Section, as shown on the screenshot:

or replace it with something of your own.