DocFlex/XML, Version 1.7.0

Table Of Contents

• Package Contents
• Technical Requirements
• Licensing / Processing Modes
  • Limited Mode
  • Full Mode
  • Trial Mode
• Installation
  • Windows Installation
  • Linux Installation
• Running XMLDoc
• Running XSDDoc
• Running Demo Samples
• Getting Help
• Change Log

Package Contents

Technical Requirements

You can freely download Java from Sun Java Technology web-site: http://java.sun.com

DocFlex/XML is a pure Java application. The Template Designer GUI is implemented entirely using Swing. Therefore, everything is supposed to work on any operating system where Java2 Runtime Environment can be installed.

Specifically, the software includes both MS Windows BAT files and Linux shell script files to run DocFlex/XML immediately on those operating systems. See Windows Installation and Linux Installation respectively.

We were also reported that DocFlex/XML worked successfully under Mac OS X.

To parse XML files, DTDs and XML Schemas, DocFlex/XML uses Apache Xerces2 Java Parser version 2.9.0. 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.

Licensing / Processing Modes

Limited Mode

• To run the Template Designer in demo mode. You will be able to investigate any functionality, however, unable to save any your created/modified templates.
• To run XMLDoc without limitations.
• To run XSDDoc (XML Schema Documentation Generator) in limited mode.

  Note:

  If you have a license for "XSDDoc" template application, you will be able to run it also in full mode even without a special license for DocFlex/XML itself.

• To use HTML output generator without limitations.
• To use RTF output generator, however, with some features disabled.

Full Mode

• To use the Template Designer without limitation to created/modified templates.
• To execute custom templates created/modified under Commercial, Academic or Trial Licenses.
• To run XMLDoc without limitations.
• To run XSDDoc (XML Schema Documentation Generator) in limited mode (with some features disabled).

  Note:

  To use XSDDoc without limitations, a separate license for it is required.

• To use all output format generators (HTML, RTF, TXT) without limitations.

Trial Mode

• You may use DocFlex/XML working in trial mode only during the limited period of time (30 days) provided by your Trial License.

• Any output documents generated in trial mode will contain special trial markers. Such documents may be used only for evaluation of this software. Any other usage is prohibited!

• Any templates created or modified (the last time) in trial mode will not work with the reduced edition DocFlex/XML (Kit), which includes only the template interpreter / output generators.

  However, you may use or further modify your trial templates once you have installed a Commercial or Academic License for DocFlex/XML.

  In addition, the Commercial License will allow you to clear your templates created/modified in trial mode from the limitation on execution by the reduced edition. To do this, you should resave the templates with the Template Designer after installing the new license.

  You can use update_templates.bat to upgrade all your templates at once in a batch mode. For more details, see the Template Designer command line options (you can use also '-?' argument in designer.bat).

Installation

Windows Installation

1. Unzip the downloaded archive.

2. Edit *.bat files in DocFlex/XML 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.

3. If you want to run those files from a different location, set also the DFH variable to the absolute pathname of the DocFlex/XML installation directory (e.g. set DFH=C:\docflex-xml-1.7.0).

4. Copy the DocFlex/XML license file 'docflex-xml.license', which you must have received by e-mail, to lib directory. This file should be always near the docflex-xml.jar file!

Linux Installation

1. Unzip the downloaded archive.

2. Edit *.sh shell script files contained 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.

   For each shell script file, edit its "Permission" properties to allow it to be executed by Linux.

3. Copy the DocFlex/XML license file 'docflex-xml.license', which you must have received by e-mail, to lib directory. This file should be always near the docflex-xml.jar file!

Running XMLDoc

1. Run generator.bat. You will see the generator dialog.
2. In "Template" field, select XMLDoc.tpl template.
3. In "XML File(s)" field, specify one or many XML files that you want to document.

   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.

4. In "Output format" field, select RTF format.
5. Click <Run> button to start generator.

Running XSDDoc

Running Demo Samples

1. Start template designer (run designer.bat)
2. Load a sample template
3. Invoke generator dialog
4. Choose the appropriate XML file(s)
5. Click <Run> button

Getting Help

Check the latest releases and documentation updates at: www.filigris.com.

Change Log

Version 1.7.0

• Improvement of “XSDDoc” templates (XML Schema Documentation Generator)

  See: templates/XSDDoc/README.html | Change Log | Version 2.0.0

• New licensing system

  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.

  Note: Any old commercial licenses for DocFlex/XML will work the same. If you have one, you may install and use it with this version as well.

• Generator GUI | Template Parameter Inspector

  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.

• Template Designer
  • The improved support of the definition of template parameters (see above).

  • Support of Copy/Paste of all settings at once specified in a particular tab (e.g. "Processing") of a component property dialog, including all sub-tabs.

    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).

Version 1.6.8

• Improvement of “XSDDoc” templates (XML Schema Documentation Generator)

  See: templates/XSDDoc/README.html | Change Log | Version 1.6.8

