Products         Customers         News         Downloads         Licensing         Shop    

 DocFlex Technology
Overview
Features
Documentation
 DocFlex/XML
Overview
Features
Documentation
XSDDoc
Features
Organization
Examples
Templates
FAQ
WSDLDoc
Integrations
Bundles
 DocFlex/Javadoc
Overview
Documentation
Basic Templates
JavadocPro
Examples
Tutorials
 DocFlex/Together
Overview
Examples
Basic Templates
Documentation
Tutorials
 Try
Downloads
Registration
Trial License
 Buy
Licensing
Shop
 Company
News
Products
Customers
About Us
Imprint
Legal
Contact
Links
 

DocFlex/XML - XSDDoc - XML Schema Documentation Generator

  1. What is DocFlex/XML XSDDoc?
  2. What you can generate with it
  3. What XML Schemas you can document
  4. XML Schema Documentation
  5. How Documentation Generator Works
  6. Running Documentation Generator
  7. Integrations
  8. How To Get Started
  9. What you need to license
  10. Does anybody use it?
  11. Future Development

1.  What is DocFlex/XML XSDDoc?

“DocFlex/XML XSDDoc” is a template application (template set) of DocFlex/XML that implements a very powerful XML Schema Documentation Generator in HTML and RTF output formats with the possibility of automatic inserting of XSD diagrams generated by either Altova XMLSpy or Oxygen XML Editor.

DocFlex/XML is a software system for development and execution of high quality documentation and report generators from any data stored in XML files. For more details, please see: What is DocFlex/XML?

The XSDDoc template set is bundled with both editions of DocFlex/XML:

  1. DocFlex/XML (Full Edition) - includes all features available in DocFlex/XML software
  2. DocFlex/XML RE - the free Runtime Environment to run template applications
It is found in 'templates/XSDDoc/' subdirectory of each edition and ready to use. Just read How To Get Started!

2.  What you can generate with it

Using XSDDoc templates set, you can generate the following types of output/documentation:

HTML Output

Framed HTML Documentation

Multi-framed HTML (Javadoc-like) XML schema documentation can be generated with FramedDoc.tpl main template by any number of W3C XML Schema definition (XSD) files.

This kind of documentation may be useful for both the XML schema authors (e.g. to publish the XML schema project on the web) and those who simply need to understand particular large XML schemas.

The framed HTML documentation provides most detailed and easy accessible information about all the XML schema components and interconnections between them.

These screenshots show such a documentation (click on a screenshot to view the real HTML):

Please, look also at XSDDoc | Examples page to view/download other demo HTML documentations generated from various large XML schemas found on Internet.

Single File HTML Documentation

The same entire documentation (above) can be equally generated as a single HTML file using PlainDoc.tpl main template. Click on the screenshot to see it:

RTF Output

RTF Documentation

Using PlainDoc.tpl main template, it is possible not only to generate a single file HTML. Simply, by switch the generator output format to “RTF”, the same template will produce a highest quality RTF file!

Similar to HTML, the RTF documentation may be also interconnected with hyperlinks. In addition, many hyperlinks are duplicated with page number references, which may greatly help to use/navigate such documentation in a printed form.

On the following screenshots, you can see pages of an RTF documentation generated by the same “XML Schema for XML Schemas” (click to enlarge):

See also Examples | RTF Documentation for more details about that demo RTF and other screenshots.

PDF Documentation

Using some RTF to PDF converter software (e.g. Adobe Acrobat PDFMaker), you can also produce a top quality PDF documentation from the RTF output generated with the PlainDoc.tpl main template.

Here is an example of the XML schema documentation in PDF format generated in that way (click on the screenshot to see/download the PDF file, 2.6 MB):

Such documentation can be used both for printing and publishing on the web.

3.  What XML Schemas you can document

Any XML schema projects

This XML schema documentation generator was designed to document any XML schema projects imaginable (see also below). The following features are most important for this:

Any XML schema size and number of components

Processing and documenting (correctly and reliably!) huge XML schemas containing thousands of components. Just look at some XML schema docs generated by our customers: This is real world stuff!

Support of any XML schema design patterns

Like a single XML schema describes the structure of infinite number of XML files, the structure of the same XML file could be described by a great (potentially infinite) number of XML schemas. All of those XML schemas would differ from each other by ways of how they are designed. Those ways are called “XML schema design patterns”. Some of them were given even special names: chameleon, russian doll, salami slice, venetian blind, etc.

