This is a change log of the entire DocFlex/XML software. The "DocFlex/XML (Full Edition)" is mentioned here as a part of the whole thing. The changes of XSDDoc template set (the implementation of XML Schema Documentation Generator) are described in {docflex-xml}/templates/XSDDoc/CHANGES.html
Template Call is a template component that allows you to call one template from another. Here, the called template (or subtemplate) serves as a procedure. It may generate either a separate file or a piece of the file generated by the calling template. A Template Call has a lot of settings (among them, of course, passing template parameters).
Now, one more group of settings has been added -- the list of style overrides.
Each template may define formatting styles. These are the named groups of formatting properties, which can be assigned to a template component at once just by specifying the style name. The formatting styles are template local things. That is, they are not imported from somewhere outside. But when a template is called from another template, the styles defined in the calling template will override the equally named styles defined in the called template. When multiple templates are called one from another, that will work in a chain. So, the styles defined in the main template will override any equally named styles defined elsewhere. As a whole, formatting styles behave as additional template parameters passed implicitly by their names. |
Now, it is possible also to specify explicitly for a given Template Call how the style overriding occurs. For each style found in the called template, a style override can be defined that tells exactly which style from the calling template will override it (regardless of the style name). That adds a lot more flexibility!
Style overrides are specified in the Template Call property dialog on the "Call Settings | Style Overrides" tab.
The HTML generator has been almost entirely redeveloped to achieve the following goals:
Now, the HTML output can be generated in one of the markups:
The markup is selected with the option: Output | Markup
For those who wanted to customize the generated HTML documentation with their own CSS rules, it is possible now!
Although, such a feature is typically ubiquitous in other doc-generators, to support it in DocFlex required some kind of breakthrough. The difference is that a typical doc-generator is developed from the start for a particular destination format (i.e. HTML) in some general programming language (like Java) or XSLT, with very meticulous coding of how all formatting constructs are generated. All CSS rules are planned beforehand and everything is adjusted to them. In DocFlex, the actual doc-generators are programmed in the form of templates, where the formatting is specified in a highly abstract way independent on the destination format. Then, it is rendered with suitable features available in a selected output format. So, the concept of CSS rules (which is available only in HTML) is somewhat foreign to all this. |
In case of HTML output, the CSS style sheet has been used before, but the CSS rules placed in it were effectively the sets of inline CSS properties generated by particular template components and collected together in a single style sheet to eliminate their repeating. The class selectors assigned to such CSS rules were completely unpredictable and could not be used to substitute the generated CSS rules with the custom ones. Such automatic CSS rules are generated now too and called anonymous CSS rules.
But since this version, a new type of CSS rules has been supported -- named CSS rules. Those are generated from the formatting styles defined in templates. When such a style is assigned to a template component, each piece of HTML output (i.e. HTML element) produced by that component can be assigned with the CSS rules generated by that style. The class selector assigned to a named CSS rule is specified in the corresponding template style. So, the relation between a particular CSS class selector and the pieces of output where it is applied is predetermined. This makes possible to substitute the CSS rules (i.e. their properties) generated for those class selectors automatically, with the custom CSS rules provided by the user.
The difficulty of implementing of named CSS rules comes from the fact that several template styles can contribute to the result formatting of a particular template component. The styles can be either assigned directly to the component or inherited from its parents. Besides that, some formatting properties can be specified on the component directly without any styles at all. When that everything is rendered with a single anonymous CSS rule, only effective properties (left after all overriding) will get there. But when named CSS rules are used, they must replicate in CSS the same property overriding that occurs on the level of template styles. That wasn't simple to achieve!
For a lot more details please see: DocFlex Technology | Documentation | Usage of CSS in generated HTML.
Specify the (X)HTML markup version of the generated output.CSS
The group of options related to formatting of HTML output, which is done through Cascading Style Sheets (CSS).CSS | Generate style sheet fileSee also: DocFlex Technology | Documentation | Usage of CSS in generated HTML
Specify whether to generate the external CSS file (global style sheet).CSS | Generate style sheet file | CSS pattern fileThis option was actually present before, however not in this group.
Specify the pattern file for the global style sheet.CSS | Generate style sheet file | Include anonymous rules
Specify whether all generated anonymous CSS rules must be stored in the external CSS file (global style sheet).CSS | Generate named rules
Specify whether to generate named CSS rules.CSS | Generate named rules | Include descriptionsGeneration of named rules is essential for applying custom CSS rules
Specify whether to add the descriptions of template formatting styles to the named CSS rules generated from them.CSS | Generate named rules | Custom rule file
Specify a (CSS) file with custom definitions for some of the automatically generated default and named CSS rules.CSS | UnitsThis setting is essential for applying custom CSS rules
Specify measurement units used in the generated HTML.Text | Render embedded HTML | Fix markupThe possible are relative, pixel and point units.
Specifies whether the embedded HTML markup must be parsed and any syntax errors found in it (e.g. missing closing tags) fixed.This setting may be particularly important in case of XHTML output.
An integration of DocFlex/XML with Oxygen XML Editor
has been implemented.
For all details, please see integrations/OxygenXML/README.html
and
Documentation | Integrations | Oxygen XML.
For Image Control, it is possible now to specify paddings around the image. See: Image Control | Properties dialog | Formatting | Image tab.
The image paddings are supported in both HTML and RTF output formats. They may be particularly useful when inserting various icons in the documentation.
A few minor bugs have been fixed.
Among them, it turned out that sortVector() FlexQuery function was sorting strings
always ignoring case. In XSDDoc, in rare cases, this caused incorrect unifying local elements by type.
|
Now, all output documents (in HTML and RTF formats) generated under the general Trial License will be heavily distorted by replacing some letters with bullet characters (as well as contain special messages).
This should help some our users to respect the trial license terms.
The Java-style typecast operator has been supported:
(type) obj
where type
may be any primitive type (like String
or Number
)
or GOM-type ("GOM" stands for Generator Object Model).
It allows you to quickly access properties of various GOM objects, provided via untyped references (mostly returned by various functions). Now, you can write something like this:
((GOMElement) getParam("name")).id
Previously, only special type-conversion functions (like toString()
or toElement()
)
were available for such operations.
Casting to array types is also supported. You can write:
(type[]) obj
At that, the necessary conversion will be done even when the initially obj
is an array
of a more generic type, however, containing only elements of the required type. For example:
(In the case, when the initial array contains object of incompatible types, an error will be reported.)objects = Array (1, 2, 3); // create an Object[] array with only integer elements ints = (int[]) objects; // convert it to an array of integers ints[0] * ints[1] * ints[2] // access array elements as integers
A new property has been added to Image Control: "Expression for Image File Name". It generates a name of the output image file.
This feature is most interesting in the case of element images, which are certain graphical depictions (e.g. some diagrams) of the entities represented by the DSM elements.
Previously, the names of the element image files were produced from certain DSM element properties (their internal names and types), which was hardcorded in the generator.
It may sound odd. What images and hyperlinks can exist in plain-text files?
Yet, the plain-text output may be just a base layer for other file formats, for instance DITA, which is an XML-based markup. There, both images and hyperlinks do exist and are required.
The following new functionality will allow you to use plain-text output capability of DocFlex/XML to generate some full-blown complex formats even when they are not supported by DocFlex/XML directly.
Images
In plain-text mode, an Image Control will produce the same image file (according to its setting). However, in addition, it also emits into the main output the image file's relative pathname. That pathname is calculated against the main file's location and the name-separator is UNIX style ("/"). In a template, you can surround the Image Control with other Text Controls generating some markup, so everything would produce both the image file and the image tag for it in the main output.
Hyperlinks
Now, you can generate cross-hyperlinks in plain-text files too. This equally includes the hyperlinks from images (the imagemaps).
What a hyperlink actually is depends on the final format you generate using the plain-text output. DocFlex/XML just provides the necessary functionality to find the things you want to link from and to. This is implemented in the form of new FlexQuery functions and GOM types/properties ("GOM" stands for Generator Object Model):
Function / Type / Property | Description |
---|---|
findHyperTarget() |
Finds a hypertarget matching the specified set of keys that may exist anywhere
in the whole generated documentation. Returns a GOMHyperTarget object
describing the target.
|
GOMHyperTarget |
Provides information about a hyperlink target. This includes the output file containing the target and the target name. |
getElementImageMapAreas() |
Returns all hypertext imagemap areas of the element image associated with the specified element.
The function returns an array of GOMImageMapArea objects.
|
GOMImageMapArea |
Represents a single area in the hypertext imagemap of an element image.
This includes the area bounds (rectangle) and the referenced GOMElement .
|
GOMElement.hasImage |
Indicates whether the element has a certain image representation (called element image). |
More information about these functions and types you can find in the Template Designer | Help | Assistant:
Template calls are the template components that invoke processing of other templates from the given one (typically to insert their output into the currently generated document).
Processing of a template call is rather time-consuming. The fewer of them are in a template the better they can be optimized. Moreover, templates cannot be called directly from FlexQuery expressions.
The solution is to use stock-sections as light-weight proxies of template calls (stock-sections can be called also from FlexQuery expressions). That is, a template call is defined only once within a stock-section, and then that stock-section is called from anywhere, instead of the template.
Previously, that was possible only by defining a Folder stock-section and the Template Call Section within it.
Now, a Template Call Section itself can be specified as stock-section (which, of course, reduces all the processing).
DSM stands for Data Source Model. DSM Type is a description of particular class of possible data sources processed by a given template.
In DocFlex/XML, DSM Type is called XML Type, since all data sources are typically XML files. |
A template based on it can be called to process any data source (or even no data source at all).
It can be called also from any other templates.
This, however, comes to a price. Such a template can do little more but process only template parameters
and #CUSTOM
elements.
Anyway, it might be useful. For instance, you can create a template that inserts in the output some complex richly formatted messages, which are the same for all template applications. It is also possible to pass quite complex data via template parameters (and even iterate by them).
The template file format has been made more friendly to view/edit template files manually (without Template Designer):
'\n'
escapes).
'\uxxxx'
).
'DSM_TYPE_ID'
property can be change manually now.
The 'DSM_TYPE_ID' property specifies the XML Type, on which the template is based.
XML Type provides the structure and data type information about possible XML files processed
by the template.
|
Notes:
|
Expression Assistant provides a dynamic help system when writing FlexQuery-expression (those used to calculate various dynamic properties of template components and for other things).
As the number of FlexQuery-functions constantly increases (many actually overload the same functionality with different parameter signatures), the function tree in the Expression Assistant has been reorganized as follows:
The primary focus of the generated RTF was always MS Word. However, following some user complaints, we uncovered and fixed a lot of problems of compatibility with other RTF readers. For instance, under WordPad, certain features of the old RTF output might be distorted, or the whole doc might get invisible starting from some point.
RTF is poorly documented format ridden with various legacy contradictions. So, it is not very simple to get all known RTF reader work correctly together, particularly, when you have a rather complex RTF. |
A bug has been fixed that in some cases caused distortion of text of formatting in page headers/footers.
See: integrations/XMLSpy/CHANGES.html
| Change Log | Version 1.5
The full edition of DocFlex/XML software, which was formerly called "DocFlex/XML SDK", is renamed back to "DocFlex/XML (Full Edition)" to reflect the fact that a "DocFlex/XML SDK" license does not cover the whole DocFlex/XML software.
The "Label Control" has been renamed into "Text Control" and more functionality added.
The purpose of Text Control is to specify some static text in templates. Now, unlike the old Label Control, it shows the full multi-line text directly in the designer pane (with the support of scrolling). This may be particular helpful, when you want to specify in templates some multi-line descriptions.
A new property has been introduced for Element Iterators: "Expression for Grouping Key" (found on the "Processing | Sorting/Grouping | Grouping" tab of the Element Iterator properties dialog in the Template Designer). It allows you to break the iterated elements into groups so as to iterate, first, by the groups and, then, by the elements within each group.
It works as follows.
After the initial elements have been collected, filtered and sorted, the result sequence of elements is broken into groups according to the grouping keys generated for each element by the FlexQuery specified in the "Expression for Grouping Key" of the Element Iterator.
Each continuous subsequence of elements with equal grouping keys produces a group. As a result, the sequence of elements prepared for iterations is converted into a sequence of element groups. The ordering of elements in each group remains the same as in the initial sequence.
Since groups are not elements, the Element Iterator cannot iterate by them directly.
So, it will iterate by the first elements taken from each group.
However, at that, on each iteration step, the Generator Object Model (GOM) property
iterator.groupElements
, which is accessible in FlexQuery expressions,
is updated so as to provide the enumeration of all elements
in the given group.
This allows you to specify a nested Element Iterator that will iterate by the elements
in the group received from the iterator.groupElements
property.
Although, dynamic HTML is not currently in the focus of DocFlex templates, the following setting has been supported: Template | Properties | Output File | HTML Head Expression.
It specifies an expression that may produce a string, which will be included in the header (between <head>...</head> tags) of an HTML file generated by the given template. In particular, this allows you to embed in the generated HTML file any custom JavaScript code (enclosed in <script>...</script> tags).
For instance, this may be used to reload the 'detail'
frame
(of a frameset defined in index.html
) with another HTML document passed
to index.html
via a URL parameter (specified after '?' in the initial URL).
That was actually supported in XSDDoc templates;
see:
templates/XSDDoc/CHANGES.html |
Version 2.5.0 | Opening of frameset on required page
|
Hyperlinks are generated according to special link/target definitions specified in template components (see component's Properties Dialog | Hypertext tab). Now, hyperlink definitions themselves look more like components. The following settings/features have been added:
Some hyperlink definitions may be so complicated that they are better to be explained.
The same as in template components, it allows switching context element used for calculations of other hyperlink's settings.
Specify one or several element types, which the context element must match. This is a kind of filter. If the context element does not match any of the specified types, the whole hyperlink definition will be skipped.
A hyperlink is created when the vector of keys generated by the Link Key Expressions matches a similar vector of keys associated with a certain target (generated by a different component).
Now, in addition to single vector of keys, it is possible to define matrix of alternative keys. The matrix columns become alternative key vectors. If one vector cannot be matched, another is tried.
This allows unifying in a single hyperlink definition what were previously several ones, which simplifies programming and improves performance of the template.
Image Control has been extended with a new property: "Expression for Image File Output Directory", which allows programming where the images produced by a given Image Control will be stored. In particular, this makes possible to save all standard documentation icons in a single directory (and, therefore, to prevent duplicating them):
{doc-root}/resources
This is supported now in XSDDoc templates;
see:
templates/XSDDoc/CHANGES.html |
Version 2.5.0 | Single directory for all documentation icons
|
FlexQuery expressions are small program blocks (called queries) with a Java-like syntax that are used in templates to calculate dynamic properties of template components and for other needs.
Now, the FlexQuery language is extended with the return statement:
return <result_expr>
It makes possible to stop the execution of the query at any point and return the query result,
which is calculated by the result_expr
specified in the return statement.
The type of the returned result is checked to comply with the data type necessary for the given query. This is done yet during the parsing of the query (e.g. in Template Designer).
A FlexQuery expression may also contain subqueries, which are nested code blocks executed not directly, but rather passed as parameters to functions. A function may call such a subquery repeatedly to calculate certain things (e.g. to check a filter condition for the elements processed by the function).
A subquery may also contain return statements, which will affect only the execution of that subquery.
The result_expr
specified in such a return statement will be also checked, however,
now only to comply with the data type necessary for the given subquery.
Embedded HTML is the HTML markup (tags) inserted by the user directly in various descriptions, annotations etc. (stored as plain text in XML files) in order to format them. To have that formatting show up in the generated documentation, in general, the embedded HTML markup needs to be processed (rendered) specifically, which depends on the output format. This is controlled by the "Render embedded HTML" option of the given output format.
Sometimes it is needed to remove all block-level HTML tags but leave any other tags, so that the result text would be displayed formatted but without any structure, as a single line. That, we call flattening.
It is supported now!
A new formatting property has been introduced for all template components: "Embedded HTML | Flatten" (found on the "Formatting | Text Flow" tab of the component properties dialog in the Template Designer). If it is selected, any embedded HTML markup found in the text output produced by the component will be flattened (given that the embedded HTML is processed both as a whole and for that component in particular). This will also affect all nested components (including called stock-sections), unless rendering of embedded HTML is specifically disabled in some of them.
Before this version, all descriptions of templates and their parameters could be stored only directly within the templates themselves. Now, they can be held also in separate text files located near the main templates. (The description text may also include HTML markup.)
This makes possible:
That functionality is achieved by introducing of a new macro:
${include <url>}
Such macros can be inserted both within the descriptions stored directly in templates
and within the included text files themselves.
The url
specified in the macro points to the file to be included.
The macro is expanded with the content of that file (after the expansion of any include
macros found in that file).
The file URL may be both absolute and relative one. If the macro is found within a description stored in a template, the relative URL is interpreted against the location of that template. If the macro is found within a text file, the URL is interpreted against the location of that file.
This everything has been applied in XSDDoc
templates; see:
templates/XSDDoc/CHANGES.html |
Version 2.5.0 | Separation of parameter descriptions from templates
|
Now, in the Parameter Inspector, those parameters that are irrelevant to the current settings (specified in other parameters) can be shown disabled. This will help navigating the parameter tree.
That is achieved by introducing new properties in the template parameter definition: "Enabling Condition" and "Group | Enabling Condition". They specify the boolean FlexQuery expressions (queries) that are evaluated each time any of the template parameters is changed:
Procedure templates are a special kind of templates that generate no output. Rather, they have been used internally in big template applications to employ the data querying and processing capabilities of template components (such as Element Iterator) for some auxiliary tasks (e.g. creating of element maps).
Now, the role of procedure templates has been extended, so they can be used also to generate multi-file documentation with no particular root. The following functionality has been supported:
A default XML catalog has been introduced. Its purpose is to point to the local copies of some standard XML schemas found in Internet (like http://www.w3.org/2001/XMLSchema.xsd), which are critical for XSDDoc templates.
Previously, those schemas were held along with the XSDDoc templates in the directory:
{docflex-xml}/templates/XSDDoc/xmltype/
Now, they have been moved to a more central location in the DocFlex/XML resource directory:
{docflex-xml}/lib/resources/
so as to allow reusing them for other things (e.g. in the coming WSDLDoc template set).
The default XML catalog, which is located in the same directory in the file:
{docflex-xml}/lib/resources/catalog.xml
allows referencing to those schemas by their standard internet URLs, yet loading them from
the local files in DocFlex/XML resources.
Now, you can document your entire XML schema project even when it is packed in a jar-file!
For example, suppose you have a jar-file 'C:\project\some.jar' ,
in which there is 'xsd' directory containing an XML schemas
'some.xsd' .
Then, the URL to be passed to the generator to document that XML schema should look as follows:
jar:file:/C:/project/some.jar!/xsd/some.xsd
|
All internal CSS declarations, which were previously defined and used only locally in every generated HTML document,
now can be held in a single 'stylesheet.css'
file stored in the documentation root.
Only links to this file will be included in the generated HTML documents.
Although such CSS declarations look typlically rather gibberish, they tend to repeat across HTML files. So, moving them to a single CSS file may substantially reduce the overall size of the generated HTML documentation.
That possibility is controlled by a new "Output | Generate style sheet file" option.
What's more, using the nested "CSS pattern file" option, you can frame the generated CSS declarations into your own CSS file. That will allow you to include in the result CSS file your custom styles, which you can use to format the HTML markup embedded in your descriptions/annotations.
Specifies the encoding of the generated HTML files.Output | Add Charset
Specifies whether to insert the character encoding declaration in the generated HTML files. The encoding name will be taken from the "Character Encoding" option.Output | Suppress Timestamp
Specifies whether to suppress the date/time information included in a special comment inserted automatically at the beginning of every generated HTML file.Output | Generate style sheet fileWhen you frequently upload the generated docs into some repository, which stores only changes of files against their previous versions and your docs actually do not change, this will relieve the repository from unnecessary updates.
Specify whether to generate a separate style sheet file containing most of internal CSS declarations generated by DocFlex (instead of holding them in every HTML documents where they are used).Output | Generate style sheet file | CSS pattern file
Allows you to frame the CSS declarations generated by DocFlex into your own CSS file.
Thanks to all recent innovations, including storage of all internal CSS declarations in a single CSS file (see Generation of CSS file) and many others, the HTML generator works now on average 5% faster and generate output 15% smaller against DocFlex/XML 1.8.0.
Before this version, all formatting styles defined across a template set, which are not overridden by other equally named styles from parent (calling) templates, would produce the same number of separate styles in the RTF.
Now, this is changed:
That optimization prevents the contamination of the generated RTF with many unused styles (which have been defined in templates but never used) and duplicated styles (which are defined in several subtemplates, but never in the main one).
The automatic wrapping of very long nonbreaking strings within table cells has been reworked once again.
The problem is that MS Word cannot wrap such strings by itself, which causes the table to stretch beyond the visible page. |
To deal with that problem, the following things have been implemented:
(e.g. see: Template Designer | Section's Properties Dialog | Formatting | General | Section Output | "Table")then a property similar to "Tables | Break long nonbreaking strings | Maximal unbroken width" option can be specified for each table cell/column; see:
Template Designer | Control's Properties Dialog | Formatting | Table Cell | Options | Max width allowed for long nonbreaking strings
The src
attribute now can specify not only a formal URL but also a local file pathname
(e.g. c:\element.gif
). Such an image will be shown in RTF.
Also, when the image file specified in src
attribute cannot be found and
the "Images | Show failed image path" RTF option selected,
the failed image's pathname (or URL) will be shown in the generated RTF (along with a placeholder).
Previously, all <img> tags with failed images were just ignored.
That has been completely reworked.
Previously, when "Text | Render line breaks" RTF option was selected and some embedded HTML happened to contain table tags (<table>,<tr>,<td>) intermitting with newlines, the rendering of such a markup in RTF could produce tables with extra cells. Now, this is fixed!
Before this version, when some HTML formatting was specified within a table cell, like:
<table><tr><td><font color="red">blah-blah-blah</font></td></tr></table>
it didn't work ('blah-blah-blah'
wouldn't be red). Now, this is fixed!
Specification of the size and scaling of EMF images in RTF has been completely reworked.
As it was implemented previously, some EMF images inserted by DocFlex in RTF were scaled incorrectly by MS Word, which resulted in displaying of too small or too large images (particularly, when the goal was just to make an image/diagram fit best in the available page size). Now, it is fixed (see below)!
EMF is a vector graphic format, which is especially useful for various diagrams. It is widely generated by many software systems (thanks to its direct support by MS Windows itself, via its APIs).
It took great efforts to understand how MS Word interprets (and calculates by itself)
the size of an EMF image specified in RTF.
When an EMF image just has been inserted in the document, MS Word 2000 displays it
on the document sheet exactly according to the pixel size of the image specified in the EMF file.
But other lengths are interpreted by MS Word not quite the same as they are.
For instance, when you specify a page width in points, MS Word converts it into the pixel width
it displays according to the formula:
The same 5/3 factor is used by MS Word 2000 to display PNG and GIF images.
Their pixel size visible in MS Word is calculated as follows:
In RTF, the image size must be specified in 0.01 mm. MS Word uses that size to display
the image as well as scale it according to \picscalex & \picscaley commands specified in RTF.
So, to be stored in RTF, the original EMF image size in pixels must be converted first
into some non-pixel units -- e.g. points, which can be converted further to mm according to standard
formula -- that will be interpreted correctly by MS Word.
(In fact, EMF file does include the image size specified in 0.01 mm, but it cannot be used here
because MS Word 2000 completely ignores it.)
From the investigation above, we've got an idea. The point size of an EMF image (to be used
for RTF) should be calculated like this:
That turned out to work perfect!
When an EMF image is specified in RTF with such a size,
both MS Word 2000 and MS Word 2010 display and scale it correctly.
|
Tables | Break long nonbreaking strings
Specify whether to break automatically the long nonbreaking strings placed within the tables with the 'table autofit' setting.Tables | Break long nonbreaking strings | Maximal unbroken length
Specify the maximal characters length for a nonbreaking string (i.e. non-wrapping text) allowed to be left unbroken.Tables | Break long nonbreaking strings | Maximal unbroken widthThis option lets you define what a long nonbreaking string actually is (thereby preventing breaking of some resonably long words and names).
Specify the maximal width for a long nonbreaking string (i.e. non-wrapping text) allowed to be left unbroken. Precisely, it is the percent of the table width, in which any nonbreaking string should be wrapped.Tables | Break long nonbreaking strings | Use optional breaksFor all details, see the description of this option in: Generator GUI | Output format | RTF | Options | "RTF Option" dialog
Specify whether to use 'Non-width Optional Breaks' when breaking long strings for wrapping.Other | Suppress Timestamp
The same as HTML option: "Output | Suppress Timestamp"
The DocFlex/XML core (namely, XML DSM [Data Source Model] 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. |
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/CHANGES.html
|
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 block-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 integrations/XMLSpy/README.html
and
Documentation | Integrations | XMLSpy.
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 DocFlex/XML | 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 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: integrations/maven/index.html
and
Documentation | Integrations | Apache Maven.
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.
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).
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.
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.
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.
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.