Therion for Debian
==================

Overview 
--------

Therion is cave surveying software. It allows the drawing of cave
surveys on the computer. Data can be added to a drawn plan and it will
be realigned to fit any new closures or fixed points. All the work is
done by the Therion program, with Survex used for loop closures if
installed. The front-end for entering data is Xtherion, which uses
Tcl/Tk.

It is the sort of software where you need to read the manual (or
better a tutorial) in order to use it effectively. You are unlikely to
get a PDF out of it without doing that.

Therion uses Survex for centreline data processing if it is installed,
but can also do this processing itself if not. Survex's centreline
processing is much better so you are advised to use it. You can
either keep all your data in Therion format, or you can keep
centreline data in Survex form and drawing data in Therion form. If
using the latter scheme, Therion can import Survex .3d files to get the
survey structure and station positions.

Therion can also import data from PocketTopo and thus supports
DistoX-based paperless surveying. A nice workflow involves using the
separate topparser program to get data and images from the pockettopo
files in a sensible therion layout.

Loch is a 3D model viewer which allows a 3D model of the cave to be
viewed and scanned maps and relief data to be included and viewed. It
uses OpenGL and VTK to provide the fancy graphics. This is packaged
separately as therion-viewer. The model is generated automatically from
the splay and/or LRUD data.

The scans used in Xtherion are limited to formats Tcl/Tk understands. By
default this is GIF and PNM (Portable Anymaps). To allow use of PNG, JPEG
and TIFF you need to install libtk-img. 

Docs
----

The documentation is in the therion-doc package.

The Therion Book (file:///usr/share/doc/therion-doc/thbook.pdf) is the
reference documentation for the system. 

To get started you will find the "Therion by Example" and "Therion for Plain
Cavers" documents more useful as an explanation of how to draw things in 
Therion. These, along with the FAQ, tips and code examples are on the
therion wiki: https://therion.speleo.sk/wiki/doku.php 
(Earlier packages of Therion 0.5.x included all the wiki in the -doc
package.)

There is a Mailing list for users at therion@speleo.sk. To subscribe just
send an empty e-mail to therion-subscribe@speleo.sk .

There is also an IRC channel #therion on irc.oftc.net.


Config and example files
------------------------

/etc/therion.ini contains the defaults the program uses without a
config file.

/etc/xtherion.ini allows you to specify various options such as 
character sets and font sizes.

/usr/share/doc/therion/examples contains some example dataset files, some of
which use Czech/Slovak fonts. If you are using TeX Live (you are if you're
using the current standard TeX packages in Debian) then you need to install
texlive-lang-czechslovak (which is a suggested dependency) to have the fonts
needed to process these.  See 'Language Support' below for details.


Language support
----------------

Therion has good support for alternate character sets. The thbook
explains how each file specifies a character set. The corresponding fonts
also need to be installed - since version 5.3.17, therion will automatically
check what fonts are installed and used them so you just need to install
the appropriate texlive-lang-xxx package(s) for the fonts you need.


TeX and MetaPost
----------------

Therion includes MetaPost and TeX macros. Until version 0.2.13 these were
installed in TeX - now they are compiled into the therion executable and 
injected into the TeX/Metapost stream as needed. This is to avoid
problems with paths on non-Debian and non-Unix systems.

If you get errors about 'TeX capacity exceeded' then you either have a
bug that is causing runaway recursion, or you really have run out of
memory. This error is more likely with therion versions after v0.3 because it
automatically generates a scrap containing all the centreline data, which
can be several megabytes. Using a select in the thconfig to select the
map(s) you actually want can solve the problem.

Alternatively - if you actually need to increase the TeX memory
then you need to change main_memory in /etc/texmf/texmf.cnf. For full
docs on this see the TeX-on-Debian doc in /usr/share/doc/tex-common/. The
short version is edit /etc/texmf.d/95NonPath.cnf, then to update the TeX
system run the following commands as root:

update-texmf
fmtutil-sys --all
 

-- Olly Betts <olly@survex.com>, Tue, 23 Feb 2017
