===== 1 Installation ===== 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. \\ ==== 1.1 Download ==== ------ 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|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). {{ images_winsetup.jpg?503x385 | }} 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''. {{ images_winmenu.jpg?480x204 | }} **Mac** (by M. Sluka) There are no precompiled binaries for Mac. You have to - Install the Developer Tools, //XCode// from Mac OS X installation - Install //Survex//: download the source tgz from the website, untar it, then ''configure'', ''make'', and install it. (Use always ''sudo'' instead of ''su''). - Install the //TeX// packageuse the ''ii'' installer from [[http://ii2.sourceforge.net/tex-index.html|http://ii2.sourceforge.net/tex-index.html]] - Install //AquaTcl/Tk// from [[http://tcltkaqua.sourceforge.net/|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. - 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|http://www.imagemagick.org/download/binaries/ImageMagick-universal-apple-darwin8.7.0.tar.gz]] - Download the //Therion// package. Follow the instructions in the appendix of //The Therion Book//. To install use ''sudo make install''. - 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|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)//__\\ == 1.1.1 cavern == ''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|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)//__\\ == 1.1.2 Tcl/Tk == ''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)//__\\ == 1.1.3 TeX, MetaPost and pdfTeX == 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. == 1.1.4 Therion == Therion can be downloaded from [[http://therion.speleo.sk/download.php|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"; [[http://www.mingw.org|MinGW]] oppure [[http://gcc.gnu.org|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''. ----- \\ ==== 1.2 Execution ==== ----- 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'' [["ref#Tu99b"|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). {{ images_startup.jpg?198x210 | Startup }} 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. {{ images_xtherion.jpg?600x482 | xtherion }} ''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. == 1.2.1 Help == 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. == 1.2.2 File == 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". == 1.2.3 Window == 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. == 1.2.4 Toolbar == 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. {{ images_toolbar.png?480x100 | Toolbar }} 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. {{ images_toolbar2.png?480x100 | Toolbar di mappa }} == 1.2.5 Controls panel == 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. == 1.2.6 Status bar == ''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. == 1.2.7 Exercise == 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. \\ ==== 1.3 Trying xtherion ==== ----- 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. == 1.3.1 Therion files == 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". == 1.3.2 Example == 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. {{ images_example.jpg?600x413 | First test }} 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". == 1.3.3 A survey == 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. \\ ==== 1.A Therion setup ==== ----- ''therion'' and ''xtherion'' rely on environment variables and initialization files to configure their execution behaviour. __//environment (therion)//__\\ == 1.A.1 Environment == ''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''. == 1.A.2 Inizialization files. == 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: - ''$THERION'' - ''$HOME/.therion'' - ''/etc'' - ''/usr/etc'' - ''/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. == 1.A.3 Execution == 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. {{ images_th-flow.png?460x300 | Flow of control }} ''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.