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 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: http://therion.speleo.sk/wiki/doku.php 
(Earlier versions of Therion 0.5.x included all the wiki in the -doc
package.)

If you need to download the therion wiki for offline (e.g. expedition) use use:


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 at irc.oftc.net


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

/etc/therion.ini contains the defaults the program uses without a
config file so you won't need to change it unless any of the therion
files you process use a non-latin character set. This is changed from
the upstream to remove the need for czech/slovak and cyrillic TeX
fonts by default.

/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 these use czech/slovak fonts. If you are using teTeX then they should
just work. If you are using TeXlive then you need to install
texlive-lang-czeckslovak (a suggests: ) and edit /etc/therion.ini to
enable the fonts. 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, and therion told about them. The texlive-lang-
packages (or tetex-extra if using tetex) contain the fonts, so install
appropriate ones. You tell therion about the fonts in /etc/therion.ini or
~/therion.ini with a line:
tex-fonts <encoding> <roman> <italic> <bold> <sansserif> <sansserifoblique>
e.g.
tex-fonts xl2 csr10 csti10 csbx10 csss10 csssi10


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 as root run:
update-texmf
fmtutil-sys --all
to update the TeX system.

 
-- Wookey <wookey@debian.org>, Mon, 25 Aug 2013
