Geeks With Blogs
Willem's... {rue if I mellow}

spy.doc 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. By providing suitably coded plugins, the documentation output can be greatly extended and enhanced.

Features

  • Windows, Console and Launcher applications.
  • Uses an XML-base project file (extension .spydoc) which can be easily edited to change application and generation settings.
  • Generates complete XMLSPY® HTML documentation for XML-schemas in an HTML Help file format.
  • Provides the same documentation settings for schema construct type, and details as provided by XMLSPY®, and also the means to order the documentation sections differently on the HTML page to the standard order provided by XMLSPY®.
  • HTML Help file is automatically generated, with complete table-of-contents, HTML content page-title based indexing, and full-text search.
  • HTML Help file is high performance, as each content page corresponds to a documentation section in the original XMLSPY® HTML documentation file.
  • Page header and footer for documentation pages can be completely user-defined.
  • The HTML page style is generated in a separate style-sheet (.css) file, allowing the styles to be easily edited in one place.
  • A separate HTML page may be defined for the HTML Help file start-page and home-page.
  • The HTML Help project file is totally user-defined with replacable parameters that are provided by the application. The HTML Help project file is input into the application as a template, from which the target .hhp file is generated which can be directly compiled.
    Automatically generates H2 and SandCastle document set name tags, which can be used for document set filtering in combined help documentation sets.
  • Provides options to retain all intermediate and temporary files, and to generate only the HTML Help build files (.hhc, .hhk, .hhp) files, so that the .chm file can easily be rebuild without having to regenerate the entire documentation set.
  • Provides for the application of user-coded plug-ins to enhance and extend the existing documentation.
  • Can generate complete documentation for large schema-sets that cannot be generated directly in one iteration by XMLSPY®.
  • No restriction on the size of the documentation, other than that imposed by the HTML Help service itself.

Function

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.

Posted on Friday, January 19, 2007 8:25 AM .NET Adventures | Back to top


Comments on this post: spy.doc 2007.1 XML-Schema Documenter released (Freeware)

# re: spy.doc 2007.1 XML-Schema Documenter released (Freeware)
Requesting Gravatar...
Piece of shit crashes all the time. with no option to save...
Left by Pras Biswas on Jul 31, 2008 8:51 AM

# re: spy.doc 2007.1 XML-Schema Documenter released (Freeware)
Requesting Gravatar...
I am a bit fan for Altova, especially there differencing tool, however I have found that liquid xml is far stronger with core xml editing and validation of wsd files
Left by xml editor on Mar 22, 2011 10:55 AM

Your comment:
 (will show your gravatar)


Copyright © Willem Fourie | Powered by: GeeksWithBlogs.net