Products         Services         Customers         News         Downloads         Licensing         Shop    

 DocFlex Technology

About
Key Features
Data Processing
Formatting
Templates / Template Designer
Documentation

 DocFlex/XML

About
Documentation
Samples
XSDDoc
Integrations
Tutorials

 DocFlex/Javadoc

About
Documentation
Templates
Examples
Tutorials

 DocFlex/Together

About
Examples
Basic Templates
Documentation
Tutorials

 Try

Downloads
Registration
Trial License

 Buy

Licensing/Pricing
Shop

 Company

News
Products
Services
Customers
About Us
Imprint
Legal
Contact
Links
 

About DocFlex/XML

  1. Overview
  2. Editions
  3. License Bundles
  4. Future Development

1.  Overview

DocFlex/XML is the most advanced application of DocFlex Technology (developed on top of the experience accumulated from the previous two: DocFlex/Javadoc and DocFlex/Together).

This tool allows you to program the automatic generation of professional quality reports and documentation by the data obtained from any kind of XML files. The output documents can be generated in RTF and HTML formats. The HTML can be both single-file and multi-framed documentation. The TXT (plain text) output is supported as well, which enables you to use this tool also for various XML file transformations.

Such a generation is programmed using templates, which function a lot the same as the full-blown scripting-language programs (such as XSLT scripts, for instance). However, the advantage of the template approach offered by the DocFlex Technology is that it requires very few coding of anything manually and allows designing your templates in WYSIWYG form in the terms of things you would expect to see in your output documents rather than on the level of abstract language operators. (For more details, please see About DocFlex Technology | What are Templates?)

The templates are visually designed basing on the information obtained from DTD or XSD (W3C XML Schema) files mostly by using mouse and specifying properties in Template Designer dialogs. The data type information (i.e. XML elements and attributes) appears in various treeviews which are used to program the data processing in the templates. (See Creating a Sample Template flash tutorial.)

The formatting of the generated documents is programmed by specifying formatting properties of template components (some of which can be changed simply by dragging mouse in the designer pane). Many of such properties are graphically visualized by the Template Designer.

The output generator can be both launched from the command line and invoked directly from the Template Designer's main menu which allows you to immediately see the result produced by your templates yet during designing them (no compilation or running any stand-alone interpreter are required).

