This chapter describes advanced usage of Therion:
xtherion 
 The panel of the compiler window of  xtherion has four controls:   
therion. These have been described in section 1.3. surveys of the survey data files; 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  cursore of the list in the  “Objects” control, and the new element is assigned to the line.  The  cursore 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 grapgical 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.  
Opne 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.
 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 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,   
The layout option “debug” can have also other values:
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 sevral 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.
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.