Actual doc/report generators are created in the form of special templates, which are designed using a graphic Template Designer basing on the datatype information obtained from DTD or XSD (W3C XML Schema) files that describe the particular XML-file data source. All formatting is specified in templates independently of any destination output formats. A template set (called "template application") is interpreted by the template interpretor / output generator, which makes the result XML doc/report generator work. The output format is selected only before generation and may be any of the currently supported by the DocFlex core.
For further details, see Documentation | About DocFlex/XML.
| 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. |
To integrate DocFlex/XML RE with Apache Ant,
you need only to add several settings in your Ant build file.
For more details, see
Documentation | Integrations | Apache Ant
and the example {docflex-xml-re}/ant/build.xml file.
The package includes a Java source implementing the Maven 2 Plugin for DocFlex/XML generator (with samples). It will allow you to run any DocFlex/XML template applications from Apache Maven.
For more details, see
maven/index.html,
Documentation | Integrations | Apache Maven.
DocFlex/XML RE also includes the XMLSpy Integration, which allows users to automatically insert graphic diagrams produced by Altova XMLSpy® into the output generated by DocFlex/XML templates (with the full support of diagram hyperlinks).
Although, all Java classes implementing XMLSpy Integration are included in the same
docflex-xml-re.jar (the DocFlex/XML RE Java library),
the integration itself is not considered a part of the core functionality (main components)
and requires separate licensing.
For more details, see
xmlspy/README.html,
Documentation | Integrations | XMLSpy,
Multiple Licenses.
LICENSE.html
|
DocFlex Freeware Edition License |
README.html
|
this file |
doc/
|
documentation |
generator.bat
|
the Windows command file to start DocFlex/XML generator |
linux/
|
Files prepared for Linux Installation: |
linux/generator.sh
|
|
linux/docflex.config
|
|
lib/
|
Runtime Environment: |
lib/docflex-xml-re.jar
|
|
lib/docflex.config
|
|
lib/xml-apis.jar
|
|
config/
|
Configuration files (created and updated dynamically): |
config/generator.config
|
|
templates/
|
bundled template applications |
templates/XMLDoc/
|
The "XML File Documentor" (XMLDoc) template set: |
templates/XMLDoc/PlainDoc.tpl
|
|
templates/XMLDoc/FramedDoc.tpl
|
|
templates/XMLDoc/xmldoc.xmltype
|
|
templates/XSDDoc/
|
The "XML Schema Documentation Generator"
(XSDDoc) template set.
For more details, see:
templates/XSDDoc/README.html
|
demo/HumanEvolution.xsd
|
A demo XML schema that shows in every detail how to use XHTML and insert images
in XML schema annotations.
To see what a documentation it produces, just run this schema with either
XSDDoc/FramedDoc.tpl (for framed HTML) or
XSDDoc/PlainDoc.tpl (for RTF) template.
|
ant/
|
Ant example files: |
ant/build.xml
|
|
ant/make.bat
|
|
ant/make.sh
|
|
maven/
|
Maven plugin for DocFlex/XML.
For more details, see:
maven/index.html
|
xmlspy/
|
Contains files related to
XMLSpy Integration.
For more details, see:
xmlspy/README.html
|
You can freely download Java from Sun Java Technology web-site: http://java.sun.com
To parse XML files, DTDs and XML Schemas, DocFlex/XML uses Apache Xerces2 Java Parser version 2.9.1. In the case of any questions concerning this library, please refer to the Apache Xerces home page: http://xerces.apache.org.
To generate XML schema documentation (for big and middle sized XML schemas) using XSDDoc template set, you may need a powerful enough computer (e.g. with Intel Pentium 4 or AMD Athlon processor) and at least 512 MB RAM memory.
generator.bat file in DocFlex/XML RE root directory
to specify the 'JAVA_HOME' variable according to the location of
Java 6, Java 5 or Java 1.4.x installed on your system.
DFH variable to the absolute pathname
of the DocFlex/XML RE installation directory (e.g.
set DFH=C:\docflex-xml-re-1.8.0).
generator.bat and run the template applications.
generator.sh shell script file in linux
subdirectory to specify the 'JAVA_HOME' variable according to
the location of Java 6, Java 5 or Java 1.4.x installed on your system.
Change "Permission" properties of this file to allow it to be executed by Linux.
generator.sh !
generator.bat. You will see the generator dialog.
XMLDoc.tpl template.
Each XML file can be specified either by local path name or by URL. In the case of a URL, the generator will try to download such a file directly from the Internet. When multiple XML files are specified, make sure that each pathname or URL is enclosed in double quotes.
templates/XSDDoc/README.html | Running XSDDoc,
Documentation | XSDDoc
We are always happy to hear any questions, suggestions, comments, etc.
about this software.
Please, e-mail us to: support@docflex.com or
contact@filigris.com
The DocFlex/XML core (namely, XML DSM driver) has been extended with an abstract functionality that allows dynamic association of some XML elements with certain graphic representations of them called element images (which are typically some diagrams). Such images may be also supplied with hypertext imagemaps, which enable generation of hyperlinks from the specific image regions to the corresponding locations in the documentation.
The element images (and imagemaps to them) are not generated by the XML DSM driver itself. Rather the driver exposes a special Element Image Provider interface, which may be implemented by another extension (or integration) specific to a particular template application field. Such an implementation should "understand" the semantics of the underlying XML data source and generate diagrams/images (along with the imagemaps) that somehow depict particular XML elements.
When supported, element images are accessible in templates via Image Controls, which makes possible to program how those images are inserted in the generated output, formatted and hyperlinked to other documentation parts.
The new Element Image functionality was immediately used to develop the XMLSpy Integration (see below).
A new property has been introduced for template sections: "Output Notification Expression" (found on the "Component | Options" tab of the section property dialog in the Template Designer).
When that expression is specified, it will be executed each time the section has produced a non-empty output (on the finishing of the section processing).
This makes possible, for instance, to program such things like tracking whether particular output sections have been generated early and, depending on it, to add some kind of separator (e.g. horizontal rule) before the output that follows them.
A new functionality has been supported that makes possible to dynamically attach any data to particular DSM elements using special service attributes.
Service attributes serve the same role as normal element attributes. They allow you to attach specific data to particular DSM elements and access those data by names. However, unlike normal DSM attributes, service attributes are not provided by the DSM driver and not connected to the external data source. Rather, they are maintained by the generator itself in the form of a special hash-map.
That hash-map is actually very simple. Each service attribute is represented by a two-part key: { attrName; element.id }, where 'attrName' is the attribute name; 'element.id' is the unique identifier of the DSM element, to which the attribute is attached. Such a key is mapped to the attribute value.
The main purpose of service attributes is to use them as a data cache. That is to store some frequently needed information about particular elements, which although can be found in the DSM, practically is difficult to collect.To work with service attributes, the following FlexQuery functions have been added:
| Function | Description |
|---|---|
setServiceAttr() |
Assigns a service attribute with the specified name and value to the specified element. |
getServiceAttr() |
Returns the value of a service attribute with the specified name attached to the specified element. |
hasServiceAttr() |
Tests if there is a service attribute with the specified name attached to the specified element. |
removeServiceAttr() |
Deletes a service attribute with the specified name attached to the specified element. |
The full descriptions of those functions can be found in the Template Designer: Help | Assistant | Functions by Category | Elements / Attributes | Attribute Access.
This new functionality was immediately used in
XSDDoc templates.
See:
templates/XSDDoc/README.html |
Change Log | Version 2.2.0 | Naming of redefined components
The HTML output generator was optimized to work about 5% faster and now produces more compact output (1-5% smaller size).
Besides this, the following HTML options have been added:
"Use fixed font sizes"
If selected (true), all font sizes will be fixed. The actual font sizes are calculated from the values specified in templates adjusted against the base font size specified in the "Base font size" option."Base font size"This option is not exactly new. It replaces the previous "Use relative font sizes" option, which had the opposite meaning.
This option is used only together with the "Use fixed font sizes" option (when checked). It specifies the base font size (in points) against which the actual fixed font sizes used in the generated HTML are calculated.
Several new RTF output options have been added to control generation of hyperlinks and bookmarks:
"Hypertext | Generate hyperlinks"
Specify whether to add hyperlinks in the RTF output."Hypertext | Generate bookmarks"Note: To have cross-reference hyperlinks (those pointing within the same document) be generated, the "Generate bookmarks" option must also be selected. Without it, only external (URL) hyperlinks will be possible.
Specify whether to add bookmarks in the RTF output."Hypertext | Bookmark name prefix"Bookmarks are needed to generated both cross-reference hyperlinks and page number references.
Specify prefix for automatically generated bookmark names.One more option was added specifically to format large images:This option may be useful when you need to merge several RTF files produced with DocFlex into a single document. In that case, you should generate those files with different bookmark prefixes. This will ensure that the bookmarks from different RTFs never overlap and all hyperlinks and page number references in the result document are correct.
"Images | Allow image rotation"
Allows rotating big images to make them better fit in the specified paper size in order to minimize the image scaling. Currently, this is supported only for the element images (diagrams) generated in PNG or GIF format and only when all graphics is stored in the RTF file.
For the case when the generator is run from Java command line (e.g. using generator.bat) and with GUI,
the generator dialog
has been re-implemented using JFrame so that it will be visible on the Windows taskbar
as a Swing application.
First sentences of description texts are used in various summary tables.
In a plain text, the first sentence is defined by the position of the dot ('.')
that ends the sentence.
When a text is formatted with HTML, extracting its first sentence becomes trickier.
In that case, besides the dot, a sentence may be terminated with a paragraph-level tag.
In the early implementation,
all such tags were taken into account. Now, all heading tags (like <h1>) are ignored.
So, when a text has a heading, it will be just added before the first sentence extracted from the actual text,
but not replace it. This will make those short descriptions placed in summary table be more informative.
An integration of DocFlex/XML with Altova XMLSpy® has been implemented.
For all details, please see xmlspy/README.html
and
Documentation | Integrations | XMLSpy.
See: templates/XSDDoc/README.html | Change Log | Version 2.2.0
To make things clearer and more convenient to the users, the following changes has been made in the DocFlex/XML product range:
Nothing has changed, however, either in the provided content/functionality or licensing of this edition. Any Commercial or Academic licenses issued previously for "DocFlex/XML" can be installed and will equally work with DocFlex/XML SDK.
That edition (the interpretor/generator itself) has been made freeware to provide the free runtime environment for execution of DocFlex/XML templates. The output generators will work without limitations (on the features of the generated output). No, special licensing is needed for this any longer.
However, the actual limitations on what you can generate may come from the template applications, which may require special licensing by their own (or need to be created/modified under a Commercial License for DocFlex/XML SDK). See also Licensing of Templates for more details.
As it was before, DocFlex/XML RE is bundled with all currently available template applications developed by us (some of which require separate licensing).
The OASIS XML Catalogs v1.1 are fully supported now. In particular, this includes:
XML Types provide the structure and data type information about possible XML files processed by a set of templates (each template is based on a certain XML Type). For more details, please see Documentation | Designing Templates | Defining XML Type | Assigning XML Schemas | xsd.catalogs.
For more details, please see Documentation | Running Generator | Generator GUI | Assigning XML Catalog(s).
XML catalogs are special XML files that allow you to redefine the physical location of the XML files (and other types of files) referred from some other XML files. See also: About XML Catalogs
The "XSDDoc" templates have been modified to support this feature as well.
A new property has been introduced for template sections: "Break Parent Section Block".
When specified, it forces the template interpreter, after the processing of the given section, to break the further processing of the containing it section block according to the property value, which may be one of the following:
"break when section executed"
The processing of the parent block will be broken only when the given section has been executed."break when section produced output"Note: The section is executed when it has passed its enabling condition (if specified) and the current generator context element complies with the Matching Element Type(s) specified on the section.
The processing of the parent block will be broken only when the given section has not only been executed but also produced some non-empty output.In the Template Designer, when the 'Break Parent Section Block' property is specified on a section, it is indicated with a special icon, which appears on that section in the left designer pane (showing the section tree). The property itself can be specified in the "Component | Options" tab of section's property dialog.
Until now, the functionality of the new property was substituted by testing
in the enabling conditions of other sections (located below the given one) one of the generator variables:
'sectionBlock.execSecNone' or 'sectionBlock.outputSecNone'.
(Those variables allow you to test if some sections in a section block have been already executed
or produced a non-empty output.)
The old approach works as well now. However, the new one adds clarity, simplifies programming and may substantially improve performance of template applications.
In particular, the new feature allowed us to boost about 15% the performance of the "XSDDoc" template application!
Since this version, DocFlex/XML supports multi-valued template parameters (called also list parameters, for short).
Such parameters allow you to pass into template the whole vector of different values
associated with the same parameter name. This provides a universal mechanism for implementing
a user control over how a set of templates processes a certain type of data (or situations)
that may come in unlimited number of variations.
A list parameter can be specified both in the Parameter Inspector dialog of the Generator GUI
and on the generator command line (using one or many -P options).
Thanks to some new optimizations, all output generators work 30% faster now.
The EMF image format has been supported. Now, the EMF images can be inserted both in the generated HTML and RTF documents. All supported (and tested) image formats now include: GIF, PNG, JPG, WMF, EMF, BMP.
The automatic wrapping of very long nonbreaking strings within table cells has been improved.
Until this version, such a wrapping was done correctly when the string was generated by the same control. When the entire nonbreaking string was produced by different controls (possibly using different fonts), it was not recognized as a single string and, therefore, was not broken as needed. That caused some summary tables in RTF JavaDoc to expand beyond the page width.
Now, this is fixed!
For more details about that problem with long nonbreaking strings in RTF, see Doclet GUI | RTF Options | Tables | Long string wrapping factor.
The processing of mouse-click events has been reworked so as to show popup menus correctly on different platforms. Until this version, the popup menus actually didn't work on Apple Mac (with its one-button mouse). Now, it is fixed!
The Apache Maven 2 Plugin for DocFlex/XML has been implemented. Now, you can easily integrate DocFlex/XML with the Apache Maven automated build system.
For more details, please see: maven/index.html
and
Documentation | Integrations | Apache Maven Plugin.
See: templates/XSDDoc/README.html | Change Log | Version 2.1.0
See: templates/XSDDoc/README.html | Change Log | Version 2.0.0
A new licensing system has been implemented with the support of multiple licenses (that cover different features within the same software package) and a possibility to attach licenses to particular sets of templates (commercial template application).
The goal is both to allow our customers to pay exactly for what they are willing to use and to provide us with more resources for further development of this software.
As the number of template parameters (controlling what is generated) ever grows, the Template Parameter Inspector in its previous form became increasingly cumbersome and difficult to navigate.
This problem has been addressed by introducing a possibility to collapse/expand the parameter group nodes dynamically
(some of which can be preset in the templates to appear initially in the collapsed form;
further, the current collapse/expand state of particular group nodes is saved in the
generator.config and restored next time).
What is more, now some of the parameter group nodes may themselves serve as the template parameters.
These improvements allow introducing lots of parameters so as to control a particular big template application. Those parameters may be organized in the form of a hierarchical tree, which is both compact and easy to navigate.
This feature may not sound very great, but it was not that easy to implement. In fact, it substantially speeds up the process of designing of templates (which we particularly need ourselves as the primary users of our own tool).
See: templates/XSDDoc/README.html | Change Log | Version 1.6.8
config/xmltypes.config file)
to any number of XML Type Configuration Files.
Now, a complete XML Type definition (which includes the XML schemas describing the particular
XML data source) can be stored together with the template set based on it and loaded dynamically when needed.
This makes possible to represent a particular template application in the form of a single software unit
that can be easily distributed and deployed by its own.
See: templates/XSDDoc/README.html | Change Log | Version 1.6.7
java.lang.ClassCastException exception
happening when a schema with unspecified (i.e. global) target namespace imported another schema using
<xs:include> directive.
In templates, the new image size must be specified in device-independent units (like points). Before that, it was an HTML browser who converted points into pixels, which might be responsible for producing images with unpredictable sizes.
Now, when generating HTML, the DocFlex generator itself converts point size into pixel size according to the DPI value specified in the formatting properties of the given templates (see: Template Designer | File | Properties | Formatting | General | Resolution (DPI)). So, in HTML, the new image size will always be specified in pixels.
Now, all supported image formats include: GIF, PNG, JPG, WMF, BMP
This open source Java library is used by DocFlex/XML (all editions) and included in the package (see Package Contents). Support of the newest version of Apache Xerces will help to integrate DocFlex/XML seamlessly with the latest versions of other important tools (e.g. Apache Ant).
The bug happened when DocFlex/XML home directory was placed inside another directory
whose name contained a space (e.g. 'C:\Program Files\docflex-xml').
It caused java.io.FileNotFoundException during opening the configuration files.
Now, this is working.
See: templates/XSDDoc/README.html | Change Log | Version 1.6.3
align attribute of an <img> tag in
a description preformatted with HTML/XHTML markup.
(See Image Control Properties Dialog | Formatting | Image tab).
firstSentence() function, which extracts the first sentence
from a long description text to be placed in a summary table, has been totally redeveloped.
Now, it recognizes the HTML markup and finds the first sentence boundary according
to the pure text extracted from the original string (i.e. without HTML tags) as well as
stops on any HTML block tag (such as <p>). In the returned string, the original HTML
markup is preserved and unfinished HTML elements are correctly closed.
(See Template Designer | Help | Expression Assistant dialog for more info).
OutputFormat.renderEmbeddedHTML has been added
to indicate if "Render embedded HTML" format option has been specified for the generator.
Now, this property is used in XSDDoc templates
to better control processing of XHTML in XML schema annotations.
stderr (by default) or in a separate 'docflex_error.log' file
(when it is specified with the newly introduced -errlog option).
GOMIterator.prevItem and GOMIterator.nextItem
were introduced as well as a method accompanying them:
GOMIterator.itemAt().
DSMElement.rawValue and
DSMAttr.rawValue. These properties allow accessing the unprocessed
text values of XML elements/attributes directly obtained from the XML files.
You can use this, for instance, like the following:
contextElement.dsmElement.rawValue
(e.g. in the Formula Expression of a Data Control).
For details, see Template Designer | Help | Expression Assistant dialog.
See: templates/XSDDoc/README.html | Change Log | Version 1.6
All generator properties accessible within FlexQuery expressions (> 100) as well as all general (148) and XML-specific (18) FlexQuery functions are fully documented now. In total this took writing more than 330 KB of explanations in HTML!
You can find everything at the Template Designer | Help | Assistant dialog.
The first version DocFlex/XML has been released, which started the third and the most advanced product line based on DocFlex Technology. (The previous two, DocFlex/Javadoc and DocFlex/Together, had been already available for more than a year before that.)
Most of the document formatting capabilities was already in place. All processing of XML files was already based on the data type information obtained from DTD or XML Schemas. However, the actual data sources possible to process at once with a single template were limited to only one XML file.
The "Sales Report" and "Alternative to XSLT" samples come from those times.