source: git/doc/manual.sgml @ e6fdc7c

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

doc/manual.sgml: Point to '*case' and '*truncate' from the 'SEE ALSO'
sections of each other.

  • Property mode set to 100644
File size: 101.7 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.21 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 &lt;quantity list&gt; &lt;zero error&gt; &lt;units&gt; [&lt;scale&gt;]
1007</Para>
1008<Para>*calibrate default
1009</Para>
1010</listitem>
1011
1012</VarListEntry>
1013
1014<VarListEntry><Term>Example</Term>
1015
1016<listitem>
1017<Para>
1018<programlisting>
1019*calibrate tape +0.3
1020</programlisting>
1021</Para>
1022</listitem>
1023
1024</VarListEntry>
1025
1026<VarListEntry><Term>Description</Term>
1027
1028<listitem>
1029
1030<Para>
1031*calibrate is used to specify instrument calibrations.
1032</Para>
1033
1034<Para>
1035&lt;quantity&gt; is one of TAPE|COMPASS|CLINO|COUNTER|DEPTH|DECLINATION|X|Y|Z
1036</Para>
1037
1038<Para>
1039Several quantities can be given in &lt;quantity list&gt;
1040</Para>
1041
1042<Para>
1043You need to be careful about the sign of the ZeroError. The value of
1044ZeroError is what the instrument would read when measuring a
1045reading which should be zero.  So for example, if your tape measure
1046has the end missing, and you are using the 30cm mark to take all
1047measurements from, then a zero distance would be measured as 30cm and
1048you would correct this with:
1049</Para>
1050
1051<programlisting>*CALIBRATE tape +0.3</programlisting>
1052
1053<Para>If you tape was too long, starting at -20cm (it does happen!)
1054then you can correct it with:
1055</Para>
1056
1057<programlisting>*CALIBRATE tape -0.2</programlisting>
1058
1059<Para>Note: ZeroError is irrelevant for Topofil counters and depth
1060gauges since pairs of readings are subtracted.
1061</Para>
1062
1063<Para>
1064In the first form in the synopsis above, the zero error is measured by the
1065instrument itself (e.g. reading off the number where a truncated tape now ends)
1066and any scale factor specified applies to it, like so:
1067</Para>
1068
1069<Para>
1070Value = ( Reading - ZeroError ) * Scale    (Scale defaults to 1.0)
1071</Para>
1072
1073<Para>
1074In the second form above (supported since Survex 1.2.21), the zero error has
1075been measured externally (e.g. measuring how much too long your tape is with
1076a ruler) - the units of the zero error are explicitly specified and any scale
1077factor isn't applied to it:
1078</Para>
1079
1080<Para>
1081Value = ( Reading * Scale ) - ZeroError    (Scale defaults to 1.0)
1082</Para>
1083
1084<Para>
1085If the scale factor is 1.0, then the two forms are equivalent, though they
1086still allow you to diffentiate between how the zero error has been determined.
1087</Para>
1088
1089<Para>
1090The magnetic declination is the difference between true north and magnetic
1091north.  This varies both by location and over time.  You can just use
1092*calibrate compass to correct for any zero error and the declination in one,
1093but it's generally preferable to keep the compass zero error and the magnetic
1094declination separate.
1095</Para>
1096
1097<Para>
1098As of Survex 1.2.21, you can specify the magnetic declination using the
1099*declination command - either by giving an explicit value, or by specifying
1100a location to use along with the survey date to calculate a value from the
1101IGRF model.  In earlier versions, you could only specify the declination
1102using *calibrate declination.
1103</Para>
1104
1105<Para>
1106Cavern calculates the true bearing as follows:
1107</Para>
1108
1109<Para>
1110(magnetic bearing) = ((reading)-(compass zero err)) * (compass
1111scale factor)
1112</Para>
1113
1114<Para>
1115(true bearing) = ((bearing)-(declination zero err))
1116</Para>
1117
1118<Para>
1119The scale factor for DECLINATION must be 1.0, otherwise an error
1120is given.
1121</Para>
1122
1123<Para>
1124Magnetic declinations are conventionally positive when magnetic north is east of
1125true north.  With *declination, you specify the declination with the conventional
1126sign, but with *calibrate declination you need to reverse the sign when
1127specifying the declination correction to use - for example, for an area where
1128the magnetic declination is 5 degrees, you should use:
1129</Para>
1130
1131<programlisting>*CALIBRATE DECLINATION -5</programlisting>
1132
1133<Para>
1134The default is all quantities calibrated to scale factor 1.0,
1135zero error 0.0
1136</Para>
1137
1138</listitem>
1139
1140</VarListEntry>
1141
1142<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1143
1144<VarListEntry><Term>See Also</Term>
1145
1146<listitem><Para>*declination, *units</Para></listitem>
1147
1148</VarListEntry>
1149
1150</VariableList>
1151
1152</Sect3>
1153
1154<Sect3><Title>CASE</Title>
1155
1156<VariableList>
1157
1158<VarListEntry><Term>Syntax</Term>
1159
1160<listitem><para>*case preserve|toupper|tolower</para></listitem>
1161
1162</VarListEntry>
1163
1164<VarListEntry><Term>Example</Term>
1165
1166<listitem>
1167<Para>
1168<programlisting>
1169*begin bobsbit
1170; Bob insists on using case sensitive station names
1171*case preserve
11721 2   10.23 106 -02
11732 2a   1.56 092 +10
11742 2A   3.12 034 +02
11752 3    8.64 239 -01
1176*end bobsbit</programlisting>
1177</Para>
1178</listitem>
1179
1180</VarListEntry>
1181
1182<VarListEntry><Term>Description</Term>
1183
1184<listitem><Para>*case determines how the case of letters in survey names is
1185handled.  By default all names are forced to lower case (which gives a case
1186insensitive match, but you can tell cavern to force to upper case, or leave
1187the case as is (in which case '2a' and '2A' will be regarded as different).
1188</Para></listitem>
1189
1190</VarListEntry>
1191
1192<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1193
1194<VarListEntry><Term>See Also</Term>
1195
1196<listitem><Para>*truncate</Para></listitem>
1197
1198</VarListEntry>
1199
1200</VariableList>
1201
1202<!-- FIXME - work this text in here or elsewhere
1203
1204What I mean (though failed to express very well) is that a dataset without
1205this information isn't the same dataset (in general anyway).  For example:
1206
1207A1 a2 10.32 140 -05
1208a2 a3  4.91 041 -01
1209a1 a3  7.01 206  02
1210
1211is either a traverse of 3 legs or a (probably badly misclosed) loop.  If
1212these names are on the original survey notes, the surveyors ought to say
1213whether "A1" is the same as "a1" (although the usual case for using this
1214feature is probably for importing data from elsewhere).  Similarly for
1215truncation.  Whether a clino of +/-90 degrees (or +/-100 grad, etc) is
1216interpreted as a plumb is something that should have been noted in the cave
1217(unless it's implicit because it's standard practice for a survey project).
1218
1219It's a similar issue to calibration data in many ways.  You can argue it's
1220not part of "the survey", but without it the survey won't be the same shape,
1221and it's not useful to process the same survey with different settings for
1222compass calibration or name case sensitivity.
1223
1224>Clearly that is unhelpfully strict, but it is
1225>important to be semantically clear about what is 'data' and what is 'commands
1226>or meta-data' which describe what to do with/how to interpret that data.
1227
1228Think of the lines starting with a "*" as "command or meta-data".
1229
1230>The most-correct solution to this is (I believe) Martin Heller's idea about
1231>including 'rules' in the datastream, but that's too big a subject for right
1232>now.
1233>
1234>The reason '-C' was made into a command-line option, was that it made very
1235>little sense to change it part way though a dataset. What exactly happens if
1236>you suddenly tell cavern to become case-sensitive halfway through a run?
1237
1238-C has always had 3 settings - "leave case alone", "force to lower", and
1239"force to upper".  It doesn't really mean "case sensitivity" but rather
1240something like "case processing".  So you can usefully change it during a
1241run.  So if my dataset treats "NoTableChamber" (so named because it was
1242lacking in furniture) as different from "NotableChamber" (which was notable
1243for other reasons) I can process it with a dataset from someone else which
1244needs to be treated as case insensitive like so:
1245
1246*begin my_cave
1247*include my_dataset
1248*end my_cave
1249
1250*equate my_cave.NoTableChamber.14 your_cave.linkpassage.13
1251
1252*begin your_cave
1253*case tolower
1254*include your_dataset
1255*end your_cave
1256
1257You may be thinking of -U<n>, which used to mean "only compare the first n
1258characters of station names", but that doesn't allow arbitrary datasets to
1259be processed together.
1260
1261So we changed it to mean "truncate station names to n characters", and
1262allowed it to be changed at any point, rather than being set once for the
1263whole run.
1264
1265-->
1266
1267</Sect3>
1268
1269<Sect3><Title>COPYRIGHT</Title>
1270
1271<VariableList>
1272
1273<VarListEntry><Term>Syntax</Term>
1274
1275<listitem><Para>*copyright &lt;date&gt; &lt;text&gt;</Para></listitem>
1276
1277</VarListEntry>
1278
1279<VarListEntry><Term>Example</Term>
1280
1281<listitem>
1282<Para>
1283<programlisting>
1284*begin littlebit
1285*copyright 1983 CUCC
12861 2 10.23 106 -02
12872 3  1.56 092 +10
1288*end littlebit</programlisting>
1289</Para>
1290</listitem>
1291
1292</VarListEntry>
1293
1294<VarListEntry><Term>Validity</Term>
1295
1296<listitem><Para>valid at the start of a *begin/*end block.
1297</Para></listitem>
1298
1299</VarListEntry>
1300
1301<VarListEntry><Term>Description</Term>
1302
1303<listitem><Para>*copyright allows the copyright information to be
1304stored in a way that can be automatically collated.
1305</Para></listitem>
1306
1307</VarListEntry>
1308
1309<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1310
1311<VarListEntry><Term>See Also</Term>
1312
1313<listitem><Para>*begin</Para></listitem>
1314
1315</VarListEntry>
1316
1317</VariableList>
1318
1319</Sect3>
1320
1321<Sect3><Title>CS</Title>
1322
1323<VariableList>
1324
1325<VarListEntry><Term>Syntax</Term>
1326
1327<listitem><Para>*cs [out] &lt;coordinate system&gt;</Para></listitem>
1328
1329</VarListEntry>
1330
1331<VarListEntry><Term>Example</Term>
1332
1333<listitem>
1334<Para>
1335<programlisting>
1336*cs UTM60S
1337*fix beehive 313800 5427953 20</programlisting>
1338</Para>
1339
1340<Para>
1341<programlisting>
1342; Output in the coordinate system used in the Totes Gebirge in Austria
1343*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>
1344</Para>
1345</listitem>
1346
1347</VarListEntry>
1348
1349<VarListEntry><Term>Description</Term>
1350
1351<listitem><Para>*cs allows the coordinate systems used for fixed points and for
1352processed survey data to be specified.
1353</Para>
1354
1355<Para>
1356*cs was added in Survex 1.2.14, but handling of fixed points specified with
1357latitude and longitude didn't work until 1.2.21.  And *fix with standard
1358deviations specified also didn't work until 1.2.21.
1359</Para>
1360
1361<Para>
1362The currently supported coordinate systems are:
1363</Para>
1364
1365<Para>CUSTOM followed by a PROJ4 string (like in the example above).</Para>
1366
1367<Para>EPSG: followed by a positive integer code.  EPSG codes cover most
1368coordinate systems in use, and PROJ supports many of these.  The website
1369<ulink url="http://epsg.io/">http://epsg.io/</ulink> is a useful resource for
1370finding the EPSG code you want.  Supported since Survex 1.2.15.</Para>
1371
1372<Para>ESRI: followed by a positive integer code.  ESRI codes are used by
1373ArcGIS to specify coordinate systems (in a similar way to EPSG codes), and PROJ
1374supports many of them.  Supported since Survex 1.2.15.</Para>
1375
1376<Para>EUR79Z30 for UTM zone 30, EUR79 datum.  Supported since Survex 1.2.15.
1377</Para>
1378
1379<Para>IJTSK for the modified version of the Czechoslovak S-JTSK system where
1380the axes point East and North.  Supported since Survex 1.2.15.</Para>
1381
1382<Para>IJTSK03 for a variant of IJTSK.  Supported since Survex 1.2.15.</Para>
1383
1384<Para>JTSK for the Czechoslovak S-JTSK system.  The axes on this point West
1385and South, so it's not support as an output coordinate system.
1386Supported since Survex 1.2.16.</Para>
1387
1388<Para>JTSK03 for a variant of JTSK.  Supported since Survex 1.2.16.</Para>
1389
1390<Para>LONG-LAT for longitude/latitude.  The WGS84 datum is assumed.  Supported
1391since Survex 1.2.15.</Para>
1392
1393<Para>OSGB: followed by a two letter code for the UK Ordnance Survey National
1394Grid.  The first letter should be 'H', 'N', 'O', 'S' or 'T'; the second any
1395letter except 'I'.  Supported since Survex 1.2.15.</Para>
1396
1397<Para>S-MERC for the "Web Mercator" spherical mercator projection, used by
1398online map sites like OpenStreetMap, Google maps, Bing maps, etc.  Supported
1399since Survex 1.2.15.
1400</Para>
1401
1402<Para>UTM followed by a zone number (1-60), optionally followed by "N" or "S"
1403(default is North).  The WGS84 datum is assumed.</Para>
1404
1405<Para>
1406By default, Survex works in an unspecified coordinate system (and this was the
1407only option before *cs was added).  However, it's useful for coordinate system
1408which the processed survey data is in to be specified if you want to use the
1409processed data in ways which required knowing the coordinate system (such as
1410exporting a list of entrances for use in a GPS).  You can now do this by using
1411"*cs out".
1412</Para>
1413
1414<Para>
1415It is also useful to be able to take coordinates for fixed points in whatever
1416coordinate system you receive them in and put them directly into Survex, rather
1417than having to convert with an external tool.  For example, you may have your
1418GPS set to show coordinates in UTM with the WGS84 datum, even though you want
1419the processed data to be in some local coordinate system.  And someone else
1420may provide GPS coordinates in yet another coordinate system.  You just need
1421to set the appropriate coordinate system with "*cs" before each group of "*fix"
1422commands in a particular coordinate system.
1423</Para>
1424
1425<Para>
1426If you're going to make use of "*cs", then the coordinate system must be
1427specified for everything, so a coordinate system must be in effect for all
1428"*fix" commands, and you must set the output coordinate system before any
1429points are fixed.
1430</Para>
1431
1432<Para>
1433Also, if "*cs" is in use, then you can't omit the coordinates in a "*fix"
1434command, and a fixed point won't be invented if none exists.
1435</Para>
1436
1437<Para>
1438If you use "*cs out" more than once, the second and subsequent commands are
1439silently ignored - this makes it possible to combine two datasets with
1440different "*cs out" settings without having to modify either of them.
1441</Para>
1442
1443<Para>
1444Something to be aware of with "*cs" is that altitudes are currently assumed to
1445be "height above the ellipsoid", whereas GPS units typically give you "height
1446above sea level", or more accurately "height above a particular geoid".  This
1447is something we're looking at how best to address, but you shouldn't need to
1448worry about it if your fixed points are in the same coordinate system as your
1449output, or if they all use the same ellipsoid.  For a more detailed discussion
1450of this, please see: http://expo.survex.com/handbook/survey/coord.htm
1451</Para>
1452</listitem>
1453
1454</VarListEntry>
1455
1456<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1457
1458<VarListEntry><Term>See Also</Term>
1459
1460<listitem><Para>*fix</Para></listitem>
1461
1462</VarListEntry>
1463
1464</VariableList>
1465
1466</Sect3>
1467<Sect3><Title>DATA</Title>
1468
1469<VariableList>
1470
1471<VarListEntry><Term>Syntax</Term>
1472
1473<listitem><Para>*data &lt;style&gt; &lt;ordering&gt;</Para></listitem>
1474<!-- BACKCOMPASS BACKCLINO -->
1475</VarListEntry>
1476
1477<VarListEntry><Term>Example</Term>
1478
1479<listitem>
1480<Para>
1481<programlisting>
1482*data normal from to compass tape clino</programlisting>
1483</Para>
1484
1485<Para>
1486<programlisting>
1487*data normal station ignoreall newline compass tape clino</programlisting>
1488</Para>
1489</listitem>
1490
1491</VarListEntry>
1492
1493<VarListEntry><Term>Description</Term>
1494
1495<listitem><Para>
1496&lt;style&gt; = DEFAULT|NORMAL|DIVING|CARTESIAN|TOPOFIL|CYLPOLAR|NOSURVEY|PASSAGE
1497</Para>
1498
1499<Para>
1500&lt;ordering&gt; = ordered list of instruments - which are valid depends on the
1501style.
1502</Para>
1503
1504<Para>
1505In Survex 1.0.2 and later, TOPOFIL is simply a synonym for NORMAL, left in to
1506allow older data to be processed without modification.  Use the name NORMAL
1507by preference.
1508</Para>
1509
1510<Para>
1511There are two variants of each style - interleaved and non-interleaved.
1512Non-interleaved is "one line per leg", interleaved has a line for the data
1513shared between two legs (e.g. STATION=FROM/TO, DEPTH=FROMDEPTH/TODEPTH,
1514COUNT=FROMCOUNT/TOCOUNT).  Note that not all interleavable readings have to
1515be interleaved - for example:
1516
1517<programlisting>
1518*data diving station newline fromdepth compass tape todepth</programlisting>
1519
1520In addition, interleaved data can have a DIRECTION reading, which can be "F"
1521for a foresight or "B" for a backsight.
1522</Para>
1523
1524<Para>
1525In NORMAL, DIVING, and CYLPOLAR data styles, TAPE may be replaced by
1526FROMCOUNT/TOCOUNT (or COUNT in interleaved data) to allow processing of surveys
1527performed with a Topofil instead of a tape.
1528</Para>
1529
1530<VariableList>
1531
1532<VarListEntry><Term>DEFAULT</Term>
1533<listitem><Para>Select the default data style and ordering (NORMAL style, ordering: from to tape compass clino).</Para></listitem>
1534</VarListEntry>
1535
1536<VarListEntry><Term>NORMAL</Term>
1537<listitem><Para>The usual tape/compass/clino centreline survey.
1538For non-interleaved data the allowed readings are:
1539FROM TO TAPE COMPASS CLINO BACKCOMPASS BACKCLINO;
1540for interleaved data the allowed readings are:
1541STATION DIRECTION TAPE COMPASS CLINO BACKCOMPASS BACKCLINO.
1542The CLINO/BACKCLINO reading is not required - if it's not given, the vertical
1543standard deviation is taken to be proportional to the tape measurement.
1544Alternatively, individual clino readings can be given as OMIT (default "-")
1545which allows for data where only some clino readings are missing.
1546E.g.:
1547
1548<programlisting>
1549*data normal from to compass clino tape
15501 2 172 -03 12.61</programlisting>
1551
1552<programlisting>
1553*data normal station newline direction tape compass clino
15541
1555 F 12.61 172 -03
15562</programlisting>
1557
1558<programlisting>
1559*data normal from to compass clino fromcount tocount
15601 2 172 -03 11532 11873</programlisting>
1561
1562<programlisting>
1563*data normal station count newline direction compass clino
15641 11532
1565 F 172 -03
15662 11873</programlisting>
1567 
1568</Para></listitem>
1569</VarListEntry>
1570
1571<VarListEntry><Term>DIVING</Term>
1572<listitem><Para>
1573An underwater survey where the vertical information is from a diver's depth
1574gauge.  This style can also be also used for an above-water survey where the
1575altitude is measured with an altimeter.  DEPTH is defined as the altitude (Z)
1576so increases upwards by default.  So for a diver's depth gauge, you'll need to
1577use *CALIBRATE with a negative scale factor (e.g. *calibrate depth 0 -1).
1578</Para>
1579
1580<Para>For non-interleaved data the allowed readings are:
1581FROM TO TAPE COMPASS CLINO BACKCOMPASS BACKCLINO FROMDEPTH TODEPTH DEPTHCHANGE (the vertical
1582can be given as readings at each station, (FROMDEPTH/TODEPTH) or as a change
1583along the leg (DEPTHCHANGE)).</Para>
1584
1585<Para>Survex 1.2.20 and later allow an optional CLINO and/or BACKCLINO reading
1586in DIVING style.  At present these extra readings are checked for syntactic
1587validity, but are otherwise ignored.  The intention is that a future version
1588will check them against the other readings to flag up likely blunders, and
1589average with the slope data from the depth gauge and tape reading.</Para>
1590
1591<Para>For interleaved data the allowed readings are:
1592STATION DIRECTION TAPE COMPASS BACKCOMPASS DEPTH DEPTHCHANGE.
1593(the vertical change can be given as a reading at the station (DEPTH) or as a change along the leg (DEPTHCHANGE)).
1594
1595<programlisting>
1596*data diving from to tape compass fromdepth todepth
15971 2 14.7 250 -20.7 -22.4</programlisting>
1598
1599<programlisting>
1600*data diving station depth newline tape compass
16011 -20.7
1602 14.7 250
16032 -22.4</programlisting>
1604
1605<programlisting>
1606*data diving from to tape compass depthchange
16071 2 14.7 250 -1.7</programlisting>
1608</Para>
1609</listitem>
1610</VarListEntry>
1611
1612<VarListEntry><Term>CARTESIAN</Term>
1613<listitem><Para>
1614Cartesian data style allows you to specify the (x,y,z) changes between
1615stations.  It's useful for digitising surveys where the original survey
1616data has been lost and all that's available is a drawn up version.
1617
1618<programlisting>
1619*data cartesian from to northing easting altitude
16201 2 16.1 20.4 8.7</programlisting>
1621
1622<programlisting>
1623*data cartesian station newline northing easting altitude
16241
1625 16.1 20.4 8.7
16262</programlisting>
1627
1628<!--FIXME: dx dy dz-->
1629</Para>
1630
1631<Note><Para>
1632Cartesian data are relative to <emphasis>true</emphasis> North not
1633<emphasis>magnetic</emphasis> North (i.e. they are unaffected by
1634<command>*calibrate declination</command>).
1635</Para></Note>
1636</listitem>
1637</VarListEntry>
1638
1639<VarListEntry><Term>CYLPOLAR</Term>
1640<listitem><Para>
1641A CYLPOLAR style survey is very similar to a diving survey, except that the tape
1642is always measured horizontally rather than along the slope of the leg.
1643
1644<programlisting>
1645*data cypolar from to tape compass fromdepth todepth
16461 2 9.45 311 -13.3 -19.0</programlisting>
1647
1648<programlisting>
1649*data cylpolar station depth newline tape compass
16501 -13.3
1651 9.45 311
16522 -19.0</programlisting>
1653
1654<programlisting>
1655*data cylpolar from to tape compass depthchange
16561 2 9.45 311 -5.7</programlisting>
1657</Para></listitem>
1658</VarListEntry>
1659
1660<VarListEntry><Term>NOSURVEY</Term>
1661<listitem><Para>
1662A NOSURVEY survey doesn't have any measurements - it merely indicates that
1663there is line of sight between the pairs of stations.
1664
1665<programlisting>
1666*data nosurvey from to
16671 7
16685 7
16699 11</programlisting>
1670
1671<programlisting>
1672*data nosurvey station
16731
16747
16755
1676
1677*data nosurvey station
16789
167911</programlisting>
1680</Para></listitem>
1681</VarListEntry>
1682
1683<VarListEntry><Term>PASSAGE</Term>
1684<listitem><Para>
1685This survey style defines a 3D "tube" modelling a passage in the cave.
1686The tube uses the survey stations listed in the order listed.  It's
1687permitted to use survey stations which aren't directly linked by
1688the centre-line survey.  This can be useful - sometimes the centreline
1689will step sideways or up/down to allow a better sight for the next
1690leg and you can ignore the extra station.  You can also define tubes
1691along unsurveyed passages, akin to "nosurvey" legs in the centreline
1692data.</Para>
1693
1694<Para>This means that you need to split off side passages into seperate
1695tubes, and hence separate sections of passage data, starting with
1696a new *data command.</Para>
1697
1698<Para>
1699Simple example of how to use this data style (note the use of ignoreall
1700to allow a free-form text description to be given):
1701
1702<programlisting>
1703*data passage station left right up down ignoreall
17041  0.1 2.3 8.0 1.4  Sticking out point on left wall
17052  0.0 1.9 9.0 0.5  Point on left wall
17063  1.0 0.7 9.0 0.8  Highest point of boulder
1707</programlisting>
1708</Para>
1709</listitem>
1710</VarListEntry>
1711</VariableList>
1712
1713<Para>
1714IGNORE skips a field (it may be used any number of times),
1715and IGNOREALL may be used last to ignore the rest of the data line.
1716</Para>
1717
1718<Para>
1719LENGTH is a synonym for TAPE; BEARING for COMPASS; GRADIENT for CLINO; COUNT for COUNTER.<!--FIXME : others?-->
1720</Para>
1721
1722<Para>
1723The units of each quantity may be set with the UNITS command.
1724</Para>
1725
1726<!-- FIXME: plumbed diving legs -->
1727
1728<!--FIXME:
1729<Para>
1730Uses for CYLPOLAR:
1731Perhaps a Grade 3 survey, or when surveying with a level and stick (?)
1732[note - UBSS use it for the old County Clare data]
1733</Para>
1734-->
1735
1736</listitem>
1737
1738</VarListEntry>
1739
1740</VariableList>
1741
1742</Sect3>
1743
1744<Sect3><Title>DATE</Title>
1745<VariableList>
1746
1747<VarListEntry><Term>Syntax</Term>
1748
1749<listitem><Para>*date &lt;year&gt;[.&lt;month&gt;[.&lt;day&gt;]][-&lt;year&gt;[.&lt;month&gt;[.&lt;day&gt;]]]</Para></listitem>
1750
1751</VarListEntry>
1752
1753<VarListEntry><Term>Example</Term>
1754
1755<listitem>
1756<Para>
1757<programlisting>
1758*date 2001</programlisting>
1759
1760<programlisting>
1761*date 2000.10</programlisting>
1762
1763<programlisting>
1764*date 1987.07.27</programlisting>
1765
1766<programlisting>
1767*date 1985.08.12-1985.08.13</programlisting>
1768</Para>
1769</listitem>
1770
1771</VarListEntry>
1772
1773<VarListEntry><Term>Validity</Term>
1774
1775<listitem><Para>valid at the start of a *begin/*end block.
1776</Para></listitem>
1777
1778</VarListEntry>
1779
1780<VarListEntry><Term>Description</Term>
1781
1782<listitem><Para>
1783*date specifies the date that the survey was done.  A range of dates
1784can be specified (useful for overnight or multi-day surveying trips).
1785</Para></listitem>
1786
1787</VarListEntry>
1788
1789<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1790
1791<VarListEntry><Term>See Also</Term>
1792
1793<listitem><Para>*begin, *instrument, *team</Para></listitem>
1794
1795</VarListEntry>
1796
1797</VariableList>
1798
1799</Sect3>
1800
1801<Sect3><Title>DECLINATION</Title>
1802
1803<VariableList>
1804
1805<VarListEntry><Term>Syntax</Term>
1806
1807<listitem>
1808<Para>*declination &lt;declination&gt; &lt;units&gt;</Para>
1809<Para>*declination &lt;auto&gt; &lt;x&gt; &lt;y&gt; &lt;z&gt;</Para>
1810</listitem>
1811
1812</VarListEntry>
1813
1814<VarListEntry><Term>Description</Term>
1815
1816<listitem>
1817
1818<Para>
1819This command allows the magnetic declination to be specified.  This is added to
1820compass readings to give bearings relative to true North.
1821</Para>
1822
1823<Para>
1824The first form above specifies an explicit value for the magnetic declination,
1825while the second tells cavern to use the IGRF (International Geomagnetic
1826Reference Field) model to calculate a value for the declination at the
1827specified coordinates on the date of each survey.  The coordinates are
1828interpreted as being in the current coordinate system (as set with *cs).
1829</Para>
1830
1831<Para>
1832This command was added in Survex 1.2.21 - in earlier versions you can set a
1833fixed declination value using <programlisting>*calibrate declination
1834&lt;value&gt;</programlisting> (but note that &lt;value&gt; needs to have the
1835opposite sign to that conventionally used for the declination, while this
1836command take the declination with the conventional sign.
1837</Para>
1838
1839</listitem>
1840
1841</VarListEntry>
1842
1843<VarListEntry><Term>See Also</Term>
1844
1845<listitem><Para>*calibrate</Para></listitem>
1846
1847</VarListEntry>
1848
1849</VariableList>
1850
1851</Sect3>
1852
1853<Sect3><Title>DEFAULT</Title>
1854
1855<VariableList>
1856
1857<VarListEntry><Term>Syntax</Term>
1858
1859<listitem><Para>*default &lt;settings list&gt;|all</Para></listitem>
1860
1861</VarListEntry>
1862
1863<VarListEntry><Term>Description</Term>
1864
1865<listitem><Para>
1866The valid settings are CALIBRATE, DATA, and UNITS.
1867</Para>
1868
1869<Para>
1870*default restores defaults for given settings.  This command is deprecated -
1871you should instead use: *calibrate default, *data default, *units default.
1872</Para></listitem>
1873
1874</VarListEntry>
1875
1876<VarListEntry><Term>See Also</Term>
1877
1878<listitem><Para>*calibrate, *data, *units</Para></listitem>
1879
1880</VarListEntry>
1881
1882</VariableList>
1883
1884</Sect3>
1885
1886<Sect3><Title>END</Title>
1887
1888<VariableList>
1889
1890<VarListEntry><Term>Syntax</Term>
1891
1892<listitem><Para>*end [&lt;survey&gt;]</Para></listitem>
1893
1894</VarListEntry>
1895
1896<VarListEntry><Term>Validity</Term>
1897
1898<listitem><Para>valid for closing a block started by *begin in the same file.
1899</Para></listitem>
1900
1901</VarListEntry>
1902
1903<VarListEntry><Term>Description</Term>
1904
1905<listitem><Para>
1906Closes a block started by *begin.
1907</Para></listitem>
1908
1909</VarListEntry>
1910
1911<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1912
1913<VarListEntry><Term>See Also</Term>
1914
1915<listitem><Para>*begin</Para></listitem>
1916
1917</VarListEntry>
1918
1919</VariableList>
1920
1921</Sect3>
1922
1923<Sect3><Title>ENTRANCE</Title>
1924
1925<VariableList>
1926
1927<VarListEntry><Term>Syntax</Term>
1928
1929<listitem><Para>*entrance &lt;station&gt;</Para></listitem>
1930
1931</VarListEntry>
1932
1933<VarListEntry><Term>Example</Term>
1934
1935<listitem>
1936<Para>
1937<programlisting>
1938*entrance P163</programlisting>
1939</Para>
1940</listitem>
1941
1942</VarListEntry>
1943
1944<VarListEntry><Term>Description</Term>
1945
1946<listitem><Para>
1947*entrance sets the <emphasis>entrance</emphasis> flag for a station.
1948This information is used by aven to allow entrances to be highlighted.
1949</Para>
1950
1951<!-- FIXME:
1952(could be inferred from surface/ug join, but better to specify because
1953of caves with no surf svy (or no underground survey)
1954and also situations in which multiple surveys leave through an entrance)
1955-->
1956</listitem>
1957
1958</VarListEntry>
1959
1960<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1961
1962<!-- <VarListEntry><Term>See Also</Term>
1963
1964<listitem><Para></Para></listitem>
1965
1966</VarListEntry>
1967-->
1968
1969</VariableList>
1970
1971</Sect3>
1972
1973<Sect3><Title>EQUATE</Title>
1974
1975<VariableList>
1976
1977<VarListEntry><Term>Syntax</Term>
1978
1979<listitem><Para>*equate &lt;station&gt; &lt;station&gt;...</Para></listitem>
1980
1981</VarListEntry>
1982
1983<VarListEntry><Term>Example</Term>
1984
1985<listitem>
1986<Para>
1987<programlisting>
1988*equate chosspot.1 triassic.27</programlisting>
1989</Para>
1990</listitem>
1991
1992</VarListEntry>
1993
1994<VarListEntry><Term>Description</Term>
1995
1996<listitem><Para>
1997*equate specifies that the station names in the list refer to the
1998same physical survey station. An error is given if there is only one station
1999listed.
2000</Para>
2001
2002<!-- FIXME:
2003<Para>
2004I think this is preferable to using:
2005</Para>
2006
2007<programlisting> a b 0.00   0   0</programlisting>
2008
2009<Para>
2010as EQUATE does not add in an extra position error. It is also clearer than
2011substituting in the original name wherever passages are linked. If you
2012disagree, you can always use one of the other methods!
2013</Para>
2014-->
2015</listitem>
2016
2017</VarListEntry>
2018
2019<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2020
2021<VarListEntry><Term>See Also</Term>
2022
2023<listitem><Para>*infer equates</Para></listitem>
2024
2025</VarListEntry>
2026
2027</VariableList>
2028
2029</Sect3>
2030
2031<Sect3><Title>EXPORT</Title>
2032
2033<VariableList>
2034
2035<VarListEntry><Term>Syntax</Term>
2036
2037<listitem><Para>*export &lt;station&gt;...</Para></listitem>
2038
2039</VarListEntry>
2040
2041<VarListEntry><Term>Example</Term>
2042
2043<!-- FIXME better example -->
2044<listitem>
2045<Para>
2046<programlisting>
2047*export 1 6 17</programlisting>
2048</Para>
2049</listitem>
2050
2051</VarListEntry>
2052
2053<VarListEntry><Term>Validity</Term>
2054
2055<listitem><Para>valid at the start of a *begin/*end block.
2056</Para></listitem>
2057
2058</VarListEntry>
2059
2060<VarListEntry><Term>Description</Term>
2061
2062<listitem><Para>
2063*export marks the stations named as referable to from the enclosing
2064survey.  To be able to refer to a station from a survey several levels
2065above, it must be exported from each enclosing survey.
2066</Para>
2067
2068<!-- FIXME:
2069<Para>
2070I think this is preferable to using:
2071</Para>
2072
2073<programlisting> a b 0.00   0   0</programlisting>
2074
2075<Para>
2076as EQUATE does not add in an extra position error. It is also clearer than
2077substituting in the original name wherever passages are linked. If you
2078disagree, you can always use one of the other methods!
2079</Para>
2080-->
2081</listitem>
2082
2083</VarListEntry>
2084
2085<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2086
2087<VarListEntry><Term>See Also</Term>
2088
2089<listitem><Para>*begin, *infer exports</Para></listitem>
2090
2091</VarListEntry>
2092
2093</VariableList>
2094
2095</Sect3>
2096
2097<Sect3><Title>FIX</Title>
2098
2099<VariableList>
2100
2101<VarListEntry><Term>Syntax</Term>
2102
2103<listitem><Para>*fix &lt;station&gt; [reference]
2104 [ &lt;x&gt; &lt;y&gt; &lt;z&gt;
2105   [ &lt;x std err&gt; &lt;y std err&gt; &lt;z std err&gt;
2106     [ &lt;cov(x,y)&gt; &lt;cov(y,z)&gt; &lt;cov(z,x)&gt; ] ] ]
2107</Para></listitem>
2108
2109</VarListEntry>
2110
2111<VarListEntry><Term>Example</Term>
2112
2113<listitem>
2114<Para>
2115<programlisting>
2116*fix entrance.0 32768 86723 1760</programlisting>
2117
2118<programlisting>
2119*fix KT114_96 reference 36670.37 83317.43 1903.97</programlisting>
2120</Para>
2121</listitem>
2122
2123</VarListEntry>
2124
2125<VarListEntry><Term>Description</Term>
2126
2127<listitem>
2128<Para>
2129*fix fixes the position of &lt;station&gt; at the given coordinates.
2130If you haven't specified the coordinate system with "*cs", you can
2131omit the position and it will default to (0,0,0).  The standard errors default
2132to zero (fix station exactly).  cavern will give an error if you attempt to fix
2133the same survey station twice at different coordinates, or a warning if you fix
2134it twice with matching coordinates.
2135</Para>
2136
2137<Para>
2138You can also specify just one standard error (in which case it is assumed
2139equal in X, Y, and Z) or two (in which case the first is taken as the
2140standard error in X and Y, and the second as the standard error in Z).
2141</Para>
2142
2143<Para>
2144If you have covariances for the fix, you can also specify these - the
2145order is cov(x,y) cov(y,z) cov(z,x).
2146</Para>
2147
2148<Para>
2149You can fix as many stations as you like - just use a *fix command for each
2150one.  Cavern will check that all stations are connected to
2151at least one fixed point so that co-ordinates can be calculated for all
2152stations.
2153</Para>
2154
2155<Para>
2156By default cavern will warn about stations which have been FIX-ed but
2157not used otherwise.  This is unhelpful if you want to include a
2158standard file of benchmarks, some of which won't be used.
2159In this sort of situation, specify "REFERENCE" after the station name
2160in the FIX command to suppress this warning for a particular station.
2161</Para>
2162
2163<Note><Para>
2164X is Easting, Y is Northing, and Z is altitude.  This convention was chosen
2165since on a map, the horizontal (X) axis is usually East, and the vertical
2166axis (Y) North.  The choice of altitude (rather than depth) for Z is taken
2167from surface maps, and makes for less confusion when dealing with cave
2168systems with more than one entrance.  It also gives a right-handed
2169set of axes.
2170</Para></Note>
2171
2172</listitem>
2173</VarListEntry>
2174
2175<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2176
2177<!-- <VarListEntry><Term>See Also</Term>
2178
2179<listitem><Para></Para></listitem>
2180
2181</VarListEntry>
2182-->
2183
2184</VariableList>
2185
2186</Sect3>
2187
2188<!--
2189<Sect3><Title></Title>
2190
2191<VariableList>
2192
2193<VarListEntry><Term>Syntax</Term>
2194
2195<listitem><Para>*</Para></listitem>
2196
2197</VarListEntry>
2198
2199<VarListEntry><Term>Example</Term>
2200
2201<listitem>
2202<Para>
2203<programlisting>
2204*</programlisting>
2205</Para>
2206</listitem>
2207
2208</VarListEntry>
2209
2210<VarListEntry><Term>Description</Term>
2211
2212<listitem><Para>
2213</Para></listitem>
2214
2215</VarListEntry>
2216
2217<VarListEntry><Term>Caveats </Term> </VarListEntry>
2218
2219<VarListEntry><Term>See Also</Term>
2220
2221<listitem><Para></Para></listitem>
2222
2223</VarListEntry>
2224
2225</VariableList>
2226
2227</Sect3>
2228-->
2229
2230<Sect3><Title>FLAGS</Title>
2231
2232<VariableList>
2233
2234<VarListEntry><Term>Syntax</Term>
2235
2236<listitem><Para>*flags &lt;flags&gt;</Para></listitem>
2237
2238</VarListEntry>
2239
2240<VarListEntry><Term>Example</Term>
2241
2242<listitem>
2243<Para>
2244<programlisting>
2245*flags duplicate not surface</programlisting>
2246</Para>
2247</listitem>
2248
2249</VarListEntry>
2250
2251<VarListEntry><Term>Description</Term>
2252
2253<listitem><Para>
2254*flags updates the current flag settings.
2255Flags not mentioned retain their previous state.  Valid flags
2256are DUPLICATE, SPLAY, and SURFACE, and a flag may be preceded with NOT to
2257turn it off.
2258</Para>
2259
2260<Para>
2261Survey legs marked SURFACE are hidden from plots by default, and not
2262included in cave survey length calculations.  Survey legs marked as
2263DUPLICATE or SPLAY are also not included in cave survey length
2264calculations; legs marked SPLAY are ignored by the extend program.
2265DUPLICATE is intended for the case when if you have two different
2266surveys along the same section of passage (for example to tie two
2267surveys into a permanent survey station); SPLAY is intended for
2268cases such as radial legs in a large chamber.
2269</Para>
2270</listitem>
2271
2272</VarListEntry>
2273
2274<VarListEntry><Term>See Also</Term>
2275
2276<listitem><Para>*begin</Para></listitem>
2277
2278</VarListEntry>
2279
2280</VariableList>
2281
2282</Sect3>
2283
2284<Sect3><Title>INCLUDE</Title>
2285
2286<VariableList>
2287
2288<VarListEntry><Term>Syntax</Term>
2289
2290<listitem><Para>*include &lt;filename&gt;</Para></listitem>
2291
2292</VarListEntry>
2293
2294<VarListEntry><Term>Example</Term>
2295
2296<listitem>
2297<Para>
2298<programlisting>
2299*include mission</programlisting>
2300
2301<programlisting>
2302*include "the pits"</programlisting>
2303</Para>
2304</listitem>
2305
2306</VarListEntry>
2307
2308<VarListEntry><Term>Description</Term>
2309
2310<listitem><Para>
2311*include processes &lt;filename&gt; as if it were inserted at this
2312place in the current file. (i.e. The current settings are carried
2313into &lt;filename&gt;, and any alterations to settings in &lt;filename&gt;
2314will be carried back again).  There's one exception to this (for
2315obscure historical reasons) which is that the survey prefix is
2316restored upon return to the original file.  Since *begin and *end
2317nesting cannot cross files, this can only make a difference if you
2318use the deprecated *prefix command.
2319</Para>
2320
2321<Para>If &lt;filename&gt; contains spaces, it must be enclosed in quotes.
2322</Para>
2323
2324<Para>An included file which does not have a complete path
2325is resolved relative to the directory which the parent file is in
2326(just as relative HTML links do).  Cavern will try adding a <filename>.svx</filename>
2327extension, and will also try translating "\" to "/".
2328And as a last
2329resort, it will try a lower case version of the filename (so if you
2330use Unix and someone sends you a DOS/Windows dataset with mismatched
2331case, unzip it with "unzip -L" and UNIX cavern will process it).
2332</Para>
2333
2334<Para>
2335The depth to which you can nest
2336include files may be limited by the operating system
2337you use.  Usually the limit is fairly high (>30), but if you want to be able to
2338process your dataset with <Application>Survex</Application> on any supported platform, it
2339would be prudent not to go overboard with nested include files.
2340</Para>
2341</listitem>
2342</VarListEntry>
2343
2344</VariableList>
2345
2346</Sect3>
2347
2348<Sect3><Title>INFER</Title>
2349
2350<VariableList>
2351
2352<VarListEntry><Term>Syntax</Term>
2353
2354<listitem>
2355<Para>*infer plumbs on|off</Para>
2356
2357<Para>*infer equates on|off</Para>
2358
2359<Para>*infer exports on|off</Para>
2360</listitem>
2361
2362</VarListEntry>
2363
2364<!--
2365<VarListEntry><Term>Example</Term>
2366
2367<listitem>
2368<programlisting>
2369</programlisting>
2370
2371</listitem>
2372
2373</VarListEntry>
2374-->
2375
2376<VarListEntry><Term>Description</Term>
2377
2378<listitem>
2379<Para>"*infer plumbs on" tells cavern to interpret gradients of +/- 90
2380degrees as UP/DOWN (so it
2381will not apply the clino correction to them). This is useful when
2382the data has not been converted to have UP and DOWN in it.
2383</Para>
2384
2385<para>"*infer equates on" tells cavern to interpret a leg with
2386a tape reading of zero as a *equate.  this prevents tape corrections
2387being applied to them.
2388</para>
2389
2390<para>"*infer exports on" is necessary when you have a dataset which is
2391partly annotated with *export.  It tells cavern not to complain about
2392missing *export commands in part of the dataset.  Also stations which
2393were used to join surveys are marked as exported in the 3d file.
2394</para>
2395</listitem>
2396
2397</VarListEntry>
2398
2399<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2400
2401<!--
2402<VarListEntry><Term>See Also</Term>
2403
2404<listitem><Para>*end, *prefix</Para></listitem>
2405
2406</VarListEntry>
2407-->
2408
2409</VariableList>
2410
2411</Sect3>
2412
2413<Sect3><Title>INSTRUMENT</Title>
2414
2415<VariableList>
2416
2417<VarListEntry><Term>Syntax</Term>
2418
2419<listitem><Para>*instrument &lt;instrument&gt; &lt;identifier&gt;</Para></listitem>
2420
2421</VarListEntry>
2422
2423<VarListEntry><Term>Example</Term>
2424
2425<listitem>
2426<Para>
2427<programlisting>
2428*instrument compass "CUCC 2"
2429*instrument clino "CUCC 2"
2430*instrument tape "CUCC Fisco Ranger open reel"</programlisting>
2431</Para>
2432</listitem>
2433
2434</VarListEntry>
2435
2436<VarListEntry><Term>Validity</Term>
2437
2438<listitem><Para>valid at the start of a *begin/*end block.
2439</Para></listitem>
2440
2441</VarListEntry>
2442
2443<VarListEntry><Term>Description</Term>
2444
2445<listitem><Para>
2446*instrument specifies the particular instruments used to perform a
2447survey.
2448</Para></listitem>
2449
2450</VarListEntry>
2451
2452<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2453
2454<VarListEntry><Term>See Also</Term>
2455
2456<listitem><Para>*begin, *date, *team</Para></listitem>
2457
2458</VarListEntry>
2459
2460</VariableList>
2461
2462</Sect3>
2463
2464<Sect3><Title>PREFIX</Title>
2465
2466<VariableList>
2467
2468<VarListEntry><Term>Syntax</Term>
2469
2470<listitem><Para>*prefix &lt;survey&gt;</Para></listitem>
2471
2472</VarListEntry>
2473
2474<VarListEntry><Term>Example</Term>
2475
2476<listitem>
2477<Para>
2478<programlisting>
2479*prefix flapjack</programlisting>
2480</Para>
2481</listitem>
2482
2483</VarListEntry>
2484
2485<VarListEntry><Term>Description</Term>
2486
2487<listitem><Para>
2488*prefix sets the current survey.
2489</Para></listitem>
2490
2491</VarListEntry>
2492
2493<VarListEntry><Term>Caveats </Term>
2494
2495<listitem><Para>*prefix is deprecated - you should use *begin and *end
2496instead.</Para></listitem>
2497
2498</VarListEntry>
2499
2500<VarListEntry><Term>See Also</Term>
2501
2502<listitem><Para>*begin, *end</Para></listitem>
2503
2504</VarListEntry>
2505
2506</VariableList>
2507
2508</Sect3>
2509
2510<Sect3><Title>REQUIRE</Title>
2511
2512<VariableList>
2513
2514<VarListEntry><Term>Syntax</Term>
2515
2516<listitem><Para>*require &lt;version&gt;</Para></listitem>
2517
2518</VarListEntry>
2519
2520<VarListEntry><Term>Example</Term>
2521
2522<listitem>
2523<Para>
2524<programlisting>
2525*require 0.98</programlisting>
2526</Para>
2527</listitem>
2528
2529</VarListEntry>
2530
2531<VarListEntry><Term>Description</Term>
2532
2533<listitem><Para>
2534*require checks that the version of cavern in use is at least
2535&lt;version&gt; and stops with an error if not.
2536So if your dataset requires a feature
2537introduced in a particular version, you can add a *require command and
2538users will know what version they need to upgrade to, rather than
2539getting an error message and having to guess what the real problem is.
2540</Para></listitem>
2541
2542</VarListEntry>
2543
2544</VariableList>
2545
2546</Sect3>
2547
2548<Sect3><Title>SD</Title>
2549
2550<VariableList>
2551
2552<VarListEntry><Term>Syntax</Term>
2553
2554<listitem><Para>*sd &lt;quantity list&gt; &lt;standard deviation&gt;
2555</Para></listitem>
2556
2557</VarListEntry>
2558
2559<VarListEntry><Term>Example</Term>
2560
2561<listitem>
2562<Para>
2563<programlisting>
2564*sd tape 0.15 metres</programlisting>
2565</Para>
2566</listitem>
2567
2568</VarListEntry>
2569
2570<VarListEntry><Term>Description</Term>
2571
2572<listitem><Para>
2573*sd sets the standard deviation of a measurement.
2574</Para>
2575
2576<Para>
2577&lt;quantity&gt; is one of (each group gives alternative names for the same
2578quantity):
2579</Para>
2580
2581<ItemizedList>
2582    <listitem><para>TAPE, LENGTH</para></listitem>
2583    <listitem><para>COMPASS, BEARING</para></listitem>
2584    <listitem><para>BACKCOMPASS, BACKBEARING</para></listitem>
2585    <listitem><para>CLINO, GRADIENT</para></listitem>
2586    <listitem><para>BACKCLINO, BACKGRADIENT</para></listitem>
2587    <listitem><para>COUNTER, COUNT</para></listitem>
2588    <listitem><para>DEPTH</para></listitem>
2589    <listitem><para>DECLINATION</para></listitem>
2590    <listitem><para>DX, EASTING</para></listitem>
2591    <listitem><para>DY, NORTHING</para></listitem>
2592    <listitem><para>DZ, ALTITUDE</para></listitem>
2593    <listitem><para>LEFT</para></listitem>
2594    <listitem><para>RIGHT</para></listitem>
2595    <listitem><para>UP, CEILING</para></listitem>
2596    <listitem><para>DOWN, FLOOR</para></listitem>
2597    <listitem><para>LEVEL</para></listitem>
2598    <listitem><para>PLUMB</para></listitem>
2599    <listitem><para>POSITION</para></listitem>
2600</ItemizedList>
2601
2602<Para>
2603&lt;standard deviation&gt; must include units and thus is typically
2604"0.05 metres", or "0.02 degrees". See *units below for full list
2605of valid units.
2606</Para>
2607
2608<!-- FIXME mention central limit theorem -->
2609<Para>
2610To utilise this command fully you need to understand what a
2611<emphasis>standard deviation</emphasis> is.
2612It gives a value to the 'spread' of the errors
2613in a measurement. Assuming that these are normally distributed
2614we can say that 95.44% of the actual lengths will fall within two
2615standard deviations of the measured length. i.e. a tape SD of
26160.25 metres means that the actual length of a tape measurement
2617is within + or - 0.5 metres of the recorded value 95.44% of the time.
2618So if the measurement is 7.34m then the actual length is very
2619likely to be between 6.84m and 7.84m. This example corresponds
2620to BCRA grade 3. Note that this is just one interpretation of
2621the BCRA standard, taking the permitted error values as 2SD 95.44%
2622confidence limits. If you want to take the readings as being some
2623other limit (e.g. 1SD = 68.26%) then you will need to change the BCRA3
2624and BCRA5 files accordingly. This issue is explored in more
2625detail in various surveying articles.
2626<!--
26272.565 sd 99%
26282.5   sd 98.76%
26292     sd 95.44%
26301     sd 68.26%
2631.97   sd 66.67%
26321.15  sd 75%
2633-->
2634</Para></listitem>
2635
2636</VarListEntry>
2637
2638<VarListEntry><Term>See Also</Term>
2639
2640<listitem><Para>*units</Para></listitem>
2641
2642</VarListEntry>
2643
2644</VariableList>
2645
2646</Sect3>
2647
2648<Sect3><Title>SET</Title>
2649
2650<VariableList>
2651
2652<VarListEntry><Term>Syntax</Term>
2653
2654<listitem><Para>*set &lt;item&gt; &lt;character list&gt;</Para></listitem>
2655
2656</VarListEntry>
2657
2658<VarListEntry><Term>Example</Term>
2659
2660<listitem>
2661<Para>
2662<programlisting>
2663*set blank x09x20
2664*set decimal ,</programlisting>
2665
2666Note that you need to eliminate comma from being a blank before setting it as
2667a decimal - otherwise the comma in "*set decimal ," is parsed as a blank, and
2668you set decimal to not have any characters representing it.
2669</Para>
2670</listitem>
2671
2672</VarListEntry>
2673
2674<VarListEntry><Term>Description</Term>
2675
2676<listitem><Para>
2677*set sets the specified &lt;item&gt; to the character or characters
2678given in &lt;character list&gt;. The example sets the decimal
2679separator to be a comma.
2680</Para>
2681
2682<Para>
2683xAB means the character with hex value AB. Eg x20 is a space.
2684</Para>
2685
2686<Para>
2687The complete list of items that can be set, the defaults (in
2688brackets), and the meaning of the item, is:
2689</Para>
2690
2691<ItemizedList>
2692
2693<ListItem><Para>
2694BLANK (x09x20,) Separates fields
2695</Para></ListItem>
2696
2697<ListItem><Para>
2698COMMENT (;) Introduces comments
2699</Para></ListItem>
2700
2701<ListItem><Para>
2702DECIMAL (.) Decimal point character
2703</Para></ListItem>
2704
2705<ListItem><Para>
2706EOL (x0Ax0D) End of line character
2707</Para></ListItem>
2708
2709<ListItem><Para>
2710KEYWORD (*) Introduces keywords
2711</Para></ListItem>
2712
2713<ListItem><Para>
2714MINUS (-) Indicates negative number
2715</Para></ListItem>
2716
2717<ListItem><Para>
2718NAMES (_-) Non-alphanumeric chars permitted in station
2719names (letters and numbers are always permitted).
2720</Para></ListItem>
2721
2722<ListItem><Para>
2723OMIT (-) Contents of field omitted (e.g. in plumbed legs)
2724</Para></ListItem>
2725
2726<ListItem><Para>
2727PLUS (+) Indicates positive number
2728</Para></ListItem>
2729
2730<ListItem><Para>
2731ROOT (\) Prefix in force at start of current file (use of ROOT is deprecated)
2732</Para></ListItem>
2733
2734<ListItem><Para>
2735SEPARATOR (.) Level separator in prefix hierarchy
2736</Para></ListItem>
2737
2738<!-- FIXME OPEN ({) and CLOSE (}) -->
2739</ItemizedList>
2740
2741<Para>
2742The special characters may not be alphanumeric.
2743</Para>
2744
2745</listitem>
2746
2747</VarListEntry>
2748
2749</VariableList>
2750
2751</Sect3>
2752
2753<Sect3><Title>SOLVE</Title>
2754
2755<VariableList>
2756
2757<VarListEntry><Term>Syntax</Term>
2758
2759<listitem><Para>*solve</Para></listitem>
2760
2761</VarListEntry>
2762
2763<VarListEntry><Term>Example</Term>
2764
2765<listitem>
2766<Para>
2767<programlisting>
2768*include 1997data
2769*solve
2770*include 1998data
2771</programlisting>
2772</Para>
2773</listitem>
2774
2775</VarListEntry>
2776
2777<VarListEntry><Term>Description</Term>
2778
2779<listitem><Para>
2780Distributes misclosures around any loops in the survey and fixes
2781the positions of all existing stations.  This command is intended
2782for situations where you have some new surveys adding extensions
2783to an already drawn-up survey which you wish to avoid completely
2784redrawing. You can read in the old data, use *SOLVE to fix it, and then
2785read in the new data.  Then old stations will be in the same
2786positions as they are in the existing drawn up survey, even if new loops
2787have been formed by the extensions.
2788</Para></listitem>
2789
2790</VarListEntry>
2791
2792</VariableList>
2793
2794</Sect3>
2795
2796<Sect3><Title>TEAM</Title>
2797
2798<VariableList>
2799
2800<VarListEntry><Term>Syntax</Term>
2801
2802<listitem><Para>*team &lt;person&gt; &lt;role&gt;...</Para></listitem>
2803
2804</VarListEntry>
2805
2806<VarListEntry><Term>Example</Term>
2807
2808<listitem>
2809<Para>
2810<programlisting>
2811*team "Nick Proctor" compass clino tape
2812*team "Anthony Day" notes pictures tape
2813</programlisting>
2814</Para>
2815</listitem>
2816
2817</VarListEntry>
2818
2819<VarListEntry><Term>Validity</Term>
2820
2821<listitem><Para>valid at the start of a *begin/*end block.
2822</Para></listitem>
2823<!-- FIXME valid roles are? -->
2824
2825</VarListEntry>
2826
2827<VarListEntry><Term>Description</Term>
2828
2829<listitem><Para>
2830*team specifies the people involved in a survey and what role they
2831filled during that trip.
2832</Para></listitem>
2833
2834</VarListEntry>
2835
2836<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2837
2838<VarListEntry><Term>See Also</Term>
2839
2840<listitem><Para>*begin, *date, *instrument</Para></listitem>
2841
2842</VarListEntry>
2843
2844</VariableList>
2845
2846</Sect3>
2847
2848<Sect3><Title>TITLE</Title>
2849
2850<VariableList>
2851
2852<VarListEntry><Term>Syntax</Term>
2853
2854<listitem><Para>*title &lt;title&gt;</Para></listitem>
2855
2856</VarListEntry>
2857
2858<VarListEntry><Term>Example</Term>
2859
2860<listitem>
2861<programlisting>
2862*title Dreamtime</programlisting>
2863
2864<programlisting>
2865*title "Mission Impossible"</programlisting>
2866</listitem>
2867
2868</VarListEntry>
2869
2870<VarListEntry><Term>Description</Term>
2871
2872<listitem><Para>*title allows you to set the descriptive title for a survey.
2873If the title contains spaces, you need to enclose it in quotes ("").
2874If there is no *title command, the title defaults to the survey name
2875given in the *begin command.
2876</Para>
2877</listitem>
2878
2879</VarListEntry>
2880
2881<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2882
2883<!--
2884<VarListEntry><Term>See Also</Term>
2885
2886<listitem><Para>*end, *prefix</Para></listitem>
2887
2888</VarListEntry>
2889-->
2890
2891</VariableList>
2892
2893</Sect3>
2894
2895<Sect3><Title>TRUNCATE</Title>
2896
2897<VariableList>
2898
2899<VarListEntry><Term>Syntax</Term>
2900
2901<listitem><Para>*truncate &lt;length&gt;|off</Para></listitem>
2902
2903</VarListEntry>
2904
2905<!-- FIXME:
2906<VarListEntry><Term>Example</Term>
2907
2908<listitem>
2909<programlisting>
2910</programlisting>
2911
2912</listitem>
2913
2914</VarListEntry>
2915-->
2916
2917<VarListEntry><Term>Description</Term>
2918
2919<listitem><Para>Station names may be of any length in <Application>Survex</Application>, but some
2920other (mostly older) cave surveying software only regard the first few
2921characters of a name as significant (e.g. "entran" and "entrance"
2922might be treated as the same).  To facilitate using data imported from
2923such a package <Application>Survex</Application> allows you to truncate names to whatever
2924length you want (but by default truncation is off).
2925</Para>
2926
2927<Para>Figures for the number of characters which are significant in various
2928software packages: Compass currently has a limit of 12,
2929CMAP has a limit of 6,
2930Smaps 4 had a limit of 8,
2931<!-- FIXME any limits for other software, winkarst for example? -->
2932Surveyor87/8 used 8.
2933<Application>Survex</Application> itself used 8 per prefix
2934level up to version 0.41, and 12 per prefix level up to 0.73 (more recent
2935versions removed this rather archaic restriction).
2936</Para>
2937</listitem>
2938
2939</VarListEntry>
2940
2941<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2942
2943<VarListEntry><Term>See Also</Term>
2944
2945<listitem><Para>*case</Para></listitem>
2946
2947</VarListEntry>
2948
2949</VariableList>
2950
2951</Sect3>
2952
2953<Sect3><Title>UNITS</Title>
2954
2955<VariableList>
2956
2957<VarListEntry><Term>Syntax</Term>
2958
2959<listitem><Para>
2960*units &lt;quantity list&gt; [&lt;factor&gt;] &lt;unit&gt;
2961</Para>
2962<Para>
2963*units default
2964</Para></listitem>
2965
2966</VarListEntry>
2967
2968<VarListEntry><Term>Example</Term>
2969
2970<listitem>
2971<Para>
2972<programlisting>
2973*units tape metres</programlisting>
2974
2975<programlisting>
2976*units compass backcompass clino backclino grads</programlisting>
2977
2978<programlisting>
2979*units dx dy dz 1000 metres ; data given as kilometres</programlisting>
2980
2981<programlisting>
2982*units left right up down feet</programlisting>
2983</Para>
2984</listitem>
2985
2986</VarListEntry>
2987
2988<VarListEntry><Term>Description</Term>
2989
2990<listitem><Para>
2991&lt;quantity&gt; is one of the following (grouped entries are just alternative names for the same thing):
2992TAPE/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
2993</Para>
2994
2995<Para>Changes current units of all the quantities listed to [&lt;factor&gt;]
2996&lt;unit&gt;. Note that quantities can be expressed either as
2997the instrument (e.g. COMPASS) or the measurement (e.g. BEARING).
2998</Para>
2999
3000<Para>&lt;factor&gt; allows you to easy specify situations such as measuring
3001distance with a diving line knotted every 10cm (*units distance 0.1 metres).
3002If &lt;factor&gt; is omitted it defaults to 1.0.  If specified, it must be
3003non-zero.
3004</Para>
3005
3006<Para>Valid units for listed quantities are:
3007</Para>
3008
3009<Para>TAPE/LENGTH, COUNTER/COUNT, DEPTH, DX/EASTING, DY/NORTHING, DZ/ALTITUDE
3010in YARDS|FEET|METRIC|METRES|METERS (default: METRES)
3011</Para>
3012
3013<Para>CLINO/GRADIENT, BACKCLINO/BACKGRADIENT
3014in DEG|DEGREES|GRADS|MILS|PERCENT|PERCENTAGE (default: DEGREES)
3015</Para>
3016
3017<Para>COMPASS/BEARING, BACKCOMPASS/BACKBEARING, DECLINATION
3018in DEG|DEGREES|GRADS|MILS|MINUTES (default: DEGREES)
3019</Para>
3020
3021<Para>(360 degrees = 400 grads (also known as Mils))
3022</Para>
3023</listitem>
3024
3025</VarListEntry>
3026
3027<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
3028
3029<VarListEntry><Term>See Also</Term>
3030
3031<listitem><Para>*calibrate</Para></listitem>
3032
3033</VarListEntry>
3034
3035</VariableList>
3036
3037</Sect3>
3038
3039</Sect2>
3040
3041</Sect1>
3042
3043<!-- FIXME rename to "Cookbook"? -->
3044<Sect1><Title>Contents of <filename>.svx</filename> files: How do I?</Title>
3045<?dbhtml filename="svxhowto.htm">
3046
3047<Para>
3048Here is some example <Application>Survex</Application> data (a very small cave numbered 1623/163):
3049</Para>
3050
3051<programlisting>
30522 1 26.60 222  17.5
30532 3 10.85 014   7
30542 4  7.89 254 -11
30554 5  2.98  - DOWN
30565 6  9.29 271 -28.5</programlisting>
3057
3058<Para>
3059You can vary the data ordering.  The default is:
3060</Para>
3061
3062<Para>
3063from-station to-station tape compass clino
3064</Para>
3065
3066<Para>
3067This data demonstrates a number of useful features of <Application>Survex</Application>:
3068</Para>
3069
3070<Para>
3071Legs can be measured either way round, which allows the use of
3072techniques like "leap-frogging" (which is where legs
3073alternate forwards and backwards).
3074</Para>
3075
3076<Para>
3077Also notice that there is a spur in the survey (2 to 3).  You
3078do not need to specify this specially.
3079</Para>
3080
3081<Para>
3082<Application>Survex</Application> places few restrictions on station naming (see "Survey
3083Station Names" in the previous section), so you can number the stations
3084as they were in the original survey notes.  Although not apparent from
3085this example, there is no requirement for each leg to connect to an
3086existing station.  <Application>Survex</Application> can accept data in any order, and will
3087check for connectedness once all the data has been read in.
3088</Para>
3089
3090<Para>
3091Each survey is also likely to have other information associated
3092with it, such as instrument calibrations, etc.  This has been
3093omitted from this example to keep things simple.
3094</Para>
3095
3096<Para>
3097Most caves will take more than just one survey trip to map.  Commonly
3098the numbering in each survey will begin at 1, so we need to be
3099able to tell apart stations with the same number in different
3100surveys.
3101</Para>
3102
3103<Para>
3104To accomplish this, <Application>Survex</Application> has a very flexible system of hierarchical
3105prefixes.  All you need do is give each survey a unique name or
3106number, and enter the data like so:
3107</Para>
3108
3109<programlisting>
3110*begin 163
3111*export 1
31122 1 26.60 222  17.5
31132 3 10.85 014   7
31142 4  7.89 254 -11
31154 5  2.98  - DOWN
31165 6  9.29 271 -28.5
3117*end 163</programlisting>
3118
3119<Para><Application>Survex</Application> will name the stations by attaching the current prefix.
3120In this case, the stations will be named 163.1, 163.2, etc.
3121</Para>
3122
3123<Para>We have a convention with the CUCC Austria data that the entrance survey
3124station of a cave is named P&lt;cave number&gt;, P163 in this case. We
3125can accomplish this like so:
3126</Para>
3127
3128<programlisting>
3129*equate P163 163.1
3130*entrance P163
3131*begin 163
3132*export 1
31332 1 26.60 222  17.5
31342 3 10.85 014   7
31352 4  7.89 254 -11
31364 5  2.98  - DOWN
31375 6  9.29 271 -28.5
3138*end 163</programlisting>
3139
3140<Sect2><Title>Specify surface survey data</Title>
3141
3142<Para>
3143Say you have 2 underground surveys and 2 surface ones with 2 fixed reference
3144points.  You want to mark the surface surveys so that their length isn't
3145included in length statistics, and so that Aven knows to display them
3146differently.  To do this you mark surface data with the "surface" flag
3147- this is set with "*flags surface" like so:
3148</Para>
3149
3150<programlisting>
3151; fixed reference points
3152*fix fix_a 12345 56789 1234
3153*fix fix_b 23456 67890 1111                                                     
3154                                                                               
3155; surface data (enclosed in *begin ... *end to stop the *flags command
3156; from "leaking" out)
3157*begin
3158*flags surface
3159*include surface1
3160*include surface2
3161*end                                                                           
3162                                                                               
3163; underground data
3164*include cave1
3165*include cave2</programlisting>
3166
3167<Para>
3168You might also have a survey which starts on the surface and heads into a
3169cave.  This can be easily handled too - here's an example which goes in
3170one entrance, through the cave, and out of another entrance:
3171</Para>
3172
3173<programlisting>
3174*begin BtoC
3175*title "161b to 161c"
3176*date 1990.08.06 ; trip 1990-161c-3 in 1990 logbook
3177
3178*begin
3179*flags surface
318002    01      3.09   249    -08.5
318102    03      4.13   252.5  -26
3182*end
3183
318404    03      6.00   020    +37
318504    05      3.07   329    -31
318606    05      2.67   203    -40.5
318706    07      2.20   014    +04
318807    08      2.98   032    +04
318908    09      2.73   063.5  +21
319009    10     12.35   059    +15
3191
3192*begin
3193*flags surface
319411    10      4.20   221.5  -11.5
319511    12      5.05   215    +03.5
319611    13      6.14   205    +12.5
319713    14     15.40   221    -14
3198*end
3199
3200*end BtoC</programlisting>
3201
3202<Para>
3203Note that to avoid needless complication, Survex regards each leg as
3204being either "surface" or "not surface" - if a leg spans the boundary you'll
3205have to call it one or the other.  It's good surveying practice to
3206deliberately put a station at the surface/underground interface
3207(typically the highest closed contour or drip line) so this generally
3208isn't an onerous restriction.
3209</Para>
3210
3211</Sect2>
3212
3213<Sect2><Title>Specify the ordering and type of data</Title>
3214
3215<Para>The *DATA command is used to specify the data style, and the
3216order in which the readings are given.</Para>
3217
3218</Sect2>
3219
3220<Sect2><Title>Deal with Plumbs or Legs Across Static Water</Title>
3221
3222<!-- FIXME
3223<Para>
3224They can be given
3225as +90, or -90, but as they are not usually measured with the
3226clino, but with a plumb of some sort, then it is useful to distinguish
3227them in this way so that any clino adjustment is not applied to
3228these values.
3229</Para>
3230
3231FIXME: paste in section from mail to list
3232
3233<Para>
3234Note that a similar effect can be achieved by using the "*infer plumbs" command
3235to stop clino corrections being applied to -90 and +90 clino readings.
3236</Para>
3237-->
3238
3239<Para>
3240Plumbed legs should be given using 'UP' or 'DOWN' in place of the
3241clino reading and a dash (or a different specified 'OMIT' character)
3242in place of the compass reading.  This distinguishes
3243them from legs measured with a compass and clino.  Here's an example:
3244</Para>
3245
3246<programlisting>
32471 2 21.54 - UP
32483 2 7.36 017 +17
32493 4 1.62 091 +08
32505 4 10.38 - DOWN</programlisting>
3251
3252<Para>
3253U/D or +V/-V may be used instead of UP/DOWN; the check is not case
3254sensitive.
3255</Para>
3256
3257<Para>
3258Legs surveyed across the surface of a static body of water where no
3259clino reading is taken (since the surface of the water can be assumed
3260to be flat) can be indicated by using LEVEL in place of a clino reading.
3261This prevents the clino correction being applied.  Here's an example:
3262</Para>
3263
3264<programlisting>
32651 2 11.37 190 -12
32663 2  7.36 017 LEVEL
32673 4  1.62 091 LEVEL</programlisting>
3268
3269</Sect2>
3270
3271<Sect2><Title>Specify a BCRA grade</Title>
3272
3273<Para>The *SD command can be used to specify the standard deviations of the
3274various measurements (tape, compass, clino, etc).  Examples files are
3275supplied which define BCRA Grade 3 and BCRA Grade 5 using a number of *sd
3276commands. You can use these by simply including them at the relevant point,
3277as follows:
3278</Para>
3279
3280<programlisting>
3281*begin somewhere
3282; This survey is only grade 3
3283*include grade3
32842 1 26.60 222  17.5
32852 3 10.85 014   7
3286; etc
3287*end somewhere</programlisting>
3288
3289<Para>The default values for the standard deviations are those for
3290BCRA grade 5. Note that it is good practice to keep the *include
3291Grade3 within *Begin and *End commands otherwise it will apply
3292to following survey data, which may not be what you intended.
3293</Para>
3294
3295</Sect2>
3296
3297<Sect2><Title>Specify different accuracy for a leg</Title>
3298
3299<Para>For example, suppose the tape on the plumbed leg in this survey
3300is suspected of being less accurate than the rest of the survey because
3301the length was obtained by measuring the length of the rope used to rig
3302the pitch.  We can set a higher sd for this one measurement and use a
3303*begin/*end block to make sure this setting only applies to the one
3304leg:
3305</Para>
3306
3307<programlisting>
33082 1 26.60 222  17.5
33092 3 10.85 014   7
33102 4  7.89 254 -11
3311*begin
3312; tape measurement was taken from the rope length
3313*sd tape 0.5 metres
33144 5  34.50 - DOWN
3315*end
33165 6  9.29 271 -28.5</programlisting>
3317
3318<!-- FIXME also *calibrate and *instrument? Except rope is measure with the
3319tape... -->
3320</Sect2>
3321
3322<Sect2><Title>Enter Repeated Readings</Title>
3323
3324<Para>If your survey data contains multiple versions of each leg (for example,
3325pockettopo produces such data), then provided these are adjacent to one another
3326Survex 1.2.17 and later will automatically average these and treat them as a
3327single leg.
3328</Para>
3329
3330</Sect2>
3331
3332<Sect2><Title>Enter Radiolocation Data</Title>
3333
3334<!-- FIXME comments from David Gibson here -->
3335<Para>This is done by using the *SD command to specify the appropriate
3336errors for the radiolocation `survey leg' so that the loop closure
3337algorithm knows how to distribute errors if it forms part of a loop.
3338</Para>
3339
3340<Para>The best approach for a radiolocation where the underground station
3341is vertically below the surface station is to represent it as a
3342plumbed leg, giving suitable SDs for the length and plumb angle. The
3343horizontal positioning of this is generally quite accurate, but the
3344vertical positioning may be much less well known. E.g: we have a
3345radiolocation of about 50m depth +/- 20m and horizontal accuracy of
3346+/- 8m. Over 50m the +/-8m is equivalent to an angle of 9 degrees, so
3347that is the expected plumb error. 20m is the expected error in the
3348length. To get the equivalent SD we assume that 99.74% of readings will
3349be within 3 standard deviations of the error value. Thus we divide the
3350expected errors by 3 to get the SD we should specify:
3351</Para> <!-- 3 SD? or same as BCRA3.SVX, etc -->
3352
3353<programlisting>
3354*begin
3355*sd length 6.67 metres
3356*sd plumb 3 degrees
3357surface underground 50 - down
3358*end</programlisting>
3359
3360<Para>
3361We wrap the radiolocation leg in a *begin/*end block to make
3362sure that the special *sd settings only apply to this one leg.
3363</Para>
3364
3365<Para>For more information on the expected errors from radiolocations
3366see Compass Points Issue 10, available online at
3367<ulink url="http://www.chaos.org.uk/survex/cp/CP10/CPoint10.htm">http://www.chaos.org.uk/survex/cp/CP10/CPoint10.htm</ulink>
3368</Para>
3369
3370</Sect2>
3371
3372<Sect2><Title>Enter Diving Data</Title>
3373
3374<Para>Surveys made underwater using a diver's depth gauge can be
3375processed - use the *Data command to specify that the following data
3376is of this type.
3377</Para>
3378
3379</Sect2>
3380
3381<Sect2><Title>Enter Theodolite data</Title>
3382
3383<Para>
3384Theodolite data with turned angles is not yet explicitly catered
3385for, so for now you will need to convert it into equivalent legs in
3386another style - normal or cylpolar are likely to be the best choices.
3387</Para>
3388
3389<Para>
3390If there is no vertical info in your theodolite data then you should
3391use the cylpolar style and use *sd command to specify very low
3392accuracy (high SD) in the depth so that the points will move in the
3393vertical plane as required if the end points are fixed or the survey
3394is part of a loop.
3395</Para>
3396
3397</Sect2>
3398
3399</Sect1>
3400
3401<Sect1><Title>General: How do I?</Title>
3402<?dbhtml filename="genhowto.htm">
3403
3404<Sect2><Title>Create a new survey</Title>
3405
3406<Para>You simply create a text file containing the relevant survey data,
3407using a text editor, and save it with a suitable name with a <filename>.svx</filename>
3408extension. The
3409easiest way is to look at some of the example data and use that
3410as a template. Nearly all surveys will need a bit of basic info
3411as well as the survey data itself: e.g. the date (*date), comments
3412about where, what cave, a name for the survey (using *begin and *end),
3413instrument error corrections etc. Here is a typical survey file:
3414</Para>
3415
3416<Para>All the lines starting with ';' are comments, which are ignored
3417by <Application>Survex</Application>. You can also see the use of 'DOWN' for plumbs, and
3418*calibrate tape for dealing with a tape length error (in this case
3419the end of the tape had fallen off so measurements were made from the
342020cm point).</Para>
3421
3422<programlisting>
3423*equate chaos.1 triassic.pt3.8
3424*equate chaos.2 triassic.pt3.9
3425
3426*begin chaos
3427*title "Bottomless Pit of Eternal Chaos to Redemption pitch"
3428*date 1996.07.11
3429*team "Nick Proctor" compass clino tape
3430*team "Anthony Day" notes pictures tape
3431*instrument compass "CUCC 2"
3432*instrument clino "CUCC 2"
3433;Calibration: Cairn-Rock 071 072 071,  -22 -22 -22
3434;       Rock-Cairn 252 251 252,  +21 +21 +21
3435;Calibration at 161d entrance from cairn nr entrance to
3436;prominent rock edge lower down. This is different from
3437;calibration used for thighs survey of 5 July 1996
3438
3439*export 1 2
3440
3441;Tape is 20cm too short
3442*calibrate tape +0.2
3443
34441 2 9.48 208 +08
34452 3 9.30 179 -23
34463 4 2.17 057 +09
34475 4 10.13 263 +78
34485 6 2.10 171 -73
34497 6 7.93 291 +75
3450*begin
3451*calibrate tape 0
34528 7 35.64 262 +86 ;true length measured for this leg
3453*end
34548 9 24.90 - DOWN
345510 9 8.61 031 -43
345610 11 2.53 008 -34
345711 12 2.70 286 -20
345813 12 5.36 135 +23
345914 13 1.52 119 -12
346015 14 2.00 036 +13
346116 15 2.10 103 +12
346217 16 1.40 068 -07
346317 18 1.53 285 -42
346419 18 5.20 057 -36
346519 20 2.41 161 -67
346620 21 27.47 - DOWN
346721 22 9.30 192 -29
3468*end chaos</programlisting>
3469
3470</Sect2>
3471
3472<Sect2><Title>Join surveys together</Title>
3473
3474<Para>Once you have more than one survey you need to specify how they
3475link together. To do this use *export to make the stations to be
3476joined accessible in the enclosing survey, then *equate in the
3477enclosing survey to join them together.
3478<!-- FIXME example -->
3479</Para>
3480
3481</Sect2>
3482
3483<Sect2><Title>Organise my surveys</Title>
3484
3485<Para>This is actually a large subject. There are many ways you can
3486organise your data using <Application>Survex</Application>. Take a look at the example dataset
3487for some ideas of ways to go about it.
3488</Para>
3489
3490<Sect3><Title>Fixed Points (Control Points)</Title>
3491
3492<Para>The *fix command is used to specify fixed points (also know as control
3493points).  See the description of this command in the "Cavern Commands"
3494section of this manual.
3495</Para>
3496
3497</Sect3>
3498
3499<Sect3><Title>More than one survey per trip</Title>
3500
3501<Para>Suppose you have two separate bits of surveying which were done on the
3502same trip.  So the calibration details, etc. are the same for both.  But you
3503want to give a different survey name to the two sections.  This is easily
3504achieved like so:
3505</Para>
3506
3507<programlisting>
3508*begin
3509*calibrate compass 1.0
3510*calibrate clino 0.5
3511*begin altroute
3512; first survey
3513*end altroute
3514*begin faraway
3515; second survey
3516*end faraway
3517*end</programlisting>
3518
3519</Sect3>
3520
3521</Sect2>
3522
3523<Sect2><Title>Add surface topography</Title>
3524
3525<Para>Survex 1.2.18 added support for loading terrain data and rendering it as
3526a transparent surface.
3527</Para>
3528
3529<Para>
3530We recommend using this new code in preference, but previously the simplest
3531approach was to generate a <filename>.svx</filename> file with the surface mesh
3532in and display it with the survey data.
3533</Para>
3534
3535<Para>
3536It is possible to generate
3537a mesh or contours overlaying your area by various means.  NASA have made
35381 arc-second (approximately 30m) terrain data available for the USA for
3539some years, with only 3 arc-second data available for other countries.
3540However, starting in 2014 they're gradually making 1 arc-second data
3541available for more countries.
3542</Para>
3543
3544<Para>
3545If you want a better resolution that this, reading heights from the
3546contours on a map is one approach.  It's laborious, but feasible for
3547a small area.
3548</Para>
3549
3550<Para>
3551Details of several methods are given in the BCRA Cave Surveying
3552Group magazine Compass Points issue 11, available online at
3553<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>
3554</Para>
3555
3556<Para>If you're using another program to generate a <filename>.svx</filename> file for the surface
3557mesh, it's best to use the NOSURVEY data style.
3558Simply fix all the grid intersections at the correct
3559coordinates and height, and put legs between them using the NOSURVEY style.
3560Here's a grid of 4 squares and 9 intersections:
3561</Para>
3562
3563<programlisting>
3564*fix 00 000 000 1070
3565*fix 01 000 100 1089
3566*fix 02 000 200 1093
3567
3568*fix 10 100 000 1062
3569*fix 11 100 100 1080
3570*fix 12 100 200 1089
3571
3572*fix 20 200 000 1050
3573*fix 21 200 100 1065
3574*fix 22 200 200 1077
3575
3576*data nosurvey station
3577
357800
357901
358002
3581
358210
358311
358412
3585
358620
358721
358822
3589
359000
359110
359220
3593
359401
359511
359621
3597
359802
359912
360022</programlisting>
3601
3602<Para>
3603This is far simpler than trying to create fake tape/compass/clino legs of
3604the right length for each line in the mesh.  It's also very fast to process
3605with cavern.
3606</Para>
3607
3608</Sect2>
3609
3610<Sect2><Title>Overlay a grid</Title>
3611
3612<Para>Aven is able to display a grid, but this functionality isn't currently
3613available in printouts.
3614You can achieve a similar effect for now by creating a <filename>.svx</filename> file
3615where the survey legs form a grid.
3616</Para>
3617
3618</Sect2>
3619
3620<Sect2><Title>Import data from other programs</Title>
3621
3622<Para><Application>Survex</Application> supports a number of features to help with importing
3623existing data. You can specify the ordering of items on a line using *Data
3624(see <Application>Survex</Application> Keywords above), and you can specify the characters used
3625to mean different things using *Set (see <Application>Survex</Application> Keywords above).
3626</Para>
3627
3628<Para>The Ignore and Ignoreall options to the *Data command are often
3629particularly useful, e.g. if you have a dataset with LRUD info or comments
3630on the ends of lines.
3631</Para>
3632
3633<Sect3><Title>Changing Meanings of Characters</Title>
3634
3635<Para>e.g. if you have some data with station names containing the
3636characters '?' and '+' (which are not permitted in a name by default)
3637then the command:
3638</Para>
3639
3640<programlisting>
3641*SET NAMES ?+</programlisting>
3642
3643<Para>
3644specifies that question marks and plus signs are permitted in station names.
3645A-Z, a-z, and 0-9 are always permitted. '_' and '-' are also permitted by
3646default, but aren't in this example.
3647</Para>
3648
3649<Para>If your data uses a comma ',' instead of a decimal point, then
3650you use
3651</Para>
3652
3653<programlisting>
3654*SET DECIMAL ,</programlisting>
3655
3656<Para>to specify that ',' is now the decimal separator instead of '.'.
3657</Para>
3658
3659<!-- FIXME
3660<Para>Note that there are plenty of ways you can use this facility to
3661completely confuse the software, as it may not be able to work out what is
3662going on, or it may simply be ambiguous. It can cope with some ambiguity (e.g.
3663the '-' character is used both for 'MINUS' and for 'OMIT'), but there are
3664limits. If you have a dataset that you can not make <Application>Survex</Application>
3665understand, then send it to us, and we will see what can be done.
3666</Para>
3667-->
3668
3669</Sect3>
3670
3671<!--
3672 Nobody seems to have the CfH convertor...
3673 but it's probably no longer useful anyway
3674
3675<Sect3><Title>Other Converters</Title>
3676
3677<Para>We have an Excel 5 macro for converting The Lotus 123 spreadsheets
3678used by the German survey software Cad F&uuml;r H&ouml;hlen into
3679<Application>Survex</Application> data files. Other converters may also come to be available.
3680These will normally be available via the
3681<ulink url="http://survex.com/"><Application>Survex</Application> Web pages</ulink>.
3682</Para>
3683
3684</Sect3>
3685-->
3686
3687</Sect2>
3688
3689<Sect2><Title>Export data from <Application>Survex</Application></Title>
3690
3691<Para>See Rosetta Stal in the Related Tools section of the Survex web
3692site.  This is a utility written by Taco van Ieperen and Gary Petrie.
3693Note though that this only supports a subset of the svx format,
3694and only work on Microsoft Windows.  The Survex support is limited
3695and doesn't understand the more recently added commands.</Para>
3696
3697</Sect2>
3698
3699<Sect2><Title>See errors and warnings that have gone off the screen</Title>
3700
3701<Para>When you run <Application>Survex</Application> it will process the specified survey data
3702files in order, reporting any warnings and errors.  If there are no
3703errors, the output files are written and various statistics about the
3704survey are displayed. If there are a lot of warnings or errors, they can
3705scroll off the screen and it's not always possible to scroll back to
3706read them.
3707</Para>
3708
3709<Para>The easiest way to see all the text is to use <command>cavern
3710--log</command> to redirect output to a <filename>.log</filename> file,
3711which you can then inspect with a text editor.
3712</Para>
3713
3714<!-- <command>cavern cavename &gt; tmpfile</command> -->
3715
3716</Sect2>
3717
3718<Sect2><Title>Create an Extended Elevation</Title>
3719
3720<Para>Use the Extend program. This takes <filename>.3d</filename> files and
3721'flattens' them.  See 'Extend' for details.
3722</Para>
3723
3724</Sect2>
3725
3726</Sect1>
3727
3728<!--
3729<Sect1><Title>Appendices</Title>
3730<?dbhtml filename="appendix.htm">
3731
3732<Para>Files provided
3733</Para>
3734
3735<Para>Command specification
3736</Para>
3737
3738</Sect1>
3739-->
3740<Sect1><Title>Working with Larry Fish's Compass</Title>
3741<?dbhtml filename="compass.htm">
3742
3743<Para>
3744Survex can read Compass survey data - both raw data (.DAT and .MAK
3745files) and processed survey data (.PLT and .PLF files).  You can even
3746use <command>*include compassfile.dat</command> in a <filename>.svx</filename> file and
3747it'll work!
3748</Para>
3749
3750<Para>
3751One point to note (this tripped us up!): station names in DAT files are
3752case sensitive and so Survex reads DAT files with the equivalent of
3753<command>*case preserve</command>.  The default in SVX files is
3754<command>*case lower</command>.  So this won't work:
3755
3756<programlisting>
3757*fix CE1 0 0 0
3758*include datfilewhichusesCE1.dat</programlisting>
3759
3760Because the CE1 in the *fix is actually interpreted as ce1.  This is
3761what you have to do:
3762
3763<programlisting>
3764*begin
3765*case preserve
3766*fix CE1 0 0 0
3767*include datfilewhichusesCE1.dat
3768*end</programlisting>
3769</Para>
3770
3771</Sect1>
3772
3773<Sect1><Title>Mailing List</Title>
3774<?dbhtml filename="maillist.htm">
3775
3776<Para>The best way to contact the authors and other Survex users is the
3777Survex mailing list - for details visit:
3778<ulink url="http://survex.com/maillist.html">http://survex.com/maillist.html</ulink>
3779</Para>
3780
3781<Para>We'd be delighted to hear how you get on with <Application>Survex</Application> and
3782welcome comments and suggestions for improvements.</Para>
3783
3784<Para>
3785And we'd love you to contribute your skills to help make <Application>Survex</Application> even
3786better.  Point out areas of the documentation which could be made clearer, or
3787sections which are missing entirely.  Download test releases, try them out, and
3788let us know if you find problems or have suggestions for improvements.
3789If there's no translation to your language, you could provide one.
3790Or if your a developer, <emphasis>"Say it with code"</emphasis>.  There's
3791plenty to do, so feel free to join in.
3792</Para>
3793
3794</Sect1>
3795
3796<Sect1><Title>Future Developments</Title>
3797<?dbhtml filename="future.htm">
3798
3799<Para>
3800Now that <Application>Survex</Application> has reached version 1.0, we are continuing progress
3801towards version 2, in a series of steps, evolving out of
3802Survex 1.0.  The GUI framework is being based on aven, with
3803the printer drivers and other utility programs being pulled in
3804and integrated into the menus.</Para>
3805
3806<Para>Aven is built on <Application>wxWidgets</Application>, which means that it can easily support
3807Unix, Microsoft Windows, and Mac OS X.</Para>
3808
3809<Para>More information on our plans is on the <ulink
3810url="http://survex.com/">web site</ulink>.
3811</Para>
3812
3813</Sect1>
3814
3815</article>
Note: See TracBrowser for help on using the repository browser.