• General architecture
  • The definitions of XML Types (which provide datatype information about XML-file data sources) have been moved from a single location (previously, in 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.

• Template Designer
  • The "New Template" dialog in the template designer has been reworked completely in order to make it easier to select the necessary XML Type (on which the new template is to be based). Now, when absent in the list, the needed XML Type can also be loaded interactively from an XML Type config file containing its definition.

  • When Copy/Paste template components, the original settings of the component being copied (including those of its nested components) that are dependant on the context (e.g. the context Element Type or formatting styles) are preserved now in some "latent" form along with the copy of that component at the new location. This is done even though those settings might be senseless according to the new context at the moment of copying. (For instance, the original component may print the value of an attribute of the context element. However, at the new location the current context Element Type has no such an attribute. Hence, the component's settings about that attribute would be lost. The same is true about formatting styles.) Once at the new location the context has been changed appropriately (e.g. the needed formatting style has been copied there as well), the latent settings will be restored as actual ones. This all may save lots of time when a piece of a template is being reused at different locations or in another template (perhaps with some little changes). All the necessary context settings simply cannot be copied to the new location together with the component at once!

  • In the Element Type Tree, which shows the data type information about the particular XML-file data source (see Template Designer | Help | Assistant | All Element Types), the child element types and attributes inherited from the ancestor types appear now in a different color. This helps to distinguish them quickly from the own children and attribute of the given type, which adds clarity to the whole representation.

Version 1.6.7

• Improvement of “XSDDoc” templates (XML Schema Documentation Generator)

  See: templates/XSDDoc/README.html | Change Log | Version 1.6.7

• Template interpreter / output generator
  • A bug has been fixed which caused java.lang.ClassCastException exception happening when a schema with unspecified (i.e. global) target namespace imported another schema using <xs:include> directive.

  • Reworked scaling of images in HTML.

    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.

  • Support of images in BMP format.

    Now, all supported image formats include: GIF, PNG, JPG, WMF, BMP

Version 1.6.6

Upgrade with the latest DocFlex core optimized for Java 6

Version 1.6.5

• Upgrade with the latest Apache Xerces2 Java Parser 2.9.0

  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).

• Fixing a bug

  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.

Version 1.6.4

Additions/improvements of the documentation.

Version 1.6.3

• Improvement of “XSDDoc” templates (XML Schema Documentation Generator)

  See: templates/XSDDoc/README.html | Change Log | Version 1.6.3

• Template interpreter / output generator
  • The general performance has been improved (about 5%).

  • Better support for image formatting. Now, an image can be aligned both to the left or right of a text and wrapped by it. This is supported both in HTML and RTF output. An image can be aligned directly in a template (e.g. by specifying properties of an Image Control) or using align attribute of an <img> tag in a description preformatted with HTML/XHTML markup.

• Template language / Generator Object Model (GOM)
  • Init/Finish Expressions are now supported in Area Sections.

  • The font size assigned to a particular template component can be specified now not only as a fixed value but also relatively (in percents) to the font size of the component's context. (See component's Properties Dialog | Formatting | Text tab).

  • The "Alignment" formatting property of Image Control has been extended up to five possible setting:
    1. Bottom (base line)
    2. Middle (base line)
    3. Top (text line)
    4. Left (margin)
    5. Right (margin)

    (See Image Control Properties Dialog | Formatting | Image tab).

  • The 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).

  • A new GOM property 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.

Version 1.6.2

• Template interpreter / output generator
  • Now, the generator consumes considerably less memory and works up to 10% faster!
  • The error reporting, when the generator works without GUI, is directed now to the stderr (by default) or in a separate 'docflex_error.log' file (when it is specified with the newly introduced -errlog option).

• Generator Object Model (GOM)
  • New properties GOMIterator.prevItem and GOMIterator.nextItem were introduced as well as a method accompanying them: GOMIterator.itemAt().

  • More new properties: 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.

Version 1.6

• Improvement of “XSDDoc” templates (XML Schema Documentation Generator)

  See: templates/XSDDoc/README.html | Change Log | Version 1.6

• New documentation

  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.

Version 1.5

The major breakthrough!

• Now, DocFlex/XML supports processing with the same template any number of XML files at once (based on the same DTD or XML scheme), which are represented as a single meta-XML document.

• The data querying capabilities are enormously enhanced by introducing Element Maps and formula-axis in Location Paths / Location Rules. Lots of new embedded FlexQuery functions have been added.

• The first real-world and very powerful template application has been developed basing on this new functionality -- the "XSDDoc" set of templates that implements a superior quality XML schema documentation generator!

• The freeware edition of DocFlex/XML called "DocFlex/XML (Kit)" has been released, which basically includes the template interpreter/documentation generator without the Template Designer. The freeware edition can be used as a runtime environment for executing your custom templates. In addition, it includes "XSDDoc" and "XMLDoc" sets of templates that allow using it simply as the best quality documentation generator for your XML Schemas or raw XML files available absolutely for free!

Version 1.0

Here, the story begins!

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 are coming from those times.