source: git/doc/manual.sgml @ 513935e

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

Document grid convergence

And improve discussion of magnetic declination

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