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.

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.

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.

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;
• CAVERN: the cavern command (from Survex);
• METAPOST: the MetaPost command;
• PDFTEX: the pdfTeX command.
• IDENTIFY: the identify command (to get the characteristics of image files).
• CONVERT: the convert command (to convert images).

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.

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.