When you design a schema, you definitely use some of those design patterns, even when you haven't heard of them. Simply, in that case you reinvent the pattern by yourself. When a schema is generated by some tool, it always follows a certain pattern.

So, how do all those design patterns differ from one another in respect of documenting them? Or asking it otherwise, what might be common?

If you look closely into this, you could notice that all XML schema design patterns come down to a few specifics, all of which can be addressed by a single documentation approach:

  • The entire XML schema is broken into a number of XSD files, some of which import/include others.

    You don't need to do anything special about this. Both <xs:import> and <xs:include> XSD elements are supported. All referenced schemas will be automatically loaded and documented.

    Moreover, using template parameters:

    you can even specificaly disable documenting of imported/included schemas (even though they will be processed still).
  • There are several XSD files and some of them redefine certain components declared within others.

    That is done using <xs:redefine> XSD elements, which are supported by XSDDoc very well!

    See: Features | XML Schemas | Processing/documenting of redefinitions

  • Some elements are declared locally. Such elements may share the same name, yet have different content models. Others may be absolutely identical (with equal names and based on the same global type), yet declared separately in numerous locations.

    If you document all of this straight (which is actually what all other known to us XML schema doc-generators do!), in certain cases you may get in your XML schema documentation a mess made of numerous repeating local element names, in which it could be difficult to find some useful information.

    This XML schema doc-generator provides two ways of dealing with that problem:

    1. Extension of Local Element Names

      When several locally declared elements have the same name but different content models, to distinguish them from one another across the documentation, the element names can be extended so us to make them unique. This is controlled by “Show | Local Element Extension” parameter.

      For more details, see Features | Local Elements | Global Naming of Local Elements.

    2. Unifying Local Elements By Type

      All those locally declared elements that share the same name and are based on the same global type (which means they have the same content model) can be represented and documented as a single entity called unified local element. That may substantially reduce and clarify the documentation!

      This is illustrated by two documentations generated from the same XML schema: http://www.w3.org/2001/XMLSchema.xsd

      On the left you can see the documentation generated with unifying local elements by type enabled. On the right, all local elements were documented straight, without any unification. Click on the screenshots to view the docs:

      The difference is quickly visible when you look at the navigation list (bottom-right frame) of both documentations.

      For further details, see Features | Local Elements | Global Documenting | Unifying Local Elements By Type.

  • Locally declared elements are used everywhere instead of attributes to hold simple data.

    Again, if you document it straight, various navigation lists and element summaries will get crowded with insignificant local elements, in which you may have trouble to find what you need.

    XSDDoc also provides a way to deal with this. The “Generate Details | Elements | Local Elements” parameter allows you to specify that all local elements with simple content should be documented only locally within the details of their parent elements.

    As an example, here are two documentations generated for the same little XML schema (from “Sales Report” sample). On the left is the documentation, in which only global elements and local elements with complex type are documented separately (globally). On the right, all elements are documented separately. Click on the screenshots to view the docs:

  • There are groups of globally declared elements that are referenced in the XML schema via single (abstract) elements representing any element in a group.

    Such groups of elements, called substitution groups, are specifically recognized and documented by XSDDoc.

    For example, the following “XML Schema for XSLT 2.0” (http://www.w3.org/2007/schema-for-xslt20.xsd) extensively uses substitution groups (click on the screenshot):

    See also: Features | Global Elements | Substitution Groups
  • The order in which elements/attributes are declared is important.

    Using the following template parameters you can preserve the original ordering of your elements/attributes at various locations of the documentation:

  • The XML schema declares a possible root XML element that needs to be highlighted in the documentation.

    In general, the W3C XML schema specification itself provides no functionality to assign which of the XML elements declared in an XML schema must be the root of any XML document that complies with that schema.

    However, you can solve this problem by placing the declaration of the root element the first in the XML schema.

    Further, when you generate documentation for that XML schema, unselect the “Generate Details | Sorting | Components” parameter so that the original order of element declarations will be preserved in the documentation.

    If your XML schema is broken into several XSD files, specify the one of them that contains the root element declaration to be processed the first by the generator (see also FAQ | How to generate a single documentation by multiple XML schemas?) and unselect the “Generate Details | Sorting | Schemas” parameter.

    That will ensure that the root element gets on the top of various navigation lists and summaries, which will highlight its special role.

Joint documenting of conflicting XML schemas

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.

Straight documenting of several conflicting XML schemas together will likely produce incorrect documentation. Some links from the references to global components defined simultaneously in different schemas would go to wrong locations. What's more, the content models of some components (as well as other things) may be derived incorrectly. As a result, the whole such a documentation may be almost unusable. Yet, those conflicting schemas themselves may be quite correct at that!

Since the version 2.6.0, XSDDoc is able to document correctly any number of conflicting XML schemas!

In short, this works as follows:

  1. Among all XML schemas initially specified for documenting, the main schemas are identified. These are the schemas that are not referenced from other schemas.

    Here, schema reference is any of the elements: <xs:import>, <xs:include> and <xs:redefine>

    Note that any conflicting schemas, if they are correct indeed, cannot reference to each other (both directly and indirectly)!

  2. The main schemas break everything into several domains adding to each name a sort extra “namespace”. This allows resolving global component references only within a particular main schema domain, which the given reference belongs to.
  3. Some XML schemas involved here may be those referenced from several conflicting schemas simultaneously. These must be some library schemas valid in all cases. For instance:
    <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.
  4. In the case of multi-file framed HTML documentation, if the names of conflicting XML schema files are repeating too, the components of those schemas will still be documented in separate subdirectories.

    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/

4.  XML Schema Documentation

Unlike various other XML schema doc-generators currently visible in Internet, which tend to produce a rather simple and obvious content not much more informative than the XML schema source itself, this XML schema doc-generator from the start was designed with a different focus.

We believe that a true XML schema documentation should allow the user to quickly find any necessary meaningful information about the XML schema, if only that information could be automatically obtained or deduced from it. (At that, everything must be accurate -- not just claimed to be there -- which in fact is not so simple to achieve!)

The following documentation features that we have worked out and supported could help to achieve that objective.

Features (How everything is documented)

This section is published on a separate page: DocFlex/XML | XSDDoc | Features. Here is its table of contents:
  1. XML Schemas
  2. Namespaces
  3. Components
  4. XML Source
  5. Annotations
  6. Simple Content
  7. Complex Content
  8. Types
  9. Global Elements
  10. Local Elements
  11. Attributes
  12. Global Groups

Organization (Documentation Structure)

This section is published on a separate page: DocFlex/XML | XSDDoc | Organization. Here is its table of contents:
  1. Main Blocks
  2. Framed HTML Documentation
  3. Single File Documentation

Examples

This section is published on a separate page: DocFlex/XML | XSDDoc | Examples. Here is its table of contents:
  1. HTML Documentation
  2. RTF Documentation
  3. Using XHTML in annotations

5.  How Documentation Generator Works

Template-Driven Architecture

This XML Schema Documentation Generator is implemented entirely as a set of XSDDoc templates using only generic capabilities of raw XML file processing supported by DocFlex/XML.

No Java code has been written anywhere specifically for the purpose of XML schema doc-generation! Neither any other XML processing technologies (e.g. XSL Transformations) are used anywhere in background!

What are Templates?

Please, see here:

Template Parameters

Since all the content and formatting of the generated documentation is programmed entirely within templates, the numerous options and switches, which normally control such things in traditional documentation generators, now simply become template parameters.

The XSDDoc templates provide great a lot of parameters (> 400), which make possible adjusting the content (and some formatting) of the generated XML Schema documentation within a huge range of details, starting from a few summaries and overviews up to the most comprehensive documentation containing every feature possible.

Template Designer

Using a visual graphic Template Designer, you can customize all “XSDDoc” templates as you need. In particular, you can easily translate any messages specified in the templates from English into your native language, insert your company logotype, change documentation design and content, extend with your own functionality and so on.

The following screenshot shows the contentElements.tpl template open in the Template Designer (click to see in full-size):

See Also: DocFlex/XML | Documentation | Designing Templates | Running Template Designer

"XSDDoc" Template Set

This section is published on a separate page: DocFlex/XML | XSDDoc | Templates. Here is its table of contents:
  1. Overview
  2. XML Type
  3. Main Templates
  4. Subtemplates
  5. Template Parameters

Generation of Diagrams

The XSD diagrams visible in all examples on this page have been actually generated not by DocFlex/XML.

However, DocFlex does support any kind of diagrams on the level of templates. Diagrams may be supplied also with hypertext imagemaps, which allow programming in templates the generation of diagram links to any parts of the documentation.

DocFlex treats diagrams as some kind of graphical representation of particular data source elements (DSM elements). Therefore, diagrams (along with the imagemaps) must come from the data source itself, via its driver. In the case of DocFlex/XML, the data source driver is basically a reader of XML files. But it can be configured with a special extension called Element Image Provider, which can generate some image representations (i.e. diagrams) for some XML elements. Those images are supplied together with the respective XML elements. So, they can be processed with templates (i.e. inserted in the output documentation).

How exactly the Element Image Provider produces the diagrams is beyond the DocFlex/XML core. It can be equally our own diagraming engine or an integration with some external system able to generate the necessary diagrams.

We do not have a diagramming engine yet. But we do have developed the integrations with several third-party XML editors able to generate the XSD diagrams. This includes:

The diagrams in the demo documentation have been generated via the integration with XMLSpy.

6.  Running Documentation Generator

Java Command Line

Please, see DocFlex/XML | Documentation | Running Generator | Launching Generator from Command Line

Generator GUI

Besides the possibility of running the generator from the command line and setting everything using command line options, DocFlex/XML also provides a little GUI that allows you to specify all the generator setting in a more user-friendly way.

Generator Dialog

When no -nodialog option is specified on the command line, the generator launches automatically the following Generator Dialog:
In the Generator Dialog, you can:

  1. Select the template (which determines what documentation you will generate).
  2. Specify the template parameters (see Parameter Inspector below).
  3. Choose the source XML files (in the case of XSDDoc, this will be XSD files).
  4. Assign one or more XML Catalogs (as an example of the XML schema that uses an XML catalog, see “XML Schemas for DITA 1.1”).
  5. Select the documentation output format.
  6. Specify the output format options (i.e. the generator settings special for that particular output format).
  7. Choose the destination folder and the main output file name for the generated documentation.
  8. Run the generator.
  9. View the generation progress.

Once you click the “Run” button, the dialog will transform itself to show the progress of the generation:

Parameter Inspector

To handle great a lot template parameters, which control XSDDoc templates, the generator provides a special GUI called Parameter Inspector.

The parameter inspector is invoked from the generator dialog by clicking “Params” button. Its content is created dynamically from the parameter definitions found in the template.

The following screenshot shows the Parameter Inspector dialog of FramedDoc.tpl template (click on the picture to see a more expanded view):

In the Parameter Inspector you can:
  • Edit each parameter according to its type.
  • View the parameter HTML description (it is also obtained from the template).
Once you have changed some parameters and closed the inspector dialog (with “OK” button), the new values will be stored (along with the parameter names) in the generator.config file. Further, the generator will use the parameter values found in that file. The same will happen when you open the Parameter Inspector dialog next time. The template parameters, whose names match those found in the generator.config file, will be initialized with the corresponding values from that file.

The parameters are organized in groups (which may contain subgroups and so on). A group heading may also be a parameter itself.

Each parameter group may appear in expanded or collapsed state like a tree node. The group states are also saved in the generator.config file to be restored again when the inspector is invoked next time for the same templates. Using inspector popup menu, you can quickly reset all parameters in a group to their default values.

Besides the Parameter Inspector dialog, you can always set any template parameters directly on the command line using -p option.

Using generator.config

The generator.config file allows you to combine interactive and command-line features together. Using -config option, you can provide on the command line a separate generator.config file, which will be used instead of the default one. With the Parameter Inspector you may interactively prepare all parameters needed for a specific kind of documentation. The parameters will be saved in this file. Further, you can use such a generator.config for generation (instead of specifying each time all needed parameter separately on the command line).

7.  Integrations

Integration

Annotation

Apache Ant You may easily run XSDDoc from your Apache Ant build project. No special plugin is required!
Apache Maven Running XSDDoc from Apache Maven is a bit more complicated. We had to develop a little “DocFlex/XML Maven Plugin” for this. Click on the link to see how to install and use it.
XMLSpy The integration with Altova XMLSpy will let you to automatically insert the graphics diagrams produced by XMLSpy into the XML schema documentation generated by XSDDoc (with full support of diagram hyperlinks).
Oxygen XML A similar integration with Oxygen XML Editor. It also inserts diagrams, however, now generated by OxygenXML.

Click on the link in the first column to see the integration details.

8.  How To Get Started

You can start generating your XML Schema documentation almost immediately. Just follow these steps:
  1. Download any of the editions of DocFlex/XML from the downloads page.
  2. Edit generator.bat to specify the 'JAVA_HOME' variable according to the location of Java 7, Java 6, Java 5 or Java 1.4.x installed on your system. (Java 7 may be preferable as it is the fastest!)

    If you don't have one of those Java versions installed on your system, you can freely download and install the most recent Java Runtime Environment (JRE) version from Java Technology web-site: http://www.oracle.com/technetwork/java/ (formerly http://java.sun.com)

  3. Run generator.bat. You will see the Generator Dialog like the one shown on this screenshot:

  4. In the “Template” field, select FramedDoc.tpl template to generate framed HTML documentation or PlainDoc.tpl template to generate single file RTF documentation.
  5. In the “XML File(s)” field, specify one or many XSD files from which you want to generate your XML schema documentation. When multiple files are specified, make sure that each pathname or URL is enclosed in double quotes.
  6. In the “Output format” field, select HTML or RTF format (RTF will work only with PlainDoc.tpl template!).
  7. Click “Run” button to start generator. For a very large XML schema (or, perhaps, on a slow computer), wait some time while the generator processes your schema.
  8. That's all. Enjoy the incredible quality XML Schema documentation you won't produce with anything else!

9.  What you need to license

Limited mode - Use it for free!

You can use the best quality XML schema documentation generator right now and absolutely free. Just download DocFlex/XML RE from the downloads page. No registration required! Then, follow the step described in How To Get Started.

By default, XSDDoc will work in limited mode under the Limited Free License.

This mode allows you to generate a complete framed HTML documentation (without diagrams) by any your XML schemas and use it for any purposes. There is no limitation on the number or content of the processed XML schemas!

In limited mode, however, you cannot (or may not) do the following things:

  • Almost all template parameters will be disabled, so there will be very few possibilities to customize the generated output.

    Hence don't be surprised that you may get too big (complete) documentation, which is not exactly what you want. That what you want may be possible too, most likely when all customization parameters are enabled. But you have to pay for this (see below).

  • The processing of XHTML tags in annotations (and, therefore, inserting of images) will not work. This is actually controlled by a template parameter, which is disabled in limited mode.
  • Each generated HTML file at the end will include some advertisement text, which you may not remove!
  • The PlainDoc.tpl template won't work. Therefore, you won't be able to generate single file HTML or RTF documentation.
Anyway, we believe, the framed HTML XML schema documentation generated in limited mode will be OK for those who just need to understand what a particular big XML schema describes (in fact, that's exactly how we ourselves frequently use this tool). Also, some XML schema authors may still be content with the produced result.

Full functionality - Pay only for what you need!

For professional users with complex requirements and serious demands, we offer three commercial products to enhance your XML schema toolkit. Please, see: DocFlex/XML | About | Commercial Licenses

10.  Does anybody use it?

Yes, they do! Here are a few links known to us: If you publish on the web an XML schema documentation generated with our tool and don't mind to be listed here, please let us know by sending an email to: contact@filigris.com or support@docflex.com

11.  Future Development

The following features are to be implemented (sooner or later):

  • Support of XSD 1.1

    It is the first thing we will do! That will be available since XSDDoc 3.0

  • Navigation menu in framed HTML

    The framed HTML XML schema documentation will include the full-blown navigation menu similar to that in classic JavaDoc.

    That will make the schema documentation more systematized and cleared up. Various trees, component usage reports etc. will get on separate pages, as it is in JavaDoc.

  • XML Schema Tree

    It will show which schemas import / include / redefine which (using the <xs:import>, <xs:include> and <xs:redefine> elements). That will give a single view of the entire XML schema project, when it is broken into a number of modules.

    That feature is what we are particularly missing ourselves. It is a very common situation, when you investigate a particular large XML schema project, the first thing you want to know is how those XML schema files involved in it are related to each other.

  • Global Type Hierarchy Tree

    The “Type Derivation Tree” is currently generated for each complex or simple type component being documented.

    The complete tree will include all those local trees as branches. It will provide a global view of how the global types defined in the XML schema are derived from each other.

  • Element Content Tree

    It will show for all XML elements defined in the schema which of them may contain which. Essentially, such a tree will represent a complete skeleton of a possible XML document described by the given XML schema.

Copyright© 2003-2014 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.