When exporting a “cave-list”, Therion tries to identify entrances and surveys, and tries to work out which survey an entrance belongs to. It also tries to work out the lengths of the various caves in the survey. While it might be nice to assume that Therion can look through all of your survey data, find all the entrances, work out which bits of survey data are connected to which other bits without using any “flags surface” legs, and add them all together to work out the cave lengths, the reality is that this kind of magic does not take place (April 2019). You need to structure your surveys (usually created as one survey per data file, just to keep everything easily findable) in a way that tells Therion “these surveys should be added together to create one “cave”.

By setting the ”-entrance“ option of a “survey”, you tell Therion that the entire survey and its subsurveys represents a single cave. It will then use that entrance as the primary entrance of the cave (and therefore its nominal coordinates), and count up the non-surface legs of that survey and all sub-surveys as a combined “cave”.

When surveying a large area, it is common to have a surface survey linking them together, or connecting to major surface structures. Several small caves are often surveyed as part of the surface surveying trips. The major caves are surveyed in a number of trips, and some of their passage may even be surveyed on the surface survey. If you leave the minor cave and segment data mixed into the surface survey, then Therion will not be able to calculate the lengths of the different caves.

Therion cannot make sense out of this situation without a little help.

Create a master survey file for each cave that you want Therion to recognise (perhaps not that 2 metre long alcove on the surface, but that 20 metre long rift that has a proper name, might just qualify). Even if it is a short cave that was surveyed as part of the surface survey, split its data out into its own survey (and its own data file, for your own sanity). If more than one cave is surveyed as part of the same trip, joined by a few legs not worthy of being considered a surface survey, split the data into separate files representing the separate caves. (For best results, put each cave's files into its own folder - perhaps even as a subfolder under a “caves” folder - again, just for your own sanity, because you will be adding a lot of other files into it for all your scraps. See also the Data Organisation page for more guidance in this area.)

Then if the cave is surveyed over several survey trips, create your subsurvey file (and preferably subfolder) for each of those trips. In the cave's master file, input each of those section files, and use “equate” to link them. In the cave's master survey, set the ”-entrance“ option to point to the main entrance. Each file can also use 'station 123 “Foo Cave” entrance' to signify additional entrances, and to name the main entrance.

Now use the same approach with the surface. For organisation's sake, put the surface survey in a folder called “surface”. Each surface survey trip gets any significant cave's data removed from it. (Normally, a cave survey has a couple of surface legs at each end just to link in to the surface survey - these are usually left in the cave's data files, with “flags surface”.) Each survey trip gets its own survey (and data file optionally in its own subfolder). Any entrances that are not going to get their own dedicated cave survey (such as that 2 metre rift that isn't worth calling a cave) can be mentioned using 'station 456 “Blind rift” entrance' If the surface survey was split over multiple trips, create a master file for the surface survey, create a master surface file, input the sub-surveys, and use “equate” to link them.

You should now have a master survey per cave, and a master survey for the surface. In the main data folder, create the overall master survey in its own file. Input the surface survey. Input the master survey for each cave that you want. Use “equate” to link them together.

When you ask Therion to export the cave-list, it should now get the right lengths for each cave.

Note that if you are using a tool like PocketTopo+TopParser or SexyTopo, you may have a single exported .xvi image file that contains the various bits of surface and cave that you surveyed at the same time. If you then split the data, then each section needs to include this image in order for you to draw your scraps. You can create a new .th2 file for the newly created data files (XTherion map editor - File - New) then include the image (Edit - Insert image - select the .xvi file), or manually create a copy of the image if you don't mind the extra file size.

It happens. If a small cave gets added to a big cave, just take that small cave out of the input list for the overall master survey, and input it to the main cave's survey instead, using “equate” to link them. Its length will now get added to the main cave. Optionally also move its data folder into the main cave's folder, just for the sake of good organisation. The smaller cave survey no longer needs its ”-survey“ option, so that can be removed.

If two major caves are connected, and you want to retain their separate identities, create a new master survey for the combined cave system. Give it an ”-entrance“ so that Therion knows it is a cave. Optionally move the two caves into subfolders within the master cave's folder. Input the two caves' master surveys, and use “equate” to link them. In the master survey file, input that new master survey instead of the two separate cave surveys. Therion can now calculate the combined length correctly. Leave the two caves with their old ”-entrance“ options, so they can get their own length counts, if you want them.

• MasterSurvey
  • Surface
    • SurfaceTrip1
    • SurfaceTrip2
  • SmallCave -entrance 3
  • MediumCave -entrance 2
    • EntranceFragmentSeparatedFromSurface
    • Extension
  • MajorCave -entrance 1@bigcave1
    • BigCave1 -entrance 1
      • Trip1
      • Trip2
    • BigCave2 -entrance 3
      • Trip1
      • Trip2

Therion just provides a combined length and depth of all caves in a map, by default. It can be asked to export a HTML cave-list, but this cannot be directly included on a PDF survey, unfortunately, because HTML does not qualify as a “map-image”. If you want to keep things simple but you still want to show separate lengths and depths for each cave, you will need to manually add this in a “layout” as a “map-comment”. Eg.

layout local
  map-comment "<si>Cave 1:<ss> length 123 m, depth 45 m<br>\
  <si>Cave 2:<ss> length 678 m, depth 90 m"
  ...
endlayout

If you only want to show the length and depth of a single main system, ignoring all of the smaller caves, you can tell Therion to use that cave's survey as the source of its length/depth statistics (and other statistics), when selecting a map:

map mymap -survey somesurvey@mycaves

If you would still like to embed the HTML into your PDF, you could use one of many external applications to convert HTML to PDF. You could, for example, call one of these applications using a Therion “system” command, to convert the HTML output from Therion's “cave-list” into a PDF which can then be included in a Therion PDF map. Some of these applications even allow you to use CSS to style it first, and JavaScript to manipulate it to remove any details you do not want on the published survey. For example, wkhtmltopdf allows you to use both CSS and JavaScript, and can produce a 14 cm wide PDF which matches the width of the default Therion PDF map-header. Use the “export” command in your thconfig to output the cave-list, then the “system” command to run the html-to-PDF conversion tool of your choice (shown here for Windows - note that you must use the shortened file path to the executable, to avoid using quotes around the executable path, which would confuse the “system” command on Windows). After that, you can use the “map-image” command in your layout to embed the newly generated PDF:

layout local
  map-image 100 100 ne cavelist.pdf
  ...
endlayout
source "allcaves.th"
select cavesMP@allcaves
export cave-list -surveys on -location on -o cavelist.html
system "C:\PROGRA~1\wkhtmltopdf\bin\wkhtmltopdf.exe --margin-top 0 --margin-right 0 --margin-bottom 0 --margin-left 0 --page-width 14cm --page-height 8cm --disable-external-links --user-style-sheet cavelist.css --run-script ""var script = document.createElement('script');script.src='cavelist.js';document.documentElement.appendChild(script);"" cavelist.html cavelist.pdf"
export map -proj plan -layout local -o "caveplan.pdf"

When using this example, cavelist.css can include styles to format the headings, avoid wasting space, hide links, and add support for any non-standard CSS:

html, body {
  padding: 0;
  margin: 0;
}
body {
  font-size: smaller;
}
a {
  text-decoration: none;
  color: inherit;
}
th:first-child + th + th + th + th {
  white-space: pre;
}
th:first-child + th + th + th + th + th {
  white-space: pre;
}
th + th {
  text-align: center !important;
}
th, td {
  padding: 0 !important;
}
th + th, td + td {
  padding-left: 6px !important;
}
td[style="padding-left:+12"] {
  padding-left: 12px !important;
}
td[style="padding-left:+24"] {
  padding-left: 24px !important;
}
td[style="padding-left:+36"] {
  padding-left: 36px !important;
}
td[style="padding-left:+48"] {
  padding-left: 48px !important;
}
td[style="padding-left:+60"] {
  padding-left: 60px !important;
}

cavelist.js can include code to change the headers to include grid information, rename headings, or remove statistics for any cave which has no survey data:

var headers = document.getElementsByTagName('th');
var rows = document.getElementsByTagName('table')[0].tBodies[0].rows;
headers[3].textContent = 'Unsurveyed';
headers[4].textContent = 'Easting\nGrid SN';
headers[5].textContent = 'Northing\nGrid SN';
for( var row = 1; row < rows.length; row++ ) {
  if( rows[row].cells[1].textContent == '0' && rows[row].cells[2].textContent == '0' ) {
    rows[row].cells[1].textContent = rows[row].cells[2].textContent = '';
  }
}