It is a set of templates that implements a high quality XML Schema Documentation Generator, which you can use to generate by any W3C XML schemas the following types of documentation:
'templates/XSDDoc/' subdirectory of each edition.
README.html
|
this file |
FramedDoc.tpl
|
The main template to generate framed HTML documentation. |
PlainDoc.tpl
|
The main template to generate single-file documentation (in HTML or RTF format). |
lib/
|
The directory containing all subtemplates (and icon files) that power the XSDDoc template application. |
xsd/
|
The directory containing the XML schema for W3C XML Schemas:
XMLSchema.xsd and accompanying files. (All these files are available at
http://www.w3.org/2001/XMLSchema.xsd).
That XML schema serves as a critical part of the definition of the |
xsddoc.xmltype
|
The configuration file that defines the 'xsddoc' XML type,
on which all XSDDoc templates are based.
|
All these files and directories are located in 'templates/XSDDoc/' subdirectory of each edition of
DocFlex/XML.
Please note, some general functionality used in a given version of XSDDoc templates may be available only since a specific version of DocFlex/XML. In particular, the XSDDoc version 2.0.0 requires DocFlex/XML version 1.7.0 or later.
Depending on your license for "DocFlex/XML | XSDDoc", it may work in one of the three different modes: limited, full or trial.
| Note: | These are the processing modes of only the XSDDoc template application -- not the entire DocFlex/XML (which has its own processing mode). For more details, please see: http://www.filigris.com/buy/licensing_pricing.php | Commercial Template Applications |
This mode will allow you to generate a certain (general) type of XML schema documentation in all supported formats.
However, most of parameters of XSDDoc templates will be disabled so that only their default values can be used. This, in effect, will limit your ability to use certain features controlled by those parameters.
In this mode, all template parameters are enabled. You are free to use all features supported by XSDDoc templates.
Once you have installed a proper license, you can use it to execute XSDDoc in the full mode with any edition of DocFlex/XML. No special license for that edition will be required. Although, the template interpreter / output generator itself will work in "limited mode", that will be enough to use most of the features supported by XSDDoc templates. (For instance, you will be able to generate the HTML documentation without any limitations.)
However, certain features of particular output generators may be limited. (For instance, without a full license covering the given DocFlex/XML edition, the HTML tags embedded in XML schema annotations will not be rendered in RTF output.) So, to use absolutely all features of XSDDoc in all output formats, you will need a full license for the given DocFlex/XML edition as well.
For more details about this, please see: http://www.filigris.com/buy/licensing_pricing.php | Multiple Licenses
It will be already pre-installed in the 'templates/XSDDoc/' directory of the main product.
(In the future, when other commercial templates applications will be developed, we may provide them as separately downloadable add-ons. However, now it is just an early stage of such a development.)
The only thing you may need specifically to install is the
'docflex-xml-xsddoc2.license' file, which contains your license
for "DocFlex/XML | XSDDoc" template application.
You will receive that file by e-mail.
The license file should be stored in the 'templates/XSDDoc/' directory
along with the FramedDoc.tpl and
PlainDoc.tpl main templates
(i.e. those called the first by the generator).
After that, the 'XSDDoc/' directory will contain everything needed to
run XSDDoc.
Actually, the "DocFlex/XML | XSDDoc" template application
is completely autonomous.
You can copy/move (or rename) the 'XSDDoc/' directory to any other location
and run the XSDDoc templates directly from there.
This may be particularly useful when you want to modify something in the original
templates and derive your own version of XSDDoc.
generator.bat (found in the root directory of your
DocFlex/XML or
DocFlex/XML (Kit)
installation). You will see the generator dialog.
While processing XSDDoc templates for big XML schemas,
the generator may be particularly hungry for memory. Lack of memory may considerably
increase the generation time!
To avoid this, make sure the maximum heap size available for JVM is 512Mb or even more
(e.g. Java option -Xmx512m sets the maximum heap size to 512Mb).
FramedDoc.tpl template.
You can choose this template from 'templates/XSDDoc' directory using File Chooser.
Each XML file can be specified either by local path name or by URL
(e.g. http://www.w3.org/2001/XMLSchema.xsd).
In the case of a URL, the generator will try to download such a file directly from the Internet.
When multiple XML files are specified, make sure that each pathname or URL is enclosed in double quotes.
The FramedDoc.tpl template is a frameset template
which can generate only HTML output!
Once all source XML Schema files are loaded, the generator enters into the estimation phase.
Lots of heavy processing is being done during that, however, you will see only
"Scanning data source, please wait..." message on the progress bar.
On large XML schemas this phase may take some time. Please wait!
After that, the generator will pass into the generation phase.
The progress bar will show what's being generated.
You can stop the generator at any time during any phase by clicking "Cancel" button.
Check the latest releases and documentation updates at: www.filigris.com.
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>
Now, XSDDoc will allow you to use such multi-language annotations
to generate different variants of the same XML schema documentation for different target languages.
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> |