This chapter describes the installation of Therion and the execution of one of the example provided with the distribution.
At the end you will have a fully functioning therion, and you will have experienced an example of what therion can do.
 Therion requires a number of external program (ie, programs that  exists independently of therion): cavern, Tex, MetaPost and pdfTeX.  xtherion requires Tcl/Tk.  All these programs are freely available for Linux, Windows and Mac OS X.  
You can download Therion from its homepage http://therion.speleo.sk/download.php.
 Linux Linux users (especially those with Debian) will have no problem,  because these programs (except for  cavern which is part of  the “survex” suite) are usually included in their distribution,  and likely already installed.  If a program is missing it is enough to install it with the  packet manager of the distribution, or, as last resort, get the  program source tgz from its website, untar it, configure, make,  and install it.  
Windows Therion programs for Windows can be downloaded as precompiled binaries. You need to get the setup file “therion-full-0.3.10.exe” (the version number might change).
When you execute the setup file, you get the installation screen as in the figure below. You must choose the installation directory and the submenu of “Start | Programs” that will be associated to Therion (you may accept the defaults).
The Therion setup installs  therion,  xtherion and all the  necessary software, cavern, MetaPost, Tex, pdfTeX, and whatever else  is required.  
When the install is over, you have the submenu “Therion” of  “Start | Program”. Select its submenu “xtherion” to start  xtherion.  
Mac (by M. Sluka) There are no precompiled binaries for Mac. You have to
configure, make, and install it. (Use always sudo instead of su). ii installer from http://ii2.sourceforge.net/tex-index.html BI installer will install the latest version. sudo make install. xpdf. It is better that Acrobat reader because it does not lock the open file, so therion may overwrite it. With acroread you allways have to close the PDF map before compiling. You can find xpdf for Mac OS X at ... You will need the DarwinPorts installer too: http://darwinports.com. If port does not work execute the command export PATH=$PATH:/opt/local/bin from the terminal. Then install xpdf: sudo port install xpdf. Under Mas OS X there are several problems. You must use the “control key” instead of the normal “command key”, the mouse right button does not work. etc.
The remainder of this section describes the installation of the  prgrams used by therion, and that of  therion from the sources.  It is not necessary to know this to use therion, and you may skip to  the next section.  
 cavern (program)
 
cavern is part of  survex, a suite of programs for the processing  of survey data. Survex is distributed under GPL and can be downloaded from  http://www.survex.org.  It is available in source code, for those who want to compiile it, or as  precompiled binary for Linux (deb and rpm), and Windows and Mac OS X.  
 Tcl/Tk (interpret)
 
 xtherion is writtenin Tcl/Tk. Therefore you need the Tcl/Tk interpreter  to execute it. If you do not have the  BWidget module, you should  add it: download the file BWidget-1.7.0.tar.gz.  
NOTE: I do not remember any more if one needs also  tclunit.tcl.  
If you plan to use scanned images in PNG or JPEG format, you need the  extension module  tkImg:  tkimg1.3.tar.bz2.  
TeX (program)
 MetaPost (program)
 
TeX is usually included in Linux distributions, and contains MetaPost within it. If this is not the case you can down load TeX and MetaPost from CTAN (Comprehensive TeX Archive Network) or from TUG (TeX users group).
I would like to say something about the possible problems that one might face, and how to solve them. Unfortunately (of by good luck) i did not have any trouble. If anyone has some experience about this ...
 pdfTeX is aversion of TeX that produces an output in PDF, besides the  DVI.  
Therion can be downloaded from http://therion.speleo.sk/download.php.
The compressed archive (therion-0.3.10.tar.gz) contains
therion; xtherion editor for the therion data files. Itis based on Tcl/Tk; therion and xtherion; therion; 
 After uncompressing the archive, you must compile with the command “make”.  By default “make” generates the program  therion and  xtherion  and the documentation (the Therion book).  If all goes well, you can install therion with the command  “make install”. If you do not install Therion, you can nevertheless  use  therion and  xtherion from the directory where you  uncompressed the archive.  
