The Virtuoso Documentation Project

The Virtuoso documentation was written completely in XML against the DocBook DTD with the intention of being able to render it in any format required. XSL was used to transform the documentation in HTML. PDF and PS versions were generated from the HTML version. At this time we are unable to produce a PDF directly from XML.

The XML and XSL source files were crafted by hand using straight text editor.

As the XML and XSL development progressed MS IE5.x was initially used as a reference for XML well formedness and XSL previewing. Using MSIE5.x makes development fairly quick and easy since you are able to drag and drop XML files straight into the browser. The default IE stylesheet produces a hierarchical tree of the documents elements and should a parse error be detected will attempt to display the significant line number where the error occured and normally works well. If an XSL stylesheet is referenced using the tag then IE will render the document using that stylesheet instead. This makes development as simple as change the document in a text editor, save, hit refresh in IE and see what happens.

When the XSL became fairly complex and made use of various methods for tracking positions and element counts IE started having some problems. At this point we moved to using XT from the James Clark XML site. This was a very late decision because in earlier days we found that the James Clark version was causing all the problems. Unfortunetaly the transition was not completely painless, IE and XT have different ideas about how to render entities which was initially very misleading. There also appears to be some problem with the stylesheet declaration. I think that IE actually has the bug this time. As a result the MS version has not been refined as much as the XT one. XT is primarily a Java program but a Win32 binary is also available.

An example of XT being used to render the Virtuoso Docs from the command line from the documentation root directory is:

	xt xmlsource\virtdocs.xml stylesheets\html_xt.xsl html\virtdocs_xt.html

The XML sources are validated against the DocBook DTD for XML maintained by Norman Walsh. The DocBook site contains extensive documentation and support regarding the project. You can also find an extensive collection of sample XSL for DocBook documents that render using James Clark's XT.

Note that the WebDAV resource of the demo database currently hosts a copy of the XML documentation sources. Currently IE sometimes seems to have a problem downloading the complete content of the DTD via HTTP. If you experience this then you may have to remove this reference.

HTMLDOC was used to generate the PDF and PS version of the Virtuoso documentation from the HTML generated documents. HTMLDOC is copyright 1997-2000 by Easy Software Products and is free software under GNU.

See also: Simple Readme for the Virtuoso Documentation Project