 About DocFlex/XML
- Overview
- Editions
- Products (Licensed Entities)
- Commercial Licenses
- 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 interpreter / 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 XML Catalogs,
which includes both a possibility to use XML catalogs during processing of 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 interpreter/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 7, 6.x, 5.x or 1.4.x
installed on your system.
(Java 7 may be preferable as it is the fastest!)
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 Plugin are provided that will allow you
to use DocFlex/XML with both Apache Ant and Maven.
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 software comes in two editions:
-
DocFlex/XML (Full Edition) - includes all features available in this product line
-
DocFlex/XML RE - provides the Runtime Environment to run template applications
Please note that DocFlex/XML software is not licensed according to the editions.
Rather, it is broken into a number logical products,
which are licensed separately according to their major functionality.
DocFlex/XML (Full Edition)
The main focus of this edition is to provide a System Development Kit (SDK)
to design and modify DocFlex/XML templates.
However, it can be equally used to run any existing template applications.
It is the most complete edition of DocFlex/XML software,
which includes all features available in this product line:
DocFlex/XML RE
This is a reduced edition that can be used as a Runtime Environment to execute
DocFlex/XML templates.
It doesn't include the
Template Designer
and, therefore, provides no possibility to create/modify templates.
Other features are essentially the same as in the full edition:
3. Products (Licensed Entities)
Since DocFlex/XML is a very complex sophisticated software
(which took many years to develop), a single license covering all features cannot be cheap
(let alone free). Moreover, far not everyone even needs everything!
So, we break the whole DocFlex/XML into a number of logical products (or licensed entities)
according to the major features implemented.
Some of those products are free, others require separate licensing.
Below is the list of such products along with the details of how they are licensed.
DocFlex/XML SDK
This product represents all DocFlex/XML functionality
needed to create, modify and run template applications – that is a System Development Kit (SDK). It includes:
-
Template Designer,
which provides a high-quality GUI to design templates.
This is the only way to create/modify templates.
In effect, the Template Designer visualizes the template language and gives you access
to the most of DocFlex Technology.
-
DocFlex/XML Generator,
which provides the Runtime Environment to execute templates and generate output.
|
Later, more features may be added to the "SDK" category, e.g. some tools for debugging and
automatic documenting of templates.
|
The SDK functionality is available only in DocFlex/XML (Full Edition)
and covered by a single “DocFlex/XML SDK” license.
Depending on that license, the SDK may work in one of three modes:
The differences between those modes are shown in the following table:
DocFlex/XML Generator
This product represents the Runtime Environment (RE) to execute
template applications, which includes:
-
Template Interpreter
-
Output generators in HTML, RTF and TXT formats
-
Generator GUI
-
The support of XML Catalogs
for input XML files
That functionality (called simply
“generator”)
is available in both editions of DocFlex/XML.
In DocFlex/XML (Full Edition), the generator is part of
DocFlex/XML SDK and covered by the “DocFlex/XML SDK” license.
In DocFlex/XML RE, the generator is covered by
Free License, which allows the following:
Feature / Functionality |
Availability |
Execution of templates provides by Filigris Works.
Note: This depends also on your license for that particular template application
(see Licensing of Templates).
|
 |
