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

1. Install the Developer Tools, XCode from Mac OS X installation
2. Install Survex: download the source tgz from the website, untar it, then configure, make, and install it. (Use always sudo instead of su).
3. Install the TeX packageuse the ii installer from http://ii2.sourceforge.net/tex-index.html
4. Install AquaTcl/Tk from http://tcltkaqua.sourceforge.net/ There is a Tcl/Tk as part of Mac OS X installation, but the BI installer will install the latest version.
5. For the latest features you will need ImageMagic as well. You may download the binaries from http://www.imagemagick.org/download/binaries/ImageMagick-universal-apple-darwin8.7.0.tar.gz
6. Download the Therion package. Follow the instructions in the appendix of The Therion Book. To install use sudo make install.
7. You may install the PDF viewer 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 programs 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

• the sourec files of the program therion;
• the xtherion editor for the therion data files. Itis based on Tcl/Tk;
• documentation: the subdirectory thbook and the man pages for therion and xtherion;
• examples, in the subdirectory tests;
• data files (definitions), in the subdirectory lib;
• MetaPost files, in the subdirectory mpost;
• a 3D viewer based on OpenGL ( thtom);
• the subdirectory tex with the file therion.tex, containing the TeX commands of therion;
• glyfs and encodings in texenc;
• the subdirectory thchencdata with characters encoding data;
• the subdirectory thlang for the localization (local languages);
• the subdirectory extern containing utility functions used by therion;
• the subdirectory thcdt with the functions for the constrained Delaunay triangulation, used in the construction of 3D models.

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:

• “Control” opens a window with the summary of the commands (controls);
• “BAC calculator”: a calculator for the percentage of alcohol in the blood (Blood Alcohol Calculator), the Metabolic Removal Rate (MRR) and how long you should wait before drawing the cave map (ETA, Estimated Time of Arrival);
• “About” displays the program version and the authors names.

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:

• “Text Editor”: editor of text data files (centerline);
• “Map Editor”: editor of drawing data files (scraps);
• “Compiler”: the confguration file editor and project compiler. This is the mode in which xtherion starts.
• “Model Viewer”: to view 3D models.

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

• “Settings”, with the program configuration settings: the “Working directory”, the name of the current “Configuration file”, and additional options of the therion command.

The panel of controls contains

• “Settings” with the configuration settings: the “Working directory”, the name of the (“Configuration file”, and the current options for the command therion. There is also a “Compile” button, that compiles the project, and a text-box, that becomes active during the compilation.
• “Survey structure” display the hierachical organization of the survey.
• “Survey info” displays some information on the survey, after the project has been compiled once.
• “Map structure” displays the structure of the map.

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

• the inizialization file: /etc/therion.ini;
• the project configuration file;
• 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:

1. $THERION
2. $HOME/.therion
3. /etc
4. /usr/etc
5. /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:

• “encoding-default”, defines the default output encoding;
• “encoding-sql”, defines the encoding for the data exported in the SQL scripts;
• “language”, defines the language for the output legends. For example “language fr”;
• “mpost-path”, specifies the path of MetaPost. The default is “mpost”;
• “pdftex-path”, specifies the path of pdfTeX. The default is “pdfetex”;
• “source-path”, is the path of search of the input files (.th e .th2) and the configuration file (“thconfig”).
• “tmp-path”, specifies the directory where the temporary directories should be created. The default is “/tmp”.
• “tmp-remove”, defines the command to remove temporary files.
• “tex-env” used only in Windows (TODO);
• “tex-font” specifies the fonts for an encoding. It ha ssyntax “tex-font encoding rm it bf ss ssi”, where the name of the encoding is followed by the fonts for the five styles: normal, italics, boldface, sans-serif, and sans-serif italics.

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

• the work directory. This is the directory where 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.
• the language used in the interface of 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.