Documentation
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