Key Features

  • Template-driven architecture
    • Actual documentation generators are created in the form of special templates, which are designed visually using a high quality graphic Template Designer, and then interpreted by a special template interpretor / output generator.
    • All formatting is specified in templates in some universal way independent of a particular destination output format using properties of template components. During the generation, it is rendered with the suitable features available in the selected output format.
    • The elaborated support of template parameters (including multivalued list parameters). The parameters are defined and accessed within templates to adjust dynamic properties of template components. Most of options previously used to control an ordinary documentation generator, now simply become template parameters!
    • The possibility to call templates from one another. This feature (along with the template parameters) allows re-using the same templates for different tasks as well as organizing template libraries.
    • Complex documentation generators are typically made of a number of templates and called template applications. (As an example, see “XSDDoc” template set, which implements a high quality XML schema documentation generator.)
  • XML file data source model
    • Generation of reports/documentation by the data obtained from any number of XML files (possibly with different structure).
    • The input XML files can be both specified initially as the generator arguments and also loaded dynamically by the templates according to the data being processed.
    • All open XML files are represented together in the form of a single tree structure (similar to XML DOM). That virtual representation, called “XML DSM” (or XML Data Source Model), also consists of DSM elements and DSM attributes. Some of them mirror the real elements and attributes found in the open XML files. Others, called pseudo-elements, represent all kinds of other (non-element/attribute) XML DOM nodes (such as TEXT-nodes) as well as individual XML files as a whole.
    • The XML DSM is associated with a certain XML Type, which provides the data type information describing any possible input XML files processed by the given template application. That information is obtained from DTD or XSD (W3C XML Schema) files, which define the XML Type. The designing and processing of all templates of that application is based on it.
    • Full support for XML namespaces.
    • Support of OASIS XML Catalogs v1.1. This includes both a possibility to use XML catalogs when processing input XML files (see -xmlcatalog generator option) and in definitions of XML Types based on multiple XML schemas (see xsd.catalogs config property).
  • Data processing
    • Dynamic resolving of the exact types of all XML elements found in open XML files. It means that given an input XML file fully complies with one of the DTD/XSD used to define the XML Type (on which the templates are based), for each XML element contained in it, a corresponding closest Element Type (linked to a DTD element declaration or XSD element component) will be found and associated with it. This allows filtering XML elements according to their types as well as knowing immediately the data types of the element values and attributes so as to process them accordingly.
    • Sophisticated capabilities for data querying and sorting based on a conceptual analogue of XPath (called DocFlex Location Paths) with some advanced features not found in XPath at all.
    • A possibility to filter and query XML elements by Element Types, which include not only those directly produced from the element declarations found in DTD files or element components (including local ones) found in XSD files, but also abstract Element Types which, in the case of XSD, represent global complex and simple types (from which some XSD element components are derived).
    • The ability to traverse XML documents with a network structure using IDREF/IDREFS attributes of XML elements.
    • With the use of element maps (which are specially adapted hash-maps), the same is possible when XML elements reference each other by qualified names specified in QName attributes, which is typically the case (for instance in XSD or WSDL files).
  • Creating hyperlinks
    • Generation of an extensive network of hyperlinks interconnecting the whole documentation.
    • The hyperlinks can be generated in all output formats that support them (this currently includes HTML and RTF).
    • The universal way of defining documentation cross-links based on the link/target keys specified in templates.
    • In RTF, the cross-links can be generated in the form of page number references, which effectively makes them usable even in the printed documentation.
    • In HTML, the possibility of loading several frame windows from a single hyperlink at once.
  • Universal support of various formatting techniques
    • text formatting: fonts, colors, borders
    • paragraph formatting: margins, pagination control, borders, colors
    • border formatting: styles (solid, double, dashed, dotted), thickness, colors
    • tables: arbitrary cell layouts, borders, nested tables
    • lists: bulleted, numbered, delimited
    • document fields (RTF): page number, number of pages, TOC, etc.
    • page formatting: size, orientation, margins, headers/footers
    • formatting styles
    • processing of XHTML markup: The XHTML tags can be recognized at specific locations of XML documents (for instance, within <xs:documentation> elements of XSD files). This must be programmed entirely within a template, which converts all XHTML tags to normal HTML tags (e.g. by removing 'xhtml' namespace prefix from the tag names). Further, everything will be processed by the generator itself (see below). As an example, see also XSDDoc | Documentation Features | Annotations | XHTML formatting.
    • rendering of embedded HTML, which means interpreting in non-HTML output formats (such as RTF) the HTML tags embedded in text data (e.g. documentation comments). Almost all HTML tags practically usable in documentation comments are supported. See Formatting Features | Rendering of embedded HTML for the list of all supported HTML tags.
  • Inserting images
    • statically specified in templates
    • dynamically, obtained directly from XML documents (base64- or hex-encoded) or from arbitrary files, URLs or Java resources
    • dynamically, obtained by <xhtml:img> tags found within special annotation elements (e.g. see XSDDoc | FAQ | How to insert images?)
    • supported image formats: GIF, PNG, JPG, WMF, EMF, BMP
  • Output formats
    • HTML (both framed multi-file and single-file output)
    • RTF (version 1.6 - supported since Word 2000)
    • TXT (plain text)
  • Generator GUI
    • Besides command line options, the template interpretor/output generator supports an alternative user-friendly way to control the template-based documentation generators interactively -- the high quality Generator GUI.
    • The generator GUI starts with the Generator Dialog, where you can specify all general settings (such as the main template, the input XML files, the output format and the output directory), start the generation, track its progress and stop at any moment you need.
    • The grid-tree-based Parameter Inspector invoked from the Generator Dialog for a selected template allows you to view the descriptions of all template parameters controlling the template application (template-driven documentation generator) and set their values according to the parameter data types.
    • The generator options specific for the selected output format can be set in the corresponding Format Option Inspector (also invoked from the Generator Dialog).
    • Once the generation is finished (or cancelled), you can start it again with different settings or a new main template without restarting the whole generator.
  • Integrations
See also DocFlex Technology | Key Features.

Technical Requirements

DocFlex/XML requires Java™ Version 6.x, 5.x or 1.4.x installed on your system. (Java 6 may be preferable as it works substantially faster.)

Since DocFlex/XML is a pure Java application (both the Template Designer and Generator GUI are based entirely on Swing), it is supposed to work on any operating system where Java2 Runtime Environment can be installed.

Specifically, the DocFlex/XML software available for downloads includes both MS Windows BAT files and Linux shell script files to run DocFlex/XML immediately on those operating systems. We have been also reported that DocFlex was successfully working under Mac OS X.

