spy.doc Function

Home ● Function ● Features ● License ● Download ● Online Help

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' and 'Used By' 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, 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.
• For many large schema-sets, it is impossible to generate the complete documentation, as XMLSPY® throws a memory exception and hangs up.

How it works

The spy.doc application takes as input the HTML page generated by the XMLSpy® XML-schema 'Generate Documentation' command, and outputs a fully-featured compiled HTML Help (.chm) file. spy.doc 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 into separate HTML pages;
• builds an HTML Help table-of-contents (.hhc), and index (.hhk) file automatically from the schema construct type and construct name that it derives 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 replacable 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;
• provides multiple XMLSPY® documentation sessions, if required, each session generating a section of the documentation. The documentation page is then split as before, then merged on a per-page basis to provide complete documentation HTML pages. These pages are then placed individually in the HTML Help file as before. Using this technique, it is possible to generate the complete documentation for large schema-sets successfully, when a single pass generation would cause XMLSPY® to fail as indicated above;
• 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.

spy.doc is provided as both a Windows application, and a Console application.