This document details the CaveScript Document Type Definitions (DTDs) for cave surveys and cave maps. There are two DTDs:
The CaveSurvey DTD in Section [->] defines the XML structure which describes cave survey data; the stations and their descriptions, shots, instruments, surveyors and hopefully everything that you would want to include in a cave survey. One might describe these things as the abstract, non-natural things about a cave survey.
The CaveMap DTD in Section [->] defines the XML structure which describes the objects in a cave which may appear on cave maps such as the walls, floor and roof features, speleothems, biota, geology etc. These are the things that you see in a cave, both natural and artificial.
The change history and version information for CaveSurvey DTD and CaveMap DTD can be found at the start of Part I and Part II respectively.
noweb Usage
Table [->] shows the noweb commands used to extract the code
and documentation. The options supplied to noweb are listed in
Table [->]. The Makefile is a more convenient way to
perform the same tasks and is covered on page [->].
| To create: | Run: |
| Makefile: | notangle -t4 -RMakefile DTD.nw > Makefile |
| CaveSurvey DTD: | notangle -t4 -Rcavesurvey.dtd DTD.nw > CaveSurvey.dtd |
| CaveMap DTD: | notangle -t4 -Rcavemap.dtd DTD.nw > CaveMap.dtd |
| Example XML file: | notangle -t4 -Rmysurvey.xml DTD.nw > mysurvey.xml |
| Example XML file: | notangle -t4 -Rmymap.xml DTD.nw > mymap.xml |
| LaTeX documentation | noweave -t4 -delay -index DTD.nw > DTD.tex |
latex DTD.tex | |
| HTML documentation | noweave -html -filter l2h -x DTD.nw | htmltoc > DTD.html |
| All the files: | noweb DTD.nw
|
| notangle/noweave options | |
| -t4 | Copy tabs untouched from input to output, and use tabs for indentation. |
| Tabs get set to 8 by default in noweb. | |
| -R | extracts root chunk from noweb file |
notangle/noweave usage
[*]
Defined chunks in this noweb document are listed in Section [->].
Throughout the dvi and Postscript documentation you will see that each chunk of code is uniquely identified by a page number and an alphabetic sub-page reference. An example is:
10b <cavesurvey.dtd 9>+=== (15) 10a 11
This line tells us that we are now in code chunk 10b. This code chunk is on page 10 and it is the second code chunk defined on this page.
The construct <cavesurvey.dtd 9>+=== tells us that we are in a code chunk called cavesurvey.dtd, that its definition began in chunk 9 and the +=== means we are adding to its definition (noweb concatenates definitions with the same name in order of appearance).
At the right margin we find: (15) 10a 11
This tells us that the chunk we're defining is used within chunk 15, and that this current chunk is continued from chunk 10a and is continued in chunk 11.
At the end of each code chunk a %def is be used to define any variables within that code chunk that we want to cross reference. These defined variables get listed in the noweb index with a page number to where they were defined. The LaTeX hyperref package is being used so this page number will be a hyperlink and show as underlined.
Any defined variables enclosed in double square brackets like this
[[variable]] in the documentation text becomes a hyperlink,
again to the place where that variable is defined.
The following Makefile provides a convenient way to create or update the code
or documentation after modifications to the noweb source file rather than
typing all the notangle or noweave commands. Code or documentation
changes are done by making the modifications in the noweb source file and
running the appropriate make command.
To extract the Makefile:
notangle -t4 -RMakefile DTD.nw > Makefile
Run ``make help'' to see what options there are.
For instance, after making changes to any of the DTD's via the
noweb source file I run ``make dvi'' to see my changes in xdvi or
do a ``make DTD'' to create the up-to-date DTD's. One generally never
changes the output files directly (except for quick hacks).
<Makefile>=
#################################################################
# Makefile for creating CaveScript DTD's and their Documentation
#################################################################
# The noweb source file
NOWEB_SOURCE = DTD.nw
# If the user just types 'make' with no args then help, being the
# first routine will be invoked.
help:
@echo 'Usage: make [dtd examples dvi ps html all clean]'
# Create DTDs
dtd: $(NOWEB_SOURCE)
@echo 'Creating CaveSurvey.dtd and CaveContent.dtd ...'
notangle -t4 -Rcavesurvey.dtd $(NOWEB_SOURCE) | cpif CaveSurvey.dtd
notangle -t4 -Rcavemap.dtd $(NOWEB_SOURCE) | cpif CaveMap.dtd
# Create examples
examples: $(NOWEB_SOURCE)
@echo 'Creating example XML files ...'
notangle -t4 -Rmysurvey.xml $(NOWEB_SOURCE) | cpif mysurvey.xml
notangle -t4 -Rmymap.xml $(NOWEB_SOURCE) | cpif mymap.xml
# Create documentation
dvi: $(NOWEB_SOURCE)
noweave -t4 -delay -index $(NOWEB_SOURCE) >| DTD.tex
@echo
@echo 'Running "latex DTD.tex" ...'
latex DTD.tex
@echo
@echo 'You may need to run latex again.'
@echo
@echo 'latex DTD.tex'
@echo
ps: dvi
dvips DTD.dvi -o DTD.ps
html: $(NOWEB_SOURCE)
noweave -html -filter l2h -index $(NOWEB_SOURCE) | htmltoc >| DTD.html
all: dtd ps html
clean:
lintex
The CaveMap DTD defines the XML structure for Cave Map XML documents.
Cave Map documents use XML tags to encapsulate just about everything that we might wish to include on a cave map. Things such as wall detail, avens and cross sections, floor deposits, speleothems, text and even artistic elements such as shading and textures. The DTD for Cave Map XML fully describes these elements and how they can be used.
Information that is not included within the cave map document is the survey data. This is in cave survey XML files and is linked to via XML Xpointers and Xlinks.
The version number here must match the latest version number in the change history below.
<cavemap version>= (U->) <!-- Version number of this CaveMap DTD --> <!ENTITY % version "0.1">
Date Version Change 01 Jan 2000: 0.1
Some comments are inserted at the start of the DTD files so that I'll know where these files came from.
Inserted at the start of the files is:
<cavemap preface>= (U->) <!-- DTD for the CaveScript CaveMap XML --> <!-- Author: Michael Lake, Mike.Lake@uts.edu.au --> <!-- This file is generated from noweb source file DTD.nw -->
<cavemap.dtd>= [D->] <cavemap preface> <cavemap version>
<cavemap.dtd>+= [<-D->] <!-- ============ Root Element Name and Content ============ --> <!ELEMENT CAVEMAP ( HEAD ) >
DefinesCAVEMAP(links are to index).
An alternative CaveMap DTD would be the following:
<cavemap2.dtd>= <!DOCTYPE CAVEMAP [ <!-- ============ Cave Map DTD ============ --> <!ENTITY % CAVESURVEY SYSTEM "cavesurvey.dtd"> <!ENTITY % CAVECONTENT SYSTEM "cavecontent.dtd"> <!ENTITY % CAVESTANDARD SYSTEM "asf.dtd"> %CAVESURVEY; %CAVECONTENT; %CAVESTANDARD; ]>
where the cave survey, the contents of the cave and the cave mapping standards were all separated.
All XML documents begin with the XML declaration and optionally a Document Type
Definition which can be used to validate the document. Note that this DTD is
different to the CaveSurvey DTD. The root element is
CAVEMAP.
<mymap.xml>= <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE CAVEMAP SYSTEM "CaveMap.dtd"> <CAVEMAP> <mymap.xml east> <mymap.xml west1> <mymap.xml west2> <mymap.xml loop> <mymap.xml avens> </CAVEMAP>
The HEAD element provides identifying information on the map.
This would contain all the information that would normally be written in
the title block of a cave map.
<cavemap.dtd>+= [<-D->] <!-- ============ Title Black Information ============ --> <!ELEMENT HEAD (TITLE, AREA, CAVE, DATE?, INSTRUMENTS, DRAWERS) >
DefinesHEAD(links are to index).
An example of a title block is as follows:
| W31 Sigma Cave |
| Wombeyan Caves NSW |
| Surveyed 1980 to 1999 by SUSS |
| Surveyors: ... |
| Drawn by M. Lake, P. Maynard 1999 |
| Scale of original 1:200 |
| Grade ASF 54 |
| Date |
| Map No. 2W356 |
| Surveyed length Surveyed depth |
Maps may also include the survey shots or legs, the data for which may be in CaveScript files.
The following declares the element and attribute structures.
<cavemap.dtd>+= [<-D->]
<!-- ============ Passage Walls ============ -->
<!ELEMENT WALL ( DATA+ ) >
<!ATTLIST WALL
NAME CDATA #IMPLIED
>
The following declares the element and attribute structures.
<cavemap.dtd>+= [<-D->]
<!ELEMENT DATA (#PCDATA) >
<!ATTLIST DATA
REF CDATA #REQUIRED
>
The simplest wall is described by a WALL element which contains at least one
DATA element. The content of the data element in its simplest form is
a sequence of real numbers which are the (x,y) coordinates of points on the
wall of the cave, measured with respect to the adjacent survey leg. The
REF attribute tells us the from station and the to
station of this leg.
<mymap.xml east>= (<-U)
<WALL NAME="Southern end of Eastern Wall">
<DATA REF="85,86"> 1.0 0.0 1.0 4.0 0.7 6.0 1.0 8.0</DATA>
<DATA REF="86"> 0.0 0.0 </DATA>
</WALL>
<WALL NAME="Northern end of Eastern Wall">
<DATA REF="86,87"> 0.0 0.0 0.2 1.0 0.5 2.0 0.3 3.0</DATA>
<DATA REF="87"> 0.3 0.0 </DATA>
<DATA REF="87,88"> 0.3 1.0 0.4 2.0 0.5 3.0 0.0 6.0</DATA>
<DATA REF="88,89"> 1.0 1.0 0.6 2.0 </DATA>
<DATA REF="89,90"> 0.5 0.0 0.4 3.0 </DATA>
</WALL>
Note that the two wall sections here will be connected as one ends at (0,0) wrt 86 and the other begins at (0,0) wrt 86. However the join is not smooth (ie. it's derivative is not a contiguous curve).
The x_i values are the distances measured perpendicular to the survey leg, the y_i are how far along the survey leg the perpendicular is starting from the from station (see Figure [->]). That means that the y value at the from station is zero and the y value of the to station is the same as the shot length.
(40,40)(70,70)(80,70) (80,70)(90,70)(100,120)
Relationship of the cave wall coordinates and the survey leg [*]
Looking along the survey leg from the from station to the to station distances to the left are defined to be negative and distances to the right to be positive.
In the example above the wall coordinates are with respect to the survey leg from station 85 to station 86. A distance of 0.0m along from stn 85 and -0.81m perpendicularly to the left is a wall point. The next point is 1.0m along and 1.01m to the left. Note that this is just the L measurement amoung the LRUD data if this was recorded with the survey data.
The (x_i, y_i) coordinates are sequential values which need to be joined together by a cave mapping program using splines, beziers or other means to form the cave wall on a screen or in a Postscript file.
To understand the difference between measured wall distances and fudgeable distances consider a typical cave survey where one has recorded with a tape the LRUD distances at the from and to stations. The wall shape was also draw on graph paper while in the cave. When one comes to draw up the map tape measured distances were accurate to 5cm but the wall detail from the graph paper depends on the drawing skill of the drawer.
"Northern end of Eastern Wall" has a coordinate at (0.4 3.0) wrt 89,90 and the "Northern end of Western Wall", (-0.8 3.0) wrt 89,90
<mymap.xml avens>= (<-U)
<AVEN>
<!-- An aven is closed by definition -->
<DATA REF="89,90">-0.8 3.0</DATA>
<DATA REF="90"> -0.7 0.0 -0.5 0.5 0.0 0.8 </DATA>
<DATA REF="89,90"> 0.4 3.0</DATA>
<DATA REF="90"> 0.3 -0.3 -0.2 -0.4</DATA>
<DATA REF="89,90">-0.8 3.0</DATA>
</AVEN>
The start of the North Western Wall at (-0.1 0.0) wrt 88a,88 must be linked to the start of Western Loop at (-0.4 0) wrt loop.1 (see the example survey on page [->]).
The start of North Western Wall can be given as an XPointer using the syntax:
root().child(all, WALL, NAME, "Western Loop")
.child(1, DATA)
This selects the first DATA element within the Western Loop wall.
Similarly we can select the first DATA element in the tight loop section,
west side:
root().child(all, WALL, NAME, "Tight loop section, west side")
.child(1, DATA)
Two situations can occur when just two walls join; an obtuse angle or an acute angle.
<mymap.xml west2>= (<-U)
<WALL NAME="Northern end of Western Wall">
<!-- The 1st point here joins to 1st point in loop section, west side. -->
<!-- Start from "loop.1" -->
<DATA REF="loop.1">-0.4 0.0</DATA>
<!-- Original data below -->
<DATA REF="88a,88"> -0.1 0.0 -0.25 1.0 -0.5 1.5</DATA>
<DATA REF="88,89"> -0.5 0.5 -0.5 1.0 -0.6 2.0</DATA>
<DATA REF="89,90"> -0.5 1.0 -0.6 2.0 -0.7 2.5 -0.8 3.0</DATA>
<XSPLINE>0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0</XSPLINE>
</WALL>
<mymap.xml loop>= (<-U)
<WALL NAME="Tight loop section, west side">
<!-- The 1st point here joins with 1st point in North West Wall -->
<DATA REF="loop.1">-0.4 0.0</DATA>
<DATA REF="loop.2">-0.4 0.0</DATA>
<DATA REF="loop.2,loop.3">0.5 1.5</DATA>
<DATA REF="loop.3">-0.8 0.0</DATA>
<DATA REF="loop.4">-0.4 0.0</DATA>
<!-- Here is where we join it to a point on -->
<!-- "Southern end of Western Wall" -->
<DATA REF="85,86">-0.7 6.0</DATA>
</WALL>
<WALL NAME="Tight loop section, east side">
<DATA REF="88,88a">-0.15 1.6</DATA>
<!-- Original data below -->
<DATA REF="loop.1,loop.2">-0.2 0.0 -0.2 3.3</DATA>
<DATA REF="loop.2,loop.3">-0.2 0.2 -0.2 3.3</DATA>
<DATA REF="loop.3,loop.4">-0.2 0.2 -0.2 2.8</DATA>
<!-- Here is where we join it to a point on -->
<!-- "Southern end of Western Wall" -->
<DATA REF="85,86"> -0.8 7.0</DATA>
</WALL>
<mymap.xml west1>= (<-U)
<WALL NAME="Southern end of Western Wall">
<DATA REF="85,86"> -1.2 0.0 -0.9 2.0 -1.0 4.0 </DATA>
<DATA REF="85,86" STYLE="drop"> -0.7 6.0 -0.8 7.0 -1.0 8.0 </DATA>
<DATA REF="86"> -1.3 1.0 </DATA>
<DATA REF="86,87"> -1.2 1.2 -0.8 2.0 -1.0 2.5 -0.3 3.0</DATA>
<DATA REF="87"> 0.0 0.0 </DATA>
<DATA REF="87,88"> -1.0 1.0 -1.0 1.5 -1.3 2.5 -0.7 3.5</DATA>
<DATA REF="87,88"> -0.2 5.7 </DATA>
<DATA REF="88,88a">-0.2 0.7 -0.2 1.0 -0.15 1.6 </DATA>
<XSPLINE>0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0</XSPLINE>
</WALL>
Special effects covers things such as fractal wall outlines, shadows and ``outside-wall halftoning''.
<WALL STYLE="dotdashdot" WIDTH="2"/>
Any combination of ``dot'' and ``dash'' can be used. Can I use ``.-.-'' or ``..-..-''?
<SHADOW SUN="90"/> ie bearing of where the sun shines from.
<SHADE attrib="value"/> ie like what SSS did with the Bungonia maps
The actual appearance of the walls drawn by the viewer could utilise a fractal dimension of say 0.43 and the random seed value of 23425 (seed value [0, 65000]).
<FRACT DIM="0.43" SEED="23425"/>
Information on the history of the cave pertaining to people ie not geological history. This would include say discovery date, discoverers etc.
Probably Xlink to another XML file eg. "mymap_history.xml"
<cavemap.dtd>+= [<-D] <!ELEMENT HISTORY (#PCDATA)? >
<mymap.xml history>= <HISTORY><A HREF="mymap_history.xml">History of MyCave</A></HISTORY>
CaveMap.dtd
mymap.xml
Hierarchical Tagged Objects (HTO) Portable Data Format Specification, Version 1.4, December 15, Doug Dotson 1994
Inside XML DTDs, St Laurent and Biggar, McGraw-Hill, 1999
Literate Programming Using Noweb, Linux Journal, October 97, Issue 42, p64-69
The site "http://www.pault.com/Xmltube/dtdgen.html" can generate a DTD for
a supplied XML document.
The following is a list of all the code chunks defined in this document.
References are interpreted as in the following example:
(cavemap 32a) 32a 32b
The code chunk cavemap was defined on page 32. The a
means it was the first chunk referenced on that page. The 32a and 32b are
all pages which reference the chunk.
This is a list of all defined variables which are declared using %def.