DocFlex/XML - XML Schema Documentation Generator and Toolkit

a powerful multi-format xml schema (xsd) documentation generator and a tool for rapid development of custom xsd documentation generators according to user needs.

about docflex/xml "xsddoc" template set template processor template designer integrations generation of xsd diagrams apache ant & maven links

about docflex/xml

docflex/xml is a java-based software system for development and execution of high performance template-driven documentation generators from any data stored in xml files.

the actual doc/report generators are programmed in the form of special templates using a graphic template designer , which represents the templates visually in a form resembling the output they generate. further, the templates are interpreted by a template processor , which takes on input the xml files and produces by them the result documentation.

this article describes an application of docflex/xml for the task of generation of high-quality xml schema documentation. that includes the following features of docflex/xml system:

1. " xsddoc " template set that implements the ready-to-use xml schema documentation generator itself.
2. template processor makes the templates works. currently, it provides three interchangeable output generators for html, rtf, txt (plain text) formats.
3. template designer provides a high quality gui to design/modify templates. if you need a special xml schema doc generator, the simplest way to create it is to modify the standard xsddoc templates. the template designer enables you to do that.
4. integrations with altova xmlspy and oxygen xml editor . if you are a user of one of those popular xml editors, you can turn it also into a dynamically linked diagramming engine for docflex, so that to include automatically the xsd diagrams generated by xmlspy/oxygenxml into the xml schema documentation generated by docflex (with the full support of hyperlinks).

"xsddoc" template set

it is the implementation of xml schema documentation itself, which provides the following functionality:

• generation of single documentation by any number of xml schema (xsd) files together, in particular:
  • highly navigable framed (javadoc-like) html documentation

    

  • single-file html documentation
  • rtf documentation (further convertible to pdf)

• processing of any referenced xml schemas, in particular:
  • correct processing of all <xs:import> , <xs:include> , <xs:redefine> elements found across all involved xsd files.
  • automatic loading and processing (i.e. inclusion in the documentation scope) all directly/indirectly referenced xsd files.
• sophisticated documenting of xsd components , including:
  • component diagrams (with hyperlinks to everything depicted on them; see also integrations )
  • xml representation summary (a textual alternative to diagrams)

    

  • lists of related components. for elements this includes also the list of possible containing elements . (such a list is never present in the output generated by xslt-based doc generators).
  • list of usage locations
• support of any xml schema design patterns . this comes down mainly to the following:
  • special treatment of local elements (see below)
  • support and documenting of substitution groups
  • support of importing, inclusion and redefinition of schema files
• special documenting of local elements .

  local elements are those <xs:element> components that are declared locally within other xsd components. w3c xml schema spec allows you to declare any number of local elements that may share the same name but have different content. that's because their meaning is local and there will be no collisions with other declarations.

  that, however, creates a problem for documenting, because in a documentation both global and local elements may appear simultaneously in various lists according to their common properties. if each element component is identified only by its name, you will get the lists with multiple repeating names but little clue what they mean. moreover, some xml schemas may contain lots of identical local element declarations (that is, they have the same both name and content). so, you'll get in those lists a mess of repeating names, some of which referencing to effectively the same entities, whereas others to complete different ones.

  in xsddoc , those problems are solved in two ways:

  1. adding extensions to local element names.

     the extension provides more information about the element (e.g. where it can be inserted or its global type or where it is defined). that makes the whole string identifying the element unique. here is how it looks. the grey text is the name extension:

     

  2. unifying local elements by type.

     on the left you can see a documentation generated with such unification. on the right, all local elements are documented straight as they are. click on each screenshot to view the docs:

     we believe the first documentation (on the left) is easier to understand and use.

• processing of xhtml markup .

  you can format your xml schema annotations with xhtml tags, which will be recognized and rendered with the appropriate formatting in both html and rtf output, as shown on the following screenshots (click to see more details):

  here, on the left you can see the xml source of an xml schema, whose annotations are heavily laden with xhtml markup (including insertion of images). the next is the html documentation generated by that schema. on the right is a page of rtf documentation also generated by that schema.

