Survex 1.0.40 Manual Olly Betts Wookey $Id: manual.sgml,v 1.117 2006-02-05 00:10:41 olly Exp $ Copyright © 1998-2010 Olly Betts $Date: 2006-02-05 00:10:41 $ This is the manual for Survex - an open-source software package for cave surveyors. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Introduction This section describes what Survex is, and outlines the scope of this manual. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ About Survex Survex is a multi-platform open-source cave surveying package. currently runs on UNIX, Microsoft Windows 95/NT and successors, Mac OS X, DOS, and Acorn RISC OS machines. We're investigating support for various palmtop devices. We are well aware that not everyone has access to super hardware - often surveying projects are run on little or no budget and any computers used are donated. We aim to ensure that Survex is feasible to use on low-spec machines. Obviously it won't be as responsive, but we intend it to be usable. Please help us to achieve this by giving us some feedback if you use Survex on a slow machine. Survex is capable of processing extremely complex caves very quickly and has a very effective, real-time cave viewer which allows you to rotate, zoom, and pan the cave using mouse or keyboard. We have tested it extensively using CUCC and ARGE's surveys of the caves under the Loser Plateau in Austria (over 11,500 survey legs, and over 66km of underground survey data). This can all be processed in a few seconds on a low-end Pentium machine. Survex is also used by many other survey projects around the world, including the Ogof Draenen survey, the Easegill resurvey project, the OFD survey, the OUCC Picos expeditions, and the Hong Meigui China expeditions. Survex is still actively being worked on. Version 1.0 is complete in some sense, but development continues - initially in reshaping Survex into a more integrated GUI package. We encourage feedback from users on important features or problems, which will help to direct future development. Contact addresses are at the end of this manual. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ About this Manual If there's a part of this manual you find hard to understand, please do let us know. We already know Survex well, so it can be hard for us to spot areas where the manual doesn't given enough information, or doesn't explain things clearly enough to follow when you don't know what's going on. It's helpful is you can suggest a better wording, but don't worry if you can't, just explain the problem as precisely as you can. The master version of this manual is an SGML document written using the docbook DTD, and automatically converted to a number of other formats. If you are going to send us major changes, it's much easier to include them if you work from this master. You can get it from the source archive (docs/manual.sgml) or from the Survex website. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Terminology Throughout this document we use British terminology for surveying. station a point in the cave that you survey from and/or to leg a line joining two stations survey a group of legs surveyed on the same trip ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Getting Started This section covers how to obtain the software, and how to unpack and install it, and how to configure it. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Obtaining Survex The latest version is available from the Survex website: http://survex.com/. If you do not have internet access or would prefer to get a copy by post, we are also happy to send out up-to-date copies on a floppy on receipt of a stamped, self-addressed envelope. See the end of this document for addresses. There's also a CD containing versions of Survex for every supported platform. You can download an image for this from the website, or we'll send you a copy on a CD-R if you send us money to cover the costs. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Installing Survex The details of installation depend greatly on what platform you are using, so there is a separate section below for each platform. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Linux We supply pre-compiled versions for x86 Linux machines in RPM format (suitable for Redhat, Mandrake, and some other distributions). Survex Debian packages are available from Debian mirror sites in the usual way. You'll need root access to install these prebuilt packages. If you don't have root access you will need to build from source (see the next section). ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Other versions of UNIX For other UNIX versions you'll need to get the source code and compile it on your system. Survex uses GNU automake and autoconf to streamline the compile process, so all you need to do is unpack the sources, then simply type ./ configure followed by make to build the programs and then make install to install them. Note: If you're building to install in your home directory (for example if you don't have root access on the machine you wish to install Survex on) configure and build with ./configure --prefix=/home/olly/survex then make to build and make install to install. There's a GUI cave viewer called aven, which needs wxWidgets to build, which in turn needs GTK+ (or Motif or just X11, but we only regularly test with the GTK+ version). ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Microsoft Windows 95/NT and successors This version comes packaged with an installation wizard. Just run the downloaded package and it will lead you through the installation process. If installing on MS Windows NT, 2000, or XP we recommend you run the installer as administrator (or as a user with administrator rights) so that the file associations can be set up for all users. This version includes a GUI cave survey viewer called aven, and a Survex printer driver (printwin) which uses the Windows printer system. The installer creates a Survex group in the Programs sub-menu of the Start menu containing the following items: • Aven • Documentation • Uninstall Survex Icons are installed for .svx, .3d, .err, and .pos files, and also for Compass Plot files (.plt and .plf) (which Survex can read). Double-clicking on a .svx file loads it for editing. To process it to produce a .3d file, right click and choose "Process" from the menu. Double-clicking the resultant .3d file views it in aven. All the Survex file types can be right clicked on to give a menu of possible actions. .svx Open Load file into SvxEdit Process Process file with cavern to produce .3d file (and .err file) .3d Open Load file into Aven Print Send to the printer Extend Produce extended elevation Convert to DXF Convert to a DXF file (suitable for importing into many CAD packages) Convert for hand plotting Produce a .pos file listing all the stations and their coordinates .err Open Load file into Notepad Sort by Error Sort .err file by the error in each traverse Sort by Horizontal Error Sort .err file by the horizontal error in each traverse Sort by Vertical Error Sort .err file by the vertical error in each traverse Sort by Percentage Error Sort .err file by the percentage error in each traverse Sort by Error per Leg Sort .err file by the error per leg in each traverse ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ MS Windows 3.1 and DOS (Intel 80386 or newer CPU) For MS Windows 3.1 we suggest using the DOS version. This version is compiled with the free DJGPP C compiler (http://www.delorie.com/djgpp/) which uses DPMI to access memory above DOS's 640k. Windows has DPMI services built in, as do QEMM and Novell DOS 7. For those situations where DPMI services aren't available, we include the free cwsdpmi.exe, which will be used automatically if it's needed. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ DOS (Intel 80286 or earlier CPU) We also supply a version suitable for use on pre-386 machines. You might wonder why - the reason is that many surveying projects have little or no budget and can acquire such machines for free. This version is suitable for caves up to medium size - a few thousand stations - which typically equates to a few kilometres of survey. A very loopy cave may need more memory. This version is built with Borland C. A feature of this is that the best way to force a program to terminate is with Ctrl-Break. Ctrl-C sometimes works, but is less reliable. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ RISC OS Survex for RISC OS comes in a zip archive. Installation is just a matter of opening the archive with !SparkPlug, !SparkFS, or similar and dragging the contents to where you want them installed. This version is known to work with RISC OS 3.1 or newer. We are unable to test compatibility with earlier versions of RISC OS. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Configuration Selecting Your Preferred Language Survex has extensive internationalisation capabilities. The language used for messages from Survex and most of the library calls it uses can be changed. By default this is picked up from the language the operating system is set to use (from "Regional Settings" in Control Panel on Microsoft Windows, from the LANG environment variable on UNIX, from the value passed to COUNTRY in CONFIG.SYS on MSDOS (but this doesn't distinguish between the different languages used in a country in most cases), or from the configured Territory on RISC OS). If no setting is found, or Survex hasn't been translated into the requested language, UK English is used. However you may want to override the language manually - for example if Survex isn't available in your native language you'll want to choose the supported language you understand best. To do this, you set the SURVEXLANG environment variable. Here's a list of the codes currently supported: ┌─────┬──────────────────────┐ │Code │ Language │ ├─────┼──────────────────────┤ │en │International English │ ├─────┼──────────────────────┤ │en_US│US English │ ├─────┼──────────────────────┤ │ca │Catalan │ ├─────┼──────────────────────┤ │de │German │ ├─────┼──────────────────────┤ │de_CH│Swiss German │ ├─────┼──────────────────────┤ │de_DE│German German │ ├─────┼──────────────────────┤ │es │Spanish │ ├─────┼──────────────────────┤ │fr │French │ ├─────┼──────────────────────┤ │it │Italian │ ├─────┼──────────────────────┤ │pt │Portuguese │ ├─────┼──────────────────────┤ │pt_BR│Brazillian Portuguese │ ├─────┼──────────────────────┤ │sk │Slovak │ └─────┴──────────────────────┘ Here are examples of how to set this environment variable to give messages in French (language code fr): DOS Put SET SURVEXLANG=fr in your AUTOEXEC.BAT script. You will need to restart DOS before it notices this setting - to set it for the current DOS session enter SET SURVEXLANG=fr at the MSDOS command prompt. Microsoft Windows For MS Windows 95 and 98 (and probably ME), you'll need to add a line containing SET SURVEXLANG=fr to your AUTOEXEC.BAT script. You need to reboot for the change to take effect. For MS Windows NT4, 2000, and XP, you should proceed as follows (this description is written from MS Windows 2000 - it should be similar on NT4 and XP): Open the Start Menu, navigate to the Settings sub-menu, and open Control Panel. Open System (picture of a computer) and click on the Advanced tab. Choose `Environmental Variables', and create a new one: name SURVEXLANG, value fr. Click OK and the new value should be effective immediately. UNIX - csh/tcsh setenv SURVEXLANG fr UNIX - sh/bash SURVEXLANG=fr ; export SURVEXLANG RISC OS Hold down Shift and double-click on !Cavern, then hold down Shift again and double-click on !Boot. Edit the line which says Set SurvexLang en and change the value to the code for the language you want from the table above. Save the file, and double-click on !Boot. This sets the language for all the Survex programs. If Survex isn't available in your language, you could help out by providing a translation. The initial translation is likely to be about a day's work; after that translations for new or changed messages are occasionally required. Contact us for details if you're interested. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Configuring the Printer Drivers Table of Contents print.ini -- survex printer settings On Microsoft Windows, we recommend you print using printwin which uses the built in drivers and so requires no separate configuration - if you can print from other programs, you can print from Survex. The only thing you may want to configure is the colours used if you have a colour printer. The drivers used for other platforms may require a small amount of configuration, which is described in the following section. print.ini Name print.ini -- survex printer settings Description The print.ini file contains printer descriptions for the Survex printer drivers. File Format The format of the print.ini file is similar to the .ini files used on Microsoft Windows. The file is divided into sections, each section corresponding to a separate printer description. A section starts with a section name in square brackets, e.g.: [generic_pcl] followed by some options of the form