The Makefile is set for Linux; Windows and Mac OS X are commented. If you are still using one of them, you must configure the compilation by typing “make config-win32” or “make config-macosx”, respectively. This assumes that you have a development environment with “make”; MinGW oppure gcc. Surely, the easiest thing to do is to get the precompiled binaries.
To install   thtom you must go into the directory  therion/thtom/linux and execute “make”. When it is done copy the  directory  Tom0.2 in the  lib directory of your Tcl/Tk distribution  (in my case this was  /usr/lib/tcllib1.6).  This directory should contain the dynamic library  libtom.so and the file  pkgIndex.tcl.  
Therion is a system for high-quality cave maps. At the heart of this system is the therion language, that is a language to define through text files the graphic elements of cave maps, ie, points, lines, symbols, and so on.
The text files, written in the  therion language, are processed  by the  therion program to  generate the cave map in PDF format.  This program relies on other program to process the survey data,  cavern, and to produce the high-quality drawings,  MetaPost,  TeX, and  pdfTeX   2 .  
While it is easy to write and edit survey data file with any text  editor, writing and editing drawing files is not easy at all, although  it is actually possible. It is better to make use of a program  with a graphical interface. One such program,  xtherion, is  distributed with  therion. Any graphical interface, compatible with  the  terion language would fit the task.  xtherion is written  in Tcl/Tk, therefore it is necessary to have the Tcl/Tk interpreter  to run it.  
xtherion is not WYSIWYG (what you see is what you get), and this  makes it less user-friendly. On the other hand the approach followed  by therion, which keeps the data separated from their presentation (and/or  final result), allows more freedom in the output, and makes the  maintenance easier.  For example, the closure of a loop, is easily taken into  account since the data used to generate the map are always the  original data (as opposed to data obtained as result of intermediate  processing).  
Make sure that the directory with  therion  and the programs it uses  are included in the  PATH.  Windows user who have installed therion with the setup program,  should have no problem here.  
Linux users who have installed all the programs should have no problem,  either.  To check that the programs are accessible through the  PATH  type the command “which cavern mpost tex pdftex therion xtherion”.  If the program is found its full path is displayed. Otherwise the  name of the program, with semicolon, is shown. Instead of  pdftex  you might have  pdfetex.  It is not necessary that  xtherion is accessible through the  PATH.  It is possible to invoke it by specifying its path.  If you want to find the program through the  PATH, you can add the  directory, that contains the program, to the  PATH with the  command “export PATH=$PATH:directory” (for the  bash shell, for the  others the command is slightly different; “echo $SHELL” tells you  which shell you are using).  
Now go into the directory of  therion and type the command  “xtherion” (or “./xtherion/xtherion” if you have not installed therion yet.  A small window appears, telling you that  xtherion is starting.  And after a short while the  xtherion window appears as in the  figure below.  
xtherion window has a menu bar with four menus:  “File”, “Edit”, “Window” and “Help”. A toolbar is underneath the menubar.  There are two work areas (both empty and black at the moment):  the upper one for the configuration file, the lower one for the  output logs. A control panel is on the right, and a status bar on the  bottom.  
The “Help” menu has three submenus:
 As you might expect, this menu has submenus to create (”New”) or  open (”Open”) a configuration file, save it (”Save”) and close it  (”Close”). There is also the submenu to compile the project,  “Compile”, and “Exit”, to quit  xtherion.  
xtherion has several shortcuts, ie, keys or key-combinations that  are equivalent to menus and commands. The most important is “F9”  which compiles the project. Thus if you press “F9” is as if you select  the menu “File | Compile”.  
 The “Window” menu switches between the interactive mode of  xtherion:   
xtherion starts. Each interactive mode has its menubar (with menus specific for each mode), its status bar (status messages specific for each mode), and control panel (with controls specific for each mode).
There are three menus to maximize the window, “Maximize”, to bring it to normal size, “Normalize”, and to toggle the position of the controls panel to the left or to the right, “Switch Panel”.
Finally there is the submenu “KBD Encoding” to select the encoding of the keyboard. If anyone drops me a note about this, i put it here.
 La toolbar di  xtherion e` stata introdotta con la versione 0.3.10.  Ha alcuni bottoni per le operazioni piu` comuni:  creare un nuovo file, aprirne uno, salvarlo, chiuderlo;  cambiare tra le modalita` di  xtherion; ed infine compilare.  
In the map editor mode, the toolbar has also buttons on the right for the most frequent graphical operations: zoom in and out; insertion of scraps, points, lines and areas; selection and deletion of the selected element.
The controls panel is, by default, on the right and contains several buttons with blue background, the controls. The number and type of controls depends on the interactive mode. The panel can be moved to the left with the menu “Window |Switch panels”.
Each control can be open or closed: when it is open the informations of the control are show below the blue button. To open or close a control double click on the button.
 xtherion window has a status bar on the bottom.  The status bar display useful messages on the status on the program.  Therefore get the habit to read its content.  
Now try to switch the interactive mode by clicking on the proper menu. Notice how the buttons of the panel change. Notice that the name of the mode appears in the window title.
Select the submenus of “Help”. You may also try out the “BAC calculator” ...
At the end go back to the “Compiler” mode.
 Before we start to work on an example, you may run  xtherion  with one of the samples provided with the distribution.  However, it is better to discuss how Therion organizes the  data.  
The drawing of a cave map is a “project”, with a configuration file which specifies what to do and how, and data files. There may be several configuration files, to process the data of the cave in different ways and generate different outputs.
Therion uses text files, that you can read and edit with any text  editor, outside of  xtherion. Of course, if you do not follow  therion syntax the files do not compile and  therion does not  generate the output you might want.  
For this reason it is better to use  xtherion to edit  the therion files. It does not do syntax controls, but it helps  a lot in the development of a cave map project.  
thconfig (Therion configuration file)
 By convention the therion configuration file is named  thconfig.  This is not necessary, and it could be named differently.  When you open a configuration file in  xtherion, by default it displays only the files that contain  the string”thconfig” in their name (”my.thconfig”, “thconfig_my”, etc.),  but you can choose to select the file among “all”.  Still by convention the therion survey data files have extension “.th”  and the map files “.th2”.  
 Now create a directory for this example.  I named it  gm-therion. For the moment it is empty, but it will  be populated with therion files and images for the drawings.  The output files will be in there too.  
Move in this directory and execute the command
    xtherion
  
After the startup little window, that tells you  xtherion is coming up,  the  xtherion window appears, in compiler mode.  
In the controls panel you find
therion command. The panel of controls contains
therion. There is also a “Compile” button, that compiles the project, and a text-box, that becomes active during the compilation. You must open a configuration file to make these controls active. Therefore, select the menu “File | New” and confirm the proposed filename for the configuration file (namely “thconfig”), then click on “Save as”. At this point the controls are active and you can see the project settings. However, if you try to compile, you get an error since you have not specified any configuration command, neither you have specified any survey data.
You can nevertheless execute  therion with one of the two options  “-h” (help) or “-v” (version). Write the option in the textbox under  “Command line options” and click the button “Compile”.  The outcome is very short, and the output of  therion is displayed in the  lower part of the window.  
 environment (therion)
 Another useful information that  therion gives even if the  project configuration file is empty, is its execution context, ie,  its environment. Write the command option “–print-environment” and  compile. The environment variables are   
/etc/therion.ini; INIT: the path where therion search for the initialization file therion.ini. This is also used by xtherion for its initialization file, xtherion.ini. SOURCE: the path of the data files (.th e .th2) and the configuration file (”thconfig”) for therion; METAPOST: the MetaPost command; PDFTEX: the pdfTeX command. 
These informations are useful to fix possible installation errors, such as  if, for instance,  therion cannot find MetaPost.  
Now close the project: select the menu “File | Close”.
 At this point it’s good to see  therion at work.  Open the configuration file for the examples that comes with the  distribution: select the menu “File | Open”.  You get a dialog window for the file selection.  Move into the root directory of Therion and select the file  thconfig.  Then click “Open”.  The file appears in the upper part of the window.  
For the moment do not worry about it, just select the menu “File | Compile” (or press the key F9). The textbox by the “Compile” button becomes yellow with the word “RUNNING”, and the output of the compilation is displayed in the lower part of the window. At the end if everything went well the textbox becomes green with written “OK”. If something went wrong it becomes red with the word “ERROR”. If this is the case you must find the problem and fix it. Be careful that the textbox may show “OK” even if there are minor errors (warnings): you have to scroll through the output in the lower part of the window to check that there is no warning. For the examples that come with the distribution everything is fine.
On Mac OS X  xtherion always finishes the compilation with a red “ERROR”,  even if there are no errors. You have to check the output of the compilation  to make sure that there are no error.  
Now you can open the file “cave.pdf” with a pdf viewer ( xpdf or  acroread if you are on the wring operating system;  xpdf has  a nice “reload” command which reload the file without having to close it),  and see the result.  
therion store the temporary files in the directory  $TMP/th$PID  where PID is the process id of the task  therion  (not that of  xtherion).  These temporary files are removed at the end of the execution.  
 therion and  xtherion rely on environment variables  and initialization files to configure their execution behaviour.  
environment (therion)
 
 therion uses the following environments   
THERION, search path for the initialization files; HOME, the path $HOME/.therion is used in the search of the initialization files when these are not found in the path THERION (or the latter is not defined); TEMP and TMP are used to make the path of the directory for the temporary files. These are $TMP/th$PID, where $PID is the process id. They are also used for the path of the debug directory whree the temporary data files are saved, $TMP/thDEBUG. The inizialization files, “therion.ini” and “xtherion.ini”, respectively, are text files written with a syntax similar to the data files, ie, with command lines and comments (these start with the character ‘#’).
Therion searches the initialization files in the following directories (on Linux; on Windows after the first two things are a little different), in the order:
$THERION $HOME/.therion /etc /usr/etc /usr/local/etc 
The search stops when an initialization file is found.  If the initialization file is not found  therion uses the default values  (hardcoded in the program). The commands of the initialization file are:   
The initailization file of  xtherion contains a list of variables  that modify the behaviour of the program.  The values of these variables can be set by replacing the default one.  Among the others we have   
xtherion starts from, when it opens the files. I found it convenient to set it to the subdirectory “Caves” of my home directory, because i keep there all the surveys: set xth(gui,initdir) $env(HOME)/Caves. xtherion. You can set it uncommenting the line ::msgcat::mclocale XX. Replace “XX” with the code for your language. It must be one of the languages compiled into the program, otherwise xtherion uses english. Therion relies on three external programs to compile the maps of a project:
cavern, to process the survey data; metapost, to process the scraps; pdfTeX, to put together the scraps and form the maps. 
Indeed you can see in the output of the project builds (the lower part of  the compiiler window in  xtherion) the outputs from these programs.  
xtherion writes the input files, both data files “.th” and “.th2”  and configuration files, on disk, so that they are in sync with their  images in  xtherion memory. Next it invokes  therion.  As a matter of fact you could do without  xtherion and call  therion from the shell (the command prompt), which is what I  do when i want to generate a map from a set of input files, without  editing them.  
therion processes the input data files and coordinates the  work of the external programs [thbook 8]. It reads the input files  and interprets the commands in them.  First it computes the positions of the stations.  In particular it find closed loops and distributes the closure error  on the shots.  
Next it processes the data of the scraps (files .th2) and transforms  them according to the positions of the stations.  After this it exports the data as MetaPost files (.mp), and invokes   mpost.  This program processes the “.mp” files and produces PostScript files (.ps).  A small file for each scrap, ie, for each piece of the map.  
The PostScript files are processed by  therion and converted into a  PDF-like format. Then it invokes  pdfetex passing it these  PDF-like files. This program produces the cave maps in PDF format,  taking care of the formatting and the inclusion of texts.