source: git/doc/manual.sgml @ 9f4264a

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

Update manual for 1.2.26

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