The new version 2.0 of DiagramKit has been supported in WSDLDoc templates.
The auxiliary lib/diagramming/DiagramKit.tpl template, which passes to DiagramKit all necessary data about XML schema components,
has been modified accordingly.
The “Diagramming | DiagramKit” parameter group has been extended substantially.
See: Docs | DocFlex/XML | DiagramKit | FAQ | Diagram Settings | How to customize generated diagrams?
W3C XML schema specification provides no functionality to tell which of the XML elements declared in the XML schema will be used as the root of an XML document that complies with that schema. However, in many concrete situations, such an intention very much exists and needs to be documented somehow. To solve that problem, we have introduced a concept of top-level elements.
Top-level element is the one, which satisfies the following conditions:
When an element matches all of those criteria, most likely it will be used as the root element of some or all XML documents described by the given XML schema.
Typically, very few such elements can be found in an XML schema (possibly one or two per a namespace). Using the template parameter:
you can separate the top-level elements and thereby highlight what you intended to be the main element in your schema (e.g. <xs:schema> in XML schema for XML schemas).
The new DocFlex/XML native diagramming engine «DiagramKit» is now supported in WSDLDoc templates.
For that a new subtemplate was implemented: lib/diagramming/DiagramKit.tpl, whose job is to pass to DiagramKit all necessary data about XML schema component,
by which it generates all the diagrams. (DiagramKit by itself doesn't parse and process XML schemas).
The old “Integrations” parameter group has been renamed into “Diagramming” and the new “Diagramming | DiagramKit” parameter group was added to control the generation of diagrams by DiagramKit.
For details, please see: Docs | FlexDoc/XML | DiagramKit | Key Features | template parameters
The activated by default «Limited Free License» has been replaced with the «Limited Free License» – equally free and activated by default.
The difference is that, when "Limited Free License" provided limited functionality on unlimited input data, the focus of "Demo License" is the opposite one – unlimited functionality on limited input data.
That will allow you to see however everything works (including any diagrams) absolutely for free without any distortions and immediately as you have downloaded FlexDoc/XML (no trial licenses are required for that)! For small WSDL files/XML schemas, you can even get a complete perfect documentation with all diagrams absolutely for free!
PlainDoc.tpl main template, which generates single-file documentation, has been renamed into SingleDoc.tpl to better reflect its purpose.
Since DocFlex/XML 1.11, a new type of template sections was introduced: Query Section. Its purpose is the execution of a specified FlexQuery expression.
Such sections are needed within lib/init.tpl template, whose job is to load all input WSDL/XSD files and
create a number of element maps used across the entire template set. That's done by executing lots of FlexQuery expressions
specified in various template sections. Previously, as a surrogate for Query Sections the Folder Sections were used with
the specified Init Expression. That looked confusing and burdened processing.
Now, all such instances have been upgraded with Query Sections.
Main template is the one, which can be specified for interpretation directly to the generator
(either with -template option on the Java command line or in the Generator Dialog).
Effectively, each main template represents a separate documentation generator.
A Javadoc-like Navigation Bar has been implemented, which appears at the top and bottom of all detail pages.
Its generation is controlled by a new parameter group: Navigation | Navigation Bar
Now, using 'FRAMES' and 'NO FRAMES' menu items found in the Navigation Bar, you can quickly switch between framed and non-framed views:
The benefit of that switching is the following. Since the non-framed view is just a detail page (i.e. an HTML file), you can easily reference to it from elsewhere. Once the detail page is open in the browser, you can immediately switch to the framed view (with the same page now in the detail frame) so that easily to navigate the whole documentation.
Now framed HTML documentation may include Index.
Index contains an alphabetic list of all documented components (presented only by their local names without namespace prefixes)
with the links to the corresponding documentation details.
Index can be generated as a single file (index-all.html) or split into multiple files
(found in index-files subdirectory) alphabetically, one file per letter.
The generation of Index is controlled by a new parameter group: Generate Details | Index
Now, besides framed HTML multi-file documentation, it is possible to generated the whole documentation as a single file in both HTML and RTF.
The single-file documentation is generated by a new (second) main template 'PlainDoc.tpl'.
This template provides also all parameters related to single-file documentation (however, various specific features controlled by those parameters are implemented across many other subtemplates).
Single-file documentation can be generated in any supported format (which currently includes HTML and RTF). You just need to switch to the necessary format while having PlainDoc.tpl specified as the main template to be interpreted by the generator.
This is the primary purpose of PlainDoc.tpl main template. So, RTF documentation is equally elaborated as framed HTML, however with specific features intended for printable output:
It is not actually generated by DocFlex. Instead, a special RTF "{TOC}" field is inserted in the output. The real TOC is generated by MS Word in place of that field according to style/level paragraph settings specified on the headings of major documentation sections. Those heading will form TOC according the documentation structure.
To have the TOC generated, the document should be loaded in MS Word and the {TOC} field updated. For instance, you can press Ctrl-A (select all) and then F9 (update selected fields).
The inclusion of TOC is controlled by the parameter: Generate Details | Table Of Contents
The page header shows the information about the current section, the footer - the documentation short title and the current page number.
Although the generated RTF includes hyperlinks (similar to those in HTML), they have no use in the printed form.
So, many hyperlinks are supplemented with the page number of the link's target shown like:
link text [page number]
The generation of that is controlled by the parameter: Pagination | Generate page references
Using the parameter group 'Pagination | Start from new page', you can force particular documentation sections to start from a new page.
You can use XHTML tags in your WSDL descriptions and XSD annotations to format the text, define lists and tables, include images etc. Equally, HTML tags can be used in some titles and descriptions passed via template parameters.
Although RTF is incompatible with HTML, all of the specified HTML/XHTML markup will be rendered with the appropriate formatting features of RTF (including lists, tables and insertion of images).
When you run the generator with PlainDoc.tpl and specify HTML as the output format, you will get single-file HTML documentation. It will look basically the same as RTF documentation, however without any pagination related features. But everything else will be there, including all hyperlinks and diagrams (when available). You may find that useful as well.
Since single-file documentation is less navigable as the framed HTML one, it is important how certain types of sections are grouped together. The most abundant are sections describing particular XSD components and WSDL definitions (which are jointly called component details). They can be grouped in three ways:
That is controlled by the parameter: Generate Details | Grouping | Components
Since single-file documentation is intended mainly for printing, it is styled somewhat differently as framed HTML one. For instance, background colors of various section headings are pale and the borders around various representations are dotted to look less contrast. That's done by specifying different properties for the global formatting styles defined in PlainDoc.tpl, which are used across all other subtemplates.
Now you can add a description to entire your WSDL/XSD project. It will appear in the Overview Summary page/section (which is loaded the first in the detail frame or at placed the beginning of single-file documentation).
The description is specified with 'Details | Overview Summary | Description' parameter (available in all main templates). It may be a plain text of any length. You can use in it also HTML tags to format the text and include lists, tables, images etc.
Since this version of DocFlex/XML (1.10) it became possible to define template formatting styles for tables, table rows, table cells and horizontal rules. That, along with paragraph and character styles existed before, allowed switching all documentation formatting programmed in WSDLDoc templates to be specified only through styles. The benefit of that is that template formatting styles can be automatically translated into named CSS rules, which in turn can be substituted by custom one.
So, now you can substantially change how your documentation looks only by applying your custom CSS stylesheet during the generation.
As an example of that, a stylesheet file azure-theme.css is provided, which implements an alternative skin for HTML documentation
generated by WSDLDoc (both framed and single-file ones).
See: README.html | Using azure-theme.css
Documenting of an XML schema like this caused a stack-oveflow error in the generator:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:complexType name="T">
<xs:sequence>
<xs:element name="A">
<xs:complexType>
<xs:sequence>
<xs:element name="B" type="T"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:element name="A"/>
<xs:element name="B"/>
</xs:schema>
Here the stack-overflow happened during the generation of name extensions for local elements A and B
defined within the complex type T.
The presence of equally named global elements A and B caused the need of name extensions for the local elements
(so as to distinguish them from the global ones). The algorithm generating the name extension for such a case is based on showing
the only possible element's parent. But both A and B may be parent and child of each other.
That caused the endless recursion in the name extension generating template.
Now that is fixed.
When an XML schema defines some namespace, it is expected that the schema file (or several related files) is held in a single location. Sometimes, however, several copies of the same schema file may exist, all of which used (referenced) somewhere in the project. When the entire such a project is documented, the namespace definition (i.e. all its components) gets duplicated as many times as there are those copies of the same schema.
Previously, such a situation led to a sort of chaos, which could cause repeated documenting of other schemas involved in the project (however presented as single file instances).
Now, several copies of the same schema used in the same project will be tolerated. You will get in the documentation exactly what you physically have.