FlexDoc/XML WSDLDoc, Version 1.2.5

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

What is WSDLDoc?

«FlexDoc/XML WSDLDoc» is a template application (template set) for FlexDoc/XML, which implements a powerful WSDL/XSD documentation generator able to document any number of both WSDL and XML schema (XSD) files as well as any interconnections between them.

WSDLDoc 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.

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

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

Content Files

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

File / Directory	Description
`README.html`	this file
`CHANGES.html`	change log of WSDLDoc 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 WSDLDoc template application.
`wsdldoc.xmltype`	The configuration file that defines the `'wsdldoc'` XML type, on which all WSDLDoc 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 WSDLDoc home directory: {flexdoc-xml}/templates/WSDLDoc/

NOTICE: Most of icons used by WSDLDoc, which are found in WSDLDoc/lib/images/ directory, have been borrowed from NetBeans. That is allowed by the CDDL license that covers NetBeans, as well as follows immediately from this explanation: http://wiki.netbeans.org/FaqUseOfImagesOtherPrograms.

Technical Requirements

Since WSDLDoc is just a set of templates (which are plain-text files), you can execute it only with the template processor (generator) included in FlexDoc/XML.

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

The execution of WSDLDoc heavily depends on the entire FlexDoc/XML Runtime Environment, which is everything found in '{flexdoc-xml}/lib/' directory. For instance, the whole data processing in WSDLDoc is based on the standard XML schemas for XSD 1.0 and WSDL 1.1. Those schemas are specified in wsdldoc.xmltype file and must be loaded each time when running WSDLDoc. But, of course, not from the Internet. Rather, local copies stored in {flexdoc-xml}/lib/resources/ directory are used. The default XML catalog {flexdoc-xml}/lib/resources/catalog.xml redirects the external schema URLs to those copies. Their integrity is critical for running WSDLDoc!

Licensing

WSDLDoc is a commercial template application developed by FILIGRIS WORKS. It is covered by a separate «FlexDoc/XML WSDLDoc» 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 WSDLDoc 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 WSDLDoc 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 WSDLDoc template set. In particular, you will be able to: Process any number of input WSDL/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 WSDLDoc templates to customize the generated WSDL/XSD documentation within a huge range of possibilities. Format your WSDL descriptions and 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 WSDLDoc 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 WSDLDoc. The WSDLDoc license does not cover: Template Designer: If you want to modify WSDLDoc templates, you will need an additional license for «FlexDoc/XML SDK». However, the full WSDLDoc 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 WSDLDoc, 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 WSDLDoc by this link: https://www.flexdoc.xyz/trial/?pid=flexdoc-xml-wsdldoc 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 WSDLDoc 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 WSDLDoc 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 WSDLDoc 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 WSDLDoc template set. In particular, you will be able to:

Process any number of input WSDL/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 WSDLDoc templates to customize the generated WSDL/XSD documentation within a huge range of possibilities.
Format your WSDL descriptions and 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 WSDLDoc 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 WSDLDoc.

The WSDLDoc license does not cover:

Template Designer: If you want to modify WSDLDoc templates, you will need an additional license for «FlexDoc/XML SDK».

However, the full WSDLDoc 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 WSDLDoc, 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 WSDLDoc 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 WSDLDoc in the directory:

{flexdoc-xml}/templates/WSDLDoc/

Actually, the WSDLDoc template application is quite autonomous. You can copy/move (or rename) the 'WSDLDoc/' directory to any other location and run the WSDLDoc 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 WSDLDoc.

Running WSDLDoc

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 WSDL / XML schema documentation, please follow these steps:

Run generator.bat found in {flexdoc-xml}/bin directory. You will see the generator dialog.

When running WSDLDoc templates for large projects (with many WSDL/XSD files or when they are large), 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/WSDLDoc' directory using File Chooser.
In «XML File(s)» field, specify one or many WSDL/XSD files, by which you want to generate the 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 WSDL/XSD 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 input data 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 WSDLDoc 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 three different diagramming plugins 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 WSDLDoc (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 WSDLDoc. 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 WSDLDoc. 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 | WSDLDoc
The most detailed and up-to-date information about WSDLDoc can be found on the product homepage: www.flexdoc.xyz/flexdoc-xml/wsdldoc/
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/WSDLDoc/CHANGES.html