source: git/doc/manual.sgml @ 040c02e

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

Update for 1.2.42

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