source: git/doc/manual.sgml @ ce92903

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

doc/manual.sgml: Fix bugs in the markup.

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