xfxDoc
The xfxDoc tool documents XML-schemas using the Altova XMLSpy XML-schema documentation format to produce Microsoft HTML Help documentation (.chm) files that feature auto-generated table-of-contents, index, and full-text search.
Links
Motivation
As the use of XML as the protocol for information interfaces is becoming more common and accepted in the industry, two important facts are emerging:
- The W3C consortium XML-schema or XSD-standard is the major standard for describing the structure and syntax of XML data.
- More than ever, these XML-schemas are becoming huge, complex and more resource-intensive, both in human- and computer- terms.
An important part of managing and utilizing large schema sets is to provide comprehensive and easy-to-use documentation describing the schemas. Altova XMLSpy provides a handy capability to do this, in both a Microsoft Word format and an HTML format. The advantage of the HTML documentation is that it can be easily published, as well as providing the following additional important advantages:
- The documentation provides XML-schema structure description using diagrams. The diagram constructs used have become a de-facto industry standard in terms of schema documentation. The HTML page also provides hot-spots within the diagrams that provide easy navigation between schema documentation constructs.
- The documentation text is easy to understand and is comprehensive.
- 'Type', 'Used By' and 'Children' sections provide easy navigation around the documentation in terms of parent-child relationships.
- Most importantly, the documentation is generated automatically, with very little user intervention.
However, when the schema(-sets) get moderately complex, the HTML documentation is inadequate, for the following reasons:
- The documentation takes the form of a single page, or sets of related pages, the size of which can easily be in excess of a few megabytes. This results in a slower loading page in the browser, the page navigation performance of the loaded page is poor, and the user experience is substantially degraded. For very large schemas, the page is often unable to load and even causes the browser to throw an exception.
- The documentation has a very simple indexing section at the top of the page, which is not efficient. It has no real table-of-contents, keyword index, or full-text search, which becomes more important as the size of the documentation increases.
How it works
The xfxDoc application takes as input the HTML page(s) generated by the XMLSpy XML-schema 'Generate Documentation' command, and outputs a fully-featured compiled HTML Help (.chm) file. Functionality includes:
- Utilizing the XMLSPY documentation 'standard' completely;
- Automatically executes XMLSPY via the XMLSPYLIB automation interface and generates documentation according to user-presets;
- Splits the generated single HTML documentation page(s) into separate HTML pages, one page per main topic;
- Builds an HTML Help table-of-contents (.hhc), and index (.hhk) file automatically from the schema construct type and construct name that it derives from the contents of each page;
- Rebuilds the HTML image hot-spot and text hyperlinks automatically to retain the original XMLSPY navigation capabilities;
- Uses a user-specified HTML Help project template (with replaceable parameters), to automatically generate the target HTML Help project file (.hhp) which can directly compiled;
- Automatically executes the Microsoft HTML Help Compiler (hhc.exe) to build the final .chm help file;
- Allows further enhancement to the generated documentation via user-coded plug-in assemblies.
The resulting HTML Help file is fully-featured, easy to navigate, and provides great performance.
xfxDoc is provided as a .NET Windows Forms application.
System Requirements
Your computer system requirements to execute this application are specified here.