therion is a language, a set of rules, ie, a syntax, to describe the drawings of the cave maps in text files. Writing therion files, both configuration and data files, is like writing a program for a computer (using a programming language). Infact a therion project must be compiled to produce an output: the cave map, the 3d model, etc. Just like a computer program must be compiled to generate the executable. The result of a therion compile are not executables but document files (pdf, 3d, ...) that can be displayed amd/or printed.

When one writes a computer program one makes mistakes, and the program does not do what he/she expects. He/she needs to correct the mistakes; the process of spotting the mistakes and correcting them is called "debugging". Something similar happens with therion projects, and the process of fixing mistakes in a therion project is also called "debugging".

Sometimes the mistakes are simple (eg. forgetting the option "-subtype presumed" to a "wall" line), and the output is not correct, but it is "almost" good. Other times they are more serious, like assigning wrong names to "station" point, and the output come out very bad. The result can be so different from what one expects that debugging the error would be hard without "debugging" facilities.

For computer programs, the debugging of errors occurs in two moments: at compilation time and at runtime (ie, during the execution). The same happens for therion. In the first case xtherion itself, or through its external helper programs, catch an error and points it out in red, in the output window of the compiler. This is like when one uses a programming language compiler, that finds syntactical errors and points them out. If there are no syntax errors the compilation is good and xtherion writes a green "OK".

However the worse errors are the "semantics" ones. The compiler cannot spot them, because the syntax is correct; the problem is that what the statement means that is not what we wanted, and the output is not what we expected. The compiler cannot see our mind, it just reads the instructions we write in the files, and it finds nothing wrong with them. With a computer program one executes the program in a debugging environment to monitor the various execution steps until he/she discover why the program does not behaves as "expected", and finds the cause of that.

For therion a semantic error means, for example, that the cave map is not as we wanted. And we see that there is such an error when we display it with a viewer. Unfortunately xtherion is not WYSIWYG, and it does not show the data as they would appear in the output. This is inevitable because therion supports a variety of different outputs. Furthermore the input data are transformed by therion during the compile process that generates the output(s).

therion offers two debugging functionalities: the command line option "-d" and the layout option(s) "debug on".

When yuo specify the layout option "debug on" therion includes in the output pdf document the intermediate steps of the transformation of the scraps. These are shown with different colors,

• red lines: the original scraps (after rotation and rescaling);
• blue lines: the scraps adjusted to the "station" positions (before the joins);
• red points: original positions of the "station" points;
• yellow points connected by yellow lines: initial positions of the pairs of points with maximal distorsion;
• black points connected by black lines: final position of pairs of points with maximal distorsion;
• orange points: points with maximal change of their distance, in the transformation;
• yellow lines between yello and black points: displacement of these points.

If there is only one black point, this indicates two stations with different names at the same point.

The layout option "debug" can have also other values:

• "off" disables the debugging
• "on" enables the debugging
• "all" displays all the debugging informations
• "first" displays the drawing after the first step of the transformation (the linear part);
• "second" displays the drawing after the second step of the transformation;
• "scrap-names" displays the names of the scraps;
• "station-names" displays the names of the stations.

The layout option survey-level controls how many survey names are printed with the station names. It takes a number, 0 for no survey name, 1 for only the first, etc. or the special value all which means that all the survey names are printed.

Another useful debugging technique is to process few pieces of the cave map at a time to make sure that they are correct. This can be done using the configuration option "select", and/or organizing the survey hierarchically.

The therion command can be invoked with the debug option, "-d". If you are using xtherion write "-d" in the "command options" textbox of the "Settings" control in the compiler window.

When therion is executed in debug mode it saves the temporary files in the directory $TMP/thTMPDIR [thwiki 10]. In the MetaPost error messages there appears the line number of the "data.mp" file, which is the file generated by therion for MetaPost. To inspect this file can be useful in order to find the cause of the errors that are pointed out by MetaPost [thwiki 16-17].

The "data.*" files are postcript files generated by MetaPost. The numbers in their extensions corresponds to the numbers written by MetaPost in its output. You can view them with a postcript viewer (or convert them to pdf and display with a pdf viewer). Add a "X Y translate" postcript command at the beginning to shift the picture in the middle of the page, if you cannot see anything. For example "200 200 translate".

Notice that MetaPost has the reverse order of the symbols than therion because, in this way, it displays the first symbol, in the list in the .th2 file, on the top of the others.