FlexDoc/XML XSDDoc, Version 2.9.5

What is XSDDoc?
Content Files
Technical Requirements
Licensing
Installation
Running XSDDoc
- Inclusion of diagrams
- Using azure-theme.css
Getting Help
Change Log

What is XSDDoc?

«FlexDoc/XML XSDDoc» is a template application (template set) for FlexDoc/XML that implements a high quality XML Schema Documentation Generator.

XSDDoc template set provides two main templates:

FramedDoc.tpl – to generate framed multi-file (Javadoc-like) HTML documentation
SingleDoc.tpl – to generate single-file HTML and RTF documentation

Main template is the one, which can be specified for interpretation directly to the generator (either with -template option on the Java command line or in the Generator Dialog). Effectively, each main template represents a separate documentation generator.

XSDDoc template set is included in FlexDoc/XML software archive and found in the directory: {flexdoc-xml}/templates/XSDDoc/

{flexdoc-xml} is a designation of your FlexDoc/XML installation directory, e.g.: C:\flexdoc-xml-1.13\

Content Files

The following files power XSDDoc (or are related to it):

File / Directory	Description
`README.html`	this file
`CHANGES.html`	change log of XSDDoc templates
`FramedDoc.tpl`	The main template to generate framed HTML documentation.
`SingleDoc.tpl`	The main template to generate single-file documentation (in HTML or RTF format).
`help/`	The descriptions of parameters of both main templates; used by the Parameter Inspector.
`lib/`	The directory containing all subtemplates (and icon files) that power the XSDDoc template application.
`xsddoc.xmltype`	The configuration file that defines the `'xsddoc'` XML type, on which all XSDDoc templates are based.
`css/azure-theme.css`	An alternative skin for HTML documentation (both framed and single-file). See: Using azure-theme.css

Note: All files and directories are located in XSDDoc home directory: {flexdoc-xml}/templates/XSDDoc/

Technical Requirements

XSDDoc is just a set of templates (which are plain-text files). To execute it, you always need the template processor (generator) included in FlexDoc/XML.

Please note that some general functionality (i.e. template language) used in a particular version of XSDDoc may be available only since the specific version of FlexDoc/XML. For instance, XSDDoc version 2.9.5 requires FlexDoc/XML version 1.13 or later.

The execution of XSDDoc heavily depends on the entire FlexDoc/XML Runtime Environment, which is everything found in the directory: {flexdoc-xml}/lib/