• possibility of unlimited customization :
  • xsddoc is controlled by more than 400 parameters, which allow you to adjust the generated documentation within huge range of included details.

    template parameters serve the same role as options in traditional doc generators. the difference is that docflex template architecture makes the support/implementation of template parameters very cheap (typically, the most of efforts takes writing their descriptions). so, there may be hundreds of parameters controlling a large template application.

  • if parameters are not enough, you can modify the templates themselves using the template designer .
  • in case of html output, you can also apply your own css styles to change how the generated documentation looks.

template processor

the template processor (also called simply "generator") makes everything work. it consists of two logical parts:

1. template interpreter
2. output generator

the output generator actually has three different implementations for each currently supported output format: html, rtf, txt (plain text). the plain-text output can be used to generate documentation in formats not supported directly by docflex.

the template processor is started directly from java command line with the following arguments:

● main template
● template parameters
● initial xsd files to be processed (documented)
● xml catalogs (to redirect physical location of input files)
● destination directory/file
● output format (this selects which output generator will be used)
● output format options (specify settings to control the selected output generator)

actually, the number of settings may be so large that the template processor provides a special gui to specify everything interactively (click to enlarge):

template designer

although docflex templates are stored as plain-text files (with an xml-like format), they are not supposed for editing manually. rather, a special graphic template designer must be used, which visualizes the templates in the form of template components they are made of. those components are the actual constructs of the template language (not some textual statements, operators, blocks etc.)

the following screenshots show templates open in the template designer (click to see a lot more):

that approach has a number of advantages, among them:

• the processing structures represented by template components may be displayed in a way that visually expresses what a component does (for instance, it may resemble the output it generates). that representation may be both expressive and compact (after all, it is not just a text), which allows you easily to navigate a template, understand what it does and modify anything you need.
• as template components are visual and interactive, they may have very complex internal structure, for instance, contain lots of properties and nested components. at that, you don't need to scroll and navigate some kind of enormous text, which encodes all of this (as it would be in case of a script). rather, you just need to invoke some property dialogs and expand/collapse some component sections.
• a template component may be easily copied, pasted and deleted as a whole. at that, you don't need to bother that the template syntax is restored after that. the template designer will also ensure that each component is created, copied or moved only in the allowed place.
• the highly structured nature of templates eliminates the need for most of various named identifiers. many connections between different template components are also maintained by the template designer (i.e. modified automatically when necessary).
• as template files are stored and read only programmatically, there is no need to know and understand their syntax. there will be no syntax errors either.
• the actual syntax of template files may be optimized not for human programmers, but for faster loading and processing of templates by the template processor . there is no need in a compilation phase.
• the separation of template semantics from the particular structure of template files helps for faster and easier evolution of the template language. the obsolete constructs of older template versions can be automatically converted into new structures. both old and new templates will look and work up-to-date.

integrations

generation of xsd diagrams

docflex/xml is able to work with any kind of diagrams (i.e. inserting them automatically in the generated output). that is supported on the level of templates, along with the generation of hypertext imagemaps, as shown on the following screenshot (click to see a lot more):

docflex/xml provides no diagramming engine of its own. instead, it includes integrations with two most popular xml editors that do generate xsd diagrams:

● altova xmlspy
● oxygen xml editor

effectively, the third-party software is used as dynamically linked diagramming engine. the advantage of such integrations is that when you are the user of one of those xml editors, you will get in the documentation generated by docflex the same diagrams as you see in your xml editor.

here is how such a documentation with diagrams looks (click on a screenshot to view the real html):

apache ant & maven

as a pure java application, docflex/xml can be run in any environment that runs java itself. the template processor can be easily integrated with ant (that can be specified just in the ant build file). in case of maven, docflex/xml includes a simple maven plugin. it is possible also to use all diagraming integrations with both ant and maven.

links

docflex/xml (home page):		http://www.filigris.com/docflex-xml/
docflex/xml xsddoc:		http://www.filigris.com/docflex-xml/xsddoc/
xsddoc examples:		http://www.filigris.com/docflex-xml/xsddoc/examples/
xmlspy integration:		http://www.filigris.com/docflex-xml/xmlspy/
oxygenxml integration:		http://www.filigris.com/docflex-xml/oxygenxml/
free downloads:		http://www.filigris.com/downloads/
this original article:		http://www.filigris.com/ann/docflex-xsd/