This chapter describes advanced usage of Therion:

• the compiler of xtherion
• understanding execution errors
• using the debugger

The panel of the compiler window of xtherion has four controls:

• “Settings”, for the excution settings of therion. These have been described in section 1.3.
• “Survey structure” shows the hierarchical organization of the surveys of the survey data files;
• “Survey info” displays some information about the survey when you click on “Survey structure”;
• “Map structure” displays the structure of the maps of the cave map(s).

The following figure shows the example of a presentation that has two surveys. The informations for the first, s1, are displayed in the “Survey info” control. There are four maps.

select (thconfig command)
When you double-click on a map line in the “Map structure” control, xtherion inserts a “select” command for that map in the configuration file (at the beginning) [thwiki 14].

This section desribes a few errors and problems that you may get working with therion, and provides hints for their solution in The Therion Way.

This occurs when you happen to click twice (a double clikc) on the same line while defining an area. In this case the contour of the area computed by therion may turn out not what you expect.

To avoid this mistake, check in the “Areas” control the list of the lines of the area contour. When you click twice on the same line, this appears on two consecutive lines. To fix the problem, select one line on the control and press the “Delete” button of the “Area control” menu.

Repeating the same line-point twice in a row is not an error, but the resulting line could not be what you wanted.

In the “Line” control you can see the list of the points that compose the line, and check if any appears twice. If this is the case, you can cancel one of them with the menu “Line edit | delete point”, after selecting it (or editing the file with the text editor).

cursor
Every graphical element must appear inside a scrap, ie, between a scrap command and its endscrap command. When you insert a graphical element in the drawing canvas a new line is open on the cursor of the list in the “Objects” control, and the new element is assigned to the line. The cursor is the “black line” between the lines of list.

When the cursor is between “endscrap” and “endoffile” the new elements are placed outside of any scrap. The only thing that you can insert here is a new scrap. Infact a scrap cannot be inside another scrap. xtherion puts the cursor here every time you open a file, ready to add a new scrap.

However this is not appropriate to make corrections and additions to an existing scrap. You must move the cursor inside the scrap by clicking on the element after which you want to add the new ones, so that the cursor appears after it.

If you happen to insert elements outside the scrap, therion gives an error when you compile the map,

     missing scrap before line command
  

To fix this error, open the “Objects” control, select the line “endscrap”, and move it down using the “Move down” button until there are no elements outside scraps.

When there are replicated points (eg, a station name assigned to more than one point) therion does not complain, but the map is likely not what you want. On the other hand when there are station points with wrong names (ie names of non-existing stations) therion gives an error message (XXX is the wrong station name)

      invalid station reference -- XXX
  

Something similar happens when you assign the station names wrong: the cave map is screwed up because the scraps are fit together according to the survey data (the centerline).

The debugger is useful to see the different positions where the scraps are placed while therion composes the map. It might be useful to comment the “join” commands during the debug, to inhibit the transformations that they cause [thwiki 4].

If you happen to put graphical elements in a scrap and realize that you actually wanted them in another scrap, you have to move them from one scrap to the other.

This is rather simple if the scraps are in the same file. Open the file in the map editor of xtherion and move the elements using the “Move” buttons in the “Objects” control.

It is possible to move graphical elements between two files, but this operation requires so much more care, that it is often easier to delete them from one file and re-draw them again in the other file. If you want to try anyways, here is how to do it. As the map editor of xtherion can open one file at a time you must use a text editor. Indeed the map files are text files with commands to draw the maps.

Open both files and use the “id” field to identify the elements that you want to move from one file to the other. Cut them from the first file and paste them in the second. This is usually not enough: the graphical elements have coordinates in different frames of reference. Even if the two scraps have the same “-scale”, the frame is given by the positions of the points of type “station”.

Now you can open the second file with the map editor of xtherion and position the elements that you pasted in in the proper places.

The temporary files of therion, MetaPost and pdfTeX are located in the (temporary) directory “/tmp/thPID” where PID is the process id of the running instance of therion.

debug
When therion is invoked with the “-d” (debug) command line option, it creates the directory /tmp/thTMPDIR and stores the intermediate files there. This directory is not removed by therion, neither it is cleared of the old files before the execution. You must remove it by hand yourself.

A. Atkinson encountered the following problem: a single scrap with a white (background) triangle in it.

outline
S. Mudrak work-around:

When I added “wall -subtype invisible” as shown on the picture, then > the problem was solved. Same with “border -subtype invisible -outline > out”. Therion obviously did not connect walls in correct order.
I am sorry for this, there must be some bug in the “outline finding” > code, but it is very difficult to find and using “invisible outlines” > allways helps.

To prevent this try not to use short (two point only) lines with general subtypes. It causes the error when \tt{therion} is analyzing the walls and it finds the nearest possible continuation not on the “correct” wall but it jumps to another wall, which starts at a shorter distance. Use “point_of_line” subtype instead, and draw as long wall as possible (M. Sluka).

debug
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 and/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 you 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 yellow and black points: displacement of these points.

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.

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”.

