source: git/doc/manual.sgml @ aa3ed76

RELEASE/1.2debug-cidebug-ci-sanitisersstereowalls-data
Last change on this file since aa3ed76 was aa3ed76, checked in by Olly Betts <olly@…>, 9 years ago

doc/manual.sgml: Strip references to obsolete versions of MS Windows.

  • Property mode set to 100644
File size: 98.4 KB
Line 
1<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
2<!ENTITY man.aven SYSTEM "aven.sgml">
3<!ENTITY man.3dtopos SYSTEM "3dtopos.sgml">
4<!ENTITY man.cad3d SYSTEM "cad3d.sgml">
5<!ENTITY man.cavern SYSTEM "cavern.sgml">
6<!ENTITY man.diffpos SYSTEM "diffpos.sgml">
7<!ENTITY man.extend SYSTEM "extend.sgml">
8<!ENTITY man.sorterr SYSTEM "sorterr.sgml">
9]>
10
11<!--
12FIXME:
13
143dfile title:
15defaults to a list of the leafnames of the <filename>.svx</filename> files specified on the
16command line (with any paths and extensions removed).
17.
18e.g.: cavern entrance.svx \data\2ndpart.svx
19.
20would give a surveytitle of 'entrance 2ndpart'.
21.
22but this may change...
23
24FIXME todo:
25mark-up of Windows Windows NT etc?
26section on "design philosophy"
27
28level sump fudge:
29
30*begin
31*data cartesian from to dx dy dz
32*sd dx dy 100 metres
33*sd dz 0.001 metres
34; upstream - downstream
35nuiping.gowiththeflow.129 dachao.upstream.105 0 0 0 ; last number is drop in height across the sump
36*end
37
38``Quick start'' section
39
40- install (by OS): unpacking, configuration (language, where support files live)
41
42- lead people through entering and processing
43a sample survey.  Take examples from surveying books and real surveys.
44
45
46<Para>The other really important commands apart from *BEGIN, *END, and
47*INCLUDE are *EQUATE and *FIX.
48</Para>
49
50<Para>*EQUATE is used to join surveys together, e.g.
51</Para>
52
53<programlisting>*equate entrance.6 adrian.1</programlisting>
54
55<Para>
56indicates that station 6 of the entrance survey was used as
57the station 1 of the Adrian's Route survey.
58</Para>
59
60<Para>*FIX is for fixing control points - for example:
61</Para>
62
63<programlisting>
64*fix 161.entrance.1    0  0  1780</programlisting>
65
66<Para>fixes the 1st point of the 'entrance' survey at the coordinates
670 (east-west), 0 (north-south), 1780 (altitude).
68</Para>
69
70
71<term>node</term>
72<listitem><para>when talking about the survey network, we talk about an
73<emphasis>n</emphasis>-node to describe the number of connections to
74a station.  So a 1-node is a station with only 1 leg to or from it
75- i.e. The end of a passage or survey. A
762-node is a typical station along a passage with a survey leg coming
77into it, and one going out.  A 3-node is a station with three legs
78joining it, e.g. at a T-junction. And so on.
79</para>
80
81-->
82
83<article Status="draft" id="index">
84 <articleinfo>
85  <Title><Application>Survex</Application> <!--VERSION-->1.2.20 Manual</Title>
86  <AuthorGroup>
87   <Author>
88    <FirstName>Olly</FirstName>
89    <SurName>Betts</SurName>
90    <AuthorBlurb><Para>
91      Olly Betts wrote most of <Application>Survex</Application>.
92    </Para></AuthorBlurb>
93    <Affiliation>
94     <Address><Email>olly@survex.com</Email></Address>
95    </Affiliation>
96   </Author>
97   <Author>
98    <SurName>Wookey</SurName>
99    <AuthorBlurb><Para>
100      Wookey is a small furry creature.
101    </Para></AuthorBlurb>
102    <Affiliation>
103     <Address><Email>wookey@survex.com</Email></Address>
104    </Affiliation>
105   </Author>
106  </AuthorGroup>
107  <copyright>
108   <year>1998-2015</year>
109   <holder role="mailto:olly@survex.com">Olly Betts</holder>
110  </copyright>
111  <Abstract>
112   <Para>
113    This is the manual for <Application>Survex</Application> - an open-source software package for
114    cave surveyors.
115   </Para>
116  </Abstract>
117 </articleinfo>
118
119<Sect1><Title>Introduction</Title>
120<?dbhtml filename="intro.htm">
121
122<Para>
123This section describes what <Application>Survex</Application> is, and outlines the scope of this
124manual.
125</Para>
126
127<Sect2><Title>About <Application>Survex</Application></Title>
128
129<Para><Application>Survex</Application> is a multi-platform open-source cave surveying
130package.
131Version 1.2 runs on UNIX, Microsoft Windows, and Mac OS X.
132We're investigating support for phones and tablets.
133</Para>
134
135<Para>We are well aware that not everyone has access to super hardware
136- often surveying projects are run on little or no budget and any
137computers used are donated.  We aim to ensure that <Application>Survex</Application> is
138feasible to use on low-spec machines.  Obviously it won't be as
139responsive, but we intend it to be usable.
140Please help us to achieve this by giving us some feedback
141if you use <Application>Survex</Application> on a slow machine.</Para>
142
143<Para><Application>Survex</Application> is capable of processing extremely complex caves very
144quickly and has a very effective, real-time cave viewer which allows
145you to rotate, zoom, and pan the cave using mouse or keyboard. We have
146tested it extensively using <Acronym>CUCC</Acronym> and <Acronym>ARGE</Acronym>'s surveys of the caves
147under the Loser Plateau in Austria (over 22,000 survey legs, and over
148120km of underground survey data). This can all be processed in around
14910 seconds on a low-end netbook.
150Survex is also used by many other survey projects around the world,
151including the
152<ulink url="http://www.oucc.org.uk/draenen/draenenmain.htm"
153>Ogof Draenen</ulink> survey, the
154<ulink url="http://www.easegill.org.uk/">Easegill</ulink> resurvey project,
155the <Acronym>OFD</Acronym> survey, the
156<!-- url="http://milos2.zoo.ox.ac.uk/~oucc/reports/surveys/surveys.htm" -->
157<ulink url="http://www.oucc.org.uk/reports/surveys/surveys.htm"
158><Acronym>OUCC</Acronym> Picos expeditions</ulink>, and the
159<ulink url="http://www.hongmeigui.net/">Hong Meigui China
160expeditions</ulink>. <!-- FIXME more? --></Para>
161
162<Para><Application>Survex</Application> is still actively being worked on.  Version 1.0 was
163complete in some sense, but development continues - initially in reshaping
164Survex into a more integrated GUI package.</Para>
165
166<Para>We encourage feedback from users on important features or problems,
167which will help to direct future development.  See the "Mailing List" section
168of this manual for the best way to contact us.</Para>
169
170</Sect2>
171
172<!--
173<Para>Because <Application>Survex</Application> is still being actively developed, this document
174has an unfortunate tendency to lag slightly behind the capabilities of the
175software. The latest version is now available on the web at <ulink
176url="http://survex.com/">http://survex.com/</ulink> - check there for latest info.
177</Para>
178-->
179
180<!--
181<Sect2><Title>Other Documentation</Title>
182
183<variablelist>
184<varlistentry>
185<term>NEWS or NEWS.txt</term>
186<listitem><Para>a list of changes of interest to
187<Application>Survex</Application> users, broken down by version number.  Consult this file
188when upgrading to find out what has changed since the version you were
189using previously.
190</Para></listitem>
191</varlistentry>
192
193<varlistentry>
194<term>ChangeLog or CHANGES.txt</term>
195<listitem><Para>a much more detailed list of changes, aimed at developers
196rather than end users.
197</Para></listitem>
198</varlistentry>
199
200<varlistentry>
201<term>BUGS or BUGS.txt</term>
202<listitem><Para>a list of known bugs.
203</Para></listitem>
204</varlistentry>
205
206<varlistentry>
207<term>TODO or TODO.txt</term>
208<listitem><Para>planned changes and enhancements.
209</Para></listitem>
210</varlistentry>
211
212FIXME: merge INSTALL* into here, then process separately and textify
213to produce INSTALL*
214
215<varlistentry>
216<term>INSTALL or INSTALL.txt</term>
217<listitem><Para>instructions for installing <Application>Survex</Application>.  The
218Microsoft Windows version comes packaged up with an installation wizard,
219so this file doesn't exist there (you just run the package and follow
220the on-screen instructions).
221</Para></listitem>
222</varlistentry>
223</variablelist>
224
225</Sect2>
226-->
227
228<Sect2><Title>About this Manual</Title>
229
230<Para>
231If there's a part of this manual you find hard to understand, please do
232let us know.  We already know Survex well, so it can be hard for us
233to spot areas where the manual doesn't given enough information, or
234doesn't explain things clearly enough to follow when you don't know what's
235going on.  It's helpful is you can suggest a better wording, but don't worry
236if you can't, just explain the problem as precisely as you can.
237</Para>
238
239<Para>
240The master version of this manual is an <acronym>SGML</acronym>
241document written using the <ulink url="http://www.docbook.org/">docbook
242<acronym>DTD</acronym></ulink>,
243and automatically converted to a number of other formats.  If
244you are going to send us <emphasis>major</emphasis> changes, it's much easier
245to include them if you work from this master.  You can get it
246from the source archive (docs/manual.sgml) or from <ulink
247url="http://survex.com/docs.html">the Survex website</ulink>.
248</Para>
249
250<Sect3><Title>Terminology</Title>
251
252<Para>Throughout this document we use British terminology for
253surveying.</Para>
254
255<variablelist>
256<varlistentry>
257<term>station</term>
258<listitem><para>a point in the cave that you survey from and/or to
259</para></listitem></varlistentry>
260
261<varlistentry>
262<term>leg</term>
263<listitem><para>a line joining two stations
264</para></listitem></varlistentry>
265
266<varlistentry>
267<term>survey</term>
268<listitem><para>a group of legs surveyed on the same trip
269</para></listitem></varlistentry>
270
271</variablelist>
272
273</Sect3>
274
275</Sect2>
276
277<!-- FIXME: Further sources of info: website, mailing lists, other docs -->
278
279</Sect1>
280
281<Sect1><Title>Getting Started</Title>
282<?dbhtml filename="getstart.htm">
283
284<Para>This section covers how to obtain the software, and how to unpack and
285install it, and how to configure it.</Para>
286
287<Sect2><Title>Obtaining <Application>Survex</Application></Title>
288
289<Para>The latest version is available from the <Application>Survex</Application> website:
290<ulink url="http://survex.com/">http://survex.com/</ulink>.  It is also
291freely redistributable, so you welcome to get a copy from someone else
292who has already downloaded it.</Para>
293
294<Para>If you want some sample data to experiment with, you can download some
295from the Survex website too:
296<ulink url="http://survex.com/software/sample.tar.gz">http://survex.com/software/sample.tar.gz</ulink></Para>
297
298</Sect2>
299
300<Sect2><Title>Installing <Application>Survex</Application></Title>
301
302<Para>The details of installation depend greatly on what platform you
303are using, so there is a separate section below for each platform.</Para>
304
305<Sect3><Title>Linux</Title>
306
307<Para>
308We supply pre-compiled versions for x86 Linux machines in RPM format
309(suitable for Redhat, Mandrake, and some other distributions).
310Survex Debian packages are available from Debian mirror sites in
311the usual way.
312</Para>
313
314<Para>
315You'll need root access to install these prebuilt packages.
316If you don't have root access you will need to build from source
317(see the next section).
318</Para>
319
320<!-- FIXME Add Gnome file association note for Linux/Unix
321<Para>On Microsoft Windows, <Application>Survex</Application> installs with
322suitable file associations so that you can drive it from the GUI.
323On UNIX you need to drive <Application>Survex</Application> from a command-line
324prompt (or set some a filemanager or graphics shell).
325</Para>
326-->
327
328</Sect3>
329
330<Sect3><Title>Other versions of UNIX</Title>
331
332<Para>For other UNIX versions you'll need to get the source code
333and compile it on your system.  Unpack the sources and read
334the file called INSTALL in the top level for details about building
335from source.
336</Para>
337
338</Sect3>
339
340<Sect3><Title>Microsoft Windows</Title>
341
342<Para>
343This version comes packaged with an installation wizard.  Just
344run the downloaded package and it will lead you through the
345installation process.  If you want the file associations to be
346set up for all user, run the installer as administrator, or as a
347user with administrator rights.
348</Para>
349
350<Para>
351The survey viewer that's part of <Application>Survex</Application> is called
352aven, and uses OpenGL for 3d rendering.
353</Para>
354
355<Para>
356If you find that 3D rendering is sometimes very slow (e.g. one user reported
357very slow performance when running full screen, while running in a window
358was fine) then try installing the OpenGL driver supplied by the manufacturer
359of your graphics card rather than the driver Microsoft supply.
360</Para>
361
362<Para>
363The installer creates a Survex group in the Programs sub-menu of the
364Start menu containing the following items:
365</Para>
366
367<ItemizedList>
368
369<ListItem><Para>Aven</Para></ListItem>
370
371<ListItem><Para>Documentation</Para></ListItem>
372
373<ListItem><Para>Uninstall Survex</Para></ListItem>
374
375</ItemizedList>
376
377<Para>
378Icons are installed for <filename>.svx</filename>, <filename>.3d</filename>, <filename>.err</filename>, and <filename>.pos</filename> files, and also for
379Compass Plot files (<filename>.plt</filename> and <filename>.plf</filename>)
380(which Survex can read). <!-- FIXME XYZ -->
381Double-clicking on a <filename>.svx</filename> file loads it for editing.  To process it to
382produce a <filename>.3d</filename> file, right click and choose "Process" from the menu.
383Double-clicking the resultant <filename>.3d</filename> file views it in aven.
384All the <Application>Survex</Application> file types can be right clicked on to give a menu of
385possible actions. 
386</Para>
387
388<VariableList>
389<VarListEntry><Term><filename>.svx</filename></Term>
390<ListItem>
391  <VariableList>
392  <VarListEntry><Term>Process</Term>
393  <ListItem><Para>
394  Process file with cavern to produce <filename>.3d</filename> file (and <filename>.err</filename> file)
395  </Para></ListItem>
396  </VarListEntry>
397  </VariableList>
398</ListItem>
399</VarListEntry>
400   
401<VarListEntry><Term><filename>.3d</filename></Term>
402<ListItem>
403  <VariableList>
404  <VarListEntry><Term>Open</Term>
405  <ListItem><Para>
406  Load file into Aven
407  </Para></ListItem>
408  </VarListEntry>
409  <VarListEntry><Term>Print</Term>
410  <ListItem><Para>
411  Send to the printer
412  </Para></ListItem>
413  </VarListEntry>
414  <VarListEntry><Term>Extend</Term>
415  <ListItem><Para>
416  Produce extended elevation
417  </Para></ListItem>
418  </VarListEntry>
419  <VarListEntry><Term>Convert to DXF</Term>
420  <ListItem><Para>
421  Convert to a DXF file (suitable for importing into many CAD packages)
422  </Para></ListItem>
423  </VarListEntry>
424  <VarListEntry><Term>Convert for hand plotting</Term>
425  <ListItem><Para>
426  Produce a <filename>.pos</filename> file listing all the stations and their coordinates
427  </Para></ListItem>
428  </VarListEntry>
429  </VariableList>
430</ListItem>
431</VarListEntry>
432
433<VarListEntry><Term><filename>.err</filename></Term>
434<ListItem>
435  <VariableList>
436  <VarListEntry><Term>Open</Term>
437  <ListItem><Para>
438  Load file into Notepad
439  </Para></ListItem>
440  </VarListEntry>
441  <VarListEntry><Term>Sort by Error</Term>
442  <ListItem><Para>
443  Sort <filename>.err</filename> file by the error in each traverse
444  </Para></ListItem>
445  </VarListEntry>
446  <VarListEntry><Term>Sort by Horizontal Error</Term>
447  <ListItem><Para>
448  Sort <filename>.err</filename> file by the horizontal error in each traverse
449  </Para></ListItem>
450  </VarListEntry>
451  <VarListEntry><Term>Sort by Vertical Error</Term>
452  <ListItem><Para>
453  Sort <filename>.err</filename> file by the vertical error in each traverse
454  </Para></ListItem>
455  </VarListEntry>
456  <VarListEntry><Term>Sort by Percentage Error</Term>
457  <ListItem><Para>
458  Sort <filename>.err</filename> file by the percentage error in each traverse
459  </Para></ListItem>
460  </VarListEntry>
461  <VarListEntry><Term>Sort by Error per Leg</Term>
462  <ListItem><Para>
463  Sort <filename>.err</filename> file by the error per leg in each traverse
464  </Para></ListItem>
465  </VarListEntry>
466  </VariableList>
467</ListItem>
468</VarListEntry>
469</VariableList>
470
471</Sect3>
472
473</Sect2>
474
475<Sect2><Title>Configuration</Title>
476
477<Sect3><Title>Selecting Your Preferred Language</Title>
478
479<Para>Survex has extensive internationalisation capabilities.  The
480language used for messages from Survex and most of the library calls
481it uses can be changed.  By default this is picked up from the
482language the operating system is set to use (from "Regional Settings"
483in Control Panel on Microsoft Windows, from the
484<systemitem>LANG</systemitem> environment variable on UNIX
485If no setting
486is found, or <Application>Survex</Application> hasn't been translated into the
487requested language, UK English is used.</Para>
488
489<Para>
490However you may want to override the language manually -
491for example if Survex isn't available in your native language
492you'll want to choose the supported language you understand best.
493</Para>
494
495<Para>
496To do this, you set the
497<systemitem>SURVEXLANG</systemitem> environment variable.  Here's a list
498of the codes currently supported:</Para>
499
500<informaltable frame="all">
501<tgroup cols="2">
502<thead>
503<row><entry>Code</entry><entry>Language</entry></row>
504</thead>
505<tbody>
506<row><entry>en</entry><entry>International English</entry></row>
507<row><entry>en_US</entry><entry>US English</entry></row>
508<row><entry>bg</entry><entry>Bulgarian</entry></row>
509<row><entry>ca</entry><entry>Catalan</entry></row>
510<row><entry>de</entry><entry>German</entry></row>
511<row><entry>de_CH</entry><entry>Swiss German</entry></row>
512<row><entry>el</entry><entry>Greek</entry></row>
513<row><entry>es</entry><entry>Spanish</entry></row>
514<row><entry>fr</entry><entry>French</entry></row>
515<row><entry>hu</entry><entry>Hungarian</entry></row>
516<row><entry>id</entry><entry>Indonesian</entry></row>
517<row><entry>it</entry><entry>Italian</entry></row>
518<row><entry>pl</entry><entry>Polish</entry></row>
519<row><entry>pt</entry><entry>Portuguese</entry></row>
520<row><entry>pt_BR</entry><entry>Brazillian Portuguese</entry></row>
521<row><entry>ro</entry><entry>Romanian</entry></row>
522<row><entry>ru</entry><entry>Russian</entry></row>
523<row><entry>sk</entry><entry>Slovak</entry></row>
524<row><entry>zh_CN</entry><entry>Chinese (Simplified)</entry></row>
525</tbody>
526</tgroup>
527</informaltable>
528
529<Para>Here are examples of how to set this environment variable to give
530messages in French (language code fr):</Para>
531
532<VariableList>
533 <VarListEntry><Term>Microsoft Windows</Term>
534   <ListItem><Para>
535For MS Windows proceed as follows (this description was written from
536MS Windows 2000, but it should be fairly similar in other versions): Open the
537Start Menu, navigate to the Settings sub-menu, and
538open Control Panel.  Open System (picture of a computer) and click on the
539Advanced tab.  Choose `Environmental Variables', and create a new one: name
540<systemitem>SURVEXLANG</systemitem>, value <systemitem>fr</systemitem>.
541Click OK and the new value should be effective immediately.
542   </Para></ListItem>
543 </VarListEntry>
544 <VarListEntry><Term>UNIX - csh/tcsh</Term>
545   <ListItem><Para><userinput>setenv SURVEXLANG fr</userinput></Para></ListItem>
546 </VarListEntry>
547 <VarListEntry><Term>UNIX - sh/bash</Term>
548   <ListItem><Para><userinput>SURVEXLANG=fr ; export SURVEXLANG</userinput></Para></ListItem>
549 </VarListEntry>
550</VariableList>
551
552<Para>If <Application>Survex</Application> isn't available in your language, you could
553help out by providing a translation.  The initial translation is
554likely to be about a day's work; after that translations for
555new or changed messages are occasionally required.  Contact us for details
556if you're interested.</Para>
557
558</Sect3>
559
560</Sect2>
561
562</Sect1>
563
564<!-- FIXME
565
566type in .svx file
567
568run cavern (through aven)
569
570run aven
571
572how to print/export etc
573
574-->
575
576<!-- FIXME perhaps move this after data files section? -->
577<Sect1><Title>Survex Programs</Title>
578<?dbhtml filename="cmdline.htm">
579
580<Sect2><Title>Standard Options</Title>
581
582<Para>All <Application>Survex</Application> programs respond to the following command line options:
583</Para>
584
585<VariableList>
586
587<VarListEntry><Term>--help</Term><listitem><Para>
588display option summary and exit
589</Para></listitem></VarListEntry>
590
591<VarListEntry><Term>--version</Term><listitem><Para>
592output version information and exit
593</Para></listitem></VarListEntry>
594
595</VariableList>
596
597</Sect2>
598
599<Sect2><Title>Short and Long Options</Title>
600
601<Para>
602Options have two forms: short (a dash followed by a single letter e.g.
603<command>cavern -p</command>) and long (two dashes followed by one or more words e.g.
604<command>cavern --percentage</command>).  The long form is generally easier to
605remember, while the short form is quicker to type.  Options are often
606available in both forms.
607</Para>
608
609<Note><Para>Command line options are case sensitive, so "-B" and "-b"
610are different (this didn't used to be the case before Survex 0.90).  Case
611sensitivity doubles the number of available short options (and is also the
612norm on UNIX).
613</Para></Note>
614</Sect2>
615
616<Sect2><Title>Filenames on the Command Line</Title>
617
618<Para>Filenames with spaces can be processed (provided your operating system
619supports them - UNIX does, and so do recent versions of Microsoft
620Windows).  You need to enclose the filename in quotes like so:
621<userinput>cavern "Spider Cave"</userinput>
622</Para>
623
624<Para>A file specified on the command line of any of the <Application>Survex</Application> suite
625of programs will be looked for as specified.  If it is not found, then the
626file is looked for with the appropriate extension appended.  So
627<userinput>cavern survey</userinput> will look first for
628<filename>survey</filename>, then for <filename>survey.svx</filename>.
629</Para>
630
631</Sect2>
632
633<Sect2><title>Command Reference</title>
634
635<refentry id="cavern">
636<?dbhtml filename="cavern.htm">
637&man.cavern;
638</refentry>
639<refentry id="aven">
640<?dbhtml filename="aven.htm">
641&man.aven;
642</refentry>
643<refentry id="x3dtopos">
644<?dbhtml filename="3dtopos.htm">
645&man.3dtopos;
646</refentry>
647<refentry id="cad3d">
648<?dbhtml filename="cad3d.htm">
649&man.cad3d;
650</refentry>
651<refentry id="diffpos">
652<?dbhtml filename="diffpos.htm">
653&man.diffpos;
654</refentry>
655<refentry id="extend">
656<?dbhtml filename="extend.htm">
657&man.extend;
658</refentry>
659<refentry id="sorterr">
660<?dbhtml filename="sorterr.htm">
661&man.sorterr;
662</refentry>
663
664</Sect2>
665
666</Sect1>
667
668<Sect1><Title><Application>Survex</Application> data files</Title>
669<?dbhtml filename="datafile.htm">
670
671<Para>Survey data is entered in the form of text files. You can use any
672text editor you like for this, so long as it has the capability of
673writing a plain ASCII text file. The data format is very flexible;
674unlike some other cave surveying software, Survex does not require
675survey legs to be rearranged to suit the computer, and the ordering
676of instrument readings on each line is fully specifiable.  So you can enter
677your data much as it appears on the survey notes, which is important
678in reducing the opportunities for transcription errors.
679</Para>
680
681<Para>
682Also all the special characters are user-definable - for example,
683the separators can be spaces and tabs, or commas (e.g. when exporting from a
684spreadsheet), etc; the decimal point can be a slash (for clarity), a comma
685(as used in continental Europe), or anything else you care to choose.
686This flexibility
687means that it should be possible to read in data from almost any sort of
688survey data file without much work.
689</Para>
690
691<Para><Application>Survex</Application> places no restrictions on you in terms of the ordering
692of survey legs. You can enter or process data in any order and <Application>Survex</Application> will
693read it all in before determining how it is connected. You can also use the
694hierarchical naming so that you do not need to worry about using the same
695station name twice.
696</Para>
697
698<!-- FIXME don't encourage separate processing -->
699<Para>The usual arrangement is to have one file which lists all the others
700that are included (e.g., <filename>161.svx</filename>). Then
701<command>cavern 161</command> will process all your data. To just process a
702section use the filename for that section, e.g. <command>cavern dtime</command>
703will process the dreamtime file/section of Kaninchenh&ouml;hle.  To
704help you out, if all legs in a survey are connected to one another
705but the survey has no fixed points, cavern
706will 'invent' a fixed point and print a warning message to this
707effect.
708</Para>
709
710<Para>
711It is up to you what data you put in which files.  You
712can have one file per trip, or per area of the cave, or just one
713file for the whole cave if you like.
714On a large survey project it makes sense to group related surveys in the
715same file or directory.
716</Para>
717<!-- FIXME: wook sez:
718
719 Point out in documentation that file structure and survey structure don't
720 have to be the same.  And in particular that folder/directory names can be
721 different.
722
723Which is partly covered above, though the last bit isn't...
724-->
725
726<!-- FIXME "Anatomy of a Survey" section -->
727<Sect2><Title>Readings</Title>
728
729<Para>Blank lines (i.e. lines consisting solely of BLANK characters)
730are ignored. The last line in the file need not be terminated by
731an end of line character. All fields on a line must be separated
732by at least one BLANK character. An OMIT character
733(default '-') indicates that a field is unused. If the field is
734not optional, then an error is given.
735</Para>
736
737</Sect2>
738
739<Sect2><Title>Survey Station Names</Title>
740
741<Para><Application>Survex</Application> has a powerful system for naming stations.  It
742uses a hierarchy of survey names, similar to the nested folders
743your computer stores files in.
744So point 6 in the entrance survey of Kaninchenh&ouml;hle
745(cave number 161) is referred to as: 161.entrance.6
746</Para>
747
748<Para>This seems a natural way to refer to station names.  It also
749means that it is very easy to include more levels, for example if you
750want to plot all the caves in the area you just list them all in
751another file, specifying a new prefix.  So to group 3 nearby caves
752on the Loser Plateau you would use a file like
753this:
754</Para>
755
756<programlisting>
757*begin Loser
758*include 161
759*include 2YrGest
760*include 145
761*end Loser</programlisting>
762
763<Para>
764The entrance series point mentioned above would now be referred
765to as: Loser.161.entrance.6
766</Para>
767
768<!--
769<Para>This may seem a tad complex but is really very natural once you
770get the hang of it.
771</Para>
772-->
773<Para>You do not have to use this system at all, and can just give all
774stations unique identifiers if you like:
775</Para>
776
777<Para>1, 2, 3, 4, 5, ... 1381, 1382
778</Para>
779
780<Para>or
781</Para>
782
783<Para>AA06, AA07, P34, ZZ6, etc.
784</Para>
785
786<!-- FIXME:
787<Para>However you'll loose the ability to handle subsurveys if you do.
788</Para>
789-->
790
791<Para>Station and survey names may contain any alphanumeric characters and
792additionally any characters in NAMES (default `_' and `-'). Alphabetic
793characters may be forced to upper or lower case by using the *case
794command. Station names may be any length - if you want to only treat
795the first few characters as significant you can get cavern to truncate
796the names using the *truncate command.
797</Para>
798
799</Sect2>
800
801<Sect2><Title>Numeric fields</Title>
802
803<Para>[&lt;MINUS&gt;|&lt;PLUS&gt;] &lt;integer part&gt; [ &lt;DECIMAL&gt;
804[ &lt;decimal fraction&gt; ] ]
805</Para>
806
807<Para>
808or [&lt;MINUS&gt;|&lt;PLUS&gt;] &lt;DECIMAL&gt; &lt;dec fraction&gt;
809</Para>
810
811<Para><!-- FIXME: put informal description first -->
812i.e. optional PLUS or MINUS sign in front, with
813optional DECIMAL character (default '.'), which may be
814embedded, leading or trailing. No spaces are allowed between the
815various elements.
816</Para>
817
818<Para>
819All of these are valid examples: +47, 23, -22, +4.5, 1.3, -0.7, +.15, .4,
820-.05
821</Para>
822
823</Sect2>
824
825<Sect2><Title>Accuracy</Title>
826
827<Para>Accuracy assessments may be provided or defaulted for any survey
828leg. These determine the distribution of loop closure errors over the
829legs in the loop. See *SD for more information.
830</Para>
831
832</Sect2>
833
834<!--
835<Sect2><Title>Survey Coordinate Range</Title>
836
837<Para>
838If we store distances to nearest 10um (0.01mm) in 4 bytes, this
839gives a range of ~20 km. This method is currently not used, but
840has several advantages (data storage space [double uses 8 bytes
841- with my C compiler], speed (unless your FP chip works in parallel
842with your CPU [e.g. the new Acorn FPU for the ARM], and numerical
843accuracy [compared to using floats at least]) and so may be adopted
844in future). Nearest 0.1mm gives -200 km, which is enough for most
845people, but may mean rounding errors become significant.
846</Para>
847
848<Para>
849I will have to do some sums...
850</Para>
851
852</Sect2>
853
854-->
855
856<Sect2><Title>Cavern Commands</Title>
857
858<Para>Commands in <filename>.svx</filename> files are introduced by an asterisk
859(by default - this can be changed using the <command>set</command> command).
860</Para>
861
862<Para>The commands are documented in a common format:
863</Para>
864
865<!-- FIXME: make this a RefGroup (or whatever that's called) of RefEntry-s? -->
866<itemizedlist>
867<listitem><para>Command Name</para></listitem>
868<listitem><para>Syntax</para></listitem>
869<listitem><para>Example</para></listitem>
870<listitem><para>Validity</para></listitem>
871<!-- FIXME
872anywhere, in a block, at start of a block, after a begin (for *end)
873-->
874<listitem><para>Description</para></listitem>
875<listitem><para>Caveats</para></listitem>
876<listitem><para>See Also</para></listitem>
877<!-- FIXME
878"Usefulness" - or status maybe?
879deprecated, esoteric (*set), useful, vital
880-->
881</itemizedlist>
882
883<Sect3><Title>ALIAS</Title>
884
885<VariableList>
886
887<VarListEntry><Term>Syntax</Term>
888
889<listitem><Para>*alias station &lt;alias&gt; [&lt;target&gt;]</Para></listitem>
890
891</VarListEntry>
892
893<VarListEntry><Term>Example</Term>
894
895<listitem>
896<Para>
897<programlisting>
898*begin parsons_nose
899*alias station - ..
9001 2 12.21 073 -12
9012 -  4.33 011 +02
9022 -  1.64 180 +03
9032 3  6.77 098 -04
904*end parsons_nose</programlisting>
905</Para>
906</listitem>
907
908</VarListEntry>
909
910<VarListEntry><Term>Description</Term>
911
912<listitem><Para>*alias allows you to map a station name which appears in
913the survey data to a different name internally.  At present, you can only
914create an alias of '-' to '..', which is intended to support the pocket topo
915style notation of '-' being a splay to an anonymous point on the cave wall.
916And you can unalias '-' with '*alias station -'.
917</Para>
918
919<Para>
920Aliases are scoped by *begin/*end blocks - when a *end is reached, the aliases
921in force at the corresponding begin are restored.
922</Para>
923
924<Para>
925*alias was added in Survex 1.2.7.
926</Para></listitem>
927
928</VarListEntry>
929
930<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
931
932<VarListEntry><Term>See Also</Term>
933
934<listitem><Para>*begin, *end</Para></listitem>
935
936</VarListEntry>
937
938</VariableList>
939
940</Sect3>
941
942<Sect3><Title>BEGIN</Title>
943
944<VariableList>
945
946<VarListEntry><Term>Syntax</Term>
947
948<listitem><Para>*begin [&lt;survey&gt;]</Para></listitem>
949
950</VarListEntry>
951
952<VarListEntry><Term>Example</Term>
953
954<listitem>
955<Para>
956<programlisting>
957*begin littlebit
9581 2 10.23 106 -02
9592 3  1.56 092 +10
960*end littlebit</programlisting>
961
962<programlisting>
963; length of leg across shaft estimated
964*begin
965*sd tape 2 metres
9669 10 6.   031 -07
967*end</programlisting>
968</Para>
969</listitem>
970
971</VarListEntry>
972
973<VarListEntry><Term>Description</Term>
974
975<listitem><Para>*begin stores the current values of the current settings
976such as instrument calibration, data format, and so on.
977These stored values are restored after the corresponding *end.
978If a survey name is given, this is used inside the *begin/*end block,
979and the corresponding *end should have the same survey name.
980*begin/*end blocks may be nested to indefinite depth.
981</Para></listitem>
982
983</VarListEntry>
984
985<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
986
987<VarListEntry><Term>See Also</Term>
988
989<listitem><Para>*end, *prefix</Para></listitem>
990
991</VarListEntry>
992
993</VariableList>
994
995</Sect3>
996
997<Sect3><Title>CALIBRATE</Title>
998
999<VariableList>
1000
1001<VarListEntry><Term>Syntax</Term>
1002
1003<listitem>
1004<Para>*calibrate &lt;quantity list&gt; &lt;zero error&gt; [&lt;scale&gt;]
1005</Para>
1006<Para>*calibrate default
1007</Para>
1008</listitem>
1009
1010</VarListEntry>
1011
1012<VarListEntry><Term>Example</Term>
1013
1014<listitem>
1015<Para>
1016<programlisting>
1017*calibrate tape +0.3
1018</programlisting>
1019</Para>
1020</listitem>
1021
1022</VarListEntry>
1023
1024<VarListEntry><Term>Description</Term>
1025
1026<listitem>
1027
1028<Para>
1029*calibrate is used to specify instrument calibrations.
1030</Para>
1031
1032<Para>
1033&lt;quantity&gt; is one of TAPE|COMPASS|CLINO|COUNTER|DEPTH|DECLINATION|X|Y|Z
1034</Para>
1035
1036<Para>
1037Several quantities can be given in &lt;quantity list&gt;
1038</Para>
1039
1040<Para>
1041Value = ( Reading - ZeroError ) * Scale    (Scale defaults to 1.0)
1042</Para>
1043
1044<Para>
1045You need to be careful about the sign of the ZeroError. The value of
1046ZeroError is what the the instrument would read when measuring a
1047reading which should be zero.  So for example, if your tape measure
1048has the end missing, and you are using the 30cm mark to take all
1049measurements from, then a zero distance would be measured as 30cm and
1050you would correct this with:
1051</Para>
1052
1053<programlisting>*CALIBRATE tape +0.3</programlisting>
1054
1055<Para>If you tape was too long, starting at -20cm (it does happen!)
1056then you can correct it with:
1057</Para>
1058
1059<programlisting>*CALIBRATE tape -0.2</programlisting>
1060
1061<Para>Note: ZeroError is irrelevant for Topofil counters and depth
1062gauges since pairs of readings are subtracted.
1063</Para>
1064
1065<Para>
1066The magnetic deviation varies from year to year and it is often
1067desirable to keep the compass zero error and the magnetic deviation
1068separate. cavern calculates the true bearing as follows:
1069</Para>
1070
1071<Para>
1072(magnetic bearing) = ((reading)-(compass zero err)) * (compass
1073scale factor)
1074</Para>
1075
1076<Para>
1077(true bearing) = ((bearing)-(declination zero err))
1078</Para>
1079
1080<Para>
1081The scale factor for DECLINATION must be 1.0, otherwise an error
1082is given. <!-- FIXME: practical example for declination -->
1083</Para>
1084
1085<Para>
1086The default is all quantities calibrated to scale factor 1.0,
1087zero error 0.0
1088</Para>
1089
1090</listitem>
1091
1092</VarListEntry>
1093
1094<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1095
1096<VarListEntry><Term>See Also</Term>
1097
1098<listitem><Para>*units</Para></listitem>
1099
1100</VarListEntry>
1101
1102</VariableList>
1103
1104</Sect3>
1105
1106<Sect3><Title>CASE</Title>
1107
1108<VariableList>
1109
1110<VarListEntry><Term>Syntax</Term>
1111
1112<listitem><para>*case preserve|toupper|tolower</para></listitem>
1113
1114</VarListEntry>
1115
1116<VarListEntry><Term>Example</Term>
1117
1118<listitem>
1119<Para>
1120<programlisting>
1121*begin bobsbit
1122; Bob insists on using case sensitive station names
1123*case preserve
11241 2   10.23 106 -02
11252 2a   1.56 092 +10
11262 2A   3.12 034 +02
11272 3    8.64 239 -01
1128*end bobsbit</programlisting>
1129</Para>
1130</listitem>
1131
1132</VarListEntry>
1133
1134<VarListEntry><Term>Description</Term>
1135
1136<listitem><Para>*case determines how the case of letters in survey names is
1137handled.  By default all names are forced to lower case (which gives a case
1138insensitive match, but you can tell cavern to force to upper case, or leave
1139the case as is (in which case '2a' and '2A' will be regarded as different).
1140</Para></listitem>
1141
1142</VarListEntry>
1143
1144<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1145
1146<!-- <VarListEntry><Term>See Also</Term>
1147
1148<listitem><Para>*end, *prefix</Para></listitem>
1149
1150</VarListEntry>
1151-->
1152
1153</VariableList>
1154
1155<!-- FIXME - work this text in here or elsewhere
1156
1157What I mean (though failed to express very well) is that a dataset without
1158this information isn't the same dataset (in general anyway).  For example:
1159
1160A1 a2 10.32 140 -05
1161a2 a3  4.91 041 -01
1162a1 a3  7.01 206  02
1163
1164is either a traverse of 3 legs or a (probably badly misclosed) loop.  If
1165these names are on the original survey notes, the surveyors ought to say
1166whether "A1" is the same as "a1" (although the usual case for using this
1167feature is probably for importing data from elsewhere).  Similarly for
1168truncation.  Whether a clino of +/-90 degrees (or +/-100 grad, etc) is
1169interpreted as a plumb is something that should have been noted in the cave
1170(unless it's implicit because it's standard practice for a survey project).
1171
1172It's a similar issue to calibration data in many ways.  You can argue it's
1173not part of "the survey", but without it the survey won't be the same shape,
1174and it's not useful to process the same survey with different settings for
1175compass calibration or name case sensitivity.
1176
1177>Clearly that is unhelpfully strict, but it is
1178>important to be semantically clear about what is 'data' and what is 'commands
1179>or meta-data' which describe what to do with/how to interpret that data.
1180
1181Think of the lines starting with a "*" as "command or meta-data".
1182
1183>The most-correct solution to this is (I believe) Martin Heller's idea about
1184>including 'rules' in the datastream, but that's too big a subject for right
1185>now.
1186>
1187>The reason '-C' was made into a command-line option, was that it made very
1188>little sense to change it part way though a dataset. What exactly happens if
1189>you suddenly tell cavern to become case-sensitive halfway through a run?
1190
1191-C has always had 3 settings - "leave case alone", "force to lower", and
1192"force to upper".  It doesn't really mean "case sensitivity" but rather
1193something like "case processing".  So you can usefully change it during a
1194run.  So if my dataset treats "NoTableChamber" (so named because it was
1195lacking in furniture) as different from "NotableChamber" (which was notable
1196for other reasons) I can process it with a dataset from someone else which
1197needs to be treated as case insensitive like so:
1198
1199*begin my_cave
1200*include my_dataset
1201*end my_cave
1202
1203*equate my_cave.NoTableChamber.14 your_cave.linkpassage.13
1204
1205*begin your_cave
1206*case tolower
1207*include your_dataset
1208*end your_cave
1209
1210You may be thinking of -U<n>, which used to mean "only compare the first n
1211characters of station names", but that doesn't allow arbitrary datasets to
1212be processed together.
1213
1214So we changed it to mean "truncate station names to n characters", and
1215allowed it to be changed at any point, rather than being set once for the
1216whole run.
1217
1218-->
1219
1220</Sect3>
1221
1222<Sect3><Title>COPYRIGHT</Title>
1223
1224<VariableList>
1225
1226<VarListEntry><Term>Syntax</Term>
1227
1228<listitem><Para>*copyright &lt;date&gt; &lt;text&gt;</Para></listitem>
1229
1230</VarListEntry>
1231
1232<VarListEntry><Term>Example</Term>
1233
1234<listitem>
1235<Para>
1236<programlisting>
1237*begin littlebit
1238*copyright 1983 CUCC
12391 2 10.23 106 -02
12402 3  1.56 092 +10
1241*end littlebit</programlisting>
1242</Para>
1243</listitem>
1244
1245</VarListEntry>
1246
1247<VarListEntry><Term>Validity</Term>
1248
1249<listitem><Para>valid at the start of a *begin/*end block.
1250</Para></listitem>
1251
1252</VarListEntry>
1253
1254<VarListEntry><Term>Description</Term>
1255
1256<listitem><Para>*copyright allow the copyright information to be
1257stored in a way that can be automatically collated.
1258</Para></listitem>
1259
1260</VarListEntry>
1261
1262<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1263
1264<VarListEntry><Term>See Also</Term>
1265
1266<listitem><Para>*begin</Para></listitem>
1267
1268</VarListEntry>
1269
1270</VariableList>
1271
1272</Sect3>
1273
1274<Sect3><Title>CS</Title>
1275
1276<VariableList>
1277
1278<VarListEntry><Term>Syntax</Term>
1279
1280<listitem><Para>*cs [out] &lt;coordinate system&gt;</Para></listitem>
1281
1282</VarListEntry>
1283
1284<VarListEntry><Term>Example</Term>
1285
1286<listitem>
1287<Para>
1288<programlisting>
1289*cs UTM60S
1290*fix beehive 313800 5427953 20</programlisting>
1291</Para>
1292
1293<Para>
1294<programlisting>
1295; Output in the coordinate system used in the Totes Gebirge in Austria
1296*cs out custom "+proj=tmerc +lat_0=0 +lon_0=13d20 +k=1 +x_0=0 +y_0=-5200000 +ellps=bessel +towgs84=577.326,90.129,463.919,5.137,1.474,5.297,2.4232"</programlisting>
1297</Para>
1298</listitem>
1299
1300</VarListEntry>
1301
1302<VarListEntry><Term>Description</Term>
1303
1304<listitem><Para>*cs allows the coordinate systems used for fixed points and for
1305processed survey data to be specified.
1306</Para>
1307
1308<Para>
1309*cs was added in Survex 1.2.14.  The currently supported coordinate systems
1310are:
1311</Para>
1312
1313<Para>CUSTOM followed by a PROJ4 string (like in the example above).</Para>
1314
1315<Para>EPSG: followed by a positive integer code.  EPSG codes cover most
1316coordinate systems in use, and PROJ supports many of these.  The website
1317<ulink url="http://epsg.io/">http://epsg.io/</ulink> is a useful resource for
1318finding the EPSG code you want.  Supported since Survex 1.2.15.</Para>
1319
1320<Para>ESRI: followed by a positive integer code.  ESRI codes are used by
1321ArcGIS to specify coordinate systems (in a similar way to EPSG codes), and PROJ
1322supports many of them.  Supported since Survex 1.2.15.</Para>
1323
1324<Para>EUR79Z30 for UTM zone 30, EUR79 datum.  Supported since Survex 1.2.15.
1325</Para>
1326
1327<Para>IJTSK for the modified version of the Czechoslovak S-JTSK system where
1328the axes point East and North.  Supported since Survex 1.2.15.</Para>
1329
1330<Para>IJTSK03 for a variant of IJTSK.  Supported since Survex 1.2.15.</Para>
1331
1332<Para>JTSK for the Czechoslovak S-JTSK system.  The axes on this point West
1333and South, so it's not support as an output coordinate system.
1334Supported since Survex 1.2.16.</Para>
1335
1336<Para>JTSK03 for a variant of JTSK.  Supported since Survex 1.2.16.</Para>
1337
1338<Para>LONG-LAT for longitude/latitude.  The WGS84 datum is assumed.  Supported
1339since Survex 1.2.15.</Para>
1340
1341<Para>OSGB: followed by a two letter code for the UK Ordnance Survey National
1342Grid.  The first letter should be 'H', 'N', 'O', 'S' or 'T'; the second any
1343letter except 'I'.  Supported since Survex 1.2.15.</Para>
1344
1345<Para>S-MERC for the "Web Mercator" spherical mercator projection, used by
1346online map sites like OpenStreetMap, Google maps, Bing maps, etc.  Supported
1347since Survex 1.2.15.
1348</Para>
1349
1350<Para>UTM followed by a zone number (1-60), optionally followed by "N" or "S"
1351(default is North).  The WGS84 datum is assumed.</Para>
1352
1353<Para>
1354By default, Survex works in an unspecified coordinate system (and this was the
1355only option before *cs was added).  However, it's useful for coordinate system
1356which the processed survey data is in to be specified if you want to use the
1357processed data in ways which required knowing the coordinate system (such as
1358exporting a list of entrances for use in a GPS).  You can now do this by using
1359"*cs out".
1360</Para>
1361
1362<Para>
1363It is also useful to be able to take coordinates for fixed points in whatever
1364coordinate system you receive them in and put them directly into Survex, rather
1365than having to convert with an external tool.  For example, you may have your
1366GPS set to show coordinates in UTM with the WGS84 datum, even though you want
1367the processed data to be in some local coordinate system.  And someone else
1368may provide GPS coordinates in yet another coordinate system.  You just need
1369to set the appropriate coordinate system with "*cs" before each group of "*fix"
1370commands in a particular coordinate system.
1371</Para>
1372
1373<Para>
1374If you're going to make use of "*cs", then the coordinate system must be
1375specified for everything, so a coordinate system must be in effect for all
1376"*fix" commands, and you must set the output coordinate system before any
1377points are fixed.
1378</Para>
1379
1380<Para>
1381Also, if "*cs" is in use, then you can't omit the coordinates in a "*fix"
1382command, and a fixed point won't be invented if none exists.
1383</Para>
1384
1385<Para>
1386If you use "*cs out" more than once, the second and subsequent commands are
1387silently ignored - this makes it possible to combine two datasets with
1388different "*cs out" settings without having to modify either of them.
1389</Para>
1390
1391<Para>
1392Something to be aware of with "*cs" is that altitudes are currently assumed to
1393be "height above the ellipsoid", whereas GPS units typically give you "height
1394above sea level", or more accurately "height above a particular geoid".  This
1395is something we're looking at how best to address, but you shouldn't need to
1396worry about it if your fixed points are in the same coordinate system as your
1397output, or if they all use the same ellipsoid.  For a more detailed discussion
1398of this, please see: http://expo.survex.com/handbook/survey/coord.htm
1399</Para>
1400</listitem>
1401
1402</VarListEntry>
1403
1404<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1405
1406<VarListEntry><Term>See Also</Term>
1407
1408<listitem><Para>*fix</Para></listitem>
1409
1410</VarListEntry>
1411
1412</VariableList>
1413
1414</Sect3>
1415<Sect3><Title>DATA</Title>
1416
1417<VariableList>
1418
1419<VarListEntry><Term>Syntax</Term>
1420
1421<listitem><Para>*data &lt;style&gt; &lt;ordering&gt;</Para></listitem>
1422<!-- BACKCOMPASS BACKCLINO -->
1423</VarListEntry>
1424
1425<VarListEntry><Term>Example</Term>
1426
1427<listitem>
1428<Para>
1429<programlisting>
1430*data normal from to compass tape clino</programlisting>
1431</Para>
1432
1433<Para>
1434<programlisting>
1435*data normal station ignoreall newline compass tape clino</programlisting>
1436</Para>
1437</listitem>
1438
1439</VarListEntry>
1440
1441<VarListEntry><Term>Description</Term>
1442
1443<listitem><Para>
1444&lt;style&gt; = DEFAULT|NORMAL|DIVING|CARTESIAN|TOPOFIL|CYLPOLAR|NOSURVEY|PASSAGE
1445</Para>
1446
1447<Para>
1448&lt;ordering&gt; = ordered list of instruments - which are valid depends on the
1449style.
1450</Para>
1451
1452<Para>
1453In Survex 1.0.2 and later, TOPOFIL is simply a synonym for NORMAL, left in to
1454allow older data to be processed without modification.  Use the name NORMAL
1455by preference.
1456</Para>
1457
1458<Para>
1459There are two variants of each style - interleaved and non-interleaved.
1460Non-interleaved is "one line per leg", interleaved has a line for the data
1461shared between two legs (e.g. STATION=FROM/TO, DEPTH=FROMDEPTH/TODEPTH,
1462COUNT=FROMCOUNT/TOCOUNT).  Note that not all interleavable readings have to
1463be interleaved - for example:
1464
1465<programlisting>
1466*data diving station newline fromdepth compass tape todepth</programlisting>
1467
1468In addition, interleaved data can have a DIRECTION reading, which can be "F"
1469for a foresight or "B" for a backsight.
1470</Para>
1471
1472<Para>
1473In NORMAL, DIVING, and CYLPOLAR data styles, TAPE may be replaced by
1474FROMCOUNT/TOCOUNT (or COUNT in interleaved data) to allow processing of surveys
1475performed with a Topofil instead of a tape.
1476</Para>
1477
1478<VariableList>
1479
1480<VarListEntry><Term>DEFAULT</Term>
1481<listitem><Para>Select the default data style and ordering (NORMAL style, ordering: from to tape compass clino).</Para></listitem>
1482</VarListEntry>
1483
1484<VarListEntry><Term>NORMAL</Term>
1485<listitem><Para>The usual tape/compass/clino centreline survey.
1486For non-interleaved data the allowed readings are:
1487FROM TO TAPE COMPASS CLINO BACKCOMPASS BACKCLINO;
1488for interleaved data the allowed readings are:
1489STATION DIRECTION TAPE COMPASS CLINO BACKCOMPASS BACKCLINO.
1490The CLINO/BACKCLINO reading is not required - if it's not given, the vertical
1491standard deviation is taken to be proportional to the tape measurement.
1492Alternatively, individual clino readings can be given as OMIT (default "-")
1493which allows for data where only some clino readings are missing.
1494E.g.:
1495
1496<programlisting>
1497*data normal from to compass clino tape
14981 2 172 -03 12.61</programlisting>
1499
1500<programlisting>
1501*data normal station newline direction tape compass clino
15021
1503 F 12.61 172 -03
15042</programlisting>
1505
1506<programlisting>
1507*data normal from to compass clino fromcount tocount
15081 2 172 -03 11532 11873</programlisting>
1509
1510<programlisting>
1511*data normal station count newline direction compass clino
15121 11532
1513 F 172 -03
15142 11873</programlisting>
1515 
1516</Para></listitem>
1517</VarListEntry>
1518
1519<VarListEntry><Term>DIVING</Term>
1520<listitem><Para>
1521An underwater survey where the vertical information is from a diver's depth
1522gauge.  This style can also be also used for an above-water survey where the
1523altitude is measured with an altimeter.  DEPTH is defined as the altitude (Z)
1524so increases upwards by default.  So for a diver's depth gauge, you'll need to
1525use *CALIBRATE with a negative scale factor (e.g. *calibrate depth 0 -1).
1526</Para>
1527
1528<Para>For non-interleaved data the allowed readings are:
1529FROM TO TAPE COMPASS CLINO BACKCOMPASS BACKCLINO FROMDEPTH TODEPTH DEPTHCHANGE (the vertical
1530can be given as readings at each station, (FROMDEPTH/TODEPTH) or as a change
1531along the leg (DEPTHCHANGE)).</Para>
1532
1533<Para>Survex 1.2.20 and later allow an optional CLINO and/or BACKCLINO reading
1534in DIVING style.  At present these extra readings are checked for syntactic
1535validity, but are otherwise ignored.  The intention is that a future version
1536will check them against the other readings to flag up likely blunders, and
1537average with the slope data from the depth gauge and tape reading.</Para>
1538
1539<Para>For interleaved data the allowed readings are:
1540STATION DIRECTION TAPE COMPASS BACKCOMPASS DEPTH DEPTHCHANGE.
1541(the vertical change can be given as a reading at the station (DEPTH) or as a change along the leg (DEPTHCHANGE)).
1542
1543<programlisting>
1544*data diving from to tape compass fromdepth todepth
15451 2 14.7 250 -20.7 -22.4</programlisting>
1546
1547<programlisting>
1548*data diving station depth newline tape compass
15491 -20.7
1550 14.7 250
15512 -22.4</programlisting>
1552
1553<programlisting>
1554*data diving from to tape compass depthchange
15551 2 14.7 250 -1.7</programlisting>
1556</Para>
1557</listitem>
1558</VarListEntry>
1559
1560<VarListEntry><Term>CARTESIAN</Term>
1561<listitem><Para>
1562Cartesian data style allows you to specify the (x,y,z) changes between
1563stations.  It's useful for digitising surveys where the original survey
1564data has been lost and all that's available is a drawn up version.
1565
1566<programlisting>
1567*data cartesian from to northing easting altitude
15681 2 16.1 20.4 8.7</programlisting>
1569
1570<programlisting>
1571*data cartesian station newline northing easting altitude
15721
1573 16.1 20.4 8.7
15742</programlisting>
1575
1576<!--FIXME: dx dy dz-->
1577</Para>
1578
1579<Note><Para>
1580Cartesian data are relative to <emphasis>true</emphasis> North not
1581<emphasis>magnetic</emphasis> North (i.e. they are unaffected by
1582<command>*calibrate declination</command>).
1583</Para></Note>
1584</listitem>
1585</VarListEntry>
1586
1587<VarListEntry><Term>CYLPOLAR</Term>
1588<listitem><Para>
1589A CYLPOLAR style survey is very similar to a diving survey, except that the tape
1590is always measured horizontally rather than along the slope of the leg.
1591
1592<programlisting>
1593*data cypolar from to tape compass fromdepth todepth
15941 2 9.45 311 -13.3 -19.0</programlisting>
1595
1596<programlisting>
1597*data cylpolar station depth newline tape compass
15981 -13.3
1599 9.45 311
16002 -19.0</programlisting>
1601
1602<programlisting>
1603*data cylpolar from to tape compass depthchange
16041 2 9.45 311 -5.7</programlisting>
1605</Para></listitem>
1606</VarListEntry>
1607
1608<VarListEntry><Term>NOSURVEY</Term>
1609<listitem><Para>
1610A NOSURVEY survey doesn't have any measurements - it merely indicates that
1611there is line of sight between the pairs of stations.
1612
1613<programlisting>
1614*data nosurvey from to
16151 7
16165 7
16179 11</programlisting>
1618
1619<programlisting>
1620*data nosurvey station
16211
16227
16235
1624
1625*data nosurvey station
16269
162711</programlisting>
1628</Para></listitem>
1629</VarListEntry>
1630
1631<VarListEntry><Term>PASSAGE</Term>
1632<listitem><Para>
1633This survey style defines a 3D "tube" modelling a passage in the cave.
1634The tube uses the survey stations listed in the order listed.  It's
1635permitted to use survey stations which aren't directly linked by
1636the centre-line survey.  This can be useful - sometimes the centreline
1637will step sideways or up/down to allow a better sight for the next
1638leg and you can ignore the extra station.  You can also define tubes
1639along unsurveyed passages, akin to "nosurvey" legs in the centreline
1640data.</Para>
1641
1642<Para>This means that you need to split off side passages into seperate
1643tubes, and hence separate sections of passage data, starting with
1644a new *data command.</Para>
1645
1646<Para>
1647Simple example of how to use this data style (note the use of ignoreall
1648to allow a free-form text description to be given):
1649
1650<programlisting>
1651*data passage station left right up down ignoreall
16521  0.1 2.3 8.0 1.4  Sticking out point on left wall
16532  0.0 1.9 9.0 0.5  Point on left wall
16543  1.0 0.7 9.0 0.8  Highest point of boulder
1655</programlisting>
1656</Para>
1657</listitem>
1658</VarListEntry>
1659</VariableList>
1660
1661<Para>
1662IGNORE skips a field (it may be used any number of times),
1663and IGNOREALL may be used last to ignore the rest of the data line.
1664</Para>
1665
1666<Para>
1667LENGTH is a synonym for TAPE; BEARING for COMPASS; GRADIENT for CLINO; COUNT for COUNTER.<!--FIXME : others?-->
1668</Para>
1669
1670<Para>
1671The units of each quantity may be set with the UNITS command.
1672</Para>
1673
1674<!-- FIXME: plumbed diving legs -->
1675
1676<!--FIXME:
1677<Para>
1678Uses for CYLPOLAR:
1679Perhaps a Grade 3 survey, or when surveying with a level and stick (?)
1680[note - UBSS use it for the old County Clare data]
1681</Para>
1682-->
1683
1684</listitem>
1685
1686</VarListEntry>
1687
1688</VariableList>
1689
1690</Sect3>
1691
1692<Sect3><Title>DATE</Title>
1693<VariableList>
1694
1695<VarListEntry><Term>Syntax</Term>
1696
1697<listitem><Para>*date &lt;year&gt;[.&lt;month&gt;[.&lt;day&gt;]][-&lt;year&gt;[.&lt;month&gt;[.&lt;day&gt;]]]</Para></listitem>
1698
1699</VarListEntry>
1700
1701<VarListEntry><Term>Example</Term>
1702
1703<listitem>
1704<Para>
1705<programlisting>
1706*date 2001</programlisting>
1707
1708<programlisting>
1709*date 2000.10</programlisting>
1710
1711<programlisting>
1712*date 1987.07.27</programlisting>
1713
1714<programlisting>
1715*date 1985.08.12-1985.08.13</programlisting>
1716</Para>
1717</listitem>
1718
1719</VarListEntry>
1720
1721<VarListEntry><Term>Validity</Term>
1722
1723<listitem><Para>valid at the start of a *begin/*end block.
1724</Para></listitem>
1725
1726</VarListEntry>
1727
1728<VarListEntry><Term>Description</Term>
1729
1730<listitem><Para>
1731*date specifies the date that the survey was done.  A range of dates
1732can be specified (useful for overnight or multi-day surveying trips).
1733</Para></listitem>
1734
1735</VarListEntry>
1736
1737<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1738
1739<VarListEntry><Term>See Also</Term>
1740
1741<listitem><Para>*begin, *instrument, *team</Para></listitem>
1742
1743</VarListEntry>
1744
1745</VariableList>
1746
1747</Sect3>
1748
1749<Sect3><Title>DEFAULT</Title>
1750
1751<VariableList>
1752
1753<VarListEntry><Term>Syntax</Term>
1754
1755<listitem><Para>*default &lt;settings list&gt;|all</Para></listitem>
1756
1757</VarListEntry>
1758
1759<VarListEntry><Term>Description</Term>
1760
1761<listitem><Para>
1762The valid settings are CALIBRATE, DATA, and UNITS.
1763</Para>
1764
1765<Para>
1766*default restores defaults for given settings.  This command is deprecated -
1767you should instead use: *calibrate default, *data default, *units default.
1768</Para></listitem>
1769
1770</VarListEntry>
1771
1772<VarListEntry><Term>See Also</Term>
1773
1774<listitem><Para>*calibrate, *data, *units</Para></listitem>
1775
1776</VarListEntry>
1777
1778</VariableList>
1779
1780</Sect3>
1781
1782<Sect3><Title>END</Title>
1783
1784<VariableList>
1785
1786<VarListEntry><Term>Syntax</Term>
1787
1788<listitem><Para>*end [&lt;survey&gt;]</Para></listitem>
1789
1790</VarListEntry>
1791
1792<VarListEntry><Term>Validity</Term>
1793
1794<listitem><Para>valid for closing a block started by *begin in the same file.
1795</Para></listitem>
1796
1797</VarListEntry>
1798
1799<VarListEntry><Term>Description</Term>
1800
1801<listitem><Para>
1802Closes a block started by *begin.
1803</Para></listitem>
1804
1805</VarListEntry>
1806
1807<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1808
1809<VarListEntry><Term>See Also</Term>
1810
1811<listitem><Para>*begin</Para></listitem>
1812
1813</VarListEntry>
1814
1815</VariableList>
1816
1817</Sect3>
1818
1819<Sect3><Title>ENTRANCE</Title>
1820
1821<VariableList>
1822
1823<VarListEntry><Term>Syntax</Term>
1824
1825<listitem><Para>*entrance &lt;station&gt;</Para></listitem>
1826
1827</VarListEntry>
1828
1829<VarListEntry><Term>Example</Term>
1830
1831<listitem>
1832<Para>
1833<programlisting>
1834*entrance P163</programlisting>
1835</Para>
1836</listitem>
1837
1838</VarListEntry>
1839
1840<VarListEntry><Term>Description</Term>
1841
1842<listitem><Para>
1843*entrance sets the <emphasis>entrance</emphasis> flag for a station.
1844This information is used by aven to allow entrances to be highlighted.
1845</Para>
1846
1847<!-- FIXME:
1848(could be inferred from surface/ug join, but better to specify because
1849of caves with no surf svy (or no underground survey)
1850and also situations in which multiple surveys leave through an entrance)
1851-->
1852</listitem>
1853
1854</VarListEntry>
1855
1856<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1857
1858<!-- <VarListEntry><Term>See Also</Term>
1859
1860<listitem><Para></Para></listitem>
1861
1862</VarListEntry>
1863-->
1864
1865</VariableList>
1866
1867</Sect3>
1868
1869<Sect3><Title>EQUATE</Title>
1870
1871<VariableList>
1872
1873<VarListEntry><Term>Syntax</Term>
1874
1875<listitem><Para>*equate &lt;station&gt; &lt;station&gt;...</Para></listitem>
1876
1877</VarListEntry>
1878
1879<VarListEntry><Term>Example</Term>
1880
1881<listitem>
1882<Para>
1883<programlisting>
1884*equate chosspot.1 triassic.27</programlisting>
1885</Para>
1886</listitem>
1887
1888</VarListEntry>
1889
1890<VarListEntry><Term>Description</Term>
1891
1892<listitem><Para>
1893*equate specifies that the station names in the list refer to the
1894same physical survey station. An error is given if there is only one station
1895listed.
1896</Para>
1897
1898<!-- FIXME:
1899<Para>
1900I think this is preferable to using:
1901</Para>
1902
1903<programlisting> a b 0.00   0   0</programlisting>
1904
1905<Para>
1906as EQUATE does not add in an extra position error. It is also clearer than
1907substituting in the original name wherever passages are linked. If you
1908disagree, you can always use one of the other methods!
1909</Para>
1910-->
1911</listitem>
1912
1913</VarListEntry>
1914
1915<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1916
1917<VarListEntry><Term>See Also</Term>
1918
1919<listitem><Para>*infer equates</Para></listitem>
1920
1921</VarListEntry>
1922
1923</VariableList>
1924
1925</Sect3>
1926
1927<Sect3><Title>EXPORT</Title>
1928
1929<VariableList>
1930
1931<VarListEntry><Term>Syntax</Term>
1932
1933<listitem><Para>*export &lt;station&gt;...</Para></listitem>
1934
1935</VarListEntry>
1936
1937<VarListEntry><Term>Example</Term>
1938
1939<!-- FIXME better example -->
1940<listitem>
1941<Para>
1942<programlisting>
1943*export 1 6 17</programlisting>
1944</Para>
1945</listitem>
1946
1947</VarListEntry>
1948
1949<VarListEntry><Term>Validity</Term>
1950
1951<listitem><Para>valid at the start of a *begin/*end block.
1952</Para></listitem>
1953
1954</VarListEntry>
1955
1956<VarListEntry><Term>Description</Term>
1957
1958<listitem><Para>
1959*export marks the stations named as referable to from the enclosing
1960survey.  To be able to refer to a station from a survey several levels
1961above, it must be exported from each enclosing survey.
1962</Para>
1963
1964<!-- FIXME:
1965<Para>
1966I think this is preferable to using:
1967</Para>
1968
1969<programlisting> a b 0.00   0   0</programlisting>
1970
1971<Para>
1972as EQUATE does not add in an extra position error. It is also clearer than
1973substituting in the original name wherever passages are linked. If you
1974disagree, you can always use one of the other methods!
1975</Para>
1976-->
1977</listitem>
1978
1979</VarListEntry>
1980
1981<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1982
1983<VarListEntry><Term>See Also</Term>
1984
1985<listitem><Para>*begin, *infer exports</Para></listitem>
1986
1987</VarListEntry>
1988
1989</VariableList>
1990
1991</Sect3>
1992
1993<Sect3><Title>FIX</Title>
1994
1995<VariableList>
1996
1997<VarListEntry><Term>Syntax</Term>
1998
1999<listitem><Para>*fix &lt;station&gt; [reference]
2000 [ &lt;x&gt; &lt;y&gt; &lt;z&gt;
2001   [ &lt;x std err&gt; &lt;y std err&gt; &lt;z std err&gt;
2002     [ &lt;cov(x,y)&gt; &lt;cov(y,z)&gt; &lt;cov(z,x)&gt; ] ] ]
2003</Para></listitem>
2004
2005</VarListEntry>
2006
2007<VarListEntry><Term>Example</Term>
2008
2009<listitem>
2010<Para>
2011<programlisting>
2012*fix entrance.0 32768 86723 1760</programlisting>
2013
2014<programlisting>
2015*fix KT114_96 reference 36670.37 83317.43 1903.97</programlisting>
2016</Para>
2017</listitem>
2018
2019</VarListEntry>
2020
2021<VarListEntry><Term>Description</Term>
2022
2023<listitem>
2024<Para>
2025*fix fixes the position of &lt;station&gt; at the given coordinates.
2026If you haven't specified the coordinate system with "*cs", you can
2027omit the position and it will default to (0,0,0).  The standard errors default
2028to zero (fix station exactly).  cavern will give an error if you attempt to fix
2029the same survey station twice at different coordinates, or a warning if you fix
2030it twice with matching coordinates.
2031</Para>
2032
2033<Para>
2034You can also specify just one standard error (in which case it is assumed
2035equal in X, Y, and Z) or two (in which case the first is taken as the
2036standard error in X and Y, and the second as the standard error in Z).
2037</Para>
2038
2039<Para>
2040If you have covariances for the fix, you can also specify these - the
2041order is cov(x,y) cov(y,z) cov(z,x).
2042</Para>
2043
2044<Para>
2045You can fix as many stations as you like - just use a *fix command for each
2046one.  Cavern will check that all stations are connected to
2047at least one fixed point so that co-ordinates can be calculated for all
2048stations.
2049</Para>
2050
2051<Para>
2052By default cavern will warn about stations which have been FIX-ed but
2053not used otherwise.  This is unhelpful if you want to include a
2054standard file of benchmarks, some of which won't be used.
2055In this sort of situation, specify "REFERENCE" after the station name
2056in the FIX command to suppress this warning for a particular station.
2057</Para>
2058
2059<Note><Para>
2060X is Easting, Y is Northing, and Z is altitude.  This convention was chosen
2061since on a map, the horizontal (X) axis is usually East, and the vertical
2062axis (Y) North.  The choice of altitude (rather than depth) for Z is taken
2063from surface maps, and makes for less confusion when dealing with cave
2064systems with more than one entrance.  It also gives a right-handed
2065set of axes.
2066</Para></Note>
2067
2068</listitem>
2069</VarListEntry>
2070
2071<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2072
2073<!-- <VarListEntry><Term>See Also</Term>
2074
2075<listitem><Para></Para></listitem>
2076
2077</VarListEntry>
2078-->
2079
2080</VariableList>
2081
2082</Sect3>
2083
2084<!--
2085<Sect3><Title></Title>
2086
2087<VariableList>
2088
2089<VarListEntry><Term>Syntax</Term>
2090
2091<listitem><Para>*</Para></listitem>
2092
2093</VarListEntry>
2094
2095<VarListEntry><Term>Example</Term>
2096
2097<listitem>
2098<Para>
2099<programlisting>
2100*</programlisting>
2101</Para>
2102</listitem>
2103
2104</VarListEntry>
2105
2106<VarListEntry><Term>Description</Term>
2107
2108<listitem><Para>
2109</Para></listitem>
2110
2111</VarListEntry>
2112
2113<VarListEntry><Term>Caveats </Term> </VarListEntry>
2114
2115<VarListEntry><Term>See Also</Term>
2116
2117<listitem><Para></Para></listitem>
2118
2119</VarListEntry>
2120
2121</VariableList>
2122
2123</Sect3>
2124-->
2125
2126<Sect3><Title>FLAGS</Title>
2127
2128<VariableList>
2129
2130<VarListEntry><Term>Syntax</Term>
2131
2132<listitem><Para>*flags &lt;flags&gt;</Para></listitem>
2133
2134</VarListEntry>
2135
2136<VarListEntry><Term>Example</Term>
2137
2138<listitem>
2139<Para>
2140<programlisting>
2141*flags duplicate not surface</programlisting>
2142</Para>
2143</listitem>
2144
2145</VarListEntry>
2146
2147<VarListEntry><Term>Description</Term>
2148
2149<listitem><Para>
2150*flags updates the current flag settings.
2151Flags not mentioned retain their previous state.  Valid flags
2152are DUPLICATE, SPLAY, and SURFACE, and a flag may be preceded with NOT to
2153turn it off.
2154</Para>
2155
2156<Para>
2157Survey legs marked SURFACE are hidden from plots by default, and not
2158included in cave survey length calculations.  Survey legs marked as
2159DUPLICATE or SPLAY are also not included in cave survey length
2160calculations; legs marked SPLAY are ignored by the extend program.
2161DUPLICATE is intended for the case when if you have two different
2162surveys along the same section of passage (for example to tie two
2163surveys into a permanent survey station); SPLAY is intended for
2164cases such as radial legs in a large chamber.
2165</Para>
2166</listitem>
2167
2168</VarListEntry>
2169
2170<VarListEntry><Term>See Also</Term>
2171
2172<listitem><Para>*begin</Para></listitem>
2173
2174</VarListEntry>
2175
2176</VariableList>
2177
2178</Sect3>
2179
2180<Sect3><Title>INCLUDE</Title>
2181
2182<VariableList>
2183
2184<VarListEntry><Term>Syntax</Term>
2185
2186<listitem><Para>*include &lt;filename&gt;</Para></listitem>
2187
2188</VarListEntry>
2189
2190<VarListEntry><Term>Example</Term>
2191
2192<listitem>
2193<Para>
2194<programlisting>
2195*include mission</programlisting>
2196
2197<programlisting>
2198*include "the pits"</programlisting>
2199</Para>
2200</listitem>
2201
2202</VarListEntry>
2203
2204<VarListEntry><Term>Description</Term>
2205
2206<listitem><Para>
2207*include processes &lt;filename&gt; as if it were inserted at this
2208place in the current file. (i.e. The current settings are carried
2209into &lt;filename&gt;, and any alterations to settings in &lt;filename&gt;
2210will be carried back again).  There's one exception to this (for
2211obscure historical reasons) which is that the survey prefix is
2212restored upon return to the original file.  Since *begin and *end
2213nesting cannot cross files, this can only make a difference if you
2214use the deprecated *prefix command.
2215</Para>
2216
2217<Para>If &lt;filename&gt; contains spaces, it must be enclosed in quotes.
2218</Para>
2219
2220<Para>An included file which does not have a complete path
2221is resolved relative to the directory which the parent file is in
2222(just as relative HTML links do).  Cavern will try adding a <filename>.svx</filename>
2223extension, and will also try translating "\" to "/".
2224And as a last
2225resort, it will try a lower case version of the filename (so if you
2226use Unix and someone sends you a DOS/Windows dataset with mismatched
2227case, unzip it with "unzip -L" and UNIX cavern will process it).
2228</Para>
2229
2230<Para>
2231The depth to which you can nest
2232include files may be limited by the operating system
2233you use.  Usually the limit is fairly high (>30), but if you want to be able to
2234process your dataset with <Application>Survex</Application> on any supported platform, it
2235would be prudent not to go overboard with nested include files.
2236</Para>
2237</listitem>
2238</VarListEntry>
2239
2240</VariableList>
2241
2242</Sect3>
2243
2244<Sect3><Title>INFER</Title>
2245
2246<VariableList>
2247
2248<VarListEntry><Term>Syntax</Term>
2249
2250<listitem>
2251<Para>*infer plumbs on|off</Para>
2252
2253<Para>*infer equates on|off</Para>
2254
2255<Para>*infer exports on|off</Para>
2256</listitem>
2257
2258</VarListEntry>
2259
2260<!--
2261<VarListEntry><Term>Example</Term>
2262
2263<listitem>
2264<programlisting>
2265</programlisting>
2266
2267</listitem>
2268
2269</VarListEntry>
2270-->
2271
2272<VarListEntry><Term>Description</Term>
2273
2274<listitem>
2275<Para>"*infer plumbs on" tells cavern to interpret gradients of +/- 90
2276degrees as UP/DOWN (so it
2277will not apply the clino correction to them). This is useful when
2278the data has not been converted to have UP and DOWN in it.
2279</Para>
2280
2281<para>"*infer equates on" tells cavern to interpret a leg with
2282a tape reading of zero as a *equate.  this prevents tape corrections
2283being applied to them.
2284</para>
2285
2286<para>"*infer exports on" is necessary when you have a dataset which is
2287partly annotated with *export.  It tells cavern not to complain about
2288missing *export commands in part of the dataset.  Also stations which
2289were used to join surveys are marked as exported in the 3d file.
2290</para>
2291</listitem>
2292
2293</VarListEntry>
2294
2295<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2296
2297<!--
2298<VarListEntry><Term>See Also</Term>
2299
2300<listitem><Para>*end, *prefix</Para></listitem>
2301
2302</VarListEntry>
2303-->
2304
2305</VariableList>
2306
2307</Sect3>
2308
2309<Sect3><Title>INSTRUMENT</Title>
2310
2311<VariableList>
2312
2313<VarListEntry><Term>Syntax</Term>
2314
2315<listitem><Para>*instrument &lt;instrument&gt; &lt;identifier&gt;</Para></listitem>
2316
2317</VarListEntry>
2318
2319<VarListEntry><Term>Example</Term>
2320
2321<listitem>
2322<Para>
2323<programlisting>
2324*instrument compass "CUCC 2"
2325*instrument clino "CUCC 2"
2326*instrument tape "CUCC Fisco Ranger open reel"</programlisting>
2327</Para>
2328</listitem>
2329
2330</VarListEntry>
2331
2332<VarListEntry><Term>Validity</Term>
2333
2334<listitem><Para>valid at the start of a *begin/*end block.
2335</Para></listitem>
2336
2337</VarListEntry>
2338
2339<VarListEntry><Term>Description</Term>
2340
2341<listitem><Para>
2342*instrument specifies the particular instruments used to perform a
2343survey.
2344</Para></listitem>
2345
2346</VarListEntry>
2347
2348<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2349
2350<VarListEntry><Term>See Also</Term>
2351
2352<listitem><Para>*begin, *date, *team</Para></listitem>
2353
2354</VarListEntry>
2355
2356</VariableList>
2357
2358</Sect3>
2359
2360<Sect3><Title>PREFIX</Title>
2361
2362<VariableList>
2363
2364<VarListEntry><Term>Syntax</Term>
2365
2366<listitem><Para>*prefix &lt;survey&gt;</Para></listitem>
2367
2368</VarListEntry>
2369
2370<VarListEntry><Term>Example</Term>
2371
2372<listitem>
2373<Para>
2374<programlisting>
2375*prefix flapjack</programlisting>
2376</Para>
2377</listitem>
2378
2379</VarListEntry>
2380
2381<VarListEntry><Term>Description</Term>
2382
2383<listitem><Para>
2384*prefix sets the current survey.
2385</Para></listitem>
2386
2387</VarListEntry>
2388
2389<VarListEntry><Term>Caveats </Term>
2390
2391<listitem><Para>*prefix is deprecated - you should use *begin and *end
2392instead.</Para></listitem>
2393
2394</VarListEntry>
2395
2396<VarListEntry><Term>See Also</Term>
2397
2398<listitem><Para>*begin, *end</Para></listitem>
2399
2400</VarListEntry>
2401
2402</VariableList>
2403
2404</Sect3>
2405
2406<Sect3><Title>REQUIRE</Title>
2407
2408<VariableList>
2409
2410<VarListEntry><Term>Syntax</Term>
2411
2412<listitem><Para>*require &lt;version&gt;</Para></listitem>
2413
2414</VarListEntry>
2415
2416<VarListEntry><Term>Example</Term>
2417
2418<listitem>
2419<Para>
2420<programlisting>
2421*require 0.98</programlisting>
2422</Para>
2423</listitem>
2424
2425</VarListEntry>
2426
2427<VarListEntry><Term>Description</Term>
2428
2429<listitem><Para>
2430*require checks that the version of cavern in use is at least
2431&lt;version&gt; and stops with an error if not.
2432So if your dataset requires a feature
2433introduced in a particular version, you can add a *require command and
2434users will know what version they need to upgrade to, rather than
2435getting an error message and having to guess what the real problem is.
2436</Para></listitem>
2437
2438</VarListEntry>
2439
2440</VariableList>
2441
2442</Sect3>
2443
2444<Sect3><Title>SD</Title>
2445
2446<VariableList>
2447
2448<VarListEntry><Term>Syntax</Term>
2449
2450<listitem><Para>*sd &lt;quantity list&gt; &lt;standard deviation&gt;
2451</Para></listitem>
2452
2453</VarListEntry>
2454
2455<VarListEntry><Term>Example</Term>
2456
2457<listitem>
2458<Para>
2459<programlisting>
2460*sd tape 0.15 metres</programlisting>
2461</Para>
2462</listitem>
2463
2464</VarListEntry>
2465
2466<VarListEntry><Term>Description</Term>
2467
2468<listitem><Para>
2469*sd sets the standard deviation of a measurement.
2470</Para>
2471
2472<Para>
2473&lt;quantity&gt; is one of (each group gives alternative names for the same
2474quantity):
2475</Para>
2476
2477<ItemizedList>
2478    <listitem><para>TAPE, LENGTH</para></listitem>
2479    <listitem><para>COMPASS, BEARING</para></listitem>
2480    <listitem><para>BACKCOMPASS, BACKBEARING</para></listitem>
2481    <listitem><para>CLINO, GRADIENT</para></listitem>
2482    <listitem><para>BACKCLINO, BACKGRADIENT</para></listitem>
2483    <listitem><para>COUNTER, COUNT</para></listitem>
2484    <listitem><para>DEPTH</para></listitem>
2485    <listitem><para>DECLINATION</para></listitem>
2486    <listitem><para>DX, EASTING</para></listitem>
2487    <listitem><para>DY, NORTHING</para></listitem>
2488    <listitem><para>DZ, ALTITUDE</para></listitem>
2489    <listitem><para>LEFT</para></listitem>
2490    <listitem><para>RIGHT</para></listitem>
2491    <listitem><para>UP, CEILING</para></listitem>
2492    <listitem><para>DOWN, FLOOR</para></listitem>
2493    <listitem><para>LEVEL</para></listitem>
2494    <listitem><para>PLUMB</para></listitem>
2495    <listitem><para>POSITION</para></listitem>
2496</ItemizedList>
2497
2498<Para>
2499&lt;standard deviation&gt; must include units and thus is typically
2500"0.05 metres", or "0.02 degrees". See *units below for full list
2501of valid units.
2502</Para>
2503
2504<!-- FIXME mention central limit theorem -->
2505<Para>
2506To utilise this command fully you need to understand what a
2507<emphasis>standard deviation</emphasis> is.
2508It gives a value to the 'spread' of the errors
2509in a measurement. Assuming that these are normally distributed
2510we can say that 95.44% of the actual lengths will fall within two
2511standard deviations of the measured length. i.e. a tape SD of
25120.25 metres means that the actual length of a tape measurement
2513is within + or - 0.5 metres of the recorded value 95.44% of the time.
2514So if the measurement is 7.34m then the actual length is very
2515likely to be between 6.84m and 7.84m. This example corresponds
2516to BCRA grade 3. Note that this is just one interpretation of
2517the BCRA standard, taking the permitted error values as 2SD 95.44%
2518confidence limits. If you want to take the readings as being some
2519other limit (e.g. 1SD = 68.26%) then you will need to change the BCRA3
2520and BCRA5 files accordingly. This issue is explored in more
2521detail in various surveying articles.
2522<!--
25232.565 sd 99%
25242.5   sd 98.76%
25252     sd 95.44%
25261     sd 68.26%
2527.97   sd 66.67%
25281.15  sd 75%
2529-->
2530</Para></listitem>
2531
2532</VarListEntry>
2533
2534<VarListEntry><Term>See Also</Term>
2535
2536<listitem><Para>*units</Para></listitem>
2537
2538</VarListEntry>
2539
2540</VariableList>
2541
2542</Sect3>
2543
2544<Sect3><Title>SET</Title>
2545
2546<VariableList>
2547
2548<VarListEntry><Term>Syntax</Term>
2549
2550<listitem><Para>*set &lt;item&gt; &lt;character list&gt;</Para></listitem>
2551
2552</VarListEntry>
2553
2554<VarListEntry><Term>Example</Term>
2555
2556<listitem>
2557<Para>
2558<programlisting>
2559*set blank x09x20
2560*set decimal ,</programlisting>
2561
2562Note that you need to eliminate comma from being a blank before setting it as
2563a decimal - otherwise the comma in "*set decimal ," is parsed as a blank, and
2564you set decimal to not have any characters representing it.
2565</Para>
2566</listitem>
2567
2568</VarListEntry>
2569
2570<VarListEntry><Term>Description</Term>
2571
2572<listitem><Para>
2573*set sets the specified &lt;item&gt; to the character or characters
2574given in &lt;character list&gt;. The example sets the decimal
2575separator to be a comma.
2576</Para>
2577
2578<Para>
2579xAB means the character with hex value AB. Eg x20 is a space.
2580</Para>
2581
2582<Para>
2583The complete list of items that can be set, the defaults (in
2584brackets), and the meaning of the item, is:
2585</Para>
2586
2587<ItemizedList>
2588
2589<ListItem><Para>
2590BLANK (x09x20,) Separates fields
2591</Para></ListItem>
2592
2593<ListItem><Para>
2594COMMENT (;) Introduces comments
2595</Para></ListItem>
2596
2597<ListItem><Para>
2598DECIMAL (.) Decimal point character
2599</Para></ListItem>
2600
2601<ListItem><Para>
2602EOL (x0Ax0D) End of line character
2603</Para></ListItem>
2604
2605<ListItem><Para>
2606KEYWORD (*) Introduces keywords
2607</Para></ListItem>
2608
2609<ListItem><Para>
2610MINUS (-) Indicates negative number
2611</Para></ListItem>
2612
2613<ListItem><Para>
2614NAMES (_-) Non-alphanumeric chars permitted in station
2615names (letters and numbers are always permitted).
2616</Para></ListItem>
2617
2618<ListItem><Para>
2619OMIT (-) Contents of field omitted (e.g. in plumbed legs)
2620</Para></ListItem>
2621
2622<ListItem><Para>
2623PLUS (+) Indicates positive number
2624</Para></ListItem>
2625
2626<ListItem><Para>
2627ROOT (\) Prefix in force at start of current file (use of ROOT is deprecated)
2628</Para></ListItem>
2629
2630<ListItem><Para>
2631SEPARATOR (.) Level separator in prefix hierarchy
2632</Para></ListItem>
2633
2634<!-- FIXME OPEN ({) and CLOSE (}) -->
2635</ItemizedList>
2636
2637<Para>
2638The special characters may not be alphanumeric.
2639</Para>
2640
2641</listitem>
2642
2643</VarListEntry>
2644
2645</VariableList>
2646
2647</Sect3>
2648
2649<Sect3><Title>SOLVE</Title>
2650
2651<VariableList>
2652
2653<VarListEntry><Term>Syntax</Term>
2654
2655<listitem><Para>*solve</Para></listitem>
2656
2657</VarListEntry>
2658
2659<VarListEntry><Term>Example</Term>
2660
2661<listitem>
2662<Para>
2663<programlisting>
2664*include 1997data
2665*solve
2666*include 1998data
2667</programlisting>
2668</Para>
2669</listitem>
2670
2671</VarListEntry>
2672
2673<VarListEntry><Term>Description</Term>
2674
2675<listitem><Para>
2676Distributes misclosures around any loops in the survey and fixes
2677the positions of all existing stations.  This command is intended
2678for situations where you have some new surveys adding extensions
2679to an already drawn-up survey which you wish to avoid completely
2680redrawing. You can read in the old data, use *SOLVE to fix it, and then
2681read in the new data.  Then old stations will be in the same
2682positions as they are in the existing drawn up survey, even if new loops
2683have been formed by the extensions.
2684</Para></listitem>
2685
2686</VarListEntry>
2687
2688</VariableList>
2689
2690</Sect3>
2691
2692<Sect3><Title>TEAM</Title>
2693
2694<VariableList>
2695
2696<VarListEntry><Term>Syntax</Term>
2697
2698<listitem><Para>*team &lt;person&gt; &lt;role&gt;...</Para></listitem>
2699
2700</VarListEntry>
2701
2702<VarListEntry><Term>Example</Term>
2703
2704<listitem>
2705<Para>
2706<programlisting>
2707*team "Nick Proctor" compass clino tape
2708*team "Anthony Day" notes pictures tape
2709</programlisting>
2710</Para>
2711</listitem>
2712
2713</VarListEntry>
2714
2715<VarListEntry><Term>Validity</Term>
2716
2717<listitem><Para>valid at the start of a *begin/*end block.
2718</Para></listitem>
2719<!-- FIXME valid roles are? -->
2720
2721</VarListEntry>
2722
2723<VarListEntry><Term>Description</Term>
2724
2725<listitem><Para>
2726*team specifies the people involved in a survey and what role they
2727filled during that trip.
2728</Para></listitem>
2729
2730</VarListEntry>
2731
2732<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2733
2734<VarListEntry><Term>See Also</Term>
2735
2736<listitem><Para>*begin, *date, *instrument</Para></listitem>
2737
2738</VarListEntry>
2739
2740</VariableList>
2741
2742</Sect3>
2743
2744<Sect3><Title>TITLE</Title>
2745
2746<VariableList>
2747
2748<VarListEntry><Term>Syntax</Term>
2749
2750<listitem><Para>*title &lt;title&gt;</Para></listitem>
2751
2752</VarListEntry>
2753
2754<VarListEntry><Term>Example</Term>
2755
2756<listitem>
2757<programlisting>
2758*title Dreamtime</programlisting>
2759
2760<programlisting>
2761*title "Mission Impossible"</programlisting>
2762</listitem>
2763
2764</VarListEntry>
2765
2766<VarListEntry><Term>Description</Term>
2767
2768<listitem><Para>*title allows you to set the descriptive title for a survey.
2769If the title contains spaces, you need to enclose it in quotes ("").
2770If there is no *title command, the title defaults to the survey name
2771given in the *begin command.
2772</Para>
2773</listitem>
2774
2775</VarListEntry>
2776
2777<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2778
2779<!--
2780<VarListEntry><Term>See Also</Term>
2781
2782<listitem><Para>*end, *prefix</Para></listitem>
2783
2784</VarListEntry>
2785-->
2786
2787</VariableList>
2788
2789</Sect3>
2790
2791<Sect3><Title>TRUNCATE</Title>
2792
2793<VariableList>
2794
2795<VarListEntry><Term>Syntax</Term>
2796
2797<listitem><Para>*truncate &lt;length&gt;|off</Para></listitem>
2798
2799</VarListEntry>
2800
2801<!-- FIXME:
2802<VarListEntry><Term>Example</Term>
2803
2804<listitem>
2805<programlisting>
2806</programlisting>
2807
2808</listitem>
2809
2810</VarListEntry>
2811-->
2812
2813<VarListEntry><Term>Description</Term>
2814
2815<listitem><Para>Station names may be of any length in <Application>Survex</Application>, but some
2816other (mostly older) cave surveying software only regard the first few
2817characters of a name as significant (e.g. "entran" and "entrance"
2818might be treated as the same).  To facilitate using data imported from
2819such a package <Application>Survex</Application> allows you to truncate names to whatever
2820length you want (but by default truncation is off).
2821</Para>
2822
2823<Para>Figures for the number of characters which are significant in various
2824software packages: Compass currently has a limit of 12,
2825CMAP has a limit of 6,
2826Smaps 4 had a limit of 8,
2827<!-- FIXME any limits for other software, winkarst for example? -->
2828Surveyor87/8 used 8.
2829<Application>Survex</Application> itself used 8 per prefix
2830level up to version 0.41, and 12 per prefix level up to 0.73 (more recent
2831versions removed this rather archaic restriction).
2832</Para>
2833</listitem>
2834
2835</VarListEntry>
2836
2837<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2838
2839<!--
2840<VarListEntry><Term>See Also</Term>
2841
2842<listitem><Para>*end, *prefix</Para></listitem>
2843
2844</VarListEntry>
2845-->
2846
2847</VariableList>
2848
2849</Sect3>
2850
2851<Sect3><Title>UNITS</Title>
2852
2853<VariableList>
2854
2855<VarListEntry><Term>Syntax</Term>
2856
2857<listitem><Para>
2858*units &lt;quantity list&gt; [&lt;factor&gt;] &lt;unit&gt;
2859</Para>
2860<Para>
2861*units default
2862</Para></listitem>
2863
2864</VarListEntry>
2865
2866<VarListEntry><Term>Example</Term>
2867
2868<listitem>
2869<Para>
2870<programlisting>
2871*units tape metres</programlisting>
2872
2873<programlisting>
2874*units compass backcompass clino backclino grads</programlisting>
2875
2876<programlisting>
2877*units dx dy dz 1000 metres ; data given as kilometres</programlisting>
2878
2879<programlisting>
2880*units left right up down feet</programlisting>
2881</Para>
2882</listitem>
2883
2884</VarListEntry>
2885
2886<VarListEntry><Term>Description</Term>
2887
2888<listitem><Para>
2889&lt;quantity&gt; is one of the following (grouped entries are just alternative names for the same thing):
2890TAPE/LENGTH, COMPASS/BEARING, BACKCOMPASS/BACKBEARING, CLINO/GRADIENT, BACKCLINO/BACKGRADIENT, COUNTER/COUNT, DEPTH, DECLINATION, DX/EASTING, DY/NORTHING, DZ/ALTITUDE, LEFT, RIGHT, UP/CEILING, DOWN/FLOOR
2891</Para>
2892
2893<Para>Changes current units of all the quantities listed to [&lt;factor&gt;]
2894&lt;unit&gt;. Note that quantities can be expressed either as
2895the instrument (e.g. COMPASS) or the measurement (e.g. BEARING).
2896</Para>
2897
2898<Para>&lt;factor&gt; allows you to easy specify situations such as measuring
2899distance with a diving line knotted every 10cm (*units distance 0.1 metres).
2900If &lt;factor&gt; is omitted it defaults to 1.0.  If specified, it must be
2901non-zero.
2902</Para>
2903
2904<Para>Valid units for listed quantities are:
2905</Para>
2906
2907<Para>TAPE/LENGTH, COUNTER/COUNT, DEPTH, DX/EASTING, DY/NORTHING, DZ/ALTITUDE
2908in YARDS|FEET|METRIC|METRES|METERS (default: METRES)
2909</Para>
2910
2911<Para>CLINO/GRADIENT, BACKCLINO/BACKGRADIENT
2912in DEG|DEGREES|GRADS|MILS|PERCENT|PERCENTAGE (default: DEGREES)
2913</Para>
2914
2915<Para>COMPASS/BEARING, BACKCOMPASS/BACKBEARING, DECLINATION
2916in DEG|DEGREES|GRADS|MILS|MINUTES (default: DEGREES)
2917</Para>
2918
2919<Para>(360 degrees = 400 grads (also known as Mils))
2920</Para>
2921</listitem>
2922
2923</VarListEntry>
2924
2925<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2926
2927<VarListEntry><Term>See Also</Term>
2928
2929<listitem><Para>*calibrate</Para></listitem>
2930
2931</VarListEntry>
2932
2933</VariableList>
2934
2935</Sect3>
2936
2937</Sect2>
2938
2939</Sect1>
2940
2941<!-- FIXME rename to "Cookbook"? -->
2942<Sect1><Title>Contents of <filename>.svx</filename> files: How do I?</Title>
2943<?dbhtml filename="svxhowto.htm">
2944
2945<Para>
2946Here is some example <Application>Survex</Application> data (a very small cave numbered 1623/163):
2947</Para>
2948
2949<programlisting>
29502 1 26.60 222  17.5
29512 3 10.85 014   7
29522 4  7.89 254 -11
29534 5  2.98  - DOWN
29545 6  9.29 271 -28.5</programlisting>
2955
2956<Para>
2957You can vary the data ordering.  The default is:
2958</Para>
2959
2960<Para>
2961from-station to-station tape compass clino
2962</Para>
2963
2964<Para>
2965This data demonstrates a number of useful features of <Application>Survex</Application>:
2966</Para>
2967
2968<Para>
2969Legs can be measured either way round, which allows the use of
2970techniques like "leap-frogging" (which is where legs
2971alternate forwards and backwards).
2972</Para>
2973
2974<Para>
2975Also notice that there is a spur in the survey (2 to 3).  You
2976do not need to specify this specially.
2977</Para>
2978
2979<Para>
2980<Application>Survex</Application> places few restrictions on station naming (see "Survey
2981Station Names" in the previous section), so you can number the stations
2982as they were in the original survey notes.  Although not apparent from
2983this example, there is no requirement for each leg to connect to an
2984existing station.  <Application>Survex</Application> can accept data in any order, and will
2985check for connectedness once all the data has been read in.
2986</Para>
2987
2988<Para>
2989Each survey is also likely to have other information associated
2990with it, such as instrument calibrations, etc.  This has been
2991omitted from this example to keep things simple.
2992</Para>
2993
2994<Para>
2995Most caves will take more than just one survey trip to map.  Commonly
2996the numbering in each survey will begin at 1, so we need to be
2997able to tell apart stations with the same number in different
2998surveys.
2999</Para>
3000
3001<Para>
3002To accomplish this, <Application>Survex</Application> has a very flexible system of hierarchical
3003prefixes.  All you need do is give each survey a unique name or
3004number, and enter the data like so:
3005</Para>
3006
3007<programlisting>
3008*begin 163
3009*export 1
30102 1 26.60 222  17.5
30112 3 10.85 014   7
30122 4  7.89 254 -11
30134 5  2.98  - DOWN
30145 6  9.29 271 -28.5
3015*end 163</programlisting>
3016
3017<Para><Application>Survex</Application> will name the stations by attaching the current prefix.
3018In this case, the stations will be named 163.1, 163.2, etc.
3019</Para>
3020
3021<Para>We have a convention with the CUCC Austria data that the entrance survey
3022station of a cave is named P&lt;cave number&gt;, P163 in this case. We
3023can accomplish this like so:
3024</Para>
3025
3026<programlisting>
3027*equate P163 163.1
3028*entrance P163
3029*begin 163
3030*export 1
30312 1 26.60 222  17.5
30322 3 10.85 014   7
30332 4  7.89 254 -11
30344 5  2.98  - DOWN
30355 6  9.29 271 -28.5
3036*end 163</programlisting>
3037
3038<Sect2><Title>Specify surface survey data</Title>
3039
3040<Para>
3041Say you have 2 underground surveys and 2 surface ones with 2 fixed reference
3042points.  You want to mark the surface surveys so that their length isn't
3043included in length statistics, and so that Aven knows to display them
3044differently.  To do this you mark surface data with the "surface" flag
3045- this is set with "*flags surface" like so:
3046</Para>
3047
3048<programlisting>
3049; fixed reference points
3050*fix fix_a 12345 56789 1234
3051*fix fix_b 23456 67890 1111                                                     
3052                                                                               
3053; surface data (enclosed in *begin ... *end to stop the *flags command
3054; from "leaking" out)
3055*begin
3056*flags surface
3057*include surface1
3058*include surface2
3059*end                                                                           
3060                                                                               
3061; underground data
3062*include cave1
3063*include cave2</programlisting>
3064
3065<Para>
3066You might also have a survey which starts on the surface and heads into a
3067cave.  This can be easily handled too - here's an example which goes in
3068one entrance, through the cave, and out of another entrance:
3069</Para>
3070
3071<programlisting>
3072*begin BtoC
3073*title "161b to 161c"
3074*date 1990.08.06 ; trip 1990-161c-3 in 1990 logbook
3075
3076*begin
3077*flags surface
307802    01      3.09   249    -08.5
307902    03      4.13   252.5  -26
3080*end
3081
308204    03      6.00   020    +37
308304    05      3.07   329    -31
308406    05      2.67   203    -40.5
308506    07      2.20   014    +04
308607    08      2.98   032    +04
308708    09      2.73   063.5  +21
308809    10     12.35   059    +15
3089
3090*begin
3091*flags surface
309211    10      4.20   221.5  -11.5
309311    12      5.05   215    +03.5
309411    13      6.14   205    +12.5
309513    14     15.40   221    -14
3096*end
3097
3098*end BtoC</programlisting>
3099
3100<Para>
3101Note that to avoid needless complication, Survex regards each leg as
3102being either "surface" or "not surface" - if a leg spans the boundary you'll
3103have to call it one or the other.  It's good surveying practice to
3104deliberately put a station at the surface/underground interface
3105(typically the highest closed contour or drip line) so this generally
3106isn't an onerous restriction.
3107</Para>
3108
3109</Sect2>
3110
3111<Sect2><Title>Specify the ordering and type of data</Title>
3112
3113<Para>The *DATA command is used to specify the data style, and the
3114order in which the readings are given.</Para>
3115
3116</Sect2>
3117
3118<Sect2><Title>Deal with Plumbs or Legs Across Static Water</Title>
3119
3120<!-- FIXME
3121<Para>
3122They can be given
3123as +90, or -90, but as they are not usually measured with the
3124clino, but with a plumb of some sort, then it is useful to distinguish
3125them in this way so that any clino adjustment is not applied to
3126these values.
3127</Para>
3128
3129FIXME: paste in section from mail to list
3130
3131<Para>
3132Note that a similar effect can be achieved by using the "*infer plumbs" command
3133to stop clino corrections being applied to -90 and +90 clino readings.
3134</Para>
3135-->
3136
3137<Para>
3138Plumbed legs should be given using 'UP' or 'DOWN' in place of the
3139clino reading and a dash (or a different specified 'OMIT' character)
3140in place of the compass reading.  This distinguishes
3141them from legs measured with a compass and clino.  Here's an example:
3142</Para>
3143
3144<programlisting>
31451 2 21.54 - UP
31463 2 7.36 017 +17
31473 4 1.62 091 +08
31485 4 10.38 - DOWN</programlisting>
3149
3150<Para>
3151U/D or +V/-V may be used instead of UP/DOWN; the check is not case
3152sensitive.
3153</Para>
3154
3155<Para>
3156Legs surveyed across the surface of a static body of water where no
3157clino reading is taken (since the surface of the water can be assumed
3158to be flat) can be indicated by using LEVEL in place of a clino reading.
3159This prevents the clino correction being applied.  Here's an example:
3160</Para>
3161
3162<programlisting>
31631 2 11.37 190 -12
31643 2  7.36 017 LEVEL
31653 4  1.62 091 LEVEL</programlisting>
3166
3167</Sect2>
3168
3169<Sect2><Title>Specify a BCRA grade</Title>
3170
3171<Para>The *SD command can be used to specify the standard deviations of the
3172various measurements (tape, compass, clino, etc).  Examples files are
3173supplied which define BCRA Grade 3 and BCRA Grade 5 using a number of *sd
3174commands. You can use these by simply including them at the relevant point,
3175as follows:
3176</Para>
3177
3178<programlisting>
3179*begin somewhere
3180; This survey is only grade 3
3181*include grade3
31822 1 26.60 222  17.5
31832 3 10.85 014   7
3184; etc
3185*end somewhere</programlisting>
3186
3187<Para>The default values for the standard deviations are those for
3188BCRA grade 5. Note that it is good practice to keep the *include
3189Grade3 within *Begin and *End commands otherwise it will apply
3190to following survey data, which may not be what you intended.
3191</Para>
3192
3193</Sect2>
3194
3195<Sect2><Title>Specify different accuracy for a leg</Title>
3196
3197<Para>For example, suppose the tape on the plumbed leg in this survey
3198is suspected of being less accurate than the rest of the survey because
3199the length was obtained by measuring the length of the rope used to rig
3200the pitch.  We can set a higher sd for this one measurement and use a
3201*begin/*end block to make sure this setting only applies to the one
3202leg:
3203</Para>
3204
3205<programlisting>
32062 1 26.60 222  17.5
32072 3 10.85 014   7
32082 4  7.89 254 -11
3209*begin
3210; tape measurement was taken from the rope length
3211*sd tape 0.5 metres
32124 5  34.50 - DOWN
3213*end
32145 6  9.29 271 -28.5</programlisting>
3215
3216<!-- FIXME also *calibrate and *instrument? Except rope is measure with the
3217tape... -->
3218</Sect2>
3219
3220<Sect2><Title>Enter Repeated Readings</Title>
3221
3222<Para>If your survey data contains multiple versions of each leg (for example,
3223pockettopo produces such data), then provided these are adjacent to one another
3224Survex 1.2.17 and later will automatically average these and treat them as a
3225single leg.
3226</Para>
3227
3228</Sect2>
3229
3230<Sect2><Title>Enter Radiolocation Data</Title>
3231
3232<!-- FIXME comments from David Gibson here -->
3233<Para>This is done by using the *SD command to specify the appropriate
3234errors for the radiolocation `survey leg' so that the loop closure
3235algorithm knows how to distribute errors if it forms part of a loop.
3236</Para>
3237
3238<Para>The best approach for a radiolocation where the underground station
3239is vertically below the surface station is to represent it as a
3240plumbed leg, giving suitable SDs for the length and plumb angle. The
3241horizontal positioning of this is generally quite accurate, but the
3242vertical positioning may be much less well known. E.g: we have a
3243radiolocation of about 50m depth +/- 20m and horizontal accuracy of
3244+/- 8m. Over 50m the +/-8m is equivalent to an angle of 9 degrees, so
3245that is the expected plumb error. 20m is the expected error in the
3246length. To get the equivalent SD we assume that 99.74% of readings will
3247be within 3 standard deviations of the error value. Thus we divide the
3248expected errors by 3 to get the SD we should specify:
3249</Para> <!-- 3 SD? or same as BCRA3.SVX, etc -->
3250
3251<programlisting>
3252*begin
3253*sd length 6.67 metres
3254*sd plumb 3 degrees
3255surface underground 50 - down
3256*end</programlisting>
3257
3258<Para>
3259We wrap the radiolocation leg in a *begin/*end block to make
3260sure that the special *sd settings only apply to this one leg.
3261</Para>
3262
3263<Para>For more information on the expected errors from radiolocations
3264see Compass Points Issue 10, available online at
3265<ulink url="http://www.chaos.org.uk/survex/cp/CP10/CPoint10.htm">http://www.chaos.org.uk/survex/cp/CP10/CPoint10.htm</ulink>
3266</Para>
3267
3268</Sect2>
3269
3270<Sect2><Title>Enter Diving Data</Title>
3271
3272<Para>Surveys made underwater using a diver's depth gauge can be
3273processed - use the *Data command to specify that the following data
3274is of this type.
3275</Para>
3276
3277</Sect2>
3278
3279<Sect2><Title>Enter Theodolite data</Title>
3280
3281<Para>
3282Theodolite data with turned angles is not yet explicitly catered
3283for, so for now you will need to convert it into equivalent legs in
3284another style - normal or cylpolar are likely to be the best choices.
3285</Para>
3286
3287<Para>
3288If there is no vertical info in your theodolite data then you should
3289use the cylpolar style and use *sd command to specify very low
3290accuracy (high SD) in the depth so that the points will move in the
3291vertical plane as required if the end points are fixed or the survey
3292is part of a loop.
3293</Para>
3294
3295</Sect2>
3296
3297</Sect1>
3298
3299<Sect1><Title>General: How do I?</Title>
3300<?dbhtml filename="genhowto.htm">
3301
3302<Sect2><Title>Create a new survey</Title>
3303
3304<Para>You simply create a text file containing the relevant survey data,
3305using a text editor, and save it with a suitable name with a <filename>.svx</filename>
3306extension. The
3307easiest way is to look at some of the example data and use that
3308as a template. Nearly all surveys will need a bit of basic info
3309as well as the survey data itself: e.g. the date (*date), comments
3310about where, what cave, a name for the survey (using *begin and *end),
3311instrument error corrections etc. Here is a typical survey file:
3312</Para>
3313
3314<Para>All the lines starting with ';' are comments, which are ignored
3315by <Application>Survex</Application>. You can also see the use of 'DOWN' for plumbs, and
3316*calibrate tape for dealing with a tape length error (in this case
3317the end of the tape had fallen off so measurements were made from the
331820cm point).</Para>
3319
3320<programlisting>
3321*equate chaos.1 triassic.pt3.8
3322*equate chaos.2 triassic.pt3.9
3323
3324*begin chaos
3325*title "Bottomless Pit of Eternal Chaos to Redemption pitch"
3326*date 1996.07.11
3327*team "Nick Proctor" compass clino tape
3328*team "Anthony Day" notes pictures tape
3329*instrument compass "CUCC 2"
3330*instrument clino "CUCC 2"
3331;Calibration: Cairn-Rock 071 072 071,  -22 -22 -22
3332;       Rock-Cairn 252 251 252,  +21 +21 +21
3333;Calibration at 161d entrance from cairn nr entrance to
3334;prominent rock edge lower down. This is different from
3335;calibration used for thighs survey of 5 July 1996
3336
3337*export 1 2
3338
3339;Tape is 20cm too short
3340*calibrate tape +0.2
3341
33421 2 9.48 208 +08
33432 3 9.30 179 -23
33443 4 2.17 057 +09
33455 4 10.13 263 +78
33465 6 2.10 171 -73
33477 6 7.93 291 +75
3348*begin
3349*calibrate tape 0
33508 7 35.64 262 +86 ;true length measured for this leg
3351*end
33528 9 24.90 - DOWN
335310 9 8.61 031 -43
335410 11 2.53 008 -34
335511 12 2.70 286 -20
335613 12 5.36 135 +23
335714 13 1.52 119 -12
335815 14 2.00 036 +13
335916 15 2.10 103 +12
336017 16 1.40 068 -07
336117 18 1.53 285 -42
336219 18 5.20 057 -36
336319 20 2.41 161 -67
336420 21 27.47 - DOWN
336521 22 9.30 192 -29
3366*end chaos</programlisting>
3367
3368</Sect2>
3369
3370<Sect2><Title>Join surveys together</Title>
3371
3372<Para>Once you have more than one survey you need to specify how they
3373link together. To do this use *export to make the stations to be
3374joined accessible in the enclosing survey, then *equate in the
3375enclosing survey to join them together.
3376<!-- FIXME example -->
3377</Para>
3378
3379</Sect2>
3380
3381<Sect2><Title>Organise my surveys</Title>
3382
3383<Para>This is actually a large subject. There are many ways you can
3384organise your data using <Application>Survex</Application>. Take a look at the example dataset
3385for some ideas of ways to go about it.
3386</Para>
3387
3388<Sect3><Title>Fixed Points (Control Points)</Title>
3389
3390<Para>The *fix command is used to specify fixed points (also know as control
3391points).  See the description of this command in the "Cavern Commands"
3392section of this manual.
3393</Para>
3394
3395</Sect3>
3396
3397<Sect3><Title>More than one survey per trip</Title>
3398
3399<Para>Suppose you have two separate bits of surveying which were done on the
3400same trip.  So the calibration details, etc. are the same for both.  But you
3401want to give a different survey name to the two sections.  This is easily
3402achieved like so:
3403</Para>
3404
3405<programlisting>
3406*begin
3407*calibrate compass 1.0
3408*calibrate clino 0.5
3409*begin altroute
3410; first survey
3411*end altroute
3412*begin faraway
3413; second survey
3414*end faraway
3415*end</programlisting>
3416
3417</Sect3>
3418
3419</Sect2>
3420
3421<Sect2><Title>Add surface topography</Title>
3422
3423<Para>Survex 1.2.18 added support for loading terrain data and rendering it as
3424a transparent surface.
3425</Para>
3426
3427<Para>
3428We recommend using this new code in preference, but previously the simplest
3429approach was to generate a <filename>.svx</filename> file with the surface mesh
3430in and display it with the survey data.
3431</Para>
3432
3433<Para>
3434It is possible to generate
3435a mesh or contours overlaying your area by various means.  NASA have made
34361 arc-second (approximately 30m) terrain data available for the USA for
3437some years, with only 3 arc-second data available for other countries.
3438However, starting in 2014 they're gradually making 1 arc-second data
3439available for more countries.
3440</Para>
3441
3442<Para>
3443If you want a better resolution that this, reading heights from the
3444contours on a map is one approach.  It's laborious, but feasible for
3445a small area.
3446</Para>
3447
3448<Para>
3449Details of several methods are given in the BCRA Cave Surveying
3450Group magazine Compass Points issue 11, available online at
3451<ulink url="http://www.chaos.org.uk/survex/cp/CP11/CPoint11.htm#Art_5">http://www.chaos.org.uk/survex/cp/CP11/CPoint11.htm#Art_5</ulink>
3452</Para>
3453
3454<Para>If you're using another program to generate a <filename>.svx</filename> file for the surface
3455mesh, it's best to use the NOSURVEY data style.
3456Simply fix all the grid intersections at the correct
3457coordinates and height, and put legs between them using the NOSURVEY style.
3458Here's a grid of 4 squares and 9 intersections:
3459</Para>
3460
3461<programlisting>
3462*fix 00 000 000 1070
3463*fix 01 000 100 1089
3464*fix 02 000 200 1093
3465
3466*fix 10 100 000 1062
3467*fix 11 100 100 1080
3468*fix 12 100 200 1089
3469
3470*fix 20 200 000 1050
3471*fix 21 200 100 1065
3472*fix 22 200 200 1077
3473
3474*data nosurvey station
3475
347600
347701
347802
3479
348010
348111
348212
3483
348420
348521
348622
3487
348800
348910
349020
3491
349201
349311
349421
3495
349602
349712
349822</programlisting>
3499
3500<Para>
3501This is far simpler than trying to create fake tape/compass/clino legs of
3502the right length for each line in the mesh.  It's also very fast to process
3503with cavern.
3504</Para>
3505
3506</Sect2>
3507
3508<Sect2><Title>Overlay a grid</Title>
3509
3510<Para>Aven is able to display a grid, but this functionality isn't currently
3511available in printouts.
3512You can achieve a similar effect for now by creating a <filename>.svx</filename> file
3513where the survey legs form a grid.
3514</Para>
3515
3516</Sect2>
3517
3518<Sect2><Title>Import data from other programs</Title>
3519
3520<Para><Application>Survex</Application> supports a number of features to help with importing
3521existing data. You can specify the ordering of items on a line using *Data
3522(see <Application>Survex</Application> Keywords above), and you can specify the characters used
3523to mean different things using *Set (see <Application>Survex</Application> Keywords above).
3524</Para>
3525
3526<Para>The Ignore and Ignoreall options to the *Data command are often
3527particularly useful, e.g. if you have a dataset with LRUD info or comments
3528on the ends of lines.
3529</Para>
3530
3531<Sect3><Title>Changing Meanings of Characters</Title>
3532
3533<Para>e.g. if you have some data with station names containing the
3534characters '?' and '+' (which are not permitted in a name by default)
3535then the command:
3536</Para>
3537
3538<programlisting>
3539*SET NAMES ?+</programlisting>
3540
3541<Para>
3542specifies that question marks and plus signs are permitted in station names.
3543A-Z, a-z, and 0-9 are always permitted. '_' and '-' are also permitted by
3544default, but aren't in this example.
3545</Para>
3546
3547<Para>If your data uses a comma ',' instead of a decimal point, then
3548you use
3549</Para>
3550
3551<programlisting>
3552*SET DECIMAL ,</programlisting>
3553
3554<Para>to specify that ',' is now the decimal separator instead of '.'.
3555</Para>
3556
3557<!-- FIXME
3558<Para>Note that there are plenty of ways you can use this facility to
3559completely confuse the software, as it may not be able to work out what is
3560going on, or it may simply be ambiguous. It can cope with some ambiguity (e.g.
3561the '-' character is used both for 'MINUS' and for 'OMIT'), but there are
3562limits. If you have a dataset that you can not make <Application>Survex</Application>
3563understand, then send it to us, and we will see what can be done.
3564</Para>
3565-->
3566
3567</Sect3>
3568
3569<!--
3570 Nobody seems to have the CfH convertor...
3571 but it's probably no longer useful anyway
3572
3573<Sect3><Title>Other Converters</Title>
3574
3575<Para>We have an Excel 5 macro for converting The Lotus 123 spreadsheets
3576used by the German survey software Cad F&uuml;r H&ouml;hlen into
3577<Application>Survex</Application> data files. Other converters may also come to be available.
3578These will normally be available via the
3579<ulink url="http://survex.com/"><Application>Survex</Application> Web pages</ulink>.
3580</Para>
3581
3582</Sect3>
3583-->
3584
3585</Sect2>
3586
3587<Sect2><Title>Export data from <Application>Survex</Application></Title>
3588
3589<Para>See Rosetta Stal in the Related Tools section of the Survex web
3590site.  This is a utility written by Taco van Ieperen and Gary Petrie.
3591Note though that this only supports a subset of the svx format,
3592and only work on Microsoft Windows.  The Survex support is limited
3593and doesn't understand the more recently added commands.</Para>
3594
3595</Sect2>
3596
3597<Sect2><Title>See errors and warnings that have gone off the screen</Title>
3598
3599<Para>When you run <Application>Survex</Application> it will process the specified survey data
3600files in order, reporting any warnings and errors.  If there are no
3601errors, the output files are written and various statistics about the
3602survey are displayed. If there are a lot of warnings or errors, they can
3603scroll off the screen and it's not always possible to scroll back to
3604read them.
3605</Para>
3606
3607<Para>The easiest way to see all the text is to use <command>cavern
3608--log</command> to redirect output to a <filename>.log</filename> file,
3609which you can then inspect with a text editor.
3610</Para>
3611
3612<!-- <command>cavern cavename &gt; tmpfile</command> -->
3613
3614</Sect2>
3615
3616<Sect2><Title>Create an Extended Elevation</Title>
3617
3618<Para>Use the Extend program. This takes <filename>.3d</filename> files and
3619'flattens' them.  See 'Extend' for details.
3620</Para>
3621
3622</Sect2>
3623
3624</Sect1>
3625
3626<!--
3627<Sect1><Title>Appendices</Title>
3628<?dbhtml filename="appendix.htm">
3629
3630<Para>Files provided
3631</Para>
3632
3633<Para>Command specification
3634</Para>
3635
3636</Sect1>
3637-->
3638<Sect1><Title>Working with Larry Fish's Compass</Title>
3639<?dbhtml filename="compass.htm">
3640
3641<Para>
3642Survex can read Compass survey data - both raw data (.DAT and .MAK
3643files) and processed survey data (.PLT and .PLF files).  You can even
3644use <command>*include compassfile.dat</command> in a <filename>.svx</filename> file and
3645it'll work!
3646</Para>
3647
3648<Para>
3649One point to note (this tripped us up!): station names in DAT files are
3650case sensitive and so Survex reads DAT files with the equivalent of
3651<command>*case preserve</command>.  The default in SVX files is
3652<command>*case lower</command>.  So this won't work:
3653
3654<programlisting>
3655*fix CE1 0 0 0
3656*include datfilewhichusesCE1.dat</programlisting>
3657
3658Because the CE1 in the *fix is actually interpreted as ce1.  This is
3659what you have to do:
3660
3661<programlisting>
3662*begin
3663*case preserve
3664*fix CE1 0 0 0
3665*include datfilewhichusesCE1.dat
3666*end</programlisting>
3667</Para>
3668
3669</Sect1>
3670
3671<Sect1><Title>Mailing List</Title>
3672<?dbhtml filename="maillist.htm">
3673
3674<Para>The best way to contact the authors and other Survex users is the
3675Survex mailing list - for details visit:
3676<ulink url="http://survex.com/maillist.html">http://survex.com/maillist.html</ulink>
3677</Para>
3678
3679<Para>We'd be delighted to hear how you get on with <Application>Survex</Application> and
3680welcome comments and suggestions for improvements.</Para>
3681
3682<Para>
3683And we'd love you to contribute your skills to help make <Application>Survex</Application> even
3684better.  Point out areas of the documentation which could be made clearer, or
3685sections which are missing entirely.  Download test releases, try them out, and
3686let us know if you find problems or have suggestions for improvements.
3687If there's no translation to your language, you could provide one.
3688Or if your a developer, <emphasis>"Say it with code"</emphasis>.  There's
3689plenty to do, so feel free to join in.
3690</Para>
3691
3692</Sect1>
3693
3694<Sect1><Title>Future Developments</Title>
3695<?dbhtml filename="future.htm">
3696
3697<Para>
3698Now that <Application>Survex</Application> has reached version 1.0, we are continuing progress
3699towards version 2, in a series of steps, evolving out of
3700Survex 1.0.  The GUI framework is being based on aven, with
3701the printer drivers and other utility programs being pulled in
3702and integrated into the menus.</Para>
3703
3704<Para>Aven is built on <Application>wxWidgets</Application>, which means that it can easily support
3705Unix, Microsoft Windows, and Mac OS X.</Para>
3706
3707<Para>More information on our plans is on the <ulink
3708url="http://survex.com/">web site</ulink>.
3709</Para>
3710
3711</Sect1>
3712
3713</article>
Note: See TracBrowser for help on using the repository browser.