For instance, the whole data processing in XSDDoc is based on the standard XML schema for XSD 1.0 (http://www.w3.org/2001/XMLSchema.xsd), which is specified in xsddoc.xmltype file and must be loaded each time when running XSDDoc. But of course it is not loaded from the Internet. Rather, a local copy is used, which is stored in {flexdoc-xml}/lib/resources/ directory. The default XML catalog {flexdoc-xml}/lib/resources/catalog.xml redirects the external schema URL to that copy. Its integrity is critical for running XSDDoc!

Licensing

XSDDoc is a commercial template application developed by FILIGRIS WORKS. It is covered by a separate «FlexDoc/XML XSDDoc» license, which may be one of three types:

License Type Description

License Type	Description
Demo License	Once you have downloaded FlexDoc/XML archive, you can run XSDDoc immediately and see what it is. You don't need to request any trial and register anywhere! By default, everything will work in demo mode. It means that all your input XSD files will be fully processed, however fully documented will be only limited number of components. XSD diagrams will be generated as well by any diagramming plugin you choose (DiagramKit by default) and as many as it's allowed by XSDDoc demo limits. What exactly the demo limits are depends on a particular main template (as well as some metrics). If those limits are not reached, you will get the complete documentation. Otherwise, some content will be omitted and the message included saying which limits were exceeded. Anyway, the result documentation will be minimally distorted, to allow you to evaluate how everything will look under the full license. Any documentation generated in demo mode is yours. You may use it for free as you wish. See also: {flexdoc-xml}/LICENSE.html \| Demo License
Full License	The full (or commercial) license unlocks all functionality implemented in XSDDoc template set. In particular, you will be able to: Process any number of input XSD files and generate complete documentation by them in any supported output format. Use FramedDoc.tpl main template to generate framed HTML documentation. Use SingleDoc.tpl main template to generate single file documentation (HTML or RTF). Use all parameters controlling XSDDoc templates to customize the generated XML schema documentation within a huge range of possibilities. Format your XML schema annotations with XHTML tags and reproduce that formatting in both HTML and RTF output. Inserting images in your annotations using XHTML `<img>` tags (supported in both HTML and RTF output). Modify XSDDoc templates as much as you need using the Template Designer (provided you also have a separate «FlexDoc/XML SDK» license). Run any custom templates derived from XSDDoc. The XSDDoc license does not cover: Template Designer: If you want to modify XSDDoc templates, you will need an additional license for «FlexDoc/XML SDK». However, the full XSDDoc license does cover running such modifications. See also: {flexdoc-xml}/LICENSE.html \| Licensing of Templates \| Custom Templates XSD diagrams: Although the automatic insertion of component diagrams is fully supported by XSDDoc, the diagrams themselves must come from elsewhere. That's the job of the diagramming plugin, a separate (interchangeable) piece of software, which is licensed separately. See: Inclusion of diagrams See also: {flexdoc-xml}/LICENSE.html \| Full License {flexdoc-xml}/LICENSE.html \| Multiple Licenses
Trial License	The trial license is functionally the same as the full one. The difference is that: It is valid only during the limited period of time. Any output documents generated under a trial license will be specifically distorted by replacing some letters with shade ('░') characters (as well as contain special messages). Such documents may be used only for evaluation of FlexDoc software. Any other use is prohibited! You can obtain a trial license for XSDDoc by this link: https://www.flexdoc.xyz/trial/?pid=flexdoc-xml-xsddoc2 You can also request a trial of all FlexDoc/XML features (products) together by this link: https://www.flexdoc.xyz/trial/?pid=flexdoc-xml Then, you will receive a single `'flexdoc-xml.license'` file with the XSDDoc trial license already included in it. At that, you won't need to request any other trial licenses (e.g. for template designer or integrations). See also: {flexdoc-xml}/LICENSE.html \| Trial License

Demo License

Once you have downloaded FlexDoc/XML archive, you can run XSDDoc immediately and see what it is. You don't need to request any trial and register anywhere!

By default, everything will work in demo mode. It means that all your input XSD files will be fully processed, however fully documented will be only limited number of components. XSD diagrams will be generated as well by any diagramming plugin you choose (DiagramKit by default) and as many as it's allowed by XSDDoc demo limits. What exactly the demo limits are depends on a particular main template (as well as some metrics).

If those limits are not reached, you will get the complete documentation. Otherwise, some content will be omitted and the message included saying which limits were exceeded. Anyway, the result documentation will be minimally distorted, to allow you to evaluate how everything will look under the full license. Any documentation generated in demo mode is yours. You may use it for free as you wish.

Full License

The full (or commercial) license unlocks all functionality implemented in XSDDoc template set. In particular, you will be able to:

Process any number of input XSD files and generate complete documentation by them in any supported output format.
Use FramedDoc.tpl main template to generate framed HTML documentation.
Use SingleDoc.tpl main template to generate single file documentation (HTML or RTF).
Use all parameters controlling XSDDoc templates to customize the generated XML schema documentation within a huge range of possibilities.
Format your XML schema annotations with XHTML tags and reproduce that formatting in both HTML and RTF output.
Inserting images in your annotations using XHTML <img> tags (supported in both HTML and RTF output).
Modify XSDDoc templates as much as you need using the Template Designer (provided you also have a separate «FlexDoc/XML SDK» license).
Run any custom templates derived from XSDDoc.

The XSDDoc license does not cover:

Template Designer: If you want to modify XSDDoc templates, you will need an additional license for «FlexDoc/XML SDK».
However, the full XSDDoc license does cover running such modifications. See also: {flexdoc-xml}/LICENSE.html | Licensing of Templates | Custom Templates
XSD diagrams: Although the automatic insertion of component diagrams is fully supported by XSDDoc, the diagrams themselves must come from elsewhere. That's the job of the diagramming plugin, a separate (interchangeable) piece of software, which is licensed separately. See: Inclusion of diagrams

Installation

Since XSDDoc is a part of FlexDoc/XML software, you don't need to do anything special to install it. Once you have installed FlexDoc/XML, you will find XSDDoc in the directory:

{flexdoc-xml}/templates/XSDDoc/

Actually, the XSDDoc template application is quite 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.

Running XSDDoc

This section describes how to generate framed HTML documentation. To generate RTF documentation, you should do the same except: use SingleDoc.tpl (instead of FramedDoc.tpl) and select RTF format (instead of HTML).

To generate XML Schema documentation, please follow these steps:

Run generator.bat found in {flexdoc-xml}/bin directory. You will see the generator dialog.
While running XSDDoc templates for large XML schema projects, the template interpreter may require a lot of memory. The lack of memory may considerably slow down the generation (or even cause the OutOfMemory exception)! To avoid this, make sure the maximum heap size available for JVM is 512Mb or more (e.g. Java option -Xmx512m sets the maximum heap size to 512Mb). Note also that on 64-bit OS (running 64-bit Java), that amount should be doubled! So, on Windows 64-bit you should specify -Xmx1024m.
In «Template» field, select FramedDoc.tpl template.
You can choose this template from 'templates/XSDDoc' directory using File Chooser.
In «XML File(s)» field, specify one or many XSD files from which you want to generate the XML schema documentation.
This field must contain one or several file specifications, which may be either:
- local file pathname or pathname pattern
- URL (e.g. http://www.w3.org/2001/XMLSchema.xsd)
Notes:
- Multiple file specifications must be separated with spaces.
- When a file specification contains spaces itself, it must be enclosed in double quotes.
- You can combine any specification types together.
- The "pathname pattern" is an Ant-style pattern for local file pathnames. See: Docs | FlexDoc/XML | Documentation | Running Generator | ... | Using file pathname patterns.
- In case of URL, the generator will try to download such a file directly from the Internet (or elsewhere). This, however, can be redirected using an XML catalog. See: Docs | FlexDoc/XML | Documentation | Running Generator | ... | Assigning XML Catalog(s).
In «Output format» field, select HTML format.
The FramedDoc.tpl main template can generate only framed HTML documentation!
Click «Run» button to start the generation.

Once all source XML Schema files are loaded, the generator enters into the estimation phase. Lots of 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 passes 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.

Inclusion of diagrams

Although XSDDoc does implement the automatic insertion of XSD diagrams (along with diagram hyperlinks) in the generated documentation, the diagrams themselves are generated by a special diagramming plugin (covered by its own license). FlexDoc/XML currently includes a single diagramming plugin able to generate XSD diagrams:

Diagramming Plugin	Description
DiagramKit	The native diagramming engine of FlexDoc/XML. It creates beautiful XSD diagrams that can be generated simultaneously along with (and inserted into) the documentation generated by XSDDoc (with the support of all possible hyperlinks). This diagramming plugin is activated by default. You don't need to setup anything. See: Docs \| FlexDoc/XML \| DiagramKit

Using azure-theme.css

The file azure-theme.css is a CSS style sheet that implements an alternative skin (look & feel) for HTML documentation generated by XSDDoc. It is applicable with both FramedDoc.tpl and SingleDoc.tpl main templates. (You can use it also as a base for your own customizations.)

To apply azure-theme.css, please follow the same steps as described in Running XSDDoc. On the step of selecting HTML format, click «Options» button and in the HTML Options dialog, which should appear, specify:

Output | Generate named rules = all
Output | Generate named rules | Custom rules file = azure-theme.css path name

Then, close that dialog by <OK> and proceed with other steps.

Notes:

The possibility to use any CSS stylesheets is available only under the «FlexDoc/XML SDK» license.
For more details about custom CSS, please see: Docs | FlexDoc.XYZ | Documentation | Usage of CSS in generated HTML

Getting Help

Docs | FlexDoc/XML | XSDDoc
The most detailed and up-to-date information about XSDDoc can be found on the product homepage: www.flexdoc.xyz/flexdoc-xml/xsddoc/
General support information: www.flexdoc.xyz/support/
User support forum (free to everyone): https://www.flexdoc.xyz/forum/
You can also send any your questions by e-mail to: support@flexdoc.xyz

Change Log

Please see: {flexdoc-xml}/templates/XSDDoc/CHANGES.html