Additionally, a sample Ant buildfile and Maven 2 Plugin are provided that will allow you to use DocFlex/XML with both Apache Ant and Maven 2. For more details, please see DocFlex/XML | Integrations.

To parse XML files, DTDs and XML Schemas, DocFlex/XML uses Apache Xerces2 Java Parser version 2.9.1, whose binaries are included in the DocFlex/XML archives. In case of any questions concerning that library, please refer to the Apache Xerces home page: http://xerces.apache.org.

Note:   Heavy template applications (like XSDDoc) may require considerable computational resources. To run them, you may need a powerful enough computer (e.g. with Intel Pentium 4 or AMD Athlon processor) and at least 512 MB RAM memory.

2.  Editions

Currently, DocFlex/XML comes in two editions:
  1. DocFlex/XML SDK - the System Development Kit to design and run template applications
  2. DocFlex/XML RE - the free Runtime Environment to run template applications

DocFlex/XML SDK

This edition represents a System Development Kit to design and run DocFlex/XML template applications. This includes:
  • The graphic Template Designer, which allows you to visually design your own sophisticated documentation or report generators (by any data stored in XML files) implemented in the form of template applications as well as to modify any existing ones.
  • The template interpreter / output generator, using which you can execute any template application and generated the high quality output documentation in framed multi-file HTML, single-file HTML and RTF output formats (as well as plain text files, which you can use to transform your XML data into other representations).
Additionally, DocFlex/XML SDK includes some sample templates and is bundled with two real template applications:
  1. XMLDoc (“XML File Documentor”) template application that will allow you to compile any number of generic XML files into a nice looking web-ready HTML or printable RTF documentation with the optional inclusion of the namespace binding report (that shows which namespace prefixes are bound to which namespace URIs and where).
  2. XSDDoc (“XML Schema Documentation Generator”) template application, which implements a professional quality W3C XML Schema Documentation Generator able to produce both multi-framed Javadoc-like HTML and printable RTF documentation.

    Note:   This is a commercial template application that requires separate licensing. For more information, please see Licensing of Templates | Commercial Template Applications and Multiple Licenses.

Since the version 1.8.0, DocFlex/XML SDK also includes XMLSpy Integration, which allows users to automatically insert graphic diagrams produced by Altova XMLSpy® into the output generated with DocFlex/XML templates (with full support of diagram hyperlinks). Although, all Java classes implementing XMLSpy Integration are included in the same docflex-xml.jar, the integration itself is not considered a part of the core functionality and requires separate licensing (see also Multiple Licenses).

The core functionality covered by a license for “DocFlex/XML SDK” includes only the Template Designer and the template interpreter / output generator. That functionality may work in three modes: limited, full and trial (which depend on your license).

The differences between those modes are shown in the following table:

Feature / Functionality

Limited Mode

Full Mode

Trial Mode

Covering license(s) Limited Free License (activated by default) Commercial or Academic License Trail License
Template Designer demo only
Possibility to create/modify templates
Execution of any custom templates (with DocFlex/XML SDK) unlimited (however, with trial markers in output)
Possibility to execute your created/modified custom templates with DocFlex/XML RE only those created or modified the last time under a Commercial License
XMLDoc (execution, features)
XSDDoc (execution, features) Limited processing (with some features disabled) is always possible. To unlock all features, a Commercial, Academic or Trail License for XSDDoc template application is required.
Any number of input XML files
Support of OASIS XML Catalogs (for input XML files)
Generator GUI
HTML generation (framed multi-file, single-file)
RTF generation
TXT generation (plain text)
Possible usage of generated documentation any usage, however modifying of HTML files is prohibited unlimited (under Academic License, only for education purposes) for evaluation only (trial markers will be inserted)
Integration with Apache Ant and Maven
Integration with Altova XMLSpy® Any processing requires a separate license for DocFlex/XML XMLSpy Integration

DocFlex/XML RE

DocFlex/XML RE is introduced since the version 1.7.2 to replace the previous reduced edition called “DocFlex/XML (Kit)”. In addition to the renaming, it is made freeware. However, this concerns only the template interpreter / output generator itself, not the commercial template applications bundled with it.

This is a reduced freeware edition that can be used as a Runtime Environment to run DocFlex/XML templates.

