'xmltype' subdirectory
block and final attributes of elements and complex/simple typesnillable attributes of elements
The new version 2.0 of DiagramKit has been supported in XSDDoc 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).
In the overview/summary pages with Component Summary sections:
Since different types of pages may include similar documentation fragments (like Schema Summary, Component Summary), it makes sense to be able controlling all those fragments together from the same place. Such parameters were introduced in the new "Details | Fragments" parameter group.
In particular
provide the default values for the similar parameters in
The new DocFlex/XML native diagramming engine «DiagramKit» is now supported in XSDDoc 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 schema files).
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.
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 DocFlex/XML (no trial licenses are required for that)! For small 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 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.
Since 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 XSDDoc 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 XSDDoc (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.
When a complexType typeA is defined by restriction of a complexType typeB
and in typeB there is an attribute wildcard, then the typeA must not
inherit that wildcard.
That is according to W3C XML schema spec. Attributes themselves are inherited at that.
Before this version, we missed to support that rule (that is, the attribute wildcards were assumed to be inherited as well, which were reflected in the generated documentation).Now, that is fixed.
New parameters have been added:
Similar to XMLSpy, now it is possible to use Oxygen XML Editor as a diagramming engine. It works about the same as in the case of XMLSpy.
There are two levels of integration.
The first level is the
OxygenXML Integration
itself, which is hardcoded in Java. This is a separate commercial product with its own licensing.
For more details, please see {docflex-xml}/integrations/OxygenXML/README.html.
The second level is implemented as lib/integrations/OxygenXML.tpl template.
That template inserts no diagrams in the output.
Rather, it is called only once by each of the main templates (FramedDoc.tpl and PlainDoc.tpl)
during the initialization (along with the lib/init.tpl template).
The job of OxygenXML.tpl is to launch OxygenXML's
own documentation generator
to generate component diagrams for all XML schemas to be documented.
The template does this using special FlexQuery functions exposed by the hardcoded part of the integration.
(You can find those functions in the Template Designer via
Help | Assistant | Functions by Category | OxygenXML Integration Functions.
Note that they will be available only when the OxygenXML Integration is properly installed.
See {docflex-xml}/integrations/OxygenXML/README.html | Installation)
Once diagrams have been generated, they are used further by the hardcoded part and eventually get accessible in other templates via Image Controls as element images.
The template level of the whole integration is necessary because of two reasons:
To control the OxygenXML integration, a new parameter group has been added: Integrations | OxygenXML
Previously, the reproduced XML source of an XML schema was always added at the end of the Schema Overview page (along with the schema description and component summaries). But some XML schemas may be very large. When XML source of such a schema is included in the Schema Overview page along with everything else, that page becomes difficult to manage in a web-browser.
Now, in case of framed HTML documentation, it is possible to have the entire XML schema source to be published in a separate HTML page. This is controlled by the new parameter:
The grouping of namespace prefix/URI bindings has been advanced further.
Now, the same namespace prefix/URI binding is documented only once per XML Namespace Bindings report with a single entry. The particular XML files and the locations within them, where the binding is defined, are documented in the entry details.
This makes the XML binding report even more compact and readable.
The subheadings of various namespace / schema / component lists in the navigation frames are no longer just lines of bold black text. Now, they are also hyperlinks that reveal themselves when you move mouse cursor over such a heading. By clicking that hyperlink, a corresponding summary will show up in the details frame – the summary of those things listed under that heading.
This is the bottom-left frame found in framed HTML documentation, which is used to display one of the second-level navigation pages (associated with a selection in the Overview Frame). The following has been changed about it:
A Table of Contents box can be generated now at the top of on each navigation list page. It includes the links to all list groups, which help you to quickly jump to any group, particularly when there are lots of items.
Whether that box is generated is controlled by the new parameter:
In the heading of element component list, now you may see two counters like this:
The first counter shows how many items in the list. The second counter is for how many actual element components have been documented by those items.
The difference is that those local element components that share the same { name; type } may be documented as a single entity represented by only one item in the list.
See also: Version 2.7.0 | Unification of local elements by type
Some XML (XSD) files may contain the same namespace prefix/URI binding specified in numerous locations around the file. (This may be done automatically by some tool used to create that XML.)
Previously, all such locations would be documented as separate entries in the XML Namespace Bindings report.
Now, the same prefix/URI bindings specified in a particular XML file are documented as a single item. Only 'Elements' property will list all actual XML elements (along with the hyperlinks to the XML source), where the binding is specified.
That improvement makes the XML Namespace Bindings report a lot clearer.
The font used for component names in component summary tables has been changed from the fixed "Courier New" to the proportional "Verdana" font.
The new font being equally clear-cut, however, makes the name column considerably narrower, which is important when there are long component names – a rather usual case.
Sometimes wrong processing may have been misprogrammed on the level of templates too (that we call template bugs). The following such bugs have been fixed:
That bug, which appeared only since the previous version 2.6.0, was found in the implementation of Joint documenting of conflicting XML schemas that uses schema file URIs as hash keys (or their parts). In some cases, the URI of a schema file was produced differently, which caused that schema to be not recognized as already documented.
That was fixed.
was not reflected in the component summaries.
That happened because the value of that parameter was not passed over automatically as the default value of the corresponding parameters controlling those summaries:
When local elements are documented globally, the documentation of each local element is stored in a separate HTML file.
But where are those files located and how named?
Before this version, all HTML files documenting any elements (both global and local ones) were stored in the directory:
.../schemas/schemaName/elements/
The file names were derived from the element names. That produced a rather compact documentation.
But different local elements defined in the same schema may have equal names. In that case, the documentation generator would add a special numeric suffix to the element name to make the corresponding file name unique. As a result, you could never be certain what the doc-file name for a particular local element would be. Therefore, you could not reference to that file from outside. (The same situation would be with the file names of element diagrams.)
It turned out that some our customers wanted exactly this: to reference particular local element doc/diagram files from outside.
To resolve that problem, we supported a possibility to reproduce in the documentation directory structure the whole structure of local element's parent components. In that way the problem with name collisions and addressing the element doc/diagram files was solved completely.
This is controlled now by a new parameter:
Conflicting XML schemas are those that define the same components (that is with the same local name in the same namespace). For instance, different versions of some your XML schema project will likely contain conflicting XML schemas.
Previously, documenting of several conflicting (however correct) XML schemas together would likely produce incorrect documentation. Some links from the references to global components defined simultaneously in different schemas would go to wrong locations. Moreover, the content models of some components (as well as other things) might be derived incorrectly.
Since this version, XSDDoc is able to document correctly any number of conflicting XML schemas!In short, this works as follows:
Here, schema reference is any of the elements: <xs:import>, <xs:include> and <xs:redefine>
<xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/xml.xsd"/>
Such schemas will belong to all domains at once. They will be documented only once. All links to the components defined in them will go to the same documentation locations from anywhere those components are used.
Normally, such a subdirectory name is derived from the name of the XML schema file. If that name duplicates another schema's name, it will be extended with a numeric suffix so as to make the subdirectory unique. For example:
{xsddoc}/schemas/XMLSchema_xsd/{xsddoc}/schemas/XMLSchema_xsd_1/
Previously, all kind of general titles found in the generated documentation were specified with the same "Documentation Title" parameter.
Now, the titles of Overview Summary and Overview Frame can be assigned separately with the corresponding parameters:
The text of the hyperlink titles (tooltips) becomes even more complex. The following parameters / functionality have been added:
New parameters have been added:
'xmltype' subdirectory
All standard XML schemas, on which "xsddoc" XML Type is based
and which were previously held in 'XSDDoc/xmltype' subdirectory
(namely, "XML Schema for XML Schemas" and related to it),
have been relocated to the central DocFlex/XML resource directory:
{docflex-xml}/lib/resources/
to be reused for other applications. Those schemas are still critical for XSDDoc and loaded from the resources through the default XML catalog (introduced exactly to point to them).
See also:
{docflex-xml}/CHANGES.html | Version 1.8.5 |
Data Processing | Default XML catalog
All descriptions of XSDDoc parameters are held now
in the 'help' subdirectory, separately from the main templates.
This made possible to shrink the main template files about twice as well as to keep only one copy
of each description to maintain.
Now, those parameters that are irrelevant to the current settings (e.g. specified in other parameters) are shown in the Parameter Inspector disabled. This will help navigating the parameter tree.
The idea behind such unification is that when many local elements across an XML schema share the same
{ namespace : elementName : typeName }
their definitions typically look like the following:
<xs:element name="elementName" type="typeName"/>
There is basically nothing (or very little) special to say about every particular such a definition. So, all of them can be documented as a single entity.
For many XML schemas, such an approach makes possible to greatly reduce the overall number of documented elements, thereby making the documentation a lot clearer.
There are even cases, when the XML schema documentation generated without such a unification would be trouble to understand and use. All you would see are lots of repeating element names with little clue what they actually mean, especially given that some of them may represent essentially the same things and others quite different ones.
But in some cases the unification of local elements by type may be excessive. What may be actually needed is to document all defined element components separately as they are, without any distortions. And before this version, that was impossible.In fact, the unification of local elements by type was supported by XSDDoc templates from the very start. This was the way in which local elements were processed. Switching off the unification was impossible.
Now, we have reprogrammed this and introduced a new parameter: "Generate Details | Elements | Local Elements | Unify By Type"
The W3C XML Schema specification allows for defining in a single XML schema multiple local element components that have the same element name but different content models. When documenting such element components, they need to be distinguished somehow across the documentation. But because of possible name repetition, the element name itself now is insufficient for this (even the qualified one).
DocFlex/XML XSDDoc solves that problem by adding a special name extension, which makes the whole element name unique. This version includes an improvement of how such name extensions are generated.
For more details please see the template parameter "Show | Local Element Extensions" and within its description, further: "About Local Element | Global Naming of Local Elements".
Now, you can specify the sorting order of namespaces, XML schemas and schema components in various locations of the generated documentation.
See the following parameters/parameter groups:
A new parameter group "Navigation" has been added in the FramedDoc.tpl main template.
It controls the generation of frameset and various navigation lists used in framed HTML documentation.
The generated HTML frameset file (i.e. 'index.html' – the documentation main file)
now supports a possibility to pass to it any HTML page contained
in the documentation to be loaded initially in the 'detail' frame on opening of the frameset.
The page pathname should be specified relatively to the documentation root directory
(where index.html is located) and passed as the URL parameter
(specified after '?' in the initial index.html URL), for example:
The Component Documentation may include various lists of related components. Since the full component names can be rather long strings (and even with spaces, e.g. the extended names of local elements), the problem arises how to display such lists to make them both dense and readable enough.
To deal with this, XSDDoc supported two layouts for component lists:
Now, one more layout was added "one column list".
It is best when component names may contain spaces and some of the names are particularly long strings. (The "comma-delimited flow" layout is not good here because it will make the list difficult to read, and "two column table" may be not much better either because the table may stretch far beyond visible page.)
As it was before, the "optimal" layout can be selected, which forces XSDDoc to choose the actual layout automatically to better fit the particular list. (This is also programmed in templates).
For further details, please see parameters:
Now, most of hyperlinks generated in HTML documentation are supplied with titles.
A link title is specified using title attribute, like this:
<a ... title="link tooltip text"> ... </a>
Many HTML browsers will interpret it as a link tooltip (a tiny window with the text that appears near the link when the mouse cursor is moved over it).
Such tooltips can be used to quickly see more information about the linked text. For instance, when the link appears on a schema component name, its tooltip may reveal the component type and the namespace it belongs to.
The generation of hyperlink titles/tooltips is controlled by a newly introduced parameter group: "Show | Hyperlink Titles (Tooltips)"
Two new parameters have been added to specify by name which exactly XML schema files (from the whole your XML schema project) need to be included or excluded from the documentation:
The processing of XSD elements <xs:import> and <xs:include> has been reworked.
Previously, when some XML schema 'A' was both imported
from another schema 'B' using <xs:import>
and included by yet another schema 'C' using <xs:include>,
the 'A' got documented twice (with all its components).
Now, this is fixed!
All documentation icons (e.g. inherit.gif) are stored now in a single
'{doc-root}/resources' directory, which prevents duplicating them.
(Previously, icons were copied to different local 'doc-files' subdirectories associated with
particular documents, where the icons were used.)
The parameter group "Integrations | XMLSpy", which controls the DocFlex/XML XMLSpy Integration, has been reworked and extended.
A new parameter "XMLSpy Version" has been added, whose actual role is only to calculate the default values of parameters in another new subgroup: "Integrations | XMLSpy | Workarounds". It switches different processing of various things related to different XMLSpy versions.
A new "Content Model Diagram" section has been added in Component Documentation blocks. It shows a graphic diagram representation of the content model of the given component. The other XML schema components depicted on the diagrams will be hyperlinked to the corresponding sections/blocks across the entire documentation.
The section is generated by the lib/content/diagram.tpl template.
The diagrams are inserted using an Image Control specified to generate the "element image"
of the current DSM element representing an XSD component.
The actual diagrams may come from any kind of diagramming engine implemented outside DocFlex/XML core,
however connected to it via the Element Image Provider interface.
Currently, this is provided only by the
DocFlex/XML XMLSpy Integration,
which uses Altova XMLSpy to generate the diagrams
(see also below).
In the future, other diagramming engines may be used or implemented.
The generation is controlled by a new parameter group: "Details | Component Documentation | Content Model Diagram", where you can specify if that section is included and how to generate diagram hyperlinks.
DocFlex/XML XSDDoc uses Altova XMLSpy as a ready available diagramming engine to generate content model diagrams inserted in the XML schema documentation (see above). For that purpose, XMLSpy is actually called via two levels of integration.
The first level is the
DocFlex/XML XMLSpy Integration
itself, which is hardcoded in Java. This is a separate commercial product with its own licensing.
For more details, please see {docflex-xml}/integrations/XMLSpy/README.html.
The second level is implemented as lib/integrations/XMLSpy.tpl template.
That template does not insert any diagrams in the output.
Rather, it is called only once by each of the main templates (FramedDoc.tpl and PlainDoc.tpl)
during the initialization (along with the lib/init.tpl template).
The job of XMLSpy.tpl is to launch XMLSpy and cause it to generate component diagrams
for all XML schemas to be documented.
The template does this using special FlexQuery functions exposed by the integration hardcoded part.
(You can find those functions in the Template Designer via
Help | Assistant | Functions by Category | XMLSpy Integration Functions.
Note that they will be available only when the XMLSpy Integration is properly installed.
See {docflex-xml}/integrations/XMLSpy/README.html | Installation)
Once diagrams have been generated, they are used further by the hardcoded part of the integration again and eventually become accessible in any other templates via Image Controls as "element images" (see above).
The template level of the whole XMLSpy integration is needed because of two reasons:
To control the XMLSpy integration, a new parameter group has been added: Integrations | XMLSpy
The documenting of redefined XML schemas has been reworked.
In particular, before now, the components being redefined were renamed by adding "$ORIGINAL" suffix
(so as to distinguish the redefinitions from the original components).
After that, such a suffix was visible everywhere (including in the reproduced XML source),
which might be looking confusing.
Now, such a renaming never happens. The reproduced XML source looks the same as the original one. (However, all hyperlinks are correctly generated to the redefinitions instead of the original components.)
In the documentation itself (in various lists etc.), the original components are shown with their original names only. The redefinitions are represented with the component names followed by "(redefinition)" or "(redef)" string. For example:
xhtml.a.attlist (redef)Nested redefinitions are also supported. Their names will be extended with "(redef 2)", "(redef 3)" etc.
The new processing of redefinitions was implemented using "service attributes" general functionality
added since DocFlex/XML v1.8.0. See
{docflex-xml}/CHANGES.html | Version 1.8.0 |
Template language / general functionality | Service Attributes.
New parameters have been added to control whether a relative or absolute XML schema file path must be displayed in the documentation and whether to generate the hyperlink to the source XML schema file.
Relative Path
Hyperlink
Those parameters can be found by the following parameter paths:
Your XML schema project may contain both XML schemas with annotations formatted using XHTML and those with plain text annotations. In the case of plain text, the only formatting available are new lines. When XHTML is processed, the new lines are ignored. So, how can you generate documentation in which both formatting approaches are used?
Now, you can do this by specifying which XML schemas use XHTML and which do not. Two parameters have been added:
Processing | Annotations | XHTML | For schemas | Include
Processing | Annotations | XHTML | For schemas | Exclude
The automatic extraction of first sentences of the annotations formatted with XHTML
has been improved. For more details, see
{docflex-xml}/CHANGES.html | Version 1.8.0 |
Template interpreter / output generator | Extraction of first sentence from HTML formatted text.
The extensions of local element names now are shown entirely in grey color, including hyperlinks. (Hyperlinks are indicated with underlining.) This should make the generated documentation to look more tidy and easy to read.
Note: The generation of local element name extensions are controlled by "Show | Local Element Extensions" parameter. See also: Version 2.1.0 | Documenting of local elements | Showing extensions of local element names.
New parameters have been added to control how various lists of components are arranged. A list may be represented either as a comma-delimited text flow, which is more compact but harder to read, or as a two-column table, which is easier to read but occupies more place. The following parameters allow you to choose between those two possibilities depending on the schemas you document:
These new parameter groups allow you to specify exactly for which components the "XML Representation Summary", "Lists of Related Components", "Usage / Definition Locations" and "Annotation" section must be generated. This may be separately selected for the following component types: elements, complex types, simple types, element groups, global attributes, attribute groups.
Specify for which components the "Attribute Detail" section is generated (e.g. elements, complex types, attribute groups) and which attribute definitions may be included in it (e.g. local attributes, references, wildcard, prohibitions, the attributes inherited from ancestor components).
Specify for which components the "Content Element Detail" section is generated (e.g. elements, complex types, element groups) and which element definitions may be included in it (e.g. local elements, references, wildcards, the elements inherited from ancestor components).
These parameters control whether to include Facet Documentation.
The full processing mode, which is activated under a Commercial or Academic License for "XSDDoc" template application, since this version unlocks all available functionality of the XML schema documentation generator. This includes what is both implemented in the templates themselves and supported by the DocFlex/XML template iterpretor / output generators.
No other licenses will be needed for this!
Previously, to use certain features supported by some output format generators (e.g. rendering in RTF the XHTML markup embedded in XML schema annotations), an additional license covering the DocFlex/XML generator was needed.
Now, DocFlex/XML RE, which was continued from the early "DocFlex/XML (Kit)" edition, provides free template interpretor / output generators.
This mode, which is activated by default without any special licenses, now enables only using of FramedDoc.tpl main template.
So, you can generate with it for free some standard (however, absolutely complete) multi-file framed XML schema documentation in HTML format (with limited possibilities of customization).
No other types of documentation (including RTF) can be generated in the limited mode.
XML catalogs are used in XML schema projects to avoid referencing XML schemas from each other
(via <xs:import>, <xs:include>, <xs:redefine> elements)
by direct file names. Instead, only some abstract URIs representing the schemas are used for that purpose.
The URIs are connected to the actual
XML schema files in a special XML catalog file. This makes possible to break the entire XML schema into a number
of XSD files (modules) and do not care further about their particular locations.
As an example of the XML schema project that uses the XML catalog see this link: http://docs.oasis-open.org/dita/v1.1/OS/schema/ditaschema.zip
Now, XSDDoc allows you to generate the complete documentation by such XML schema projects as well !
When an element is affiliated to a substitution group and the element type is not specified,
inheriting the type from the head element of the substitution group
(specified with substitutionGroup attribute).
Generation of the list of elements which the given element may substitute for. (That is, the given element may be used anywhere instead of the elements in the list.)
Controlled by the parameter: "Details | Component Documentation | List of Related Components | Substitutable Elements"
Generation of the list of elements which may substitute for the given element. (These are the members of the substitution group headed by the given element.)
Controlled by the parameter: "Details | Component Documentation | List of Related Components | Substituting Elements"
Generation of the list of all known elements that may be included in the given element by substitutions.
Controlled by the parameter: "Details | Component Documentation | List of Related Components | Children By Substitutions"
Generation of the list of all known elements that may include the given element by substitutions.
Controlled by the parameter: "Details | Component Documentation | List of Related Components | Parents By Substitutions"
In the element's "Usage Locations", generation of the list of elements where the given element
is specified as the value of the substitutionGroup attribute.
Note: All the lists are produced according to the values of substitutionGroup
and block attributes of global element components (as well as considering
blockDefault attribute of <xs:schema>).
The abstract attributes specified on global element and complex type components
are documented now in the component profile sections.
Moreover, anywhere an abstract element or complex type is mentioned in the documentation,
its name will be highlighted with italic font.
block and final attributes of elements and complex/simple types
Those attributes are documented now in profile sections of corresponding components (with possible explanations).
The block attributes are used also to calculate actual members of substitution groups.
The blockDefault and finalDefault attributes of <xs:schema>,
which provide the default values of the block and final attributes of elements and types,
are taken into account and documented in XML schema profile as well.
nillable attributes of elements
(in profile sections of element documentation and content element details)
These files/blocks are organized the same as similar ones generated for particular XML schemas or namespaces, however, now they list all documented XSD components (i.e. those for which separate Component Documentation blocks have been generated).
Actually, the exact content of the "All Component Summary" document can be specified in "Details | All Component Summary" parameter group.
A template parameter "Show | Namespace Prefixes" has been introduced to switch on/off showing namespace prefixes in the names of XML schema components being documented or mentioned in the documentation.
Any namespace prefixes used in the output documentation originate from the namespace URI/prefix bindings declared in the source XSD files. For a particular XML name, its namespace prefix is generated according to the binding for the given namespace found the nearest to the documentation context where that XML name appears.
Previously, such prefixes were generated in any case. However, sometimes the XML schema authors may declare very long namespace prefixes (even without actually using them), which would completely overwhelm the documentation. So, the showing of such prefixes needs to be switched off in that case.
The settings of elementFormDefault and attributeFormDefault attributes
specified in the <xs:schema> element are documented now in the
XML schema profile.
You may specify which information is included in the XML schema profile, for instance, in the parameter group "Details | Schema Overview | Schema Profile".
The local elements with the namespace-unqualified form are documented now as belonging to global namespace. Previously they were still linked to the namespace targeted by the parent schema (where they are declared).
A template parameter "Show | Local Element Extensions" has been introduced to control the generation of the extensions of local element names.
The extended name of a local element is made of its normal name extended with some short info about the possible element location or its type. For example:
configuration (in plugin in plugins in reporting)
xs:complexType (type xs:localComplexType)
here in the brackets are the local element name extensions.
The name extensions are needed to distinguish the element in the documentation from other local elements, which share the same XML names, however have different content.
The name extensions may be not necessary for local element with unique names. For instance, some XML schemas are designed (or generated) so that almost all element components are declared locally, except only the root element. At that, all element names may be unique. So, the name extensions are not really needed and will only overload the documentation.
Before this version, the extensions of local element names were generated in any case. Now, it is also possible to specify not generating them at all or generating them only for local elements with non-unique (repeating) names.
A unique feature of this XML schema documentation generator (XSDDoc) is the possibility to document local elements both locally and globally. (For more details see parameter: "Generate Details | Elements | Local Elements".)
In the case of global documenting, all local elements that share the same { namespace, name, type } are documented as a single quasi-global element. This is possible because many things that can be said about each particular local element component covered by it are the same. Documenting them together as a single entity may actually reveal more information.
However, there are a few things that may vary at each particular location. Annotations are among them.
Now, the unified quasi-global element documentation will list all annotations specified locally at each covered local element component. At that, when the annotation text actually repeats, it will be printed only once with the list of all locations where such a text was specified.
From the very start, XSDDoc has been able to recognize and process the XHTML tags (elements) embedded in any XML schema annotations (so as to format with HTML the annotation text and include images).
It was only required that any markup elements supposed to be XHTML were actually associated with
the XHTML namespace URI http://www.w3.org/1999/xhtml that must be specified with
'xmlns' attribute. (For more details, please see
DocFlex/XML | XSDDoc | FAQ | How to use XHTML?)
Switching to XHTML namespace would be always correct from the point of overall XML integrity. However, since many people actually want to use HTML tags without bothering much about all those namespaces, we have eased that requirement.
Now, you can use HTML tags directly without switching the context namespace to the true XHTML. To have such tags to be processed as XHTML, you will need
true)
"process as XHTML".
An additional parameter has been introduced related to HTML markup: "Processing | Annotations | Encode markup characters". It controls whether to encode the HTML markup characters contained in the annotation text.
The purpose of this parameter is the following:
A < B
You need to show the '<' character as it is.
Since the whole annotation will be converted into HTML, that character needs to be encoded.
In that case, this parameter should be selected.
<xs:annotation>
<xs:documentation>
This is <b>keyword</b>
</xs:documentation>
</xs:annotation>
This is <b>keyword</b>
which could be immediately passed to an HTML viewer or added to HTML output. In that case, the HTML markup characters should not be encoded!
Therefore, if you have an XML schema like this, you should unselect this parameter. (An example of such a schema you can find by this link: http://maven.apache.org/xsd/maven-4.0.0.xsd)
In fact, XML schema <xs:annotation> element does not allow inserting the annotation text directly into it. Instead, XSD language defines its two possible children: <xs:documentation> and <xs:appinfo> elements.
It is the <xs:documentation> elements where you actually put the human-readable text.
The <xs:appinfo> elements are supposed to store the data or instructions intended for some software that would process the XML schema. Because of this, generally, it is unclear how <xs:appinfo> elements should be documented (except of reproducing their XML source as is).
However, some people want to use <xs:appinfo> elements in the same way as <xs:documentation> elements and place the human-readable text there too. For such people, we have supported a possibility to process the <xs:appinfo> elements in that way as well. It is controlled by the new parameter: "Processing | Annotations | <xs:appinfo>"
A new parameter group "Generate Details | For Schemas" has been supported that allows you to specify which XML schemas (and their components) are to be documented.
The XML schema files you initially specify on the command line (or in the generator dialog) are the primary XML files to be processed by the XSDDoc template set.
However, those initial XML schemas may call from themselves some other XML schema files
(via the <xs:import>, <xs:include> and
<xs:redefine> elements) and they, in turn, yet more extra schemas.
All those extra XML schema files plus the schemas specified initially will constitute
the whole your XML schema project. Generally, all of them must be loaded and processed
in order to make sense of your initial XML schemas (that is, to interpret and document them).
Some of such imported extra XML schemas may be the standard ones used in other your projects
(in addition, they may be rather big).
Before this version, all the extra XML schemas involved in your project would be fully documented as well. But what if you actually want to document only the explicitly specified XML schemas?
Now, you can do it using the new parameters in "Generate Details | For Schemas" group!
Using PlainDoc.tpl main template, you can document now
not only the whole XML schema but to generate separate documentation for several selected (or even single)
XML schema components (e.g. elements, global complex/simple types, groups, etc) specified by their local names.
For instance, the parameter "Generate Details | Elements | Names" available in
PlainDoc.tpl
allows you to specify directly the names of the elements to be documented in separate
Element Documentation blocks. When the list of names is specified, only the element components
with the specified names will be documented.
The same is supported for other component types.
A new parameter "Details | Component Documentation | XML Representation Summary | Sorting" (and even some general template language functionality for it) has been supported to specify sorting of attributes shown in the XML Representation Summary of a component (e.g. element).
When the parameter selected (true), the attributes will be sorted
in alphabetic order of their qualified names.
When unselected (false), the attributes will follow according
to some natural order determined by how and where the attributes have been defined.
In a simplest case, when all attributes are defined within the same component,
that will be exactly the order of their definitions. When the given component
(whose attributes are represented) is based on other components, some of such ancestor components
may define particular attributes (and even block some of those defined within their own ancestors).
In that case, the result attribute ordering will appear from the subsequent interpretation of
all involved components.
Thanks to DocFlex template technology, overall, it was possible to support more than 300 template parameters (working the same as "options" of an ordinary documentation generator), which gives you an unprecedented control over the content, look & feel of the generated XML schema documentation!
Since this version, XSDDoc becomes a commercial template application, that is a separate commercial product with individual licensing and its own version numbering.
The system of parameters that control XSDDoc has been entirely reworked. The total number of parameters now exceeds 170. This will allow you to control almost every aspect of the generated XML Schema documentation and vary its content (and some formatting) within a great range of details, starting from a few summaries and overviews up to the most comprehensive documentation containing every feature possible.
On the other hand, such a large number of parameters should not hinder you because all of them have the default values, some of which are calculated dynamically from the values of other parameters.
What is more, thanks to the new capabilities of the Template Parameter Inspector introduced in the latest DocFlex/XML v1.7.0, all parameters of XSDDoc are organized in the form of a hierarchical tree (with dynamically collapsed/expanded nodes) that is both compact and easy to use.
Before this version, the local elements (i.e. the element components defined locally within complex types and groups) were documented in the same way as the global ones. The emphasis was to treat each pair { local element name : type } as a quasi-global element so as to collect and document about such a pair all the information possible.
That approach worked well for many big XML schemas (e.g. like "XML Schema for XML Schemas" found at http://www.w3.org/2001/XMLSchema.xsd) and helped to reveal lots of information about the XML elements defined by the schema.
However, for certain types of XML schema design, documenting of local elements along with the global ones is not good and, rather than clearing things up, may produce a mess. This is especially true when the XML schema authors avoid defining element attributes. Instead, in order to store the elementary data normally supposed for attributes, they define lots of local elements with primitive simple types. As a result, such an XML schema contains great a lot of insignificant local element components. When all of them are documented separately (and appear in all element component lists) they may overwhelm anything else. In that case, such local elements need to be documented locally, exactly where they are defined!
XSDDoc now supports this. The local elements can be documented simultaneously in two ways: locally and globally. The local documenting means that the element component is documented together with its parent component (where it is defined). The details about the element will appear in the "Content Element Detail" section of the Component Documentation generated for its parent component.
That was before this XSDDoc version, of course. However, now a lot more details (almost all) about each element can be included in the "Content Element Detail" section as well. Which exactly details are generated is controlled by the parameter group: "Details | Component Documentation | Content Element Detail".
What is more, the parameter "Generate Details | Elements | Local Elements" allows you to specify whether to document local elements separately (globally) and which of them. For instance, if this parameter is set to "with complex type only", then the local elements with simple types (which normally substitute attributes) will be documented only locally. That will allow you to avoid the mess mentioned above.
Now, for all situations when a simple content (i.e. simple datatype) is used or defined:
the following details can be generated:
The list of actual facets is produced as the following.
First, the initial facets are collected by all types starting from the type assigned to the component throughout the chain of all its ancestor types (both global and anonymous) until the top ancestor passed or a derivation by list or union reached. Further, the produced sequence of facets is filtered so as the facets collected earliest (that is defined in lower descendant types) remain and those overridden by them are removed. In particular:
xs:pattern facets will remain, because the allowed value must match all of them.
xs:enumeration facets will remain only those that are defined in the same type,
which is either the component's type itself or the one nearest to it.
When you need to annotate your XML schemas simultaneously in several languages,
you should use several sibling <xs:documentation> elements with
different xml:lang attributes. For example:
<xs:element name="author" type="author">
<xs:annotation>
<xs:documentation xml:lang="en">
The author of a book.
</xs:documentation>
<xs:documentation xml:lang="fr">
Designe l'auteur d'un livre.
</xs:documentation>
</xs:annotation>
</xs:element>
When you specify the target language code in the "Processing | Annotations | Language"
template parameter,
only those <xs:documentation> elements will be processed,
which contain the xml:lang attribute assigned with that code.
<xs:any> and <xs:anyAttribute>
wildcards are fully documented now (the same like other elements and attributes).
xmlns attribute in <xs:schema>
element) includes another schema using a <xs:include> or
<xs:redefine> directive and the included schema has no default
namespace specified. Such a situation happens in case of so-called "chameleon design",
when the included/redefined schema is assumed to adopt the default namespace of
the calling schema. Before v1.6.8, the XSDDoc did not process it accordingly,
which caused generating a wrong documentation. Now, it is fixed!
<xs:import>,
<xs:include>, <xs:redefine> directives.
lib/init.tpl template,
which caused the attributes specified within a child element defined locally within
another element to be documented also as the attributes of the parent element.
PlainDoc.tpl and
FramedDoc.tpl templates to remove
<xs:annotation> elements from the reproduced XML source
(see in parameter inspector "Sections | XML Source | Remove Annotation").
This can by controlled specifically for different types of XML source fragments
(e.g. for components the annotation can be removed, but the full XML schema source
will be reproduced as is).
<img> tags) in XML schema annotations.
The XSDDoc templates are upgraded now to support
the XML Schema annotations (the content of <xs:annotation> elements)
preformatted with XHTML tags, including possibility to insert images
(using <xhtml:img> tag).
The processing of XHTML tags is programmed entirely within annotation.tpl
subtemplate (located at templates/xsddoc/misc/ directory).
All XHTML tags are converted to the normal HTML tags (actually, just
'xhtml' namespace prefix is removed from the tag names).
Further, everything is processed by the generator itself.
In the case of HTML output, each annotation text together with HTML tags is inserted
as is into the generated output file. Additionally, the image files specified in
<xhtml:img> tags can be copied automatically to the documentation
destination directory. This is also programmed in annotation.tpl subtemplate
and controlled by "Formatting | Annotation | Copy images" parameter of both
PlainDoc.tpl and
FramedDoc.tpl main templates.
In the case of RTF output
(generated with PlainDoc.tpl template),
all HTML tags embedded in annotations are parsed and interpreted with the appropriate
RTF formatting features. Almost all HTML tags (and their attributes) practically
usable in documentation comments are processed in that way. Here's the list
of all supported HTML tags:
| Text | <b>, <strong>, <i>, <em>, <code>, <tt>, <u>, <s>, <strike>, <sub>, <sup>, <font>, <br> |
| Paragraphs | <p>, <center>, <div>, <pre>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <blockquote> |
| Lists | <ul>, <ol>, <li>, <dl>, <dt>, <dd> |
| Table | <table>, <tr>, <td>, <th> |
| Other | <hr>, <img>, <a>...</a> |