therion and the external programs it uses can detect several errors in the input data, and generate useful error messages. These messages are usually clear enough to point the user to the cause of the error.

This appendix lists some of the error messages, and describes what they mean, and how to fix the error. The messages are listed alphabetically. Unfortunately the error messages are in english only. To localize the error reporting, it would not be enough to do it for therion (and xtherion), but one should have it also for cavern, mpost, pdfetex and tex.

Error: area borders X and Y don't intersect in scrap Z This is a MetaPost error message, that is not intercepted by xtherion (which shows an “OK” result). You should open the file containing the named scrap and find the lines that produced the error (use the “Search” control of the map editor). Probably the two lines are consecutive lines in the area contour, but do not intersect, as pointed out by MetaPost. You must correct one of the lines (or both).

Warning: scrap outline intersect itself in scrap Z This is a MetaPost error. It is displayed by xtherion in the output frame, but it shows an “OK” result nevertheless. You must open the file with that scrap and fix the outline. If your scraps are spread on several files, it might be hard to find where it is. xtherion cannot help you, because it has no information about which source file produced the problem. You can use a text search tool (eg, grep) to locate the file with that scrap.

A situation in which the scrap outline intersects itself occurs when a “wall” line has a kink due to long handles of line-points, as in the figure below.

Sometimes a “scrap outline intersect itself” may be induced by the scrap “join”. When therion must join scraps it deform the joining lines of the two scraps to smooth them together. A slight misplacement of a station in a scrap may induce a curling in the end of a line that give rise to this error.

If you compile the project with the debug option (“-d” on the therion command line), the postscript file of the wrong scrap is “$(thTMPDIR)/data.XX”. Here “XX” is the number in square brackets that follows the error message in the output of MetaPost. You can view the scrap, with a postscript viewer or converting it to PDF and with the pdf viewer. You might need to edit the file and add a “200 200 translate” line at the beginning.

In this way you can see the scrap outline, processed by Metapost, and spot the place of the error.

Path X and Y don't intersect TODO

The angle between two identical points is undefined TODO

can not connect 1@subsurvey.survey to centerline network It may denote an error in a “point” command of type “station”: the given station name is not present in the centerline data. Another possibility is that the centerline is not connected, ie, an “equate” command is missing.

duplicate object name – scrap1 This can happen when scraps are spread on several source files and you forget to assign their names. xtherion names the scraps following a default pattern, “scrap1” and so on. Therefore, if you do not name the scraps, two of them can get the same default name. To fix this problem, it is enough to rename the scraps.

incompatible scrap projection The scrap projection is not coherent with that of the map. Check the “-proj” option of the “scrap” control.

line (.th command)
invalid line type - subtype combination This message denotes a “line” command with and invalid “-subtype” option. The name of the line is displayed and when you click on it xtherion takes you to the map editor with the incorrect line selected.

names
invalid name format This message is followed by the invalid name. It can be that there are more than one space in the name, when only one is allowed, as in the names of people. For example, “M. Budaj (SCC)”. To fix it replace a space with a slash '/': “M. Budaj/(SCC)”.

station (type)
invalid station reference The name of a “station” point is incorrect. This message is followed by the wrong station name. xtherion switches automatically to the map editor and highlights the point (it is selected), so that you can correct the mistake.

MetaPost capacity exceeded, sorry [main memory size=3000001]. You must split the scrap in smaller scraps because you got to the limits of memory of the MetaPost program.

missing scrap before line command Graphical elements have been inserted outside a scrap. Open the map file “.th2” in the map editor and check the list of elements in the “Objects” control.

missing survey before equate command The “equate” command must appear inside a survey. The surveys must be hierarchically ordered, and the survey with the “equate” command must see (ie, contain) the stations this command refers to. These can be immediate stations of the survey, or belong to one of its subsurveys.

For example:

    survey X
      survey A
        1 ...
      endsurvey A
 
      survey B
        2 ...
      endsurvey B
 
      equate 1@A 2@B
    endsurvey X
  

Another example:

    survey X
      survey A
        1 ...
      endsurvey A
      
      2 ...
 
      equate 2 1@A
    endsurvey X
  

station (type)
no reference station found in scrap This message is followed by the name of the scrap. It states that the named scrap has no “station” point that refers to the survey data. Therefore, it cannot be placed on the map. Fix the scrap and insert points of type “station” or add the suitable “-name” options to those you already put in the scrap.

not enough layout option arguments This message is followed by the name of the layout option that has too few arguments. Fix the configuration file adding the missing arguments to the option.

object does not exist This is followed by the name (id) of the object that is referenced but not defined. You may have mispelled a name, or you might not have included (“input” command) the file with that object.

projection mishmash The projections of the elements of a map do not match: they must all have the same projection.

strange path in … This message may denote the presence of a line with only two coincident points. Search lines with only 2 points and which have the “close” option set. Unset the option and remove the 3rd point on the list, it's make a loop on the 2 points.

survey does not exist The name (id) that you used is not that of a survey.

unknown option – input test-layout.th In the configuration file the input command has been used inside a layout block.