 DocFlex/XML - XSDDoc - XML Schema Documentation Generator
|
The fully functional XML Schema Documentation Generator described here
is included in all editions
of DocFlex/XML.
It is ready for free downloads and immediate use (no registration required).
As a freeware (that is without any special license),
you can use the XSDDoc templates to generate a complete XML schema documentation
(however, with few possibilities to customize it; see also limited mode).
Please note that much of the functionality we offer for free now you won't get from any other software vendor
even for money!
|
- What is DocFlex/XML XSDDoc?
- What you can generate with it
- Which XML Schemas you can document
- XML Schema Documentation
- How Documentation Generator Works
- Running Documentation Generator
- Integrations
- How To Get Started
- What you need to license
- Does anybody use it?
- Future Development
1. What is DocFlex/XML XSDDoc?
“DocFlex/XML XSDDoc” is a
commercial template application (template set)
of DocFlex/XML
that implements a very powerful XML Schema Documentation Generator in HTML and RTF output formats.
Currently, the XSDDoc template set is bundled with both editions of DocFlex/XML:
- DocFlex/XML SDK - the System Development Kit to design and run template applications
- DocFlex/XML RE - the free Runtime Environment to run template applications
You can find the XSDDoc templates
in 'templates/XSDDoc/' subdirectory of each edition.
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 both to the XML schema authors
(e.g. to publish the XML schema project on the web)
and to those who simply need to understand particular big XML schemas.
The framed HTML documentation can provide most detailed and easy accessible information about
all the XML schema components and interconnections between them.
The following screenshot shows such a documentation generated for “XML Schema for XML Schemas”
(directly from the file: http://www.w3.org/2001/XMLSchema.xsd).
Click on the screenshot to see the real HTML:
Look also at XSDDoc | Examples page to view/download
other demo HTML documentations
generated from various big 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, 1.9 MB):
Such documentation can be used both for printing and publishing on the web.
3. Which XML Schemas you can document
This XML schema documentation generator was designed to document any XML schema projects imaginable
(see also Support of any XML schema design patterns).
The following features are most important for this:
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 a lot more informative than the XML schema source itself,
this XML schema documentation generator from the start has 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, everyhting must be accurate -- not just claimed to be there -- which in fact is not so simple to achieve!)
The following documentation features, which we have worked out and supported,
could help to achieve exactly 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:
Organization (Documentation Structure)
This section is published on a separate page:
DocFlex/XML | XSDDoc | Organization.
Here is its table of contents:
Examples
This section is published on a separate page:
DocFlex/XML | XSDDoc | Examples.
Here is its table of contents:
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 the 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
(like XSL Transformations)
are used anywhere in background!
What are Templates?
Please, see:
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
(provided with the DocFlex/XML SDK),
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.
This picture shows the PlainDoc.tpl
template open with the Template Designer
under Linux and the generator dialog
invoked to generate with this template a sample XML schema documentation in RTF format
(click to see the full-size screenshot).
"XSDDoc" Template Set
This section is published on a separate page:
DocFlex/XML | XSDDoc | Templates.
Here is its table of contents:
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:
-
Select the template (which determines what documentation you are going to generate).
-
Specify the template parameters
(see Parameter Inspector below).
- Choose the source XML files (in the case of XSDDoc, this will be XSD files).
-
Assign one or more OASIS XML Catalogs v1.1
(as an example of the XML schema that uses an XML catalog, see
“XML Schemas for DITA 1.1”).
- Select the documentation output format.
-
Specify the output format options
(i.e. some generator settings special for the selected output format).
- Choose the destination folder and the main output file name for the generated documentation.
- Run the generator.
- View the generation progress.
Once you click the “Run” button, the dialog transforms itself to show
the progress of the generation:
Parameter Inspector
To handle great a lot template parameters that 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
Apache Ant
See: DocFlex/XML | Integations | Apache Ant
Apache Maven
See: DocFlex/XML | Integations | Apache Maven
XMLSpy
See: DocFlex/XML | Integations | XMLSpy
8. How To Get Started
You can start generating your XML Schema documentation almost immediately.
Just follow these steps:
-
Download any of the editions
of DocFlex/XML
from the downloads page.
-
Edit
generator.bat to specify the 'JRE' variable according
to the location of Java 6, Java 5 or Java 1.4.x installed on your system.
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 6.x
from Sun Java Technology web-site: http://java.sun.com
-
Run
generator.bat. You will see the Generator Dialog
like the one shown on this screenshot:
-
In the “Template” field, select
FramedDoc.tpl
template to generate framed HTML documentation or
PlainDoc.tpl
template to generate single file RTF documentation.
-
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.
-
In the “Output format” field, select HTML or RTF format
(RTF will work only with
PlainDoc.tpl
template!).
-
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.
-
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:
|
Product
|
Description
|
|
DocFlex/XML XSDDoc
|
A commercial license for “DocFlex/XML XSDDoc”
will unlock all fuctionality implemented in XSDDoc templates.
In particular, you will be able:
-
To use all parameters
(more than 350 now!) that control XSDDoc templates to customize the generated XML schema documentation
within a huge range of possibilities.
-
To use PlainDoc.tpl
main template to generate single file HTML
or RTF documentation.
-
To format your XML schema annotations with
XHTML tags
and reproduce that formatting both in HTML and
RTF output.
-
To inserting images
in your annotations using XHTML
<img> tags (supported both in HTML and RTF output).
-
To run any your custom templates derived from XSDDoc templates.
You can modify XSDDoc templates as much as you need using the
Template Designer
included in DocFlex/XML SDK
(provided you have a separate license for that product, see below).
|
|
DocFlex/XML XMLSpy
Integration
|
If you are already a user of
Altova XMLSpy®
(or may acquire it soon), we offer you to purchase an additional license
for the integration of DocFlex/XML with XMLSpy.
This will allow you to automatically insert the graphics diagrams produced by XMLSpy into
the XML schema documentation generated by DocFlex/XML XSDDoc
(with full support of diagram hyperlinks).
Together with the license for “DocFlex/XML XSDDoc”,
that will give you a fantastic XML Schema Documentation Generator with diagramming capabilities
no other single product is offering now!
|
|
DocFlex/XML SDK
|
This is a universal System Development Kit and Runtime Environment
for rapid development and execution of template-driven automatic documentation/report
generators by any data obtained from XML files.
In fact, the whole XML schema documentation generator described here
(DocFlex/XML XSDDoc) has been developed with this tool.
A commercial license for DocFlex/XML SDK
will give you the ultimate control over the XSDDoc template set:
-
Using the graphic Template Designer
included in DocFlex/XML SDK,
you will be able to customize whatever was impossible to do with only
template parameters.
-
Furthermore, basing on the standard XSDDoc
you could develop your own XML schema documentation generators, which would represent your XML schemas
in some very special way.
For instance, you may want to avoid in your documentation all those technical terms like
"namespaces", "AttributeGroups", "SimpleTypes" and "ComplexTypes" etc. and rather describe
everything defined in your XML schemas using the notions of a business language familiar to your customers.
The XML schemas aside, you can use DocFlex/XML SDK
to develop any other documentation/report generators from any data stored in XML files
(see also DocFlex/XML | Samples).
What's more, as soon as other our commercial template applications arrive (e.g.
WSDLDoc),
you could use your DocFlex/XML SDK license
to customize them as well.
|
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 gradually during 2010 (and later):
- Navigation menu in framed HTML
The framed HTML
XML schema documentation will include the full-blown navigation menu
similar to that
in classic JavaDoc.
-
Project Annotation
A new template component will be added:
Include Text Control,
which will allow dynamic inclusion in the generated documentation of the content of an external
plain-text or HTML file specified by a local pathname or URL.
This will be used in XSDDoc
to support specifying an external description/annotation file for the whole XML schema project
(the same as
-overview
option in Javadoc).
The content of that file will be included in the
Overview Summary
documentation.
- Dynamic hyperlinks in XML Schema annotations
A possibility will be supported to insert within XML schema annotations the in-line links
that point to the documentation generated for the specified XML schema components.
This will work essentially the same as the inline
{@link}
tags in Javadoc.
Within the schema annotations, such links will be defined using the
XHTML markup like this:
<a href="{@link ...}"> ... </a>
where the content of the href attribute will specify how
the actual hyperlink's destination must be generated.
The same will be supported for the hypertext imagemaps (those defined with the
<map> tags). This will allow you to enrich your XML Schema documentation with various
images and diagrams
depicting things that are directly hyperlinked to the details of the XML schema components
related to them.
- 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.
- 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.
- XML Schema Project Tree
That tree will show which schemas import, include and redefine other sub-schemas
(using the <xs:import>, <xs:include> and <xs:redefine> elements).
This will give a single view of the entire XML schema project when it is broken into a number of modules.
- Documenting of Notations
|