Execution of any custom templates.
Note: If your custom templates are derived from a template set provided by Filigris Works,
their execution will depend also on your license for that template application
(see Licensing of Templates).
|
only those created or modified the last time under a
Commercial License
for DocFlex/XML SDK
|
|
Any number of input XML files
|
|
|
Support of XML Catalogs
for input XML files
|
|
|
Generator GUI
|
|
|
Generation of HTML, RTF, TXT (plain text) output
|
|
|
Any number of output files of any size
|
|
Possible usage of generated documentation.
Note: This depends also on your licenses for other features
used during the generation, e.g. the template set, integrations
(see Multiple Licenses).
|
any usage
|
Template Applications
DocFlex/XML currently provides two
ready-to-use template applications useful for real tasks.
(One of them – XSDDoc – demonstrates what DocFlex/XML
was actually developed for).
All template applications are available in both editions of DocFlex/XML.
However, each of them is a separate product:
App |
Description |
License |
|
|
Allows you to compile any number of generic XML files into a web-ready HTML or printable RTF documentation
with the optional inclusion of a namespace binding report that shows which namespace prefixes are bound
to which namespace URIs and where.
Although, we put this template set into
“ Samples” category, we think it might be
quite useful anyway. For more details, please see:
DocFlex/XML | Sample | XMLDoc
|
free
|
|
|
Implements a very powerful XML Schema Documentation Generator
able to produce both multi-framed Javadoc-like
HTML and printable
RTF documentation.
For more details, please see:
DocFlex/XML | XSDDoc.
Note: This is a commercial template application, which requires separate licensing. See also:
|
|
One more big template application is coming: WSDLDoc
Integrations
Currently, there are three integrations
of DocFlex/XML with other software systems.
All integrations are available in both editions of DocFlex/XML.
However, each of them is considered a separate product:
System |
Integration |
Implementation |
License |
|
|
|
settings in your Ant build file
|
free
|
|
|
|
Maven plugin (Java open source); settings in your Maven project file
|
free
|
|
|
Allows you automatically to insert the graphics diagrams produced by XMLSpy into the
XML schema documentation generated by DocFlex/XML XSDDoc
(with full support of diagram hyperlinks). For more details, please see:
DocFlex/XML | Integrations | XMLSpy.
This integration is a commercial product, which requires separate licensing!
See also:
|
hardcoded in Java (included in docflex-xml.jar);
specifically supported in XSDDoc templates
|
|
More integrations are coming!
4. Commercial Licenses
License For |
Description |
|
|
This license covers a universal System Development Kit and Runtime Environment
for rapid development and execution of template-driven automatic documentation/report
generators by any data obtained from XML files.
In fact, the whole XML schema documentation generator
( DocFlex/XML XSDDoc) has been developed only with this tool!
A commercial license for DocFlex/XML SDK
will give you the ultimate control over the XSDDoc template set:
-
Using the graphic Template Designer
included in DocFlex/XML SDK,
you will be able to customize whatever was impossible to do with only
template parameters.
-
Furthermore, basing on the standard XSDDoc
you could develop your own XML schema documentation generators, which would represent your XML schemas
in some very special way.
For instance, you may want to avoid in your documentation all those technical terms like
"namespaces", "AttributeGroups", "SimpleTypes" and "ComplexTypes" etc. and rather describe
everything defined in your XML schemas using the notions of a business language familiar to your customers.
The XML schemas aside, you can use DocFlex/XML SDK
to develop any other documentation/report generators from any data stored in XML files
(see also DocFlex/XML | Samples).
What's more, as soon as other our commercial template applications arrive (e.g.
WSDLDoc),
you could use your DocFlex/XML SDK license
to customize them as well.
|
|
|
A commercial license for “ DocFlex/XML XSDDoc”
will unlock all fuctionality implemented in
XSDDoc templates.
In particular, you will be able:
-
To use all parameters
(more than 400 now!) that control XSDDoc templates to customize the generated XML schema documentation
within a huge range of possibilities.
-
To use PlainDoc.tpl
main template to generate single file HTML
or RTF documentation.
-
To format your XML schema annotations with
XHTML tags
and reproduce that formatting both in HTML and
RTF output.
-
To inserting images
in your annotations using XHTML
<img> tags (supported both in HTML and RTF output).
-
To modify XSDDoc templates
as much as you need using the
Template Designer
included in DocFlex/XML SDK
(provided that you also have a separate license for that product,
see above).
-
To run any your custom templates derived from XSDDoc.
|
|
|
If you are already a user of
Altova XMLSpy®
(or may acquire it soon), we offer you to purchase an additional license
for the integration of DocFlex/XML with XMLSpy.
This will allow you to automatically insert the graphics diagrams produced by XMLSpy into
the XML schema documentation generated by DocFlex/XML XSDDoc
(with full support of diagram hyperlinks).
Together with the license for “ DocFlex/XML XSDDoc”,
that will give you a fantastic XML Schema Documentation Generator with diagramming capabilities
no other single product is offering now!
|
|
License Bundles
|
|
|
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 commercial licenses cover this:
|
|
|
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 commercial licenses:
|
5. Future Development
|
In fact, it is always difficult to know in advance what will be included in next versions,
because it depends very much on how people use the software and what they actually need.
If you are interested in certain features to be supported, please do not hesitate to let us know by sending an email to:
support@docflex.com.
We are always happy to hear your opinion, no matter whether you are registered DocFlex/XML user or not!
|
General functionality
These features are planned to be implemented sometime:
-
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.
For more details, please see:
DocFlex/XML | WSDLDoc
|