DocFlex/XML RE includes the template interpreter / output generator, which by itself will work without limitations. That means, it will generate any output in all formats with all features supported. However, you can use it to interpret (execute) only two kinds of templates:

  1. The templates developed by Filigris Works. Some of them, called commercial template applications, require separate licensing.
  2. Custom templates, however, only those created or modified the last time with DocFlex/XML SDK working under a Commercial License.
The Template Designer is not included in DocFlex/XML RE and you won't be able to create or modify any templates using it.

DocFlex/XML RE is bundled with two template applications:

  1. XMLDoc (“XML File Documentor”), which allows you to convert any your generic XML files (that is without recognizing and documenting of any specific XML-based vocabulary) into a framed or single-file HTML or printable RTF documentation with the optional inclusion of the namespace binding report (that shows which namespace prefixes are bound to which namespace URIs and where). You can use it for free!
  2. XSDDoc (“XML Schema Documentation Generator”) template application, which implements a professional quality W3C XML Schema Documentation Generator able to produce both multi-framed Javadoc-like HTML and printable RTF documentation.

    Note:   This is a commercial template application that requires separate licensing. For more information, please see Licensing of Templates | Commercial Template Applications.

Since the version 1.8.0, DocFlex/XML RE also includes XMLSpy Integration, which allows users to automatically insert graphic diagrams produced by Altova XMLSpy® into the output generated with DocFlex/XML templates (with full support of diagram hyperlinks). Although, all Java classes implementing XMLSpy Integration are included in the same docflex-xml-re.jar, the integration itself is not considered a part of the core functionality and requires separate licensing (see also Multiple Licenses).

DocFlex/XML RE is available for free downloads and you can use it immediately without any special licenses. However, the free license covers only the core functionality, which is basically the template interpreter / output generator. To use special features (like some integrations and commercial template applications) the appropriate licenses covering them will be needed.

The following table lists all features and functionality included/supported in DocFlex/XML RE and how you can use them.

Feature / Functionality

Availability

Possibility to execute your custom templates Only those created or modified the last time under a Commercial License for DocFlex/XML SDK. If your custom templates are derived from a commercial template application, the license for it is required as well.
XMLDoc (execution, features)
XSDDoc (execution, features) Limited processing (with some features disabled) is always possible. To unlock all features, a Commercial, Academic or Trail License for XSDDoc template application is required.
Any number of input XML files
Support of OASIS XML Catalogs (for input XML files)
Generator GUI
HTML generation (framed multi-file, single-file)
RTF generation
TXT generation (plain text)
Possible usage of generated documentation Depends on other licenses you use (e.g. for some integrations or commercial template applications). See also Multiple Licenses.
Integration with Apache Ant and Maven
Integration with Altova XMLSpy® Included. However, any usage requires a separate license for DocFlex/XML XMLSpy Integration

3.  License Bundles

DocFlex/XML XSDDoc & XMLSpy Integration

This license pack will allow you both to generate fully featured XML schema documentation and automatically insert in it the content model diagrams generated by Altova XMLSpy®. In effect, that will let you use the unified DocFlex/XML XSDDoc+XMLSpy XML schema documentation generator. Two licenses cover this:

DocFlex/XSD II

This license pack will let you not only generate fully featured XML schema documentation with XMLSpy diagrams included, but also redesign that documentation so much you need (as well as create/modify any other documentation generators based on DocFlex/XML templates). It includes three licenses:

4.  Future Development

General functionality

The following features are to be implemented gradually during 2009 (and later):
  • Template Language / Output Generators

    A new template component will be added: Include Text Control. This will make possible to include dynamically into the generated documentation the content of external plain-text or HTML files specified with local pathnames or URLs.

  • RTF Generator

    Most of the pagination settings (e.g. paper size, orientation, etc.), which currently can be assigned only in the templates, will be made possible to specify directly in the RTF Option Inspector (or on the command line using the -O option).

  • Internationalization

    A possibility will be supported to specify all static text labels that appear in the generated documentation not only directly in the templates (as it is now), but also by references in a separate property file (which will be supplied together with the templates).

    This will streamline the translation of all text labels into any non-English language and make it easier to migrate to a new version of the given template set. All our commercial template applications (e.g. XSDDoc and future WSDLDoc) will be made to support it.

XSDDoc templates (XML Schema Documentation Generator)

Please, see: DocFlex/XML | XSDDoc | Future Development

WSDLDoc templates (WSDL Documentation Generator)

We are working on such a documentation generator now. It will be implemented as the “WSDLDoc” template set, the same way as the current XSDDoc.

This will be the second Commercial Template Application of DocFlex/XML.

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