source: git/doc/manual.sgml @ 5cc4a99

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

Fix *declination syntax synopsis

"auto" is a literal string, not a placeholder.

  • Property mode set to 100644
File size: 110.0 KB
RevLine 
[e6aa3b1]1<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
[ce92903]2<!ENTITY man.aven SYSTEM "aven.sgml">
3<!ENTITY man.cavern SYSTEM "cavern.sgml">
4<!ENTITY man.diffpos SYSTEM "diffpos.sgml">
[eda91a1]5<!ENTITY man.dump3d SYSTEM "dump3d.sgml">
[ce92903]6<!ENTITY man.extend SYSTEM "extend.sgml">
7<!ENTITY man.sorterr SYSTEM "sorterr.sgml">
[79b32a95]8<!ENTITY man.survexport SYSTEM "survexport.sgml">
[40647f5]9]>
[6eadc5b]10
[6aef4f1]11<!--
[a6d094f]12FIXME:
[2463f16]13
[e74904e]143dfile title:
[6af6d51]15defaults to a list of the leafnames of the <filename>.svx</filename> files specified on the
[e74904e]16command line (with any paths and extensions removed).
[f9dc4a0]17.
[e74904e]18e.g.: cavern entrance.svx \data\2ndpart.svx
[f9dc4a0]19.
[e74904e]20would give a surveytitle of 'entrance 2ndpart'.
[f9dc4a0]21.
22but this may change...
[e74904e]23
[6aef4f1]24FIXME todo:
[c1573d8]25mark-up of Windows Windows NT etc?
[6aef4f1]26section on "design philosophy"
[3b5acb5]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
[64d37a3]38``Quick start'' section
39
40- install (by OS): unpacking, configuration (language, where support files live)
41
42- lead people through entering and processing
[3162ed8]43a sample survey.  Take examples from surveying books and real surveys.
44
[0706076]45
[e6aa3b1]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
[a6d094f]60<Para>*FIX is for fixing control points - for example:
[e6aa3b1]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
[21c226e]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
[6aef4f1]81-->
82
[ce92903]83<article Status="draft" id="index">
[6eadc5b]84 <articleinfo>
[66b555d]85  <Title><Application>Survex</Application> <!--VERSION-->1.2.38 Manual</Title>
[40647f5]86  <AuthorGroup>
87   <Author>
[38335b7]88    <FirstName>Olly</FirstName>
89    <SurName>Betts</SurName>
[40647f5]90    <AuthorBlurb><Para>
[6af6d51]91      Olly Betts wrote most of <Application>Survex</Application>.
[40647f5]92    </Para></AuthorBlurb>
[fbc41c2]93    <Affiliation>
[6af6d51]94     <Address><Email>olly@survex.com</Email></Address>
[fbc41c2]95    </Affiliation>
[40647f5]96   </Author>
97   <Author>
[38335b7]98    <SurName>Wookey</SurName>
[40647f5]99    <AuthorBlurb><Para>
[fbc41c2]100      Wookey is a small furry creature.
[40647f5]101    </Para></AuthorBlurb>
[fbc41c2]102    <Affiliation>
[6af6d51]103     <Address><Email>wookey@survex.com</Email></Address>
[fbc41c2]104    </Affiliation>
[40647f5]105   </Author>
106  </AuthorGroup>
[fbc41c2]107  <copyright>
[66d93d5]108   <year>1998-2018</year>
[6af6d51]109   <holder role="mailto:olly@survex.com">Olly Betts</holder>
[fbc41c2]110  </copyright>
[40647f5]111  <Abstract>
112   <Para>
[6af6d51]113    This is the manual for <Application>Survex</Application> - an open-source software package for
[40647f5]114    cave surveyors.
[c1573d8]115   </Para>
[40647f5]116  </Abstract>
[6eadc5b]117 </articleinfo>
[40647f5]118
[c1573d8]119<Sect1><Title>Introduction</Title>
[0d62afe]120<?dbhtml filename="intro.htm">
[40647f5]121
[21c226e]122<Para>
[6af6d51]123This section describes what <Application>Survex</Application> is, and outlines the scope of this
[21c226e]124manual.
125</Para>
126
[6af6d51]127<Sect2><Title>About <Application>Survex</Application></Title>
[21c226e]128
[6af6d51]129<Para><Application>Survex</Application> is a multi-platform open-source cave surveying
[6e420ba]130package.
[aa3ed76]131Version 1.2 runs on UNIX, Microsoft Windows, and Mac OS X.
132We're investigating support for phones and tablets.
[a6d094f]133</Para>
[40647f5]134
[c1573d8]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
[6af6d51]137computers used are donated.  We aim to ensure that <Application>Survex</Application> is
[57a5ebb]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
[6af6d51]141if you use <Application>Survex</Application> on a slow machine.</Para>
[6aef4f1]142
[6af6d51]143<Para><Application>Survex</Application> is capable of processing extremely complex caves very
[c1eff09]144quickly and has a very effective, real-time cave viewer which allows
[0706076]145you to rotate, zoom, and pan the cave using mouse or keyboard. We have
[6af6d51]146tested it extensively using <Acronym>CUCC</Acronym> and <Acronym>ARGE</Acronym>'s surveys of the caves
[1352bb9]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
[a3f8737]14910 seconds on a low-end netbook.
[0706076]150Survex is also used by many other survey projects around the world,
[c2832c8]151including the
[27b8b59]152<ulink url="http://www.oucc.org.uk/draenen/draenenmain.htm"
[c2832c8]153>Ogof Draenen</ulink> survey, the
154<ulink url="http://www.easegill.org.uk/">Easegill</ulink> resurvey project,
[38335b7]155the <Acronym>OFD</Acronym> survey, the
[27b8b59]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"
[38335b7]158><Acronym>OUCC</Acronym> Picos expeditions</ulink>, and the
[27b8b59]159<ulink url="http://www.hongmeigui.net/">Hong Meigui China
[21c226e]160expeditions</ulink>. <!-- FIXME more? --></Para>
[0706076]161
[6af6d51]162<Para><Application>Survex</Application> is still actively being worked on.  Version 1.0 was
[21c226e]163complete in some sense, but development continues - initially in reshaping
[0706076]164Survex into a more integrated GUI package.</Para>
[6aef4f1]165
[c1573d8]166<Para>We encourage feedback from users on important features or problems,
[77a3d7a]167which will help to direct future development.  See the "Mailing List" section
168of this manual for the best way to contact us.</Para>
[21c226e]169
170</Sect2>
[40647f5]171
[0706076]172<!--
[6af6d51]173<Para>Because <Application>Survex</Application> is still being actively developed, this document
[fbc41c2]174has an unfortunate tendency to lag slightly behind the capabilities of the
175software. The latest version is now available on the web at <ulink
[d417499]176url="https://survex.com/">https://survex.com/</ulink> - check there for latest info.
[c1573d8]177</Para>
[0706076]178-->
[647407d]179
[c359bfd]180<!--
[647407d]181<Sect2><Title>Other Documentation</Title>
182
[e6aa3b1]183<variablelist>
184<varlistentry>
185<term>NEWS or NEWS.txt</term>
186<listitem><Para>a list of changes of interest to
[6af6d51]187<Application>Survex</Application> users, broken down by version number.  Consult this file
[c1eff09]188when upgrading to find out what has changed since the version you were
189using previously.
[e6aa3b1]190</Para></listitem>
191</varlistentry>
[647407d]192
[e6aa3b1]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>
[647407d]199
[e6aa3b1]200<varlistentry>
201<term>BUGS or BUGS.txt</term>
202<listitem><Para>a list of known bugs.
203</Para></listitem>
204</varlistentry>
[647407d]205
[e6aa3b1]206<varlistentry>
207<term>TODO or TODO.txt</term>
208<listitem><Para>planned changes and enhancements.
209</Para></listitem>
210</varlistentry>
[647407d]211
[6eadc5b]212FIXME: merge INSTALL* into here, then process separately and textify
213to produce INSTALL*
214
[e6aa3b1]215<varlistentry>
216<term>INSTALL or INSTALL.txt</term>
[6af6d51]217<listitem><Para>instructions for installing <Application>Survex</Application>.  The
[23d2a0e]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).
[e6aa3b1]221</Para></listitem>
222</varlistentry>
223</variablelist>
[ff003b3]224
[647407d]225</Sect2>
[c359bfd]226-->
[647407d]227
[21c226e]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
[d417499]247url="https://survex.com/docs.html">the Survex website</ulink>.
[21c226e]248</Para>
249
250<Sect3><Title>Terminology</Title>
[e6aa3b1]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
[21c226e]273</Sect3>
274
[e6aa3b1]275</Sect2>
276
[21c226e]277<!-- FIXME: Further sources of info: website, mailing lists, other docs -->
278
[e189be2]279</Sect1>
[40647f5]280
[c1573d8]281<Sect1><Title>Getting Started</Title>
[0d62afe]282<?dbhtml filename="getstart.htm">
[40647f5]283
[c1573d8]284<Para>This section covers how to obtain the software, and how to unpack and
[6eadc5b]285install it, and how to configure it.</Para>
[40647f5]286
[6af6d51]287<Sect2><Title>Obtaining <Application>Survex</Application></Title>
[c1573d8]288
[6af6d51]289<Para>The latest version is available from the <Application>Survex</Application> website:
[d417499]290<ulink url="https://survex.com/">https://survex.com/</ulink>.  It is also
[77a3d7a]291freely redistributable, so you welcome to get a copy from someone else
292who has already downloaded it.</Para>
[21c226e]293
[3d56564]294<Para>If you want some sample data to experiment with, you can download some
295from the Survex website too:
[d417499]296<ulink url="https://survex.com/software/sample.tar.gz">https://survex.com/software/sample.tar.gz</ulink></Para>
[3d56564]297
[6eadc5b]298</Sect2>
299
[6af6d51]300<Sect2><Title>Installing <Application>Survex</Application></Title>
[6eadc5b]301
[c1573d8]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
[6af6d51]305<Sect3><Title>Linux</Title>
[c1573d8]306
[229c6ca]307<Para>
[6af6d51]308We supply pre-compiled versions for x86 Linux machines in RPM format
[558779a]309(suitable for Redhat, Mandrake, and some other distributions).
310Survex Debian packages are available from Debian mirror sites in
311the usual way.
[229c6ca]312</Para>
313
[e6aa3b1]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
[b462168]320<!-- FIXME Add Gnome file association note for Linux/Unix
[6af6d51]321<Para>On Microsoft Windows, <Application>Survex</Application> installs with
[b462168]322suitable file associations so that you can drive it from the GUI.
[6af6d51]323On UNIX you need to drive <Application>Survex</Application> from a command-line
[b462168]324prompt (or set some a filemanager or graphics shell).
325</Para>
326-->
327
[ce92903]328</Sect3>
329
[6af6d51]330<Sect3><Title>Other versions of UNIX</Title>
[0706076]331
[6af6d51]332<Para>For other UNIX versions you'll need to get the source code
[7a0710c]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.
[229c6ca]336</Para>
[6e0ec04]337
[e189be2]338</Sect3>
[c1573d8]339
[aa3ed76]340<Sect3><Title>Microsoft Windows</Title>
[c1573d8]341
[3162ed8]342<Para>
[a6d094f]343This version comes packaged with an installation wizard.  Just
[eb48e2b]344run the downloaded package and it will lead you through the
[aa3ed76]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.
[3162ed8]348</Para>
[c1573d8]349
[3162ed8]350<Para>
[aa3ed76]351The survey viewer that's part of <Application>Survex</Application> is called
352aven, and uses OpenGL for 3d rendering.
[b4b840a]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.
[3b5acb5]360</Para>
[c1573d8]361
[1b92879]362<Para>
363The installer creates a Survex group in the Programs sub-menu of the
364Start menu containing the following items:
[3162ed8]365</Para>
366
367<ItemizedList>
[9e507547]368
[3162ed8]369<ListItem><Para>Aven</Para></ListItem>
370
[1b92879]371<ListItem><Para>Documentation</Para></ListItem>
[3162ed8]372
373<ListItem><Para>Uninstall Survex</Para></ListItem>
374
375</ItemizedList>
376
377<Para>
[6af6d51]378Icons are installed for <filename>.svx</filename>, <filename>.3d</filename>, <filename>.err</filename>, and <filename>.pos</filename> files, and also for
[eb48e2b]379Compass Plot files (<filename>.plt</filename> and <filename>.plf</filename>)
380(which Survex can read). <!-- FIXME XYZ -->
[6af6d51]381Double-clicking on a <filename>.svx</filename> file loads it for editing.  To process it to
[ff0494f]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.
[6af6d51]385All the <Application>Survex</Application> file types can be right clicked on to give a menu of
[b4b840a]386possible actions. 
[3162ed8]387</Para>
388
[c460f15]389<VariableList>
[6af6d51]390<VarListEntry><Term><filename>.svx</filename></Term>
[c460f15]391<ListItem>
392  <VariableList>
393  <VarListEntry><Term>Process</Term>
394  <ListItem><Para>
[76debf4]395  Process file with aven to produce <filename>.3d</filename> file (and <filename>.err</filename> file)
[c460f15]396  </Para></ListItem>
397  </VarListEntry>
398  </VariableList>
399</ListItem>
400</VarListEntry>
401   
[6af6d51]402<VarListEntry><Term><filename>.3d</filename></Term>
[c460f15]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>
[ff0494f]412  Print the file via Aven
[c460f15]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>
[ff0494f]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.
[c460f15]426  </Para></ListItem>
427  </VarListEntry>
428  <VarListEntry><Term>Convert for hand plotting</Term>
429  <ListItem><Para>
[ff0494f]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.
[c460f15]434  </Para></ListItem>
435  </VarListEntry>
436  </VariableList>
437</ListItem>
[ce92903]438</VarListEntry>
[c460f15]439
[6af6d51]440<VarListEntry><Term><filename>.err</filename></Term>
[c460f15]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>
[6af6d51]450  Sort <filename>.err</filename> file by the error in each traverse
[c460f15]451  </Para></ListItem>
452  </VarListEntry>
453  <VarListEntry><Term>Sort by Horizontal Error</Term>
454  <ListItem><Para>
[6af6d51]455  Sort <filename>.err</filename> file by the horizontal error in each traverse
[c460f15]456  </Para></ListItem>
457  </VarListEntry>
458  <VarListEntry><Term>Sort by Vertical Error</Term>
459  <ListItem><Para>
[6af6d51]460  Sort <filename>.err</filename> file by the vertical error in each traverse
[c460f15]461  </Para></ListItem>
462  </VarListEntry>
463  <VarListEntry><Term>Sort by Percentage Error</Term>
464  <ListItem><Para>
[6af6d51]465  Sort <filename>.err</filename> file by the percentage error in each traverse
[c460f15]466  </Para></ListItem>
467  </VarListEntry>
468  <VarListEntry><Term>Sort by Error per Leg</Term>
469  <ListItem><Para>
[6af6d51]470  Sort <filename>.err</filename> file by the error per leg in each traverse
[c460f15]471  </Para></ListItem>
472  </VarListEntry>
473  </VariableList>
474</ListItem>
475</VarListEntry>
476</VariableList>
[3162ed8]477
[67fffdf]478</Sect3>
[9e507547]479
[e189be2]480</Sect2>
[40647f5]481
[6eadc5b]482<Sect2><Title>Configuration</Title>
[375f7f6]483
[63dc4eb]484<Sect3><Title>Selecting Your Preferred Language</Title>
[e189be2]485
[e6aa3b1]486<Para>Survex has extensive internationalisation capabilities.  The
[1b92879]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
[6af6d51]491<systemitem>LANG</systemitem> environment variable on UNIX
[6e420ba]492If no setting
[6af6d51]493is found, or <Application>Survex</Application> hasn't been translated into the
[1b92879]494requested language, UK English is used.</Para>
[40647f5]495
[e6aa3b1]496<Para>
[1b92879]497However you may want to override the language manually -
498for example if Survex isn't available in your native language
[63dc4eb]499you'll want to choose the supported language you understand best.
[e6aa3b1]500</Para>
[40647f5]501
[e6aa3b1]502<Para>
503To do this, you set the
504<systemitem>SURVEXLANG</systemitem> environment variable.  Here's a list
[63dc4eb]505of the codes currently supported:</Para>
[40647f5]506
[e6aa3b1]507<informaltable frame="all">
[c1573d8]508<tgroup cols="2">
509<thead>
[38335b7]510<row><entry>Code</entry><entry>Language</entry></row>
[c1573d8]511</thead>
512<tbody>
[38335b7]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>
[c1573d8]532</tbody>
[e189be2]533</tgroup>
[c1573d8]534</informaltable>
[40647f5]535
[e6aa3b1]536<Para>Here are examples of how to set this environment variable to give
537messages in French (language code fr):</Para>
[40647f5]538
539<VariableList>
[d7b3fd3]540 <VarListEntry><Term>Microsoft Windows</Term>
541   <ListItem><Para>
[aa3ed76]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
[af1e622]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.
[d7b3fd3]549   </Para></ListItem>
[40647f5]550 </VarListEntry>
[6af6d51]551 <VarListEntry><Term>UNIX - csh/tcsh</Term>
[e6aa3b1]552   <ListItem><Para><userinput>setenv SURVEXLANG fr</userinput></Para></ListItem>
[40647f5]553 </VarListEntry>
[6af6d51]554 <VarListEntry><Term>UNIX - sh/bash</Term>
[e6aa3b1]555   <ListItem><Para><userinput>SURVEXLANG=fr ; export SURVEXLANG</userinput></Para></ListItem>
[40647f5]556 </VarListEntry>
557</VariableList>
558
[6af6d51]559<Para>If <Application>Survex</Application> isn't available in your language, you could
[e6aa3b1]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>
[40647f5]564
[6eadc5b]565</Sect3>
566
[1a50c3c]567</Sect2>
568
[e189be2]569</Sect1>
570
[6eadc5b]571<!-- FIXME
572
573type in .svx file
574
[4e8d288]575run cavern (through aven)
[6eadc5b]576
[6e420ba]577run aven
[6eadc5b]578
[4e8d288]579how to print/export etc
[6eadc5b]580
581-->
582
[eb48e2b]583<!-- FIXME perhaps move this after data files section? -->
[6eadc5b]584<Sect1><Title>Survex Programs</Title>
[0d62afe]585<?dbhtml filename="cmdline.htm">
[51c0677]586
[6eadc5b]587<Sect2><Title>Standard Options</Title>
[51c0677]588
[6af6d51]589<Para>All <Application>Survex</Application> programs respond to the following command line options:
[e189be2]590</Para>
[51c0677]591
592<VariableList>
593
594<VarListEntry><Term>--help</Term><listitem><Para>
[6eadc5b]595display option summary and exit
[51c0677]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
[6eadc5b]604</Sect2>
605
606<Sect2><Title>Short and Long Options</Title>
607
[e6aa3b1]608<Para>
609Options have two forms: short (a dash followed by a single letter e.g.
[21904d3]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
[e6aa3b1]612remember, while the short form is quicker to type.  Options are often
613available in both forms.
[e189be2]614</Para>
[51c0677]615
[e6aa3b1]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
[6af6d51]619norm on UNIX).
[e6aa3b1]620</Para></Note>
[6eadc5b]621</Sect2>
[40647f5]622
[6eadc5b]623<Sect2><Title>Filenames on the Command Line</Title>
[40647f5]624
[e6aa3b1]625<Para>Filenames with spaces can be processed (provided your operating system
[ff0494f]626supports them - UNIX does, and so do modern versions of Microsoft
[e6aa3b1]627Windows).  You need to enclose the filename in quotes like so:
628<userinput>cavern "Spider Cave"</userinput>
629</Para>
[e189be2]630
[6af6d51]631<Para>A file specified on the command line of any of the <Application>Survex</Application> suite
[6eadc5b]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>.
[1a50c3c]636</Para>
[40647f5]637
[e189be2]638</Sect2>
639
[6eadc5b]640<Sect2><title>Command Reference</title>
[e189be2]641
[6eadc5b]642<refentry id="cavern">
[0d62afe]643<?dbhtml filename="cavern.htm">
[6eadc5b]644&man.cavern;
645</refentry>
[27b8b59]646<refentry id="aven">
[0d62afe]647<?dbhtml filename="aven.htm">
[27b8b59]648&man.aven;
649</refentry>
[6eadc5b]650<refentry id="diffpos">
[0d62afe]651<?dbhtml filename="diffpos.htm">
[6eadc5b]652&man.diffpos;
653</refentry>
654<refentry id="extend">
[0d62afe]655<?dbhtml filename="extend.htm">
[6eadc5b]656&man.extend;
657</refentry>
658<refentry id="sorterr">
[0d62afe]659<?dbhtml filename="sorterr.htm">
[6eadc5b]660&man.sorterr;
661</refentry>
[79b32a95]662<refentry id="survexport">
663<?dbhtml filename="survexport.htm">
664&man.survexport;
665</refentry>
[e189be2]666
667</Sect2>
[40647f5]668
[e189be2]669</Sect1>
670
[6af6d51]671<Sect1><Title><Application>Survex</Application> data files</Title>
[0d62afe]672<?dbhtml filename="datafile.htm">
[c1573d8]673
[ff003b3]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
[1a50c3c]676writing a plain ASCII text file. The data format is very flexible;
[eb48e2b]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
[1a50c3c]680your data much as it appears on the survey notes, which is important
[eb48e2b]681in reducing the opportunities for transcription errors.
[1a50c3c]682</Para>
683
[191536f]684<Para>
[a7e3295]685Also all the special characters are user-definable - for example,
[191536f]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
[1a50c3c]688(as used in continental Europe), or anything else you care to choose.
689This flexibility
[ff003b3]690means that it should be possible to read in data from almost any sort of
[191536f]691survey data file without much work.
[e189be2]692</Para>
[c1573d8]693
[6af6d51]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
[c1573d8]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.
[e189be2]699</Para>
[c1573d8]700
[1a50c3c]701<!-- FIXME don't encourage separate processing -->
[3d5fb53]702<Para>The usual arrangement is to have one file which lists all the others
[38335b7]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>
[c1573d8]706will process the dreamtime file/section of Kaninchenh&ouml;hle.  To
[1a50c3c]707help you out, if all legs in a survey are connected to one another
708but the survey has no fixed points, cavern
[c1573d8]709will 'invent' a fixed point and print a warning message to this
710effect.
[e189be2]711</Para>
[c1573d8]712
[a7e3295]713<Para>
714It is up to you what data you put in which files.  You
[40647f5]715can have one file per trip, or per area of the cave, or just one
716file for the whole cave if you like.
[a7e3295]717On a large survey project it makes sense to group related surveys in the
718same file or directory.
[e189be2]719</Para>
[9e507547]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-->
[40647f5]728
[eb48e2b]729<!-- FIXME "Anatomy of a Survey" section -->
[e189be2]730<Sect2><Title>Readings</Title>
[c1573d8]731
[a7e3295]732<Para>Blank lines (i.e. lines consisting solely of BLANK characters)
[6aef4f1]733are ignored. The last line in the file need not be terminated by
[40647f5]734an end of line character. All fields on a line must be separated
[a7e3295]735by at least one BLANK character. An OMIT character
[40647f5]736(default '-') indicates that a field is unused. If the field is
737not optional, then an error is given.
[e189be2]738</Para>
[40647f5]739
[e189be2]740</Sect2>
741
742<Sect2><Title>Survey Station Names</Title>
[40647f5]743
[6af6d51]744<Para><Application>Survex</Application> has a powerful system for naming stations.  It
[eb48e2b]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
[a4458fd5]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
[eb48e2b]754another file, specifying a new prefix.  So to group 3 nearby caves
755on the Loser Plateau you would use a file like
[a4458fd5]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
[a7e3295]795additionally any characters in NAMES (default `_' and `-'). Alphabetic
[c1573d8]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
[375f7f6]798the first few characters as significant you can get cavern to truncate
[c1573d8]799the names using the *truncate command.
[e189be2]800</Para>
[c1573d8]801
[44b4d84]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>
[58e3c13]828</VariableList>
[44b4d84]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
[e189be2]844</Sect2>
845
846<Sect2><Title>Numeric fields</Title>
[c1573d8]847
848<Para>[&lt;MINUS&gt;|&lt;PLUS&gt;] &lt;integer part&gt; [ &lt;DECIMAL&gt;
[40647f5]849[ &lt;decimal fraction&gt; ] ]
[e189be2]850</Para>
851
[40647f5]852<Para>
853or [&lt;MINUS&gt;|&lt;PLUS&gt;] &lt;DECIMAL&gt; &lt;dec fraction&gt;
[e189be2]854</Para>
855
[63dc4eb]856<Para><!-- FIXME: put informal description first -->
[a7e3295]857i.e. optional PLUS or MINUS sign in front, with
858optional DECIMAL character (default '.'), which may be
[40647f5]859embedded, leading or trailing. No spaces are allowed between the
860various elements.
[e189be2]861</Para>
862
[40647f5]863<Para>
[0706076]864All of these are valid examples: +47, 23, -22, +4.5, 1.3, -0.7, +.15, .4,
[40647f5]865-.05
[e189be2]866</Para>
[40647f5]867
[e189be2]868</Sect2>
869
870<Sect2><Title>Accuracy</Title>
[c1573d8]871
[ff003b3]872<Para>Accuracy assessments may be provided or defaulted for any survey
873leg. These determine the distribution of loop closure errors over the
[c1573d8]874legs in the loop. See *SD for more information.
[e189be2]875</Para>
876
877</Sect2>
[40647f5]878
879<!--
[e189be2]880<Sect2><Title>Survey Coordinate Range</Title>
[40647f5]881
[e189be2]882<Para>
[40647f5]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
[c1573d8]887with your CPU [e.g. the new Acorn FPU for the ARM], and numerical
[40647f5]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.
[e189be2]891</Para>
892
[40647f5]893<Para>
[6aef4f1]894I will have to do some sums...
[e189be2]895</Para>
896
897</Sect2>
898
[40647f5]899-->
900
[f9dc4a0]901<Sect2><Title>Cavern Commands</Title>
[c1573d8]902
[6af6d51]903<Para>Commands in <filename>.svx</filename> files are introduced by an asterisk
[38335b7]904(by default - this can be changed using the <command>set</command> command).
[e189be2]905</Para>
[c1573d8]906
907<Para>The commands are documented in a common format:
[e189be2]908</Para>
[c1573d8]909
[a7e3295]910<!-- FIXME: make this a RefGroup (or whatever that's called) of RefEntry-s? -->
[c1573d8]911<itemizedlist>
[e189be2]912<listitem><para>Command Name</para></listitem>
913<listitem><para>Syntax</para></listitem>
914<listitem><para>Example</para></listitem>
[ea52d7e]915<listitem><para>Validity</para></listitem>
[1a50c3c]916<!-- FIXME
917anywhere, in a block, at start of a block, after a begin (for *end)
918-->
[e189be2]919<listitem><para>Description</para></listitem>
920<listitem><para>Caveats</para></listitem>
921<listitem><para>See Also</para></listitem>
[1a50c3c]922<!-- FIXME
923"Usefulness" - or status maybe?
924deprecated, esoteric (*set), useful, vital
925-->
[c1573d8]926</itemizedlist>
927
[dcbcae0]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
[e189be2]987<Sect3><Title>BEGIN</Title>
[c1573d8]988
989<VariableList>
990
[e189be2]991<VarListEntry><Term>Syntax</Term>
[c1573d8]992
[ea52d7e]993<listitem><Para>*begin [&lt;survey&gt;]</Para></listitem>
[c1573d8]994
[e189be2]995</VarListEntry>
996
997<VarListEntry><Term>Example</Term>
[c1573d8]998
999<listitem>
[0706076]1000<Para>
[c1573d8]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>
[0706076]1013</Para>
[e189be2]1014</listitem>
1015
1016</VarListEntry>
1017
1018<VarListEntry><Term>Description</Term>
[c1573d8]1019
[ea52d7e]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>
[e189be2]1027
1028</VarListEntry>
[c1573d8]1029
[e189be2]1030<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
[c1573d8]1031
[e189be2]1032<VarListEntry><Term>See Also</Term>
[c1573d8]1033
[e189be2]1034<listitem><Para>*end, *prefix</Para></listitem>
1035
1036</VarListEntry>
[c1573d8]1037
1038</VariableList>
1039
[e189be2]1040</Sect3>
1041
[0706076]1042<Sect3><Title>CALIBRATE</Title>
[c1573d8]1043
[0706076]1044<VariableList>
1045
1046<VarListEntry><Term>Syntax</Term>
1047
1048<listitem>
[a7e3295]1049<Para>*calibrate &lt;quantity list&gt; &lt;zero error&gt; [&lt;scale&gt;]
[0706076]1050</Para>
[88569fe]1051<Para>*calibrate &lt;quantity list&gt; &lt;zero error&gt; &lt;units&gt; [&lt;scale&gt;]
1052</Para>
[0706076]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>
[9e507547]1074
[be1a437]1075<Para>
[513935e]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.
[e189be2]1079</Para>
[c1573d8]1080
[be1a437]1081<Para>
1082&lt;quantity&gt; is one of TAPE|COMPASS|CLINO|COUNTER|DEPTH|DECLINATION|X|Y|Z
[e189be2]1083</Para>
[c1573d8]1084
[be1a437]1085<Para>
[513935e]1086Several quantities can be given in &lt;quantity list&gt; - the specified
1087calibration will be applied to each of them.
[be1a437]1088</Para>
1089
1090<Para>
[513935e]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:
[e189be2]1097</Para>
[c1573d8]1098
[be1a437]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:
[e189be2]1103</Para>
[c1573d8]1104
[be1a437]1105<programlisting>*CALIBRATE tape -0.2</programlisting>
1106
[0706076]1107<Para>Note: ZeroError is irrelevant for Topofil counters and depth
1108gauges since pairs of readings are subtracted.
[be1a437]1109</Para>
1110
[88569fe]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
[e1888e5]1134still allow you to differentiate between how the zero error has been determined.
[88569fe]1135</Para>
1136
[41e98ad]1137<Para>
[513935e]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.
[be1a437]1143</Para>
1144
[0706076]1145</listitem>
1146
1147</VarListEntry>
1148
1149<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1150
1151<VarListEntry><Term>See Also</Term>
1152
[58c7b459]1153<listitem><Para>*declination, *units</Para></listitem>
[0706076]1154
1155</VarListEntry>
1156
1157</VariableList>
1158
[be1a437]1159</Sect3>
1160
1161<Sect3><Title>CASE</Title>
1162
1163<VariableList>
1164
1165<VarListEntry><Term>Syntax</Term>
1166
[c57e9da]1167<listitem><para>*case preserve|toupper|tolower</para></listitem>
[be1a437]1168
1169</VarListEntry>
1170
1171<VarListEntry><Term>Example</Term>
1172
1173<listitem>
[0706076]1174<Para>
[be1a437]1175<programlisting>
1176*begin bobsbit
1177; Bob insists on using case sensitive station names
[c57e9da]1178*case preserve
[be1a437]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>
[0706076]1184</Para>
[be1a437]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
[e6fdc7c]1201<VarListEntry><Term>See Also</Term>
[be1a437]1202
[e6fdc7c]1203<listitem><Para>*truncate</Para></listitem>
[be1a437]1204
1205</VarListEntry>
1206
1207</VariableList>
1208
1209<!-- FIXME - work this text in here or elsewhere
[c1573d8]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
[3d5fb53]1237>The most-correct solution to this is (I believe) Martin Heller's idea about
[c1573d8]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
[375f7f6]1243>you suddenly tell cavern to become case-sensitive halfway through a run?
[c1573d8]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
[e189be2]1274</Sect3>
[f63df3e]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>
[0706076]1289<Para>
[f63df3e]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>
[0706076]1296</Para>
[f63df3e]1297</listitem>
1298
1299</VarListEntry>
1300
[ea52d7e]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
[f63df3e]1308<VarListEntry><Term>Description</Term>
1309
[58c7b459]1310<listitem><Para>*copyright allows the copyright information to be
[f63df3e]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
[0706076]1320<listitem><Para>*begin</Para></listitem>
[f63df3e]1321
1322</VarListEntry>
1323
1324</VariableList>
1325
1326</Sect3>
[e189be2]1327
[abd0310]1328<Sect3><Title>CS</Title>
1329
1330<VariableList>
1331
1332<VarListEntry><Term>Syntax</Term>
1333
[ad5bd05]1334<listitem><Para>*cs [out] &lt;coordinate system&gt;</Para></listitem>
[abd0310]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>
[ad5bd05]1346
1347<Para>
1348<programlisting>
1349; Output in the coordinate system used in the Totes Gebirge in Austria
[935824f]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>
[ad5bd05]1351</Para>
[abd0310]1352</listitem>
1353
1354</VarListEntry>
1355
1356<VarListEntry><Term>Description</Term>
1357
[ad5bd05]1358<listitem><Para>*cs allows the coordinate systems used for fixed points and for
1359processed survey data to be specified.
[abd0310]1360</Para>
1361
1362<Para>
[b102633]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:
[ad5bd05]1370</Para>
1371
[16734b2]1372<Para>CUSTOM followed by a PROJ4 string (like in the example above).</Para>
1373
[ddd24f28]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
[d417499]1376<ulink url="https://epsg.io/">https://epsg.io/</ulink> is a useful resource for
[ddd24f28]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
[5598e2c]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
[10af28e]1391<Para>JTSK for the Czechoslovak S-JTSK system.  The axes on this point West
[ef100d0]1392and South, so it's not supported as an output coordinate system.
[10af28e]1393Supported since Survex 1.2.16.</Para>
1394
1395<Para>JTSK03 for a variant of JTSK.  Supported since Survex 1.2.16.</Para>
1396
[50d6de2]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>
[16734b2]1401
[a4cd4eea]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
[2076d59]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
[16734b2]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
[ad5bd05]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>
[abd0310]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>
[ea52d7e]1476<Sect3><Title>DATA</Title>
1477
1478<VariableList>
1479
1480<VarListEntry><Term>Syntax</Term>
[40647f5]1481
[667e803c]1482<listitem>
1483<Para>*data &lt;style&gt; &lt;ordering&gt;</Para>
1484<Para>*data</Para>
1485</listitem>
1486
[6114207]1487<!-- BACKCOMPASS BACKCLINO -->
[ea52d7e]1488</VarListEntry>
1489
1490<VarListEntry><Term>Example</Term>
1491
1492<listitem>
[40647f5]1493<Para>
[ea52d7e]1494<programlisting>
1495*data normal from to compass tape clino</programlisting>
[e189be2]1496</Para>
[c746b4d]1497
1498<Para>
1499<programlisting>
1500*data normal station ignoreall newline compass tape clino</programlisting>
1501</Para>
[ea52d7e]1502</listitem>
1503
1504</VarListEntry>
[e189be2]1505
[ea52d7e]1506<VarListEntry><Term>Description</Term>
[e189be2]1507
[ea52d7e]1508<listitem><Para>
[b458119]1509&lt;style&gt; = DEFAULT|NORMAL|DIVING|CARTESIAN|TOPOFIL|CYLPOLAR|NOSURVEY|PASSAGE
[e189be2]1510</Para>
1511
[40647f5]1512<Para>
[6114207]1513&lt;ordering&gt; = ordered list of instruments - which are valid depends on the
1514style.
1515</Para>
1516
[107b8bd]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
[6114207]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.
[e189be2]1535</Para>
1536
[107b8bd]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
[667e803c]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
[c746b4d]1550<VariableList>
[e189be2]1551
[c746b4d]1552<VarListEntry><Term>DEFAULT</Term>
[6114207]1553<listitem><Para>Select the default data style and ordering (NORMAL style, ordering: from to tape compass clino).</Para></listitem>
[c746b4d]1554</VarListEntry>
[e189be2]1555
[c746b4d]1556<VarListEntry><Term>NORMAL</Term>
[6114207]1557<listitem><Para>The usual tape/compass/clino centreline survey.
[b14f44f]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.
[6114207]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
[13ba257]1578<programlisting>
[107b8bd]1579*data normal from to compass clino fromcount tocount
[13ba257]15801 2 172 -03 11532 11873</programlisting>
1581
1582<programlisting>
[107b8bd]1583*data normal station count newline direction compass clino
[13ba257]15841 11532
1585 F 172 -03
15862 11873</programlisting>
1587 
1588</Para></listitem>
1589</VarListEntry>
1590
[c746b4d]1591<VarListEntry><Term>DIVING</Term>
1592<listitem><Para>
[eb48e2b]1593An underwater survey where the vertical information is from a diver's depth
[1ff6864]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
[b14f44f]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:
[aacc3e6]1601FROM TO TAPE COMPASS CLINO BACKCOMPASS BACKCLINO FROMDEPTH TODEPTH DEPTHCHANGE (the vertical
[b14f44f]1602can be given as readings at each station, (FROMDEPTH/TODEPTH) or as a change
1603along the leg (DEPTHCHANGE)).</Para>
1604
[aacc3e6]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
[b14f44f]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)).
[6114207]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>
[b14f44f]1628</Para>
1629</listitem>
[c746b4d]1630</VarListEntry>
1631
1632<VarListEntry><Term>CARTESIAN</Term>
1633<listitem><Para>
[6114207]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
[e74904e]1648<!--FIXME: dx dy dz-->
[e189be2]1649</Para>
1650
[e74904e]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>
[ce92903]1656</listitem>
[c746b4d]1657</VarListEntry>
[e74904e]1658
[13ba257]1659<VarListEntry><Term>CYLPOLAR</Term>
[c746b4d]1660<listitem><Para>
[b14f44f]1661A CYLPOLAR style survey is very similar to a diving survey, except that the tape
[13ba257]1662is always measured horizontally rather than along the slope of the leg.
[6114207]1663
1664<programlisting>
[13ba257]1665*data cypolar from to tape compass fromdepth todepth
16661 2 9.45 311 -13.3 -19.0</programlisting>
[6114207]1667
1668<programlisting>
[13ba257]1669*data cylpolar station depth newline tape compass
16701 -13.3
1671 9.45 311
16722 -19.0</programlisting>
[e189be2]1673
[13ba257]1674<programlisting>
1675*data cylpolar from to tape compass depthchange
16761 2 9.45 311 -5.7</programlisting>
[c746b4d]1677</Para></listitem>
1678</VarListEntry>
[9e507547]1679
[c746b4d]1680<VarListEntry><Term>NOSURVEY</Term>
1681<listitem><Para>
[6114207]1682A NOSURVEY survey doesn't have any measurements - it merely indicates that
[13ba257]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>
[c746b4d]1700</Para></listitem>
1701</VarListEntry>
[e189be2]1702
[b458119]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
[40647f5]1718<Para>
[b458119]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>
[667e803c]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>
[e189be2]1750</Para>
[ce92903]1751</listitem>
[b458119]1752</VarListEntry>
[c746b4d]1753</VariableList>
[e189be2]1754
[40647f5]1755<Para>
[c746b4d]1756IGNORE skips a field (it may be used any number of times),
[13ba257]1757and IGNOREALL may be used last to ignore the rest of the data line.
[e189be2]1758</Para>
1759
[c746b4d]1760<Para>
1761LENGTH is a synonym for TAPE; BEARING for COMPASS; GRADIENT for CLINO; COUNT for COUNTER.<!--FIXME : others?-->
1762</Para>
1763
[e74904e]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>
[f3ed07f]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]
[e74904e]1775</Para>
1776-->
1777
[ea52d7e]1778</listitem>
1779
1780</VarListEntry>
1781
1782</VariableList>
1783
[e189be2]1784</Sect3>
1785
[e74904e]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
[58c7b459]1843<Sect3><Title>DECLINATION</Title>
1844
1845<VariableList>
1846
1847<VarListEntry><Term>Syntax</Term>
1848
1849<listitem>
[5cc4a99]1850<Para>*declination auto &lt;x&gt; &lt;y&gt; &lt;z&gt;</Para>
[513935e]1851<Para>*declination &lt;declination&gt; &lt;units&gt;</Para>
[58c7b459]1852</listitem>
1853
1854</VarListEntry>
1855
1856<VarListEntry><Term>Description</Term>
1857
[41e98ad]1858<listitem>
1859
[58c7b459]1860<Para>
[513935e]1861The *declination command is the modern way to specify magnetic declinations in
[f65e7e9]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.
[513935e]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.
[58c7b459]1909</Para>
1910
1911<Para>
[513935e]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
[a4de12f]1921of time that the magnetic declination won't have changed significantly, you
[513935e]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.
[58c7b459]1928</Para>
1929
1930<Para>
[513935e]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.
[58c7b459]1936</Para>
1937
[41e98ad]1938</listitem>
1939
[58c7b459]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
[ea52d7e]1952<Sect3><Title>DEFAULT</Title>
[e189be2]1953
[ea52d7e]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.
[e189be2]1966</Para>
1967
[40647f5]1968<Para>
[ea52d7e]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>
[e189be2]2019
2020</Sect3>
2021
[ea52d7e]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>
[e189be2]2033
[ea52d7e]2034<listitem>
[40647f5]2035<Para>
[ea52d7e]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.
[e74904e]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>
[ea52d7e]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
[e189be2]2070</Sect3>
2071
[ea52d7e]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>
[e189be2]2079
[ea52d7e]2080</VarListEntry>
2081
2082<VarListEntry><Term>Example</Term>
2083
2084<listitem>
[40647f5]2085<Para>
[ea52d7e]2086<programlisting>
2087*equate chosspot.1 triassic.27</programlisting>
[e189be2]2088</Para>
[ea52d7e]2089</listitem>
2090
2091</VarListEntry>
[e189be2]2092
[ea52d7e]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:
[40647f5]2102<Para>
[ea52d7e]2103I think this is preferable to using:
[e189be2]2104</Para>
[6aef4f1]2105
2106<programlisting> a b 0.00   0   0</programlisting>
2107
[e189be2]2108<Para>
[6aef4f1]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!
[e189be2]2112</Para>
[ea52d7e]2113-->
2114</listitem>
2115
2116</VarListEntry>
2117
2118<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2119
[eb48e2b]2120<VarListEntry><Term>See Also</Term>
[ea52d7e]2121
[eb48e2b]2122<listitem><Para>*infer equates</Para></listitem>
[ea52d7e]2123
2124</VarListEntry>
2125
2126</VariableList>
[e189be2]2127
2128</Sect3>
[6aef4f1]2129
[6048971]2130<Sect3><Title>EXPORT</Title>
[9e507547]2131
[6048971]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
[e74904e]2142<!-- FIXME better example -->
[6048971]2143<listitem>
[9e507547]2144<Para>
[6048971]2145<programlisting>
2146*export 1 6 17</programlisting>
[9e507547]2147</Para>
[6048971]2148</listitem>
[9e507547]2149
[6048971]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
[4f0b498]2164above, it must be exported from each enclosing survey.
[6048971]2165</Para>
2166
2167<!-- FIXME:
[9e507547]2168<Para>
[6048971]2169I think this is preferable to using:
[9e507547]2170</Para>
2171
[6048971]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
[eb48e2b]2188<listitem><Para>*begin, *infer exports</Para></listitem>
[6048971]2189
2190</VarListEntry>
2191
2192</VariableList>
2193
[9e507547]2194</Sect3>
2195
[6048971]2196<Sect3><Title>FIX</Title>
2197
2198<VariableList>
2199
2200<VarListEntry><Term>Syntax</Term>
2201
2202<listitem><Para>*fix &lt;station&gt; [reference]
[dab6a62]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;
[6048971]2205     [ &lt;cov(x,y)&gt; &lt;cov(y,z)&gt; &lt;cov(z,x)&gt; ] ] ]
2206</Para></listitem>
[e189be2]2207
[6048971]2208</VarListEntry>
[e189be2]2209
[6048971]2210<VarListEntry><Term>Example</Term>
[e189be2]2211
[6048971]2212<listitem>
[40647f5]2213<Para>
[6048971]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>
[e189be2]2219</Para>
[6048971]2220</listitem>
2221
2222</VarListEntry>
2223
2224<VarListEntry><Term>Description</Term>
[e189be2]2225
[6048971]2226<listitem>
[40647f5]2227<Para>
[a7e3295]2228*fix fixes the position of &lt;station&gt; at the given coordinates.
[ad5bd05]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.
[e189be2]2234</Para>
2235
[2109b07]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
[dab6a62]2242<Para>
2243If you have covariances for the fix, you can also specify these - the
[f9dc4a0]2244order is cov(x,y) cov(y,z) cov(z,x).
2245</Para>
2246
[567efed]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
[f9dc4a0]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.
[dab6a62]2262</Para>
2263
2264<Para>
2265By default cavern will warn about stations which have been FIX-ed but
[10909c2]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.
[2109b07]2271</Para>
2272
[e74904e]2273<Note><Para>
[fe16ba3]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.
[e74904e]2280</Para></Note>
[6048971]2281
[ce92903]2282</listitem>
[6048971]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
[e189be2]2296</Sect3>
2297
[6048971]2298<!--
2299<Sect3><Title></Title>
2300
2301<VariableList>
2302
2303<VarListEntry><Term>Syntax</Term>
[9e507547]2304
[6048971]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>
[9e507547]2353<Para>
[6048971]2354<programlisting>
2355*flags duplicate not surface</programlisting>
[9e507547]2356</Para>
[6048971]2357</listitem>
2358
2359</VarListEntry>
2360
2361<VarListEntry><Term>Description</Term>
[9e507547]2362
[6048971]2363<listitem><Para>
2364*flags updates the current flag settings.
2365Flags not mentioned retain their previous state.  Valid flags
[3162ed8]2366are DUPLICATE, SPLAY, and SURFACE, and a flag may be preceded with NOT to
[9e507547]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
[3162ed8]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.
[9e507547]2379</Para>
[6048971]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>
[9e507547]2391
2392</Sect3>
2393
[6048971]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>
[e189be2]2405
[6048971]2406<listitem>
[40647f5]2407<Para>
[6048971]2408<programlisting>
2409*include mission</programlisting>
2410
2411<programlisting>
2412*include "the pits"</programlisting>
[e189be2]2413</Para>
[6048971]2414</listitem>
[40647f5]2415
[6048971]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
[c1573d8]2422place in the current file. (i.e. The current settings are carried
[40647f5]2423into &lt;filename&gt;, and any alterations to settings in &lt;filename&gt;
[f9dc4a0]2424will be carried back again).  There's one exception to this (for
2425obscure historical reasons) which is that the survey prefix is
[cb69f36]2426restored upon return to the original file.  Since *begin and *end
[f9dc4a0]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.
[6048971]2432</Para>
[e189be2]2433
[6048971]2434<Para>An included file which does not have a complete path
[9e507547]2435is resolved relative to the directory which the parent file is in
[6af6d51]2436(just as relative HTML links do).  Cavern will try adding a <filename>.svx</filename>
[6e420ba]2437extension, and will also try translating "\" to "/".
2438And as a last
[9e507547]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
[6af6d51]2441case, unzip it with "unzip -L" and UNIX cavern will process it).
[6048971]2442</Para>
[51c0677]2443
[f9dc4a0]2444<Para>
[63dc4eb]2445The depth to which you can nest
2446include files may be limited by the operating system
[f9dc4a0]2447you use.  Usually the limit is fairly high (>30), but if you want to be able to
[6af6d51]2448process your dataset with <Application>Survex</Application> on any supported platform, it
[f9dc4a0]2449would be prudent not to go overboard with nested include files.
2450</Para>
2451</listitem>
[6048971]2452</VarListEntry>
2453
2454</VariableList>
[40647f5]2455
[e189be2]2456</Sect3>
2457
[be1a437]2458<Sect3><Title>INFER</Title>
2459
2460<VariableList>
2461
2462<VarListEntry><Term>Syntax</Term>
2463
[3404462]2464<listitem>
2465<Para>*infer plumbs on|off</Para>
[be1a437]2466
[3404462]2467<Para>*infer equates on|off</Para>
[eb48e2b]2468
2469<Para>*infer exports on|off</Para>
[3404462]2470</listitem>
[be374fc]2471
[be1a437]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
[3404462]2488<listitem>
2489<Para>"*infer plumbs on" tells cavern to interpret gradients of +/- 90
[be1a437]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
[eb48e2b]2495<para>"*infer equates on" tells cavern to interpret a leg with
2496a tape reading of zero as a *equate.  this prevents tape corrections
[be374fc]2497being applied to them.
[eb48e2b]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>
[be374fc]2505</listitem>
2506
[be1a437]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
[e74904e]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
[6048971]2574<Sect3><Title>PREFIX</Title>
[e189be2]2575
[6048971]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>
[40647f5]2587<Para>
[6048971]2588<programlisting>
2589*prefix flapjack</programlisting>
[e189be2]2590</Para>
[6048971]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>
[e189be2]2617
2618</Sect3>
2619
[ce15637]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"
[58e3c13]2636</programlisting>
[ce15637]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>
[399acd6]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.
[ce15637]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
[6048971]2676<Sect3><Title>REQUIRE</Title>
[9e507547]2677
[6048971]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>
[9e507547]2689<Para>
[6048971]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
[9e507547]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.
[6048971]2706</Para></listitem>
2707
2708</VarListEntry>
2709
2710</VariableList>
[9e507547]2711
2712</Sect3>
2713
[6048971]2714<Sect3><Title>SD</Title>
2715
2716<VariableList>
2717
2718<VarListEntry><Term>Syntax</Term>
[e189be2]2719
[6048971]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>
[40647f5]2728<Para>
[6048971]2729<programlisting>
2730*sd tape 0.15 metres</programlisting>
[e189be2]2731</Para>
[6048971]2732</listitem>
[e189be2]2733
[6048971]2734</VarListEntry>
2735
2736<VarListEntry><Term>Description</Term>
2737
2738<listitem><Para>
2739*sd sets the standard deviation of a measurement.
[e189be2]2740</Para>
2741
[40647f5]2742<Para>
[bfd5706]2743&lt;quantity&gt; is one of (each group gives alternative names for the same
2744quantity):
[e189be2]2745</Para>
2746
[bfd5706]2747<ItemizedList>
2748    <listitem><para>TAPE, LENGTH</para></listitem>
[4f38f94]2749    <listitem><para>BACKTAPE, BACKLENGTH (added in Survex 1.2.25)</para></listitem>
[bfd5706]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
[40647f5]2769<Para>
2770&lt;standard deviation&gt; must include units and thus is typically
[63dc4eb]2771"0.05 metres", or "0.02 degrees". See *units below for full list
[6048971]2772of valid units.
[e189be2]2773</Para>
2774
[6048971]2775<!-- FIXME mention central limit theorem -->
[40647f5]2776<Para>
[6048971]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
[c1573d8]2780in a measurement. Assuming that these are normally distributed
[770157e]2781we can say that 95.44% of the actual lengths will fall within two
[40647f5]2782standard deviations of the measured length. i.e. a tape SD of
[770157e]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.
[40647f5]2785So if the measurement is 7.34m then the actual length is very
[6048971]2786likely to be between 6.84m and 7.84m. This example corresponds
[40647f5]2787to BCRA grade 3. Note that this is just one interpretation of
[770157e]2788the BCRA standard, taking the permitted error values as 2SD 95.44%
[40647f5]2789confidence limits. If you want to take the readings as being some
[6048971]2790other limit (e.g. 1SD = 68.26%) then you will need to change the BCRA3
[c1573d8]2791and BCRA5 files accordingly. This issue is explored in more
[40647f5]2792detail in various surveying articles.
[6048971]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>
[e189be2]2812
2813</Sect3>
2814
[6048971]2815<Sect3><Title>SET</Title>
[e189be2]2816
[6048971]2817<VariableList>
[e189be2]2818
[6048971]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>
[40647f5]2828<Para>
[6048971]2829<programlisting>
[21c226e]2830*set blank x09x20
[6048971]2831*set decimal ,</programlisting>
[21c226e]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.
[e189be2]2836</Para>
[6048971]2837</listitem>
[e189be2]2838
[6048971]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
[40647f5]2845given in &lt;character list&gt;. The example sets the decimal
[11f9067]2846separator to be a comma.
2847</Para>
2848
2849<Para>
2850xAB means the character with hex value AB. Eg x20 is a space.
[e189be2]2851</Para>
2852
[40647f5]2853<Para>
[11f9067]2854The complete list of items that can be set, the defaults (in
[40647f5]2855brackets), and the meaning of the item, is:
[e189be2]2856</Para>
2857
[6048971]2858<ItemizedList>
2859
2860<ListItem><Para>
[11f9067]2861BLANK (x09x20,) Separates fields
[6048971]2862</Para></ListItem>
[e189be2]2863
[6048971]2864<ListItem><Para>
[40647f5]2865COMMENT (;) Introduces comments
[6048971]2866</Para></ListItem>
[e189be2]2867
[6048971]2868<ListItem><Para>
[40647f5]2869DECIMAL (.) Decimal point character
[6048971]2870</Para></ListItem>
[e189be2]2871
[6048971]2872<ListItem><Para>
2873EOL (x0Ax0D) End of line character
2874</Para></ListItem>
[e189be2]2875
[6048971]2876<ListItem><Para>
[40647f5]2877KEYWORD (*) Introduces keywords
[6048971]2878</Para></ListItem>
[e189be2]2879
[6048971]2880<ListItem><Para>
[40647f5]2881MINUS (-) Indicates negative number
[6048971]2882</Para></ListItem>
[e189be2]2883
[6048971]2884<ListItem><Para>
[f3ac7d4]2885NAMES (_-) Non-alphanumeric chars permitted in station
2886names (letters and numbers are always permitted).
[6048971]2887</Para></ListItem>
[e189be2]2888
[6048971]2889<ListItem><Para>
[c1573d8]2890OMIT (-) Contents of field omitted (e.g. in plumbed legs)
[6048971]2891</Para></ListItem>
[e189be2]2892
[6048971]2893<ListItem><Para>
[40647f5]2894PLUS (+) Indicates positive number
[6048971]2895</Para></ListItem>
[e189be2]2896
[6048971]2897<ListItem><Para>
[b15eeda]2898ROOT (\) Prefix in force at start of current file (use of ROOT is deprecated)
[6048971]2899</Para></ListItem>
[e189be2]2900
[6048971]2901<ListItem><Para>
[40647f5]2902SEPARATOR (.) Level separator in prefix hierarchy
[6048971]2903</Para></ListItem>
2904
[eb48e2b]2905<!-- FIXME OPEN ({) and CLOSE (}) -->
[6048971]2906</ItemizedList>
[e189be2]2907
[40647f5]2908<Para>
2909The special characters may not be alphanumeric.
[e189be2]2910</Para>
[40647f5]2911
[6048971]2912</listitem>
[e189be2]2913
[6048971]2914</VarListEntry>
[e189be2]2915
[6048971]2916</VariableList>
[e189be2]2917
2918</Sect3>
2919
2920<Sect3><Title>SOLVE</Title>
[40647f5]2921
[6048971]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>
[40647f5]2933<Para>
[6048971]2934<programlisting>
2935*include 1997data
2936*solve
2937*include 1998data
2938</programlisting>
[e189be2]2939</Para>
[6048971]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
[63dc4eb]2953positions as they are in the existing drawn up survey, even if new loops
[6048971]2954have been formed by the extensions.
2955</Para></listitem>
2956
2957</VarListEntry>
2958
2959</VariableList>
[40647f5]2960
[e189be2]2961</Sect3>
2962
[e74904e]2963<Sect3><Title>TEAM</Title>
[be1a437]2964
2965<VariableList>
2966
2967<VarListEntry><Term>Syntax</Term>
2968
[3bb963aa]2969<listitem><Para>*team &lt;person&gt; [&lt;role&gt;...]</Para></listitem>
[be1a437]2970
2971</VarListEntry>
2972
2973<VarListEntry><Term>Example</Term>
2974
2975<listitem>
[e74904e]2976<Para>
[be1a437]2977<programlisting>
[e74904e]2978*team "Nick Proctor" compass clino tape
2979*team "Anthony Day" notes pictures tape
[be1a437]2980</programlisting>
[e74904e]2981</Para>
[be1a437]2982</listitem>
2983
2984</VarListEntry>
[e74904e]2985
2986<VarListEntry><Term>Validity</Term>
2987
2988<listitem><Para>valid at the start of a *begin/*end block.
2989</Para></listitem>
[eb48e2b]2990<!-- FIXME valid roles are? -->
[e74904e]2991
2992</VarListEntry>
[be1a437]2993
2994<VarListEntry><Term>Description</Term>
2995
[e74904e]2996<listitem><Para>
[3bb963aa]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.
[e74904e]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>
[be1a437]3013
[e74904e]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.
[be1a437]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
[e74904e]3073<!-- FIXME:
[be1a437]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
[6af6d51]3087<listitem><Para>Station names may be of any length in <Application>Survex</Application>, but some
[be1a437]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
[6af6d51]3091such a package <Application>Survex</Application> allows you to truncate names to whatever
[eb48e2b]3092length you want (but by default truncation is off).
[be1a437]3093</Para>
3094
[f9dc4a0]3095<Para>Figures for the number of characters which are significant in various
[a4458fd5]3096software packages: Compass currently has a limit of 12,
[f9dc4a0]3097CMAP has a limit of 6,
[b554a4b]3098Smaps 4 had a limit of 8,
[eb48e2b]3099<!-- FIXME any limits for other software, winkarst for example? -->
3100Surveyor87/8 used 8.
[6af6d51]3101<Application>Survex</Application> itself used 8 per prefix
[be1a437]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
[e6fdc7c]3113<listitem><Para>*case</Para></listitem>
[be1a437]3114
3115</VarListEntry>
3116
3117</VariableList>
3118
3119</Sect3>
3120
[e74904e]3121<Sect3><Title>UNITS</Title>
[c1573d8]3122
[e74904e]3123<VariableList>
[9e507547]3124
[e74904e]3125<VarListEntry><Term>Syntax</Term>
3126
3127<listitem><Para>
3128*units &lt;quantity list&gt; [&lt;factor&gt;] &lt;unit&gt;
[e189be2]3129</Para>
[e74904e]3130<Para>
3131*units default
3132</Para></listitem>
3133
3134</VarListEntry>
3135
3136<VarListEntry><Term>Example</Term>
[c1573d8]3137
[e74904e]3138<listitem>
3139<Para>
3140<programlisting>
3141*units tape metres</programlisting>
3142
3143<programlisting>
[b14f44f]3144*units compass backcompass clino backclino grads</programlisting>
[e74904e]3145
3146<programlisting>
3147*units dx dy dz 1000 metres ; data given as kilometres</programlisting>
[b5283af]3148
3149<programlisting>
3150*units left right up down feet</programlisting>
[e189be2]3151</Para>
[e74904e]3152</listitem>
[c1573d8]3153
[e74904e]3154</VarListEntry>
3155
3156<VarListEntry><Term>Description</Term>
3157
3158<listitem><Para>
[b5283af]3159&lt;quantity&gt; is one of the following (grouped entries are just alternative names for the same thing):
[4f38f94]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
[e189be2]3161</Para>
[c1573d8]3162
3163<Para>Changes current units of all the quantities listed to [&lt;factor&gt;]
[40647f5]3164&lt;unit&gt;. Note that quantities can be expressed either as
[fa42426]3165the instrument (e.g. COMPASS) or the measurement (e.g. BEARING).
[e189be2]3166</Para>
[c1573d8]3167
[fa42426]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.
[e189be2]3172</Para>
[c1573d8]3173
3174<Para>Valid units for listed quantities are:
[e189be2]3175</Para>
[c1573d8]3176
[4f38f94]3177<Para>TAPE/LENGTH, BACKTAPE/BACKLENGTH, COUNTER/COUNT, DEPTH, DX/EASTING, DY/NORTHING, DZ/ALTITUDE
[b5283af]3178in YARDS|FEET|METRIC|METRES|METERS (default: METRES)
[e189be2]3179</Para>
[c1573d8]3180
[b5283af]3181<Para>CLINO/GRADIENT, BACKCLINO/BACKGRADIENT
[70fa970]3182in DEGS|DEGREES|GRADS|MINUTES|PERCENT|PERCENTAGE (default: DEGREES)
[e74904e]3183</Para>
3184
[b5283af]3185<Para>COMPASS/BEARING, BACKCOMPASS/BACKBEARING, DECLINATION
[70fa970]3186in DEGS|DEGREES|GRADS|MINUTES (default: DEGREES)
[e74904e]3187</Para>
3188
[70fa970]3189<Para>(360 degrees = 400 grads)
[e74904e]3190</Para>
3191
[70fa970]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>
[e74904e]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>
[c1573d8]3233
[e189be2]3234</Sect3>
3235
3236</Sect2>
3237
3238</Sect1>
3239
[63dc4eb]3240<!-- FIXME rename to "Cookbook"? -->
[6af6d51]3241<Sect1><Title>Contents of <filename>.svx</filename> files: How do I?</Title>
[0d62afe]3242<?dbhtml filename="svxhowto.htm">
[c1573d8]3243
[40647f5]3244<Para>
[6af6d51]3245Here is some example <Application>Survex</Application> data (a very small cave numbered 1623/163):
[e189be2]3246</Para>
[fbc41c2]3247
3248<programlisting>
[40647f5]32492 1 26.60 222  17.5
32502 3 10.85 014   7
32512 4  7.89 254 -11
32524 5  2.98  - DOWN
[fbc41c2]32535 6  9.29 271 -28.5</programlisting>
3254
[40647f5]3255<Para>
3256You can vary the data ordering.  The default is:
[e189be2]3257</Para>
3258
[40647f5]3259<Para>
3260from-station to-station tape compass clino
[e189be2]3261</Para>
3262
[40647f5]3263<Para>
[6af6d51]3264This data demonstrates a number of useful features of <Application>Survex</Application>:
[e189be2]3265</Para>
3266
[40647f5]3267<Para>
3268Legs can be measured either way round, which allows the use of
[b462168]3269techniques like "leap-frogging" (which is where legs
3270alternate forwards and backwards).
[e189be2]3271</Para>
3272
[40647f5]3273<Para>
3274Also notice that there is a spur in the survey (2 to 3).  You
[6aef4f1]3275do not need to specify this specially.
[e189be2]3276</Para>
3277
[40647f5]3278<Para>
[6af6d51]3279<Application>Survex</Application> places few restrictions on station naming (see "Survey
[ff003b3]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
[6af6d51]3283existing station.  <Application>Survex</Application> can accept data in any order, and will
[ff003b3]3284check for connectedness once all the data has been read in.
[e189be2]3285</Para>
3286
[40647f5]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.
[e189be2]3291</Para>
3292
[40647f5]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.
[e189be2]3298</Para>
3299
[40647f5]3300<Para>
[6af6d51]3301To accomplish this, <Application>Survex</Application> has a very flexible system of hierarchical
[40647f5]3302prefixes.  All you need do is give each survey a unique name or
3303number, and enter the data like so:
[e189be2]3304</Para>
[fbc41c2]3305
3306<programlisting>
[40647f5]3307*begin 163
[e74904e]3308*export 1
[40647f5]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
[fbc41c2]3314*end 163</programlisting>
3315
[6af6d51]3316<Para><Application>Survex</Application> will name the stations by attaching the current prefix.
[fbc41c2]3317In this case, the stations will be named 163.1, 163.2, etc.
[e189be2]3318</Para>
[fbc41c2]3319
[ff003b3]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
[fbc41c2]3322can accomplish this like so:
[e189be2]3323</Para>
[fbc41c2]3324
3325<programlisting>
[b15eeda]3326*equate P163 163.1
[e74904e]3327*entrance P163
[40647f5]3328*begin 163
[e74904e]3329*export 1
[40647f5]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
[fbc41c2]3335*end 163</programlisting>
3336
[b462168]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:
[ce92903]3345</Para>
[b462168]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
[e189be2]3410<Sect2><Title>Specify the ordering and type of data</Title>
3411
[e74904e]3412<Para>The *DATA command is used to specify the data style, and the
3413order in which the readings are given.</Para>
[e189be2]3414
3415</Sect2>
3416
[1a50c3c]3417<Sect2><Title>Deal with Plumbs or Legs Across Static Water</Title>
[e189be2]3418
[1a50c3c]3419<!-- FIXME
[40647f5]3420<Para>
[1a50c3c]3421They can be given
[40647f5]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.
[e189be2]3426</Para>
3427
[63dc4eb]3428FIXME: paste in section from mail to list
3429
[40647f5]3430<Para>
[4eba0d9]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.
[e189be2]3433</Para>
[1a50c3c]3434-->
[e189be2]3435
[40647f5]3436<Para>
[eb48e2b]3437Plumbed legs should be given using 'UP' or 'DOWN' in place of the
[1a50c3c]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:
[e189be2]3441</Para>
[fbc41c2]3442
3443<programlisting>
[40647f5]34441 2 21.54 - UP
34453 2 7.36 017 +17
34463 4 1.62 091 +08
[fbc41c2]34475 4 10.38 - DOWN</programlisting>
3448
[e189be2]3449<Para>
[eb48e2b]3450U/D or +V/-V may be used instead of UP/DOWN; the check is not case
[1a50c3c]3451sensitive.
[e189be2]3452</Para>
3453
[4eba0d9]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.
[1a50c3c]3458This prevents the clino correction being applied.  Here's an example:
[4eba0d9]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
[e189be2]3466</Sect2>
[fbc41c2]3467
[e189be2]3468<Sect2><Title>Specify a BCRA grade</Title>
[40647f5]3469
[fbc41c2]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
[eb48e2b]3473commands. You can use these by simply including them at the relevant point,
3474as follows:
[e189be2]3475</Para>
[fbc41c2]3476
3477<programlisting>
[40647f5]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
[fbc41c2]3484*end somewhere</programlisting>
3485
3486<Para>The default values for the standard deviations are those for
[6aef4f1]3487BCRA grade 5. Note that it is good practice to keep the *include
[c1573d8]3488Grade3 within *Begin and *End commands otherwise it will apply
[40647f5]3489to following survey data, which may not be what you intended.
[e189be2]3490</Para>
3491
3492</Sect2>
[40647f5]3493
[e189be2]3494<Sect2><Title>Specify different accuracy for a leg</Title>
[fbc41c2]3495
[c1573d8]3496<Para>For example, suppose the tape on the plumbed leg in this survey
[1a50c3c]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:
[e189be2]3502</Para>
[fbc41c2]3503
3504<programlisting>
[40647f5]35052 1 26.60 222  17.5
35062 3 10.85 014   7
35072 4  7.89 254 -11
3508*begin
[1a50c3c]3509; tape measurement was taken from the rope length
[40647f5]3510*sd tape 0.5 metres
[1a50c3c]35114 5  34.50 - DOWN
[40647f5]3512*end
[1a50c3c]35135 6  9.29 271 -28.5</programlisting>
[fbc41c2]3514
[eb48e2b]3515<!-- FIXME also *calibrate and *instrument? Except rope is measure with the
3516tape... -->
[e189be2]3517</Sect2>
3518
[fbf7fa0]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
[ff003b3]3529<Sect2><Title>Enter Radiolocation Data</Title>
[fbc41c2]3530
[a4458fd5]3531<!-- FIXME comments from David Gibson here -->
[5b5a89f]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
[e74904e]3545length. To get the equivalent SD we assume that 99.74% of readings will
[5b5a89f]3546be within 3 standard deviations of the error value. Thus we divide the
3547expected errors by 3 to get the SD we should specify:
[eb48e2b]3548</Para> <!-- 3 SD? or same as BCRA3.SVX, etc -->
[fbc41c2]3549
3550<programlisting>
[5b5a89f]3551*begin
[e74904e]3552*sd length 6.67 metres
[5b5a89f]3553*sd plumb 3 degrees
3554surface underground 50 - down
[e74904e]3555*end</programlisting>
[5b5a89f]3556
3557<Para>
[e74904e]3558We wrap the radiolocation leg in a *begin/*end block to make
[5b5a89f]3559sure that the special *sd settings only apply to this one leg.
3560</Para>
[fbc41c2]3561
3562<Para>For more information on the expected errors from radiolocations
[b462168]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>
[e189be2]3565</Para>
3566
3567</Sect2>
[fbc41c2]3568
[e189be2]3569<Sect2><Title>Enter Diving Data</Title>
[fbc41c2]3570
[0706076]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.
[e189be2]3574</Para>
3575
3576</Sect2>
[fbc41c2]3577
[e189be2]3578<Sect2><Title>Enter Theodolite data</Title>
[fbc41c2]3579
[e74904e]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.
[e189be2]3592</Para>
3593
3594</Sect2>
3595
3596</Sect1>
[fbc41c2]3597
[e189be2]3598<Sect1><Title>General: How do I?</Title>
[0d62afe]3599<?dbhtml filename="genhowto.htm">
[fbc41c2]3600
[e189be2]3601<Sect2><Title>Create a new survey</Title>
[fbc41c2]3602
3603<Para>You simply create a text file containing the relevant survey data,
[6af6d51]3604using a text editor, and save it with a suitable name with a <filename>.svx</filename>
[e6aa3b1]3605extension. The
[40647f5]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
[e6aa3b1]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:
[e189be2]3611</Para>
[fbc41c2]3612
3613<Para>All the lines starting with ';' are comments, which are ignored
[6af6d51]3614by <Application>Survex</Application>. You can also see the use of 'DOWN' for plumbs, and
[b462168]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>
[40647f5]3618
[fbc41c2]3619<programlisting>
[e74904e]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"
[40647f5]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
[e74904e]3635
3636*export 1 2
3637
[40647f5]3638;Tape is 20cm too short
3639*calibrate tape +0.2
[e74904e]3640
[40647f5]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
[e74904e]3647*begin
[40647f5]3648*calibrate tape 0
36498 7 35.64 262 +86 ;true length measured for this leg
[e74904e]3650*end
[40647f5]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
[fbc41c2]3665*end chaos</programlisting>
[40647f5]3666
[e189be2]3667</Sect2>
3668
3669<Sect2><Title>Join surveys together</Title>
[fbc41c2]3670
3671<Para>Once you have more than one survey you need to specify how they
[e74904e]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 -->
[e189be2]3676</Para>
3677
3678</Sect2>
[40647f5]3679
[e189be2]3680<Sect2><Title>Organise my surveys</Title>
[fbc41c2]3681
3682<Para>This is actually a large subject. There are many ways you can
[6af6d51]3683organise your data using <Application>Survex</Application>. Take a look at the example dataset
[40647f5]3684for some ideas of ways to go about it.
[e189be2]3685</Para>
[40647f5]3686
[e189be2]3687<Sect3><Title>Fixed Points (Control Points)</Title>
[fbc41c2]3688
[f9dc4a0]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.
[e189be2]3692</Para>
3693
3694</Sect3>
[fbc41c2]3695
[e189be2]3696<Sect3><Title>More than one survey per trip</Title>
[fbc41c2]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
[e74904e]3700want to give a different survey name to the two sections.  This is easily
[fbc41c2]3701achieved like so:
[e189be2]3702</Para>
[fbc41c2]3703
3704<programlisting>
[40647f5]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
[fbc41c2]3714*end</programlisting>
[40647f5]3715
[e189be2]3716</Sect3>
3717
3718</Sect2>
3719
[419befc]3720<Sect2><Title>Add surface topography</Title>
[fbc41c2]3721
[705aaedd]3722<Para>Survex 1.2.18 added support for loading terrain data and rendering it as
[c0a12f9]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.
[705aaedd]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.
[f9dc4a0]3732</Para>
3733
3734<Para>
3735It is possible to generate
[705aaedd]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
[f9dc4a0]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
[6af6d51]3755<Para>If you're using another program to generate a <filename>.svx</filename> file for the surface
[f9dc4a0]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
[27b8b59]3775*data nosurvey station
[f9dc4a0]3776
[27b8b59]377700
377801
377902
[f9dc4a0]3780
[27b8b59]378110
378211
378312
[f9dc4a0]3784
[27b8b59]378520
378621
378722
[f9dc4a0]3788
[27b8b59]378900
379010
379120
[f9dc4a0]3792
[27b8b59]379301
379411
379521
[f9dc4a0]3796
[27b8b59]379702
379812
379922</programlisting>
[f9dc4a0]3800
3801<Para>
3802This is far simpler than trying to create fake tape/compass/clino legs of
[eb48e2b]3803the right length for each line in the mesh.  It's also very fast to process
[f9dc4a0]3804with cavern.
3805</Para>
3806
[e189be2]3807</Sect2>
3808
3809<Sect2><Title>Overlay a grid</Title>
[fbc41c2]3810
[f9dc4a0]3811<Para>Aven is able to display a grid, but this functionality isn't currently
[4e8d288]3812available in printouts.
[6af6d51]3813You can achieve a similar effect for now by creating a <filename>.svx</filename> file
[e74904e]3814where the survey legs form a grid.
[e189be2]3815</Para>
[fbc41c2]3816
[e189be2]3817</Sect2>
3818
3819<Sect2><Title>Import data from other programs</Title>
[fbc41c2]3820
[6af6d51]3821<Para><Application>Survex</Application> supports a number of features to help with importing
[fbc41c2]3822existing data. You can specify the ordering of items on a line using *Data
[6af6d51]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).
[e189be2]3825</Para>
[fbc41c2]3826
[c1573d8]3827<Para>The Ignore and Ignoreall options to the *Data command are often
[fbc41c2]3828particularly useful, e.g. if you have a dataset with LRUD info or comments
3829on the ends of lines.
[e189be2]3830</Para>
[fbc41c2]3831
[e6aa3b1]3832<Sect3><Title>Changing Meanings of Characters</Title>
[fbc41c2]3833
[e6aa3b1]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:
[e189be2]3837</Para>
[fbc41c2]3838
3839<programlisting>
[e6aa3b1]3840*SET NAMES ?+</programlisting>
[fbc41c2]3841
[e189be2]3842<Para>
[e6aa3b1]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.
[e189be2]3846</Para>
[fbc41c2]3847
3848<Para>If your data uses a comma ',' instead of a decimal point, then
[40647f5]3849you use
[e189be2]3850</Para>
[fbc41c2]3851
3852<programlisting>
3853*SET DECIMAL ,</programlisting>
3854
3855<Para>to specify that ',' is now the decimal separator instead of '.'.
[e189be2]3856</Para>
[fbc41c2]3857
[e74904e]3858<!-- FIXME
[fbc41c2]3859<Para>Note that there are plenty of ways you can use this facility to
[6aef4f1]3860completely confuse the software, as it may not be able to work out what is
[c1573d8]3861going on, or it may simply be ambiguous. It can cope with some ambiguity (e.g.
[6aef4f1]3862the '-' character is used both for 'MINUS' and for 'OMIT'), but there are
[6af6d51]3863limits. If you have a dataset that you can not make <Application>Survex</Application>
[6aef4f1]3864understand, then send it to us, and we will see what can be done.
[e189be2]3865</Para>
[e74904e]3866-->
[e189be2]3867
3868</Sect3>
[fbc41c2]3869
[49920d0]3870<!--
3871 Nobody seems to have the CfH convertor...
3872 but it's probably no longer useful anyway
3873
[e189be2]3874<Sect3><Title>Other Converters</Title>
[fbc41c2]3875
3876<Para>We have an Excel 5 macro for converting The Lotus 123 spreadsheets
[40647f5]3877used by the German survey software Cad F&uuml;r H&ouml;hlen into
[6af6d51]3878<Application>Survex</Application> data files. Other converters may also come to be available.
[ff003b3]3879These will normally be available via the
[d417499]3880<ulink url="https://survex.com/"><Application>Survex</Application> Web pages</ulink>.
[e189be2]3881</Para>
3882
3883</Sect3>
[dcc1947]3884-->
3885
[e189be2]3886</Sect2>
[40647f5]3887
[6af6d51]3888<Sect2><Title>Export data from <Application>Survex</Application></Title>
[fbc41c2]3889
[e6aa3b1]3890<Para>See Rosetta Stal in the Related Tools section of the Survex web
[eb48e2b]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>
[e189be2]3895
3896</Sect2>
[40647f5]3897
[e189be2]3898<Sect2><Title>See errors and warnings that have gone off the screen</Title>
[fbc41c2]3899
[6af6d51]3900<Para>When you run <Application>Survex</Application> it will process the specified survey data
[e74904e]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.
[e189be2]3906</Para>
[fbc41c2]3907
[e74904e]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.
[e189be2]3911</Para>
3912
[38335b7]3913<!-- <command>cavern cavename &gt; tmpfile</command> -->
[fbc41c2]3914
[e189be2]3915</Sect2>
3916
3917<Sect2><Title>Create an Extended Elevation</Title>
[fbc41c2]3918
[6af6d51]3919<Para>Use the Extend program. This takes <filename>.3d</filename> files and
[c1573d8]3920'flattens' them.  See 'Extend' for details.
[e189be2]3921</Para>
3922
3923</Sect2>
[fbc41c2]3924
[e189be2]3925</Sect1>
3926
[6048971]3927<!--
[e189be2]3928<Sect1><Title>Appendices</Title>
[0d62afe]3929<?dbhtml filename="appendix.htm">
[fbc41c2]3930
3931<Para>Files provided
[e189be2]3932</Para>
[fbc41c2]3933
3934<Para>Command specification
[e189be2]3935</Para>
3936
3937</Sect1>
[6048971]3938-->
[b462168]3939<Sect1><Title>Working with Larry Fish's Compass</Title>
[0d62afe]3940<?dbhtml filename="compass.htm">
[b462168]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
[6af6d51]3945use <command>*include compassfile.dat</command> in a <filename>.svx</filename> file and
[b462168]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>
[40647f5]3971
[e189be2]3972<Sect1><Title>Mailing List</Title>
[0d62afe]3973<?dbhtml filename="maillist.htm">
[40647f5]3974
[8ed91e39]3975<Para>The best way to contact the authors and other Survex users is the
3976Survex mailing list - for details visit:
[d417499]3977<ulink url="https://survex.com/maillist.html">https://survex.com/maillist.html</ulink>
[e189be2]3978</Para>
[40647f5]3979
[6af6d51]3980<Para>We'd be delighted to hear how you get on with <Application>Survex</Application> and
[018db6f]3981welcome comments and suggestions for improvements.</Para>
3982
3983<Para>
[6af6d51]3984And we'd love you to contribute your skills to help make <Application>Survex</Application> even
[018db6f]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.
[6c33e75]3989Or if you're a developer, <emphasis>"Say it with code"</emphasis>.  There's
[018db6f]3990plenty to do, so feel free to join in.
3991</Para>
3992
[e189be2]3993</Sect1>
3994
[375f7f6]3995<Sect1><Title>Future Developments</Title>
[0d62afe]3996<?dbhtml filename="future.htm">
[40647f5]3997
3998<Para>
[6af6d51]3999Now that <Application>Survex</Application> has reached version 1.0, we are continuing progress
[b462168]4000towards version 2, in a series of steps, evolving out of
4001Survex 1.0.  The GUI framework is being based on aven, with
[6048971]4002the printer drivers and other utility programs being pulled in
4003and integrated into the menus.</Para>
4004
[6af6d51]4005<Para>Aven is built on <Application>wxWidgets</Application>, which means that it can easily support
[8ed91e39]4006Unix, Microsoft Windows, and Mac OS X.</Para>
[6048971]4007
[b462168]4008<Para>More information on our plans is on the <ulink
[d417499]4009url="https://survex.com/">web site</ulink>.
[e189be2]4010</Para>
4011
[647407d]4012</Sect1>
[375f7f6]4013
[6eadc5b]4014</article>
Note: See TracBrowser for help on using the repository browser.