All the documentation was written using noweb - a literate programming tool. Noweb allows you to mix code, and the text that describes what that code chunk does, in a single document. When noweb is run on that document the code chunks are extracted and arranged into your program and the documentation chunks are formatted into LaTeX. The LaTeX can then be turned into nice looking Postscript documentation or HTML. A good introduction was published in the Linux Journal in 1997. (Literate Programming Using Noweb, Linux Journal, October 1997, Issue 42, p64-69)

The HTML documentation here was produced automatically by noweb and has hyper-linked cross references and indexes to the code. There are a few small but obvious HTML glitches from the translation. It may take you a little while to work out where things are jumping to. If you want nice Postscript documentation you will find it in each of the complete tarballs. Download it from the Downloads Page.

DTD and Schema for CaveScript's CaveSurvey XML

CaveSurvey DTD/Schema Documentation: This HTML document describes the draft Document Type Definition and Schema for the CaveSurvey XML being developed by Mike Lake. Martin Laverty (see contacts page) has contributed by recasting my original DTD into a schema and this has now been moved into the same documentation as the DTD. These are still draft documents. If you don't know what a DTD or Schema is you will find this interesting but probably useless.

Current DTDs and Schemas
CaveSurvey.dtd: This is the CaveSurvey Document Type Definition.
CaveSurvey.xsd: This is the CaveSurvey schema.
CaveMap.dtd: This is the CaveMap DTD.

A DTD or schema, when used with a validating parser, can check that the XML document contains information that is correct and makes sense.

Example XML files
mysurvey.xml: is an example of a CaveSurvey XML file.

Utility Programs - Survex to/from XML

Survex-XML Documentation: This HTML document describes the Survex to XML (svx2xml) and XML to Survex (xml2svx) Perl scripts. There are some example Survex survey files and CaveMap XML files that will show clearly what XML is like.

Example XML Files
This is an example Survex file: example.svx
We can convert this to a poor but valid XML document with: svx2xml example.svx > example.xml
This is the converted example Survex file: example.xml

Taking full advantage of the CaveScript XML format the information would be encoded like: example2.xml

CaveView - A CaveMap XML to Postscript Converter

CaveView Documentation: This HTML document describes the CaveView program. This is a Perl script that reads a CaveMap XML file and creates a Postscript file for printing the cave map. You can edit the Survex data with a text editor, modifying shot angles and distances, then run "cv mycave" and watch the Postscript map update in Ghostview. Walls will follow the traverse lines.

Example XML Files
To see what the CaveMap XML files look like have a peek at the;
Cave Map XML: mycave.xml