source: git/doc/manual.sgml @ f584e56

RELEASE/1.2debug-cidebug-ci-sanitiserswalls-data debian/1.2.39-1
Last change on this file since f584e56 was 9fe70e44, checked in by Olly Betts <olly@…>, 5 years ago

Update for 1.2.39

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