[ci] Add a separate job which makes tarballs

[survex.git] / doc / manual.sgml

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
<!ENTITY man.aven SYSTEM "aven.sgml">
<!ENTITY man.cavern SYSTEM "cavern.sgml">
<!ENTITY man.diffpos SYSTEM "diffpos.sgml">
<!ENTITY man.dump3d SYSTEM "dump3d.sgml">
<!ENTITY man.extend SYSTEM "extend.sgml">
<!ENTITY man.sorterr SYSTEM "sorterr.sgml">
<!ENTITY man.survexport SYSTEM "survexport.sgml">
]>

<!--
FIXME:

3dfile title:
defaults to a list of the leafnames of the <filename>.svx</filename> files specified on the
command line (with any paths and extensions removed).
.
e.g.: cavern entrance.svx \data\2ndpart.svx
.
would give a surveytitle of 'entrance 2ndpart'.
.
but this may change...

FIXME todo:
mark-up of Windows Windows NT etc?
section on "design philosophy"

level sump fudge:

*begin
*data cartesian from to dx dy dz
*sd dx dy 100 metres
*sd dz 0.001 metres
; upstream - downstream
nuiping.gowiththeflow.129 dachao.upstream.105 0 0 0 ; last number is drop in height across the sump
*end

``Quick start'' section

- install (by OS): unpacking, configuration (language, where support files live)

- lead people through entering and processing
a sample survey.  Take examples from surveying books and real surveys.


<Para>The other really important commands apart from *BEGIN, *END, and
*INCLUDE are *EQUATE and *FIX.
</Para>

<Para>*EQUATE is used to join surveys together, e.g.
</Para>

<programlisting>*equate entrance.6 adrian.1</programlisting>

<Para>
indicates that station 6 of the entrance survey was used as
the station 1 of the Adrian's Route survey.
</Para>

<Para>*FIX is for fixing control points - for example:
</Para>

<programlisting>
*fix 161.entrance.1    0  0  1780</programlisting>

<Para>fixes the 1st point of the 'entrance' survey at the coordinates
0 (east-west), 0 (north-south), 1780 (altitude).
</Para>


<term>node</term>
<listitem><para>when talking about the survey network, we talk about an
<emphasis>n</emphasis>-node to describe the number of connections to
a station.  So a 1-node is a station with only 1 leg to or from it
- i.e. The end of a passage or survey. A
2-node is a typical station along a passage with a survey leg coming
into it, and one going out.  A 3-node is a station with three legs
joining it, e.g. at a T-junction. And so on.
</para>

-->

<article Status="draft" id="index">
 <articleinfo>
  <Title><Application>Survex</Application> <!--VERSION-->1.4.8 Manual</Title>
  <AuthorGroup>
   <Author>
    <FirstName>Olly</FirstName>
    <SurName>Betts</SurName>
    <AuthorBlurb><Para>
      Olly Betts wrote most of <Application>Survex</Application>.
    </Para></AuthorBlurb>
    <Affiliation>
     <Address><Email>olly@survex.com</Email></Address>
    </Affiliation>
   </Author>
   <Author>
    <SurName>Wookey</SurName>
    <AuthorBlurb><Para>
      Wookey is a small furry creature.
    </Para></AuthorBlurb>
    <Affiliation>
     <Address><Email>wookey@survex.com</Email></Address>
    </Affiliation>
   </Author>
  </AuthorGroup>
  <copyright>
   <year>1998-2018</year>
   <holder role="mailto:olly@survex.com">Olly Betts</holder>
  </copyright>
  <Abstract>
   <Para>
    This is the manual for <Application>Survex</Application> - an open-source software package for
    cave surveyors.
   </Para>
  </Abstract>
 </articleinfo>

<Sect1><Title>Introduction</Title>
<?dbhtml filename="intro.htm">

<Para>
This section describes what <Application>Survex</Application> is, and outlines the scope of this
manual.
</Para>

<Sect2><Title>About <Application>Survex</Application></Title>

<Para><Application>Survex</Application> is a multi-platform open-source cave surveying
package.
Versions 1.2 and later run on UNIX, Microsoft Windows, and macOS.
We're investigating support for phones and tablets.
</Para>

<Para>We are well aware that not everyone has access to super hardware
- often surveying projects are run on little or no budget and any
computers used are donated.  We aim to ensure that <Application>Survex</Application> is
feasible to use on low-spec machines.  Obviously it won't be as
responsive, but we intend it to be usable.
Please help us to achieve this by giving us some feedback
if you use <Application>Survex</Application> on a slow machine.</Para>

<Para><Application>Survex</Application> is capable of processing extremely complex caves very
quickly and has a very effective, real-time cave viewer which allows
you to rotate, zoom, and pan the cave using mouse or keyboard. We have
tested it extensively using <Acronym>CUCC</Acronym> and <Acronym>ARGE</Acronym>'s surveys of the caves
under the Loser Plateau in Austria (over 25,000 survey legs, and over
140km of underground survey data). This can all be processed in around
10 seconds on a low-end netbook.
Survex is also used by many other survey projects around the world,
including the 
<ulink url="http://www.oucc.org.uk/draenen/draenenmain.htm"
>Ogof Draenen</ulink> survey, the 
<ulink url="http://www.easegill.org.uk/">Easegill</ulink> resurvey project,
the <Acronym>OFD</Acronym> survey, the 
<!-- url="http://milos2.zoo.ox.ac.uk/~oucc/reports/surveys/surveys.htm" -->
<ulink url="http://www.oucc.org.uk/reports/surveys/surveys.htm"
><Acronym>OUCC</Acronym> Picos expeditions</ulink>, and the 
<ulink url="http://www.hongmeigui.net/">Hong Meigui China
expeditions</ulink>. <!-- FIXME more? --></Para>

<Para><Application>Survex</Application> is still actively being worked on.  Version 1.0 was
complete in some sense, but development continues - initially in reshaping
Survex into a more integrated GUI package.</Para>

<Para>We encourage feedback from users on important features or problems,
which will help to direct future development.  See the "Mailing List" section
of this manual for the best way to contact us.</Para>

</Sect2>

<!--
<Para>Because <Application>Survex</Application> is still being actively developed, this document
has an unfortunate tendency to lag slightly behind the capabilities of the
software. The latest version is now available on the web at <ulink
url="https://survex.com/">https://survex.com/</ulink> - check there for latest info.
</Para>
-->

<!--
<Sect2><Title>Other Documentation</Title>

<variablelist>
<varlistentry>
<term>NEWS or NEWS.txt</term>
<listitem><Para>a list of changes of interest to
<Application>Survex</Application> users, broken down by version number.  Consult this file
when upgrading to find out what has changed since the version you were
using previously.
</Para></listitem>
</varlistentry>

<varlistentry>
<term>ChangeLog or CHANGES.txt</term>
<listitem><Para>a much more detailed list of changes, aimed at developers
rather than end users.
</Para></listitem>
</varlistentry>

<varlistentry>
<term>BUGS or BUGS.txt</term>
<listitem><Para>a list of known bugs.
</Para></listitem>
</varlistentry>

<varlistentry>
<term>TODO or TODO.txt</term>
<listitem><Para>planned changes and enhancements.
</Para></listitem>
</varlistentry>

FIXME: merge INSTALL* into here, then process separately and textify
to produce INSTALL*

<varlistentry>
<term>INSTALL or INSTALL.txt</term>
<listitem><Para>instructions for installing <Application>Survex</Application>.  The
Microsoft Windows version comes packaged up with an installation wizard,
so this file doesn't exist there (you just run the package and follow
the on-screen instructions).
</Para></listitem>
</varlistentry>
</variablelist>

</Sect2>
-->

<Sect2><Title>About this Manual</Title>

<Para>
If there's a part of this manual you find hard to understand, please do
let us know.  We already know Survex well, so it can be hard for us
to spot areas where the manual doesn't given enough information, or
doesn't explain things clearly enough to follow when you don't know what's
going on.  It's helpful is you can suggest a better wording, but don't worry
if you can't, just explain the problem as precisely as you can.
</Para>

<Para>
The master version of this manual is an <acronym>SGML</acronym>
document written using the <ulink url="http://www.docbook.org/">docbook
<acronym>DTD</acronym></ulink>,
and automatically converted to a number of other formats.  If
you are going to send us <emphasis>major</emphasis> changes, it's much easier
to include them if you work from this master.  You can get it
from the source archive (docs/manual.sgml) or from <ulink
url="https://survex.com/docs.html">the Survex website</ulink>.
</Para>

<Sect3><Title>Terminology</Title>

<Para>Throughout this document we use British terminology for
surveying.</Para>

<variablelist>
<varlistentry>
<term>station</term>
<listitem><para>a point in the cave that you survey from and/or to
</para></listitem></varlistentry>

<varlistentry>
<term>leg</term>
<listitem><para>a line joining two stations
</para></listitem></varlistentry>

<varlistentry>
<term>survey</term>
<listitem><para>a group of legs surveyed on the same trip
</para></listitem></varlistentry>

</variablelist>

</Sect3>

</Sect2>

<!-- FIXME: Further sources of info: website, mailing lists, other docs -->

</Sect1>

<Sect1><Title>Getting Started</Title>
<?dbhtml filename="getstart.htm">

<Para>This section covers how to obtain the software, and how to unpack and
install it, and how to configure it.</Para>

<Sect2><Title>Obtaining <Application>Survex</Application></Title>

<Para>The latest version is available from the <Application>Survex</Application> website:
<ulink url="https://survex.com/">https://survex.com/</ulink>.  It is also
freely redistributable, so you welcome to get a copy from someone else
who has already downloaded it.</Para>

<Para>If you want some sample data to experiment with, you can download some
from the Survex website too:
<ulink url="https://survex.com/software/sample.tar.gz">https://survex.com/software/sample.tar.gz</ulink></Para>

</Sect2>

<Sect2><Title>Installing <Application>Survex</Application></Title>

<Para>The details of installation depend greatly on what platform you
are using, so there is a separate section below for each platform.</Para>

<Sect3><Title>Linux</Title>

<Para>
Pre-built versions of Survex are available for some Linux distributions.
See the <ulink url="https://survex.com/download.html?platform=linux">Survex
for Linux download page</ulink> on our website for up-to-date information.
</Para>

<Para>
You'll need root access to install these prebuilt packages.
If you don't have root access you will need to build from source
(see the next section).
</Para>

<!-- FIXME Add Gnome file association note for Linux/Unix
<Para>On Microsoft Windows, <Application>Survex</Application> installs with
suitable file associations so that you can drive it from the GUI.
On UNIX you need to drive <Application>Survex</Application> from a command-line
prompt (or set some a filemanager or graphics shell).
</Para>
-->

</Sect3>

<Sect3><Title>macOS</Title>

<Para>
The easiest way to install a recent release of Survex on macOS is by using
the Homebrew package manager. If you don't already use Homebrew, you'll
need to install it first.  See the
<ulink url="https://survex.com/download.html?platform=macosx">macOS
download page on the website</ulink> for installation instructions.
</Para>

</Sect3>

<Sect3><Title>Other versions of UNIX</Title>

<Para>For other UNIX versions you'll need to get the source code
and compile it on your system.  Unpack the sources and read
the file called INSTALL in the top level for details about building
from source.
</Para>

</Sect3>

<Sect3><Title>Microsoft Windows</Title>

<Para>
This version comes packaged with an installation wizard.  Just
run the downloaded package and it will lead you through the
installation process.
</Para>

<Para>
Survex 1.4.8 and later support installing for all users (which requires
administrator rights) or just for the current user (which doesn't).
If installed for just the current user, other user accounts won't see
the file associations, menu entries, desktop icons, etc for Survex.
</Para>

<Para>
Note that if you have an existing installation the installer will see
it and try to upgrade it, and if that installation was done with administrator
rights (which any installation of 1.4.7 or earlier will be) you'll also
need administrator rights to upgrade.  To change to a non-admin installation
you need to first uninstall the existing admin install (which will need admin
rights) then install the new version.
</Para>

<Para>
The survey viewer that's part of <Application>Survex</Application> is called
aven, and uses OpenGL for 3d rendering.
</Para>

<Para>
If you find that 3D rendering is sometimes very slow (e.g. one user reported
very slow performance when running full screen, while running in a window
was fine) then try installing the OpenGL driver supplied by the manufacturer
of your graphics card rather than the driver Microsoft supply.
</Para>

<Para>
The installer creates a Survex group in the Programs sub-menu of the
Start menu containing the following items:
</Para>

<ItemizedList>

<ListItem><Para>Aven</Para></ListItem>

<ListItem><Para>Documentation</Para></ListItem>

<ListItem><Para>Uninstall Survex</Para></ListItem>

</ItemizedList>

<Para>
Icons are installed for <filename>.svx</filename>, <filename>.3d</filename>, <filename>.err</filename>, and <filename>.pos</filename> files, and also for
Compass Plot files (<filename>.plt</filename> and <filename>.plf</filename>)
(which Survex can read). <!-- FIXME XYZ -->
Double-clicking on a <filename>.svx</filename> file loads it for editing.  To process it to
produce a <filename>.3d</filename> file, right click and choose "Process" from
the menu - this runs aven to process the <filename>.svx</filename> file and
automatically load the resultant <filename>.3d</filename> file.
All the <Application>Survex</Application> file types can be right clicked on to give a menu of
possible actions.  
</Para>

<VariableList>
<VarListEntry><Term><filename>.svx</filename></Term>
<ListItem>
  <VariableList>
  <VarListEntry><Term>Process</Term>
  <ListItem><Para>
  Process file with aven to produce <filename>.3d</filename> file (and <filename>.err</filename> file)
  </Para></ListItem>
  </VarListEntry>
  </VariableList>
</ListItem>
</VarListEntry>
    
<VarListEntry><Term><filename>.3d</filename></Term>
<ListItem>
  <VariableList>
  <VarListEntry><Term>Open</Term>
  <ListItem><Para>
  Load file into Aven
  </Para></ListItem>
  </VarListEntry>
  <VarListEntry><Term>Print</Term>
  <ListItem><Para>
  Print the file via Aven
  </Para></ListItem>
  </VarListEntry>
  <VarListEntry><Term>Extend</Term>
  <ListItem><Para>
  Produce extended elevation
  </Para></ListItem>
  </VarListEntry>
  <VarListEntry><Term>Convert to DXF</Term>
  <ListItem><Para>
  This entry used to be provided to allow converting to a DXF file (suitable
  for importing into many CAD packages) but this functionality is now available
  from inside Aven with the ability to control what is exported, and this entry
  was dropped in 1.2.35.
  </Para></ListItem>
  </VarListEntry>
  <VarListEntry><Term>Convert for hand plotting</Term>
  <ListItem><Para>
  This entry used to be provided to allow converting to a <filename>.pos</filename> file
  listing all the stations and their coordinates, but this functionality is now
  available from inside Aven with the ability to control what is exported, and
  this entry was dropped in 1.2.35.
  </Para></ListItem>
  </VarListEntry>
  </VariableList>
</ListItem>
</VarListEntry>

<VarListEntry><Term><filename>.err</filename></Term>
<ListItem>
  <VariableList>
  <VarListEntry><Term>Open</Term>
  <ListItem><Para>
  Load file into Notepad
  </Para></ListItem>
  </VarListEntry>
  <VarListEntry><Term>Sort by Error</Term>
  <ListItem><Para>
  Sort <filename>.err</filename> file by the error in each traverse
  </Para></ListItem>
  </VarListEntry>
  <VarListEntry><Term>Sort by Horizontal Error</Term>
  <ListItem><Para>
  Sort <filename>.err</filename> file by the horizontal error in each traverse
  </Para></ListItem>
  </VarListEntry>
  <VarListEntry><Term>Sort by Vertical Error</Term>
  <ListItem><Para>
  Sort <filename>.err</filename> file by the vertical error in each traverse
  </Para></ListItem>
  </VarListEntry>
  <VarListEntry><Term>Sort by Percentage Error</Term>
  <ListItem><Para>
  Sort <filename>.err</filename> file by the percentage error in each traverse
  </Para></ListItem>
  </VarListEntry>
  <VarListEntry><Term>Sort by Error per Leg</Term>
  <ListItem><Para>
  Sort <filename>.err</filename> file by the error per leg in each traverse
  </Para></ListItem>
  </VarListEntry>
  </VariableList>
</ListItem>
</VarListEntry>
</VariableList>

</Sect3>

</Sect2>

<Sect2><Title>Configuration</Title>

<Sect3><Title>Selecting Your Preferred Language</Title>

<Para>Survex has extensive internationalisation capabilities.  The
language used for messages from Survex and most of the library calls
it uses can be changed.  By default this is picked up from the
language the operating system is set to use (from "Regional Settings"
in Control Panel on Microsoft Windows, from the
<systemitem>LANG</systemitem> environment variable on UNIX
If no setting
is found, or <Application>Survex</Application> hasn't been translated into the
requested language, UK English is used.</Para>

<Para>
However you may want to override the language manually -
for example if Survex isn't available in your native language
you'll want to choose the supported language you understand best.
</Para>

<Para>
To do this, you set the
<systemitem>SURVEXLANG</systemitem> environment variable.  Here's a list
of the codes currently supported:</Para>

<informaltable frame="all">
<tgroup cols="2">
<thead>
<row><entry>Code</entry><entry>Language</entry></row>
</thead>
<tbody>
<row><entry>en</entry><entry>International English</entry></row>
<row><entry>en_US</entry><entry>US English</entry></row>
<row><entry>bg</entry><entry>Bulgarian</entry></row>
<row><entry>ca</entry><entry>Catalan</entry></row>
<row><entry>de</entry><entry>German</entry></row>
<row><entry>de_CH</entry><entry>Swiss German</entry></row>
<row><entry>el</entry><entry>Greek</entry></row>
<row><entry>es</entry><entry>Spanish</entry></row>
<row><entry>fr</entry><entry>French</entry></row>
<row><entry>hu</entry><entry>Hungarian</entry></row>
<row><entry>id</entry><entry>Indonesian</entry></row>
<row><entry>it</entry><entry>Italian</entry></row>
<row><entry>pl</entry><entry>Polish</entry></row>
<row><entry>pt</entry><entry>Portuguese</entry></row>
<row><entry>pt_BR</entry><entry>Brazillian Portuguese</entry></row>
<row><entry>ro</entry><entry>Romanian</entry></row>
<row><entry>ru</entry><entry>Russian</entry></row>
<row><entry>sk</entry><entry>Slovak</entry></row>
<row><entry>zh_CN</entry><entry>Chinese (Simplified)</entry></row>
</tbody>
</tgroup>
</informaltable>

<Para>Here are examples of how to set this environment variable to give
messages in French (language code fr):</Para>

<VariableList>
 <VarListEntry><Term>Microsoft Windows</Term>
   <ListItem><Para>
For MS Windows proceed as follows (this description was written from
MS Windows 2000, but it should be fairly similar in other versions): Open the
Start Menu, navigate to the Settings sub-menu, and
open Control Panel.  Open System (picture of a computer) and click on the
Advanced tab.  Choose `Environmental Variables', and create a new one: name
<systemitem>SURVEXLANG</systemitem>, value <systemitem>fr</systemitem>.
Click OK and the new value should be effective immediately.
   </Para></ListItem>
 </VarListEntry>
 <VarListEntry><Term>UNIX - csh/tcsh</Term>
   <ListItem><Para><userinput>setenv SURVEXLANG fr</userinput></Para></ListItem>
 </VarListEntry>
 <VarListEntry><Term>UNIX - sh/bash</Term>
   <ListItem><Para><userinput>SURVEXLANG=fr ; export SURVEXLANG</userinput></Para></ListItem>
 </VarListEntry>
</VariableList>

<Para>If <Application>Survex</Application> isn't available in your language, you could
help out by providing a translation.  The initial translation is
likely to be about a day's work; after that translations for
new or changed messages are occasionally required.  Contact us for details
if you're interested.</Para>

</Sect3>

</Sect2>

<Sect2><Title>Using <Application>Survex</Application></Title>

<Para>
Most common tasks can now be accomplished through Aven - processing survey
data, viewing the processed data, printing, exporting to other formats,
and producing simple extended elevations.
</Para>

<Para>
A few tasks still require you to use the command line.  And some functionality
is available both via aven and from the command line, which allows it to be
scripted.
</Para>

<Para>
The command line programs that come with Survex are:
</Para>

<VariableList>

<VarListEntry><Term>extend</Term>
    <listitem><Para>
        Produces extended elevations - this is probably the most useful of
        these command line tools.  Since version 1.2.27 you can produce simple
        extended elevations from Aven using the "Extended Elevation" function.
        However the command line tool allows you to specify a spec file to
        control how the survey is extended, which you can't currently do via
        Aven.
    </Para></listitem>
</VarListEntry>

<VarListEntry><Term>diffpos</Term>
    <listitem><Para>
        Compares the positions of stations in two .3d, .pos, etc files.
    </Para></listitem>
</VarListEntry>

<VarListEntry><Term>sorterr</Term>
    <listitem><Para>
         Sorts a .err file by a specified field.
    </Para></listitem>
</VarListEntry>

<VarListEntry><Term>survexport</Term>
    <listitem><Para>
        Provides access to Aven's "Export" functionality from the command line,
        which can be useful in scripts.
    </Para></listitem>
</VarListEntry>

<VarListEntry><Term>cavern</Term>
    <listitem><Para>
        Processes survey data, but since version 1.2.3 you can process .svx
        files by simply opening them with Aven, so you no longer need to run
        cavern from the command line.  The main reason to run cavern directly
        is for use in scripts.
    </Para></listitem>
</VarListEntry>

<VarListEntry><Term>dump3d</Term>
    <listitem><Para>
        Dumps out a list of the items in a .3d file - it's mainly useful for
        debugging.
    </Para></listitem>
</VarListEntry>

</VariableList>

</Sect2>

</Sect1>

<!-- FIXME

type in .svx file

run cavern (through aven)

run aven

how to print/export etc

-->

<!-- FIXME perhaps move this after data files section? -->
<Sect1><Title>Survex Programs</Title>
<?dbhtml filename="cmdline.htm">

<Sect2><Title>Standard Options</Title>

<Para>All <Application>Survex</Application> programs respond to the following command line options:
</Para>

<VariableList>

<VarListEntry><Term>--help</Term><listitem><Para>
display option summary and exit
</Para></listitem></VarListEntry>

<VarListEntry><Term>--version</Term><listitem><Para>
output version information and exit
</Para></listitem></VarListEntry>

</VariableList>

</Sect2>

<Sect2><Title>Short and Long Options</Title>

<Para>
Options have two forms: short (a dash followed by a single letter e.g.
<command>cavern -q</command>) and long (two dashes followed by one or more words e.g.
<command>cavern --quiet</command>).  The long form is generally easier to
remember, while the short form is quicker to type.  Options are often
available in both forms.
</Para>

<Note><Para>Command line options are case sensitive, so "-B" and "-b"
are different (this didn't used to be the case before Survex 0.90).  Case
sensitivity doubles the number of available short options (and is also the
norm on UNIX).
</Para></Note>
</Sect2>

<Sect2><Title>Filenames on the Command Line</Title>

<Para>Filenames with spaces can be processed (provided your operating system
supports them - UNIX does, and so do modern versions of Microsoft
Windows).  You need to enclose the filename in quotes like so:
<userinput>cavern "Spider Cave"</userinput>
</Para>

<Para>A file specified on the command line of any of the <Application>Survex</Application> suite
of programs will be looked for as specified.  If it is not found, then the
file is looked for with the appropriate extension appended.  So
<userinput>cavern survey</userinput> will look first for
<filename>survey</filename>, then for <filename>survey.svx</filename>.
</Para>

</Sect2>

<Sect2><title>Command Reference</title>

<refentry id="cavern">
<?dbhtml filename="cavern.htm">
&man.cavern;
</refentry>
<refentry id="aven">
<?dbhtml filename="aven.htm">
&man.aven;
</refentry>
<refentry id="diffpos">
<?dbhtml filename="diffpos.htm">
&man.diffpos;
</refentry>
<refentry id="extend">
<?dbhtml filename="extend.htm">
&man.extend;
</refentry>
<refentry id="sorterr">
<?dbhtml filename="sorterr.htm">
&man.sorterr;
</refentry>
<refentry id="survexport">
<?dbhtml filename="survexport.htm">
&man.survexport;
</refentry>

</Sect2>

</Sect1>

<Sect1><Title><Application>Survex</Application> data files</Title>
<?dbhtml filename="datafile.htm">

<Para>Survey data is entered in the form of text files. You can use any
text editor you like for this, so long as it has the capability of
writing a plain ASCII text file. The data format is very flexible;
unlike some other cave surveying software, Survex does not require
survey legs to be rearranged to suit the computer, and the ordering 
of instrument readings on each line is fully specifiable.  So you can enter
your data much as it appears on the survey notes, which is important
in reducing the opportunities for transcription errors.
</Para>

<Para>
Also all the special characters are user-definable - for example,
the separators can be spaces and tabs, or commas (e.g. when exporting from a
spreadsheet), etc; the decimal point can be a slash (for clarity), a comma
(as used in continental Europe), or anything else you care to choose.
This flexibility
means that it should be possible to read in data from almost any sort of
survey data file without much work.
</Para>

<Para><Application>Survex</Application> places no restrictions on you in terms of the ordering
of survey legs. You can enter or process data in any order and <Application>Survex</Application> will
read it all in before determining how it is connected. You can also use the
hierarchical naming so that you do not need to worry about using the same
station name twice.
</Para>

<!-- FIXME don't encourage separate processing -->
<Para>The usual arrangement is to have one file which lists all the others
that are included (e.g., <filename>161.svx</filename>). Then
<command>cavern 161</command> will process all your data. To just process a
section use the filename for that section, e.g. <command>cavern dtime</command>
will process the dreamtime file/section of Kaninchenh&ouml;hle.  To
help you out, if all legs in a survey are connected to one another
but the survey has no fixed points, cavern
will 'invent' a fixed point and print a warning message to this
effect.
</Para>

<Para>
It is up to you what data you put in which files.  You
can have one file per trip, or per area of the cave, or just one
file for the whole cave if you like.
On a large survey project it makes sense to group related surveys in the
same file or directory.
</Para>
<!-- FIXME: wook sez:

 Point out in documentation that file structure and survey structure don't
 have to be the same.  And in particular that folder/directory names can be
 different.

Which is partly covered above, though the last bit isn't... 
-->

<!-- FIXME "Anatomy of a Survey" section -->
<Sect2><Title>Readings</Title>

<Para>Blank lines (i.e. lines consisting solely of BLANK characters)
are ignored. The last line in the file need not be terminated by
an end of line character. All fields on a line must be separated
by at least one BLANK character. An OMIT character
(default '-') indicates that a field is unused. If the field is
not optional, then an error is given.
</Para>

</Sect2>

<Sect2><Title>Survey Station Names</Title>

<Para><Application>Survex</Application> has a powerful system for naming stations.  It
uses a hierarchy of survey names, similar to the nested folders
your computer stores files in.
So point 6 in the entrance survey of Kaninchenh&ouml;hle
(cave number 161) is referred to as: 161.entrance.6
</Para>

<Para>This seems a natural way to refer to station names.  It also
means that it is very easy to include more levels, for example if you
want to plot all the caves in the area you just list them all in
another file, specifying a new prefix.  So to group 3 nearby caves
on the Loser Plateau you would use a file like
this:
</Para>

<programlisting>
*begin Loser
*include 161
*include 2YrGest
*include 145
*end Loser</programlisting>

<Para>
The entrance series point mentioned above would now be referred
to as: Loser.161.entrance.6
</Para>

<!--
<Para>This may seem a tad complex but is really very natural once you
get the hang of it.
</Para>
-->
<Para>You do not have to use this system at all, and can just give all
stations unique identifiers if you like:
</Para>

<Para>1, 2, 3, 4, 5, ... 1381, 1382
</Para>

<Para>or
</Para>

<Para>AA06, AA07, P34, ZZ6, etc.
</Para>

<!-- FIXME:
<Para>However you'll loose the ability to handle subsurveys if you do.
</Para>
-->

<Para>Station and survey names may contain any alphanumeric characters and
additionally any characters in NAMES (default `_' and `-'). Alphabetic
characters may be forced to upper or lower case by using the *case
command. Station names may be any length - if you want to only treat
the first few characters as significant you can get cavern to truncate
the names using the *truncate command.
</Para>

<Sect3><Title>Anonymous Stations</Title>

<Para>
Survex supports the concept of anonymous survey stations.  That is
survey stations without a name.  Each time an anonymous station name is
used it represents a different point.  Currently three types of anonymous
station are supported, referred to by one, two or three separator characters
- with the default separator of '.', that means '.', '..', and '...' are
anonymous stations.  Their meanings are:</Para>

<VariableList>
<VarListEntry><Term>Single separator ('.' by default)</Term>
<ListItem><Para>
An anonymous non-wall point at the end of an implicit splay.
</Para></ListItem></VarListEntry>

<VarListEntry><Term>Double separator ('..' by default)</Term>
<ListItem><Para>
An anonymous wall point at the end of an implicit splay.
</Para></ListItem></VarListEntry>

<VarListEntry><Term>Triple separator ('...' by default)</Term>
<ListItem><Para>
an anonymous point with no implicit flags on the leg (intended for cases like
a disto leg along a continuing passage).
</Para></ListItem></VarListEntry>
</VariableList>

<Para>
You can map '-' to '..' (for compatibility with data from pocket topo) using
the command:
</Para>

<programlisting>
*alias station - ..
</programlisting>

<Para>Support for anonymous stations and for '*alias station - ..' was added in
Survex 1.2.7.</Para>

</Sect3>

</Sect2>

<Sect2><Title>Numeric fields</Title>

<Para>[&lt;MINUS&gt;|&lt;PLUS&gt;] &lt;integer part&gt; [ &lt;DECIMAL&gt;
[ &lt;decimal fraction&gt; ] ]
</Para>

<Para>
or [&lt;MINUS&gt;|&lt;PLUS&gt;] &lt;DECIMAL&gt; &lt;dec fraction&gt;
</Para>

<Para><!-- FIXME: put informal description first -->
i.e. optional PLUS or MINUS sign in front, with
optional DECIMAL character (default '.'), which may be
embedded, leading or trailing. No spaces are allowed between the
various elements.
</Para>

<Para>
All of these are valid examples: +47, 23, -22, +4.5, 1.3, -0.7, +.15, .4,
-.05
</Para>

</Sect2>

<Sect2><Title>Accuracy</Title>

<Para>Accuracy assessments may be provided or defaulted for any survey
leg. These determine the distribution of loop closure errors over the
legs in the loop. See *SD for more information.
</Para>

</Sect2>

<!--
<Sect2><Title>Survey Coordinate Range</Title>

<Para>
If we store distances to nearest 10um (0.01mm) in 4 bytes, this
gives a range of ~20 km. This method is currently not used, but
has several advantages (data storage space [double uses 8 bytes
- with my C compiler], speed (unless your FP chip works in parallel
with your CPU [e.g. the new Acorn FPU for the ARM], and numerical
accuracy [compared to using floats at least]) and so may be adopted
in future). Nearest 0.1mm gives -200 km, which is enough for most
people, but may mean rounding errors become significant. 
</Para>

<Para>
I will have to do some sums...
</Para>

</Sect2>

-->

<Sect2><Title>Cavern Commands</Title>

<Para>Commands in <filename>.svx</filename> files are introduced by an asterisk
(by default - this can be changed using the <command>set</command> command).
</Para>

<Para>The commands are documented in a common format:
</Para>

<!-- FIXME: make this a RefGroup (or whatever that's called) of RefEntry-s? -->
<itemizedlist>
<listitem><para>Command Name</para></listitem>
<listitem><para>Syntax</para></listitem>
<listitem><para>Example</para></listitem>
<listitem><para>Validity</para></listitem>
<!-- FIXME
anywhere, in a block, at start of a block, after a begin (for *end)
-->
<listitem><para>Description</para></listitem>
<listitem><para>Caveats</para></listitem>
<listitem><para>See Also</para></listitem>
<!-- FIXME
"Usefulness" - or status maybe?
deprecated, esoteric (*set), useful, vital
-->
</itemizedlist>

<Sect3><Title>ALIAS</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*alias station &lt;alias&gt; [&lt;target&gt;]</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*begin parsons_nose
*alias station - ..
1 2 12.21 073 -12
2 -  4.33 011 +02
2 -  1.64 180 +03
2 3  6.77 098 -04
*end parsons_nose</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>*alias allows you to map a station name which appears in
the survey data to a different name internally.  At present, you can only
create an alias of '-' to '..', which is intended to support the pocket topo
style notation of '-' being a splay to an anonymous point on the cave wall.
And you can unalias '-' with '*alias station -'.
</Para>

<Para>
Aliases are scoped by *begin/*end blocks - when a *end is reached, the aliases
in force at the corresponding begin are restored.
</Para>

<Para>
*alias was added in Survex 1.2.7.
</Para></listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<VarListEntry><Term>See Also</Term>

<listitem><Para>*begin, *end</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>BEGIN</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*begin [&lt;survey&gt;]</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*begin littlebit
1 2 10.23 106 -02
2 3  1.56 092 +10
*end littlebit</programlisting>

<programlisting>
; length of leg across shaft estimated
*begin
*sd tape 2 metres
9 10 6.   031 -07
*end</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>*begin stores the current values of the current settings
such as instrument calibration, data format, and so on.
These stored values are restored after the corresponding *end.
If a survey name is given, this is used inside the *begin/*end block,
and the corresponding *end should have the same survey name.
*begin/*end blocks may be nested to indefinite depth.
</Para></listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<VarListEntry><Term>See Also</Term>

<listitem><Para>*end, *prefix</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>CALIBRATE</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem>
<Para>*calibrate &lt;quantity list&gt; &lt;zero error&gt; [&lt;scale&gt;]
</Para>
<Para>*calibrate &lt;quantity list&gt; &lt;zero error&gt; &lt;units&gt; [&lt;scale&gt;]
</Para>
<Para>*calibrate default
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*calibrate tape +0.3
</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem>

<Para>
*calibrate is used to specify instrument calibrations, via a zero error
and an optional scale factor (which defaults to 1.0 if not specified).
Without an explicit calibration the zero error is 0.0 and the scale factor is
1.0.
</Para>

<Para>
&lt;quantity list&gt; is one or more of:
</Para>

<informaltable frame="all">
<tgroup cols="2">
<thead>
<row><entry>Quantity</entry><entry>Aliases</entry></row>
</thead>
<tbody>
<row><entry>LENGTH</entry><entry>TAPE</entry></row>
<row><entry>BEARING</entry><entry>COMPASS</entry></row>
<row><entry>GRADIENT</entry><entry>CLINO</entry></row>
<row><entry>BACKLENGTH</entry><entry>BACKTAPE</entry></row>
<row><entry>BACKBEARING</entry><entry>BACKCOMPASS</entry></row>
<row><entry>BACKGRADIENT</entry><entry>BACKCLINO</entry></row>
<row><entry>COUNT</entry><entry>COUNTER</entry></row>
<row><entry>LEFT</entry><entry></entry></row>
<row><entry>RIGHT</entry><entry></entry></row>
<row><entry>UP</entry><entry>CEILING</entry></row>
<row><entry>DOWN</entry><entry>FLOOR</entry></row>
<row><entry>DEPTH</entry><entry></entry></row>
<row><entry>DECLINATION</entry><entry></entry></row>
<row><entry>EASTING</entry><entry>DX</entry></row>
<row><entry>NORTHING</entry><entry>DY</entry></row>
<row><entry>ALTITUDE</entry><entry>DZ</entry></row>
<row><entry>DECLINATION</entry><entry></entry></row>
</tbody>
</tgroup>
</informaltable>

<Para>
The specified calibration is applied to each quantity in the list, which
is handy if you use the same instrument to measure several things, for
example:
</Para>

<programlisting>*calibrate left right up down +0.1</programlisting>

<Para>
You need to be careful about the sign of the ZeroError.  Survex follows
the convention used with scientific instruments - the ZeroError is what
the instrument reads when measuring a reading which should be zero.  So
for example, if your tape measure has the end missing, and you are using the
30cm mark to take all measurements from, then a zero distance would be measured
as 30cm and you would correct this with:
</Para>

<programlisting>*CALIBRATE tape +0.3</programlisting>

<Para>If you tape was too long, starting at -20cm (it does happen!)
then you can correct it with:
</Para>

<programlisting>*CALIBRATE tape -0.2</programlisting>

<Para>Note: ZeroError is irrelevant for Topofil counters and depth
gauges since pairs of readings are subtracted.
</Para>

<Para>
In the first form in the synopsis above, the zero error is measured by the
instrument itself (e.g. reading off the number where a truncated tape now ends)
and any scale factor specified applies to it, like so:
</Para>

<Para>
Value = ( Reading - ZeroError ) * Scale    (Scale defaults to 1.0)
</Para>

<Para>
In the second form above (supported since Survex 1.2.21), the zero error has
been measured externally (e.g. measuring how much too long your tape is with
a ruler) - the units of the zero error are explicitly specified and any scale
factor isn't applied to it:
</Para>

<Para>
Value = ( Reading * Scale ) - ZeroError    (Scale defaults to 1.0)
</Para>

<Para>
If the scale factor is 1.0, then the two forms are equivalent, though they
still allow you to differentiate between how the zero error has been determined.
</Para>

<Para>
With older Survex versions, you would specify the magnetic declination
(difference between True North and Magnetic North) by using *calibrate
declination to set an explicit value (with no scale factor allowed).  Since
Survex 1.2.22, it's recommended to instead use the new *declination command
instead - see the documentation of that command for more details.
</Para>

</listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<VarListEntry><Term>See Also</Term>

<listitem><Para>*declination, *units</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>CASE</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><para>*case preserve|toupper|tolower</para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*begin bobsbit
; Bob insists on using case sensitive station names
*case preserve
1 2   10.23 106 -02
2 2a   1.56 092 +10
2 2A   3.12 034 +02
2 3    8.64 239 -01
*end bobsbit</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>*case determines how the case of letters in survey names is
handled.  By default all names are forced to lower case (which gives a case
insensitive match, but you can tell cavern to force to upper case, or leave
the case as is (in which case '2a' and '2A' will be regarded as different).
</Para></listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<VarListEntry><Term>See Also</Term>

<listitem><Para>*truncate</Para></listitem>

</VarListEntry>

</VariableList>

<!-- FIXME - work this text in here or elsewhere

What I mean (though failed to express very well) is that a dataset without
this information isn't the same dataset (in general anyway).  For example:

A1 a2 10.32 140 -05
a2 a3  4.91 041 -01
a1 a3  7.01 206  02

is either a traverse of 3 legs or a (probably badly misclosed) loop.  If
these names are on the original survey notes, the surveyors ought to say
whether "A1" is the same as "a1" (although the usual case for using this
feature is probably for importing data from elsewhere).  Similarly for
truncation.  Whether a clino of +/-90 degrees (or +/-100 grad, etc) is
interpreted as a plumb is something that should have been noted in the cave
(unless it's implicit because it's standard practice for a survey project).

It's a similar issue to calibration data in many ways.  You can argue it's
not part of "the survey", but without it the survey won't be the same shape,
and it's not useful to process the same survey with different settings for
compass calibration or name case sensitivity.

>Clearly that is unhelpfully strict, but it is
>important to be semantically clear about what is 'data' and what is 'commands
>or meta-data' which describe what to do with/how to interpret that data.

Think of the lines starting with a "*" as "command or meta-data".

>The most-correct solution to this is (I believe) Martin Heller's idea about
>including 'rules' in the datastream, but that's too big a subject for right
>now.
>
>The reason '-C' was made into a command-line option, was that it made very
>little sense to change it part way though a dataset. What exactly happens if
>you suddenly tell cavern to become case-sensitive halfway through a run?

-C has always had 3 settings - "leave case alone", "force to lower", and
"force to upper".  It doesn't really mean "case sensitivity" but rather
something like "case processing".  So you can usefully change it during a
run.  So if my dataset treats "NoTableChamber" (so named because it was
lacking in furniture) as different from "NotableChamber" (which was notable
for other reasons) I can process it with a dataset from someone else which
needs to be treated as case insensitive like so:

*begin my_cave
*include my_dataset
*end my_cave

*equate my_cave.NoTableChamber.14 your_cave.linkpassage.13

*begin your_cave
*case tolower
*include your_dataset
*end your_cave

You may be thinking of -U<n>, which used to mean "only compare the first n
characters of station names", but that doesn't allow arbitrary datasets to
be processed together.

So we changed it to mean "truncate station names to n characters", and
allowed it to be changed at any point, rather than being set once for the
whole run.

-->

</Sect3>

<Sect3><Title>COPYRIGHT</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*copyright &lt;date&gt; &lt;text&gt;</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*begin littlebit
*copyright 1983 CUCC
1 2 10.23 106 -02
2 3  1.56 092 +10
*end littlebit</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Validity</Term>

<listitem><Para>valid at the start of a *begin/*end block.
</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>*copyright allows the copyright information to be
stored in a way that can be automatically collated.
</Para></listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<VarListEntry><Term>See Also</Term>

<listitem><Para>*begin</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>CS</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*cs [out] &lt;coordinate system&gt;</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*cs UTM60S
*fix beehive 313800 5427953 20</programlisting>
</Para>

<Para>
<programlisting>
; Output in the coordinate system used in the Totes Gebirge in Austria
*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>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>*cs allows the coordinate systems used for fixed points and for
processed survey data to be specified.
</Para>

<Para>
The "input" coordinate system is set with <command>*cs</command> and you can
change it between fixed points if you have some fixed points in different
coordinate systems to others.
</Para>

<Para>
The "output" coordinate system is set with <command>*cs out</command> and is
what the survey data is processed in and the coordinate system used for
resultant <command>.3d</command> file. The output coordinate system must be
in metres with axis order (East, North, Up), so for example
<command>*cs out long-lat</command> isn't valid.
</Para>

<Para>
*cs was added in Survex 1.2.14, but handling of fixed points specified with
latitude and longitude didn't work until 1.2.21.  Also *fix with standard
deviations specified also didn't work until 1.2.21.
</Para>

<Para>
The currently supported coordinate systems are:
</Para>

<Para>CUSTOM followed by a PROJ string (like in the example above).</Para>

<Para>EPSG: followed by a positive integer code.  EPSG codes cover most
coordinate systems in use, and PROJ supports many of these.  The website
<ulink url="https://epsg.io/">https://epsg.io/</ulink> is a useful resource for
finding the EPSG code you want.  For example, <command>EPSG:4167</command> is
NZGD2000.  Supported since Survex 1.2.15.</Para>

<Para>ESRI: followed by a positive integer code.  ESRI codes are used by
ArcGIS to specify coordinate systems (in a similar way to EPSG codes), and PROJ
supports many of them.  Supported since Survex 1.2.15.</Para>

<Para>EUR79Z30 for UTM zone 30, EUR79 datum.  Supported since Survex 1.2.15.
</Para>

<Para>IJTSK for the modified version of the Czechoslovak S-JTSK system where
the axes point East and North.  Supported since Survex 1.2.15.</Para>

<Para>IJTSK03 for a variant of IJTSK.  Supported since Survex 1.2.15.</Para>

<Para>JTSK for the Czechoslovak S-JTSK system.  Its axes point West
and South, so it's not supported as an output coordinate system.
Supported since Survex 1.2.16.</Para>

<Para>JTSK03 for a variant of JTSK.  Supported since Survex 1.2.16.</Para>

<Para>LONG-LAT for longitude/latitude.  The WGS84 datum is assumed.
NB <command>*fix</command> expects the coordinates in the order x,y,z which
means longitude (i.e. E/W), then latitude (i.e. N/S), then altitude.
Supported since Survex 1.2.15.</Para>

<Para>OSGB: followed by a two letter code for the UK Ordnance Survey National
Grid.  The first letter should be 'H', 'N', 'O', 'S' or 'T'; the second any
letter except 'I'.  For example, <command>OSGB:SD</command>.
Supported since Survex 1.2.15.</Para>

<Para>S-MERC for the "Web Mercator" spherical mercator projection, used by
online map sites like OpenStreetMap, Google maps, Bing maps, etc.  Supported
since Survex 1.2.15.
</Para>

<Para>UTM followed by a zone number (1-60), optionally followed by "N" or "S"
(default is North).  The WGS84 datum is assumed.</Para>

<Para>
By default, Survex works in an unspecified coordinate system (and this was the
only option before *cs was added).  However, it's useful for the coordinate
system which the processed survey data is in to be specified if you want to use
the processed data in ways which required knowing the coordinate system (such as
exporting a list of entrances for use in a GPS).  You can now do this by using
"*cs out".
</Para>

<Para>
It is also useful to be able to take coordinates for fixed points in whatever
coordinate system you receive them in and put them directly into Survex, rather
than having to convert with an external tool.  For example, you may have your
GPS set to show coordinates in UTM with the WGS84 datum, even though you want
the processed data to be in some local coordinate system.  And someone else
may provide GPS coordinates in yet another coordinate system.  You just need
to set the appropriate coordinate system with "*cs" before each group of "*fix"
commands in a particular coordinate system.
</Para>

<Para>
If you're going to make use of "*cs", then the coordinate system must be
specified for everything, so a coordinate system must be in effect for all
"*fix" commands, and you must set the output coordinate system before any
points are fixed.
</Para>

<Para>
Also, if "*cs" is in use, then you can't omit the coordinates in a "*fix"
command, and a fixed point won't be invented if none exists.
</Para>

<Para>
If you use "*cs out" more than once, the second and subsequent commands are
silently ignored - this makes it possible to combine two datasets with
different "*cs out" settings without having to modify either of them.
</Para>

<Para>
Something to be aware of with "*cs" is that altitudes are currently assumed to
be "height above the ellipsoid", whereas GPS units typically give you "height
above sea level", or more accurately "height above a particular geoid".  This
is something we're looking at how best to address, but you shouldn't need to
worry about it if your fixed points are in the same coordinate system as your
output, or if they all use the same ellipsoid.  For a more detailed discussion
of this, please see: http://expo.survex.com/handbook/survey/coord.htm
</Para>
</listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<VarListEntry><Term>See Also</Term>

<listitem><Para>*fix</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>
<Sect3><Title>DATA</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem>
<Para>*data &lt;style&gt; &lt;ordering&gt;</Para>
<Para>*data</Para>
</listitem>

<!-- BACKCOMPASS BACKCLINO -->
</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*data normal from to compass tape clino</programlisting>
</Para>

<Para>
<programlisting>
*data normal station ignoreall newline compass tape clino</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
&lt;style&gt; = DEFAULT|NORMAL|DIVING|CARTESIAN|TOPOFIL|CYLPOLAR|NOSURVEY|PASSAGE
</Para>

<Para>
&lt;ordering&gt; = ordered list of instruments - which are valid depends on the
style.
</Para>

<Para>
In Survex 1.0.2 and later, TOPOFIL is simply a synonym for NORMAL, left in to
allow older data to be processed without modification.  Use the name NORMAL
by preference.
</Para>

<Para>
There are two variants of each style - interleaved and non-interleaved.
Non-interleaved is "one line per leg", interleaved has a line for the data
shared between two legs (e.g. STATION=FROM/TO, DEPTH=FROMDEPTH/TODEPTH,
COUNT=FROMCOUNT/TOCOUNT).  Note that not all readings that can be shared
have to be, for example here the to/from station name is shared but the
depth gauge readings aren't:

<programlisting>
*data diving station newline fromdepth compass tape todepth</programlisting>

In addition, interleaved data can have a DIRECTION reading, which can be "F"
for a foresight or "B" for a backsight (meaning the direction of the leg is
reversed).
</Para>

<Para>
In interleaved data, a blank line (one which contains only characters which
are set as BLANK) ends the current traverse so can be used to handle
branches in the survey, e.g.:
<programlisting>
*data normal station newline tape compass clino

1
    9.34   087   -05
2
    ; single leg up unexplored side passage
    4.30   002    +06
3

2
    ; and back to the main package
    6.29   093    -02
4</programlisting>
</Para>

<Para>
In data styles which include a TAPE reading (i.e. NORMAL, DIVING, and CYLPOLAR
data styles), TAPE may be replaced by FROMCOUNT/TOCOUNT (or COUNT in
interleaved data) to allow processing of surveys performed with a Topofil
instead of a tape.
</Para>

<Para>
In Survex 1.2.44 and later, you can use <command>*data</command> without any
arguments to keep the currently set data style, but resetting any state.  This
is useful when you're entering passage tubes with branches - see the description
of the "PASSAGE" style below.  (This feature was originally added in 1.2.31,
but was buggy until 1.2.44 - any data up to the next <command>*data</command>
gets quietly ignored).
</Para>

<VariableList>

<VarListEntry><Term>DEFAULT</Term>
<listitem><Para>Select the default data style and ordering (NORMAL style, ordering: from to tape compass clino).</Para></listitem>
</VarListEntry>

<VarListEntry><Term>NORMAL</Term>
<listitem><Para>The usual tape/compass/clino centreline survey.
For non-interleaved data the allowed readings are:
FROM TO TAPE COMPASS CLINO BACKCOMPASS BACKCLINO;
for interleaved data the allowed readings are:
STATION DIRECTION TAPE COMPASS CLINO BACKCOMPASS BACKCLINO.
The CLINO/BACKCLINO reading is not required - if it's not given, the vertical
standard deviation is taken to be proportional to the tape measurement.
Alternatively, individual clino readings can be given as OMIT (default "-")
which allows for data where only some clino readings are missing.
E.g.:

<programlisting>
*data normal from to compass clino tape
1 2 172 -03 12.61</programlisting>

<programlisting>
*data normal station newline direction tape compass clino
1
 F 12.61 172 -03
2</programlisting>

<programlisting>
*data normal from to compass clino fromcount tocount
1 2 172 -03 11532 11873</programlisting>

<programlisting>
*data normal station count newline direction compass clino
1 11532
 F 172 -03
2 11873</programlisting>
 
</Para></listitem>
</VarListEntry>

<VarListEntry><Term>DIVING</Term>
<listitem><Para>
An underwater survey where the vertical information is from a diver's depth
gauge.  This style can also be also used for an above-water survey where the
altitude is measured with an altimeter.  DEPTH is defined as the altitude (Z)
so increases upwards by default.  So for a diver's depth gauge, you'll need to
use *CALIBRATE with a negative scale factor (e.g. *calibrate depth 0 -1).
</Para>

<Para>For non-interleaved data the allowed readings are:
FROM TO TAPE COMPASS CLINO BACKCOMPASS BACKCLINO FROMDEPTH TODEPTH DEPTHCHANGE (the vertical
can be given as readings at each station, (FROMDEPTH/TODEPTH) or as a change
along the leg (DEPTHCHANGE)).</Para>

<Para>Survex 1.2.20 and later allow an optional CLINO and/or BACKCLINO reading
in DIVING style.  At present these extra readings are checked for syntactic
validity, but are otherwise ignored.  The intention is that a future version
will check them against the other readings to flag up likely blunders, and
average with the slope data from the depth gauge and tape reading.</Para>

<Para>For interleaved data the allowed readings are:
STATION DIRECTION TAPE COMPASS BACKCOMPASS DEPTH DEPTHCHANGE.
(the vertical change can be given as a reading at the station (DEPTH) or as a change along the leg (DEPTHCHANGE)).

<programlisting>
*data diving from to tape compass fromdepth todepth
1 2 14.7 250 -20.7 -22.4</programlisting>

<programlisting>
*data diving station depth newline tape compass
1 -20.7
 14.7 250
2 -22.4</programlisting>

<programlisting>
*data diving from to tape compass depthchange
1 2 14.7 250 -1.7</programlisting>
</Para>
</listitem>
</VarListEntry>

<VarListEntry><Term>CARTESIAN</Term>
<listitem><Para>
Cartesian data style allows you to specify the (x,y,z) changes between
stations.  It's useful for digitising surveys where the original survey
data has been lost and all that's available is a drawn up version.

<programlisting>
*data cartesian from to northing easting altitude
1 2 16.1 20.4 8.7</programlisting>

<programlisting>
*data cartesian station newline northing easting altitude
1
 16.1 20.4 8.7
2</programlisting>

<!--FIXME: dx dy dz-->
</Para>

<Note><Para>
Cartesian data are relative to <emphasis>true</emphasis> North not
<emphasis>magnetic</emphasis> North (i.e. they are unaffected by
<command>*calibrate declination</command>).
</Para></Note>
</listitem>
</VarListEntry>

<VarListEntry><Term>CYLPOLAR</Term>
<listitem><Para>
A CYLPOLAR style survey is very similar to a diving survey, except that the tape
is always measured horizontally rather than along the slope of the leg.

<programlisting>
*data cylpolar from to tape compass fromdepth todepth
1 2 9.45 311 -13.3 -19.0</programlisting>

<programlisting>
*data cylpolar station depth newline tape compass
1 -13.3
 9.45 311
2 -19.0</programlisting>

<programlisting>
*data cylpolar from to tape compass depthchange
1 2 9.45 311 -5.7</programlisting>
</Para></listitem>
</VarListEntry>

<VarListEntry><Term>NOSURVEY</Term>
<listitem><Para>
A NOSURVEY survey doesn't have any measurements - it merely indicates that
there is line of sight between the pairs of stations.

<programlisting>
*data nosurvey from to
1 7
5 7
9 11</programlisting>

<programlisting>
*data nosurvey station
1
7
5

*data nosurvey station
9
11</programlisting>
</Para></listitem>
</VarListEntry>

<VarListEntry><Term>PASSAGE</Term>
<listitem><Para>
This survey style defines a 3D "tube" modelling a passage in the cave.
The tube uses the survey stations listed in the order listed.  It's
permitted to use survey stations which aren't directly linked by
the centre-line survey.  This can be useful - sometimes the centreline
will step sideways or up/down to allow a better sight for the next
leg and you can ignore the extra station.  You can also define tubes
along unsurveyed passages, akin to "nosurvey" legs in the centreline
data.</Para>

<Para>This means that you need to split off side passages into separate
tubes, and hence separate sections of passage data, starting with
a new *data command.</Para>

<Para>
Simple example of how to use this data style (note the use of ignoreall
to allow a free-form text description to be given):

<programlisting>
*data passage station left right up down ignoreall
1  0.1 2.3 8.0 1.4  Sticking out point on left wall
2  0.0 1.9 9.0 0.5  Point on left wall
3  1.0 0.7 9.0 0.8  Highest point of boulder
</programlisting>

Each <command>*data passage</command> data block describes a single continuous
tube - to break a tube or to enter a side passage you need to have a second
block.  With Survex 1.2.30 and older, you had to repeat the entire
<command>*data passage</command> line to start a new tube, but in Survex 1.2.31
and later, you can just use <command>*data</command> without any arguments.
</Para>

<Para>
For example here the main passage is 1-2-3 and a side passage is 2-4:

<programlisting>
*data passage station left right up down ignoreall
1  0.1 2.3 8.0 1.4  Sticking out point on left wall
2  0.0 1.9 9.0 0.5  Point on left wall opposite side passage
3  1.0 0.7 9.0 0.8  Highest point of boulder
; If you're happy to require Survex 1.2.31 or later, you can just use
; "*data" here instead.
*data passage station left right up down ignoreall
2  0.3 0.2 9.0 0.5
4  0.0 0.5 6.5 1.5  Fossil on left wall
</programlisting>
</Para>
</listitem>
</VarListEntry>
</VariableList>

<Para>
IGNORE skips a field (it may be used any number of times),
and IGNOREALL may be used last to ignore the rest of the data line.
</Para>

<Para>
LENGTH is a synonym for TAPE; BEARING for COMPASS; GRADIENT for CLINO; COUNT for COUNTER.<!--FIXME : others?-->
</Para>

<Para>
The units of each quantity may be set with the UNITS command.
</Para>

<!-- FIXME: plumbed diving legs -->

<!--FIXME:
<Para>
Uses for CYLPOLAR:
Perhaps a Grade 3 survey, or when surveying with a level and stick (?)
[note - UBSS use it for the old County Clare data]
</Para>
-->

</listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>DATE</Title>
<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*date &lt;year&gt;[.&lt;month&gt;[.&lt;day&gt;]][-&lt;year&gt;[.&lt;month&gt;[.&lt;day&gt;]]]</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*date 2001</programlisting>

<programlisting>
*date 2000.10</programlisting>

<programlisting>
*date 1987.07.27</programlisting>

<programlisting>
*date 1985.08.12-1985.08.13</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Validity</Term>

<listitem><Para>valid at the start of a *begin/*end block.
</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
*date specifies the date that the survey was done.  A range of dates
can be specified (useful for overnight or multi-day surveying trips).
</Para></listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<VarListEntry><Term>See Also</Term>

<listitem><Para>*begin, *instrument, *team</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>DECLINATION</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem>
<Para>*declination auto &lt;x&gt; &lt;y&gt; &lt;z&gt;</Para>
<Para>*declination &lt;declination&gt; &lt;units&gt;</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem>

<Para>
The *declination command is the modern way to specify magnetic declinations in
Survex.  Magnetic declination is the difference between Magnetic North and True
North.  It varies over time as the Earth's magnetic field moves, and also with
location.  Compass bearings are measured relative to Magnetic North - adding the
magnetic declination gives bearings relative to True North.
</Para>

<Para>
Prior to 1.2.22, *calibrate declination was used instead.  If you
use a mixture of *calibrate declination and *declination, they interact in
the natural way - whichever was set most recently is used for each compass
reading (taking into account survey scope).  We don't generally recommend
mixing the two, but it's useful to understand how they interact if you want to
combine datasets using the old and new commands, and perhaps if you have a
large existing dataset and want to migrate it without having to change
everything at once.
</Para>

<Para>
Note that the value specified uses the conventional sign for magnetic
declination, unlike the old *calibrate declination which needed a value with
the opposite sign (because *calibrate specifies a zero error), so take care
when updating old data, or if you're used to the semantics of *calibrate
declination.
</Para>

<Para>
If you have specified the output coordinate system (using *cs out) then you can
use *declination auto (and we recommend that you do).  This is supported since
Survex 1.2.21 and automatically calculates magnetic declinations based on the
IGRF (International Geomagnetic Reference Field) model.  A revised version of
the IGRF model is usually issued every 5 years, and calculates values using a
model based on observations for years before it is issued, and on predictions
for 5 years after it is issued.  Survex 1.2.43 updated to using version 13 in
early 2020.
</Para>

<Para>
The IGRF model takes a date and a location as inputs. Survex uses the
specified date of the survey, and uses the "x y z" coordinates specified
in the *declination auto command as the location in the current input
coordinate system (as set by *cs).  Most users can just specify a single
representative location somewhere in the area of the cave.  If you're
not sure what to use pick some coordinates roughly in the middle of
the bounding box of the cave - it doesn't need to be a fixed point or a known
refindable location, though it can be if you prefer.
</Para>

<Para>
For each *declination auto command cavern will (since Survex 1.4.2) report
the range of calculated declination values and the dates at which the ends of
the range were obtained, and also the grid convergence (which doesn't vary with
time).  This appears in the log - if you processed the data with aven you can
view this by using "File->View Log".  It looks like this:
</Para>

<programlisting>
/home/ol/1623.svx:20: info: Declination: -0.4° @ 1977-07-02 / 3.8° @ 2018-07-21, grid convergence: -0.9°
 *declination auto 36670.37 83317.43 1903.97
</programlisting>

<Para>
You might wonder why Survex needs a representative location instead of
calculating the magnetic declination and grid convergence for the actual
position of each survey station.  The reason is that we need to adjust the
compass bearings before we can solve the network to find survey station
locations.  Both magnetic declination and grid convergence don't generally vary
significantly over the area of a typical cave system - if you are mapping a
very large cave system, or caves over a wide area, or are working close to a
magnetic pole or where the output coordinate system is rather distorted, then
you can specify *declination auto several times with different representative
locations for different areas of the cave system - the one currently in effect
is used for each survey leg.
</Para>

<Para>
Survex 1.2.27 and later also automatically correct for grid convergence (the
difference between Grid North and True North) when *declination auto is in use,
based on the same specified representative location.
</Para>

<Para>
Generally it's best to specify a suitable output coordinate system, and use
*declination auto so Survex corrects for magnetic declination and grid
convergence for you.  Then Aven knows how to translate coordinates to allow
export to formats such as GPX and KML, and to overlay terrain data.
</Para>

<Para>
If you don't specify an output coordinate system, but fix one or more points
then Survex works implicitly in the coordinate system your fixed points were
specified in.  This mode of operation is provided for compatibility with
datasets from before support for explicit coordinate systems was added to
Survex - it's much better to specify the output coordinate system as above.
But if you have a survey of a cave which isn't connected to any known fixed
points then you'll need to handle it this way, either fixing an entrance
to some arbitrary coordinates (probably (0,0,0)) or letting Survex pick a
station as the origin.  If the survey was all done in a short enough period
of time that the magnetic declination won't have changed significantly, you
can just ignore it and Grid North in the implicit coordinate system will be
Magnetic North at the time of the survey.  If you want to correct for magnetic
declination, you can't use *declination auto because the IGRF model needs the
real world coordinates, but you can specify literal declination values for each
survey using *declination &lt;declination&gt; &lt;units&gt;.  Then Grid North
in the implicit coordinate system is True North.
</Para>

</listitem>

</VarListEntry>

<VarListEntry><Term>See Also</Term>

<listitem><Para>*calibrate</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>DEFAULT</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*default &lt;settings list&gt;|all</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
The valid settings are CALIBRATE, DATA, and UNITS.
</Para>

<Para>
*default restores defaults for given settings.  This command is deprecated -
you should instead use: *calibrate default, *data default, *units default.
</Para></listitem>

</VarListEntry>

<VarListEntry><Term>See Also</Term>

<listitem><Para>*calibrate, *data, *units</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>END</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*end [&lt;survey&gt;]</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Validity</Term>

<listitem><Para>valid for closing a block started by *begin in the same file.
</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
Closes a block started by *begin.
</Para></listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<VarListEntry><Term>See Also</Term>

<listitem><Para>*begin</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>ENTRANCE</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*entrance &lt;station&gt;</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*entrance P163</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
*entrance sets the <emphasis>entrance</emphasis> flag for a station.
This information is used by aven to allow entrances to be highlighted.
</Para>

<!-- FIXME:
(could be inferred from surface/ug join, but better to specify because
of caves with no surf svy (or no underground survey) 
and also situations in which multiple surveys leave through an entrance)
-->
</listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<!-- <VarListEntry><Term>See Also</Term>

<listitem><Para></Para></listitem>

</VarListEntry>
-->

</VariableList>

</Sect3>

<Sect3><Title>EQUATE</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*equate &lt;station&gt; &lt;station&gt;...</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*equate chosspot.1 triassic.27</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
*equate specifies that the station names in the list refer to the
same physical survey station. An error is given if there is only one station
listed.
</Para>

<!-- FIXME:
<Para>
I think this is preferable to using:
</Para>

<programlisting> a b 0.00   0   0</programlisting>

<Para>
as EQUATE does not add in an extra position error. It is also clearer than
substituting in the original name wherever passages are linked. If you
disagree, you can always use one of the other methods!
</Para>
-->
</listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<VarListEntry><Term>See Also</Term>

<listitem><Para>*infer equates</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>EXPORT</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*export &lt;station&gt;...</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<!-- FIXME better example -->
<listitem>
<Para>
<programlisting>
*export 1 6 17</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Validity</Term>

<listitem><Para>valid at the start of a *begin/*end block.
</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
*export marks the stations named as referable to from the enclosing
survey.  To be able to refer to a station from a survey several levels
above, it must be exported from each enclosing survey.
</Para>

<!-- FIXME:
<Para>
I think this is preferable to using:
</Para>

<programlisting> a b 0.00   0   0</programlisting>

<Para>
as EQUATE does not add in an extra position error. It is also clearer than
substituting in the original name wherever passages are linked. If you
disagree, you can always use one of the other methods!
</Para>
-->
</listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<VarListEntry><Term>See Also</Term>

<listitem><Para>*begin, *infer exports</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>FIX</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*fix &lt;station&gt; [reference]
 [ &lt;x&gt; &lt;y&gt; &lt;z&gt;
   [ &lt;x std err&gt; &lt;y std err&gt; &lt;z std err&gt;
     [ &lt;cov(x,y)&gt; &lt;cov(y,z)&gt; &lt;cov(z,x)&gt; ] ] ]
</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*fix entrance.0 32768 86723 1760</programlisting>

<programlisting>
*fix KT114_96 reference 36670.37 83317.43 1903.97</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem>
<Para>
*fix fixes the position of &lt;station&gt; at the given coordinates.
If you haven't specified the coordinate system with "*cs", you can
omit the position and it will default to (0,0,0).  The standard errors default
to zero (fix station exactly).  cavern will give an error if you attempt to fix
the same survey station twice at different coordinates, or a warning if you fix
it twice with matching coordinates.
</Para>

<Para>
You can also specify just one standard error (in which case it is assumed
equal in X, Y, and Z) or two (in which case the first is taken as the
standard error in X and Y, and the second as the standard error in Z).
</Para>

<Para>
If you have covariances for the fix, you can also specify these - the
order is cov(x,y) cov(y,z) cov(z,x). 
</Para>

<Para>
If you've specified a coordinate system (see <command>*cs</command>) then
that determines the meaning of X, Y and Z (if you want to specify the
units for altitude, note that using a PROJ string containing
<command>+vunits</command> allows this - e.g. <command>+vunits=us-ft</command>
for US survey feet).  If you don't specify a coordinate system, then the
coordinates must be in metres.  The standard deviations must always be
in metres (and the covariances in metres squared).
</Para>

<Para>
You can fix as many stations as you like - just use a *fix command for each
one.  Cavern will check that all stations are connected to
at least one fixed point so that co-ordinates can be calculated for all
stations.
</Para>

<Para>
By default cavern will warn about stations which have been FIX-ed but
are not used otherwise, as this might be due to a typo in the station
name.  Uses in survey data and (since 1.4.9) <command>*entrance</command>
count for these purposes. This warning is unhelpful if you want to include a
standard file of benchmarks, some of which won't be used. In this sort of
situation, specify "REFERENCE" after the station name in the FIX command to
suppress this warning for a particular station.  It's OK to use "REFERENCE"
on a station which is used.
</Para>

<Note><Para>
X is Easting, Y is Northing, and Z is altitude.  This convention was chosen
since on a map, the horizontal (X) axis is usually East, and the vertical
axis (Y) North.  The choice of altitude (rather than depth) for Z is taken
from surface maps, and makes for less confusion when dealing with cave
systems with more than one entrance.  It also gives a right-handed
set of axes.
</Para></Note>

</listitem>
</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<!-- <VarListEntry><Term>See Also</Term>

<listitem><Para></Para></listitem>

</VarListEntry>
-->

</VariableList>

</Sect3>

<!--
<Sect3><Title></Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Caveats </Term> </VarListEntry>

<VarListEntry><Term>See Also</Term>

<listitem><Para></Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>
-->

<Sect3><Title>FLAGS</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*flags &lt;flags&gt;</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*flags duplicate not surface</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
*flags updates the current flag settings.
Flags not mentioned retain their previous state.  Valid flags
are DUPLICATE, SPLAY, and SURFACE, and a flag may be preceded with NOT to
turn it off.
</Para>

<Para>
Survey legs marked SURFACE are hidden from plots by default, and not
included in cave survey length calculations.  Survey legs marked as
DUPLICATE or SPLAY are also not included in cave survey length
calculations; legs marked SPLAY are ignored by the extend program.
DUPLICATE is intended for the case when if you have two different
surveys along the same section of passage (for example to tie two
surveys into a permanent survey station); SPLAY is intended for 
cases such as radial legs in a large chamber.
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>See Also</Term>

<listitem><Para>*begin</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>INCLUDE</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*include &lt;filename&gt;</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*include mission</programlisting>

<programlisting>
*include "the pits"</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
*include processes &lt;filename&gt; as if it were inserted at this
place in the current file. (i.e. The current settings are carried
into &lt;filename&gt;, and any alterations to settings in &lt;filename&gt;
will be carried back again).  There's one exception to this (for
obscure historical reasons) which is that the survey prefix is
restored upon return to the original file.  Since *begin and *end
nesting cannot cross files, this can only make a difference if you
use the deprecated *prefix command.
</Para>

<Para>If &lt;filename&gt; contains spaces, it must be enclosed in quotes.
</Para>

<Para>An included file which does not have a complete path
is resolved relative to the directory which the parent file is in
(just as relative HTML links do).  Cavern will try adding a <filename>.svx</filename>
extension, and will also try translating "\" to "/".
</Para>

<Para>
To help users wanting to take a dataset from a platform where filenames
are case-insenstive and process it on a platform where filenames are
case-sensitive, if the file isn't found cavern will try a few variations of the
case.  First it will try all lower case (in Survex 1.4.5 and older this was
the only case variant tried), then all lower case except with the first
character of the leafname upper case, and finally all upper case.  These
different variants are only tried if the case as given doesn't match
so there's no overhead in the normal situation.
</Para>

<Para>
One specific trick this enables which is worth noting is that if you're using
Unix and someone sends you a DOS/Windows dataset with mismatched filename case,
you can unzip it using <command>unzip -L</command> to unpack all the filenames
in lower case and UNIX cavern should successfully process it.
</Para>

<Para>
The depth to which you can nest include files may be limited by the operating
system you use.  Usually the limit is fairly high (>30), but if you want to be
able to process your dataset with <Application>Survex</Application> on any
supported platform, it would be prudent not to go overboard with deeply nested
include files.
</Para>
</listitem>
</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>INFER</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem>
<Para>*infer plumbs on|off</Para>

<Para>*infer equates on|off</Para>

<Para>*infer exports on|off</Para>
</listitem>

</VarListEntry>

<!--
<VarListEntry><Term>Example</Term>

<listitem>
<programlisting>
</programlisting>

</listitem>

</VarListEntry>
-->

<VarListEntry><Term>Description</Term>

<listitem>
<Para>"*infer plumbs on" tells cavern to interpret gradients of +/- 90
degrees as UP/DOWN (so it
will not apply the clino correction to them). This is useful when
the data has not been converted to have UP and DOWN in it.
</Para>

<para>"*infer equates on" tells cavern to interpret a leg with
a tape reading of zero as a *equate.  this prevents tape corrections
being applied to them.
</para>

<para>"*infer exports on" is necessary when you have a dataset which is
partly annotated with *export.  It tells cavern not to complain about
missing *export commands in part of the dataset.  Also stations which
were used to join surveys are marked as exported in the 3d file.
</para>
</listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<!--
<VarListEntry><Term>See Also</Term>

<listitem><Para>*end, *prefix</Para></listitem>

</VarListEntry>
-->

</VariableList>

</Sect3>

<Sect3><Title>INSTRUMENT</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*instrument &lt;instrument&gt; &lt;identifier&gt;</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*instrument compass "CUCC 2"
*instrument clino "CUCC 2"
*instrument tape "CUCC Fisco Ranger open reel"</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Validity</Term>

<listitem><Para>valid at the start of a *begin/*end block.
</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
*instrument specifies the particular instruments used to perform a
survey.
</Para></listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<VarListEntry><Term>See Also</Term>

<listitem><Para>*begin, *date, *team</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>PREFIX</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*prefix &lt;survey&gt;</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*prefix flapjack</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
*prefix sets the current survey.
</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Caveats </Term>

<listitem><Para>*prefix is deprecated - you should use *begin and *end
instead.</Para></listitem>

</VarListEntry>

<VarListEntry><Term>See Also</Term>

<listitem><Para>*begin, *end</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>REF</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*ref &lt;string&gt;</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*ref "survey folder 2007#12"
</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Validity</Term>

<listitem><Para>valid at the start of a *begin/*end block.
</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
*ref allows you to specify a reference.  If the reference contains spaces, you
must enclose it in double quotes.  Survex doesn't try to interpret the
reference in any way, so it's up to you how you use it - for example it could
specify where the original survey notes can be found.
</Para>

<Para>
*ref was added in Survex 1.2.23.
</Para></listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<VarListEntry><Term>See Also</Term>

<listitem><Para>*begin, *date, *instrument, *team</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>REQUIRE</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*require &lt;version&gt;</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*require 0.98</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
*require checks that the version of cavern in use is at least
&lt;version&gt; and stops with an error if not.
So if your dataset requires a feature
introduced in a particular version, you can add a *require command and
users will know what version they need to upgrade to, rather than
getting an error message and having to guess what the real problem is.
</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>SD</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*sd &lt;quantity list&gt; &lt;standard deviation&gt;
</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*sd tape 0.15 metres</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
*sd sets the standard deviation of a measurement.
</Para>

<Para>
&lt;quantity&gt; is one of (each group gives alternative names for the same
quantity):
</Para>

<ItemizedList>
    <listitem><para>TAPE, LENGTH</para></listitem>
    <listitem><para>BACKTAPE, BACKLENGTH (added in Survex 1.2.25)</para></listitem>
    <listitem><para>COMPASS, BEARING</para></listitem>
    <listitem><para>BACKCOMPASS, BACKBEARING</para></listitem>
    <listitem><para>CLINO, GRADIENT</para></listitem>
    <listitem><para>BACKCLINO, BACKGRADIENT</para></listitem>
    <listitem><para>COUNTER, COUNT</para></listitem>
    <listitem><para>DEPTH</para></listitem>
    <listitem><para>DECLINATION</para></listitem>
    <listitem><para>DX, EASTING</para></listitem>
    <listitem><para>DY, NORTHING</para></listitem>
    <listitem><para>DZ, ALTITUDE</para></listitem>
    <listitem><para>LEFT</para></listitem>
    <listitem><para>RIGHT</para></listitem>
    <listitem><para>UP, CEILING</para></listitem>
    <listitem><para>DOWN, FLOOR</para></listitem>
    <listitem><para>LEVEL</para></listitem>
    <listitem><para>PLUMB</para></listitem>
    <listitem><para>POSITION</para></listitem>
</ItemizedList>

<Para>
&lt;standard deviation&gt; must include units and thus is typically
"0.05 metres", or "0.02 degrees". See *units below for full list
of valid units.
</Para>

<!-- FIXME mention central limit theorem -->
<Para>
To utilise this command fully you need to understand what a
<emphasis>standard deviation</emphasis> is.
It gives a value to the 'spread' of the errors
in a measurement. Assuming that these are normally distributed
we can say that 95.44% of the actual lengths will fall within two
standard deviations of the measured length. i.e. a tape SD of
0.25 metres means that the actual length of a tape measurement
is within + or - 0.5 metres of the recorded value 95.44% of the time.
So if the measurement is 7.34m then the actual length is very
likely to be between 6.84m and 7.84m. This example corresponds
to BCRA grade 3. Note that this is just one interpretation of
the BCRA standard, taking the permitted error values as 2SD 95.44%
confidence limits. If you want to take the readings as being some
other limit (e.g. 1SD = 68.26%) then you will need to change the BCRA3
and BCRA5 files accordingly. This issue is explored in more
detail in various surveying articles.
<!--
2.565 sd 99%
2.5   sd 98.76%
2     sd 95.44%
1     sd 68.26%
.97   sd 66.67%
1.15  sd 75%
-->
</Para></listitem>

</VarListEntry>

<VarListEntry><Term>See Also</Term>

<listitem><Para>*units</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>SET</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*set &lt;item&gt; &lt;character list&gt;</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*set blank x09x20
*set decimal ,</programlisting>

Note that you need to eliminate comma from being a blank before setting it as
a decimal - otherwise the comma in "*set decimal ," is parsed as a blank, and
you set decimal to not have any characters representing it.
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
*set sets the specified &lt;item&gt; to the character or characters
given in &lt;character list&gt;. The example sets the decimal
separator to be a comma.
</Para>

<Para>
xAB means the character with hex value AB. Eg x20 is a space.
</Para>

<Para>
The complete list of items that can be set, the defaults (in
brackets), and the meaning of the item, is:
</Para>

<ItemizedList>

<ListItem><Para>
BLANK (x09x20,) Separates fields
</Para></ListItem>

<ListItem><Para>
COMMENT (;) Introduces comments
</Para></ListItem>

<ListItem><Para>
DECIMAL (.) Decimal point character 
</Para></ListItem>

<ListItem><Para>
EOL (x0Ax0D) End of line character
</Para></ListItem>

<ListItem><Para>
KEYWORD (*) Introduces keywords
</Para></ListItem>

<ListItem><Para>
MINUS (-) Indicates negative number
</Para></ListItem>

<ListItem><Para>
NAMES (_-) Non-alphanumeric chars permitted in station
names (letters and numbers are always permitted).
</Para></ListItem>

<ListItem><Para>
OMIT (-) Contents of field omitted (e.g. in plumbed legs)
</Para></ListItem>

<ListItem><Para>
PLUS (+) Indicates positive number 
</Para></ListItem>

<ListItem><Para>
ROOT (\) Prefix in force at start of current file (use of ROOT is deprecated)
</Para></ListItem>

<ListItem><Para>
SEPARATOR (.) Level separator in prefix hierarchy
</Para></ListItem>

<!-- FIXME OPEN ({) and CLOSE (}) -->
</ItemizedList>

<Para>
The special characters may not be alphanumeric.
</Para>

</listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>SOLVE</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*solve</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*include 1997data
*solve
*include 1998data
</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
Distributes misclosures around any loops in the survey and fixes
the positions of all existing stations.  This command is intended
for situations where you have some new surveys adding extensions
to an already drawn-up survey which you wish to avoid completely
redrawing. You can read in the old data, use *SOLVE to fix it, and then
read in the new data.  Then old stations will be in the same
positions as they are in the existing drawn up survey, even if new loops
have been formed by the extensions.
</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>TEAM</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*team &lt;person&gt; [&lt;role&gt;...]</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*team "Nick Proctor" compass clino tape
*team "Anthony Day" notes pictures tape
</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Validity</Term>

<listitem><Para>valid at the start of a *begin/*end block.
</Para></listitem>
<!-- FIXME valid roles are? -->

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
*team specifies the people involved in a survey and optionally what role or
roles they filled during that trip.  Unless the person is only identified by
one name you need to put double quotes around their name.
</Para></listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<VarListEntry><Term>See Also</Term>

<listitem><Para>*begin, *date, *instrument</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>TITLE</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*title &lt;title&gt;</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<programlisting>
*title Dreamtime</programlisting>

<programlisting>
*title "Mission Impossible"</programlisting>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>*title allows you to set the descriptive title for a survey.
If the title contains spaces, you need to enclose it in quotes ("").
If there is no *title command, the title defaults to the survey name
given in the *begin command.
</Para>
</listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<!--
<VarListEntry><Term>See Also</Term>

<listitem><Para>*end, *prefix</Para></listitem>

</VarListEntry>
-->

</VariableList>

</Sect3>

<Sect3><Title>TRUNCATE</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>*truncate &lt;length&gt;|off</Para></listitem>

</VarListEntry>

<!-- FIXME:
<VarListEntry><Term>Example</Term>

<listitem>
<programlisting>
</programlisting>

</listitem>

</VarListEntry>
-->

<VarListEntry><Term>Description</Term>

<listitem><Para>Station names may be of any length in <Application>Survex</Application>, but some
other (mostly older) cave surveying software only regard the first few
characters of a name as significant (e.g. "entran" and "entrance"
might be treated as the same).  To facilitate using data imported from
such a package <Application>Survex</Application> allows you to truncate names to whatever
length you want (but by default truncation is off).
</Para>

<Para>Figures for the number of characters which are significant in various
software packages: Compass currently has a limit of 12,
CMAP has a limit of 6,
Smaps 4 had a limit of 8,
<!-- FIXME any limits for other software, winkarst for example? -->
Surveyor87/8 used 8.
<Application>Survex</Application> itself used 8 per prefix
level up to version 0.41, and 12 per prefix level up to 0.73 (more recent
versions removed this rather archaic restriction).
</Para>
</listitem>

</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<VarListEntry><Term>See Also</Term>

<listitem><Para>*case</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

<Sect3><Title>UNITS</Title>

<VariableList>

<VarListEntry><Term>Syntax</Term>

<listitem><Para>
*units &lt;quantity list&gt; [&lt;factor&gt;] &lt;unit&gt;
</Para>
<Para>
*units default
</Para></listitem>

</VarListEntry>

<VarListEntry><Term>Example</Term>

<listitem>
<Para>
<programlisting>
*units tape metres</programlisting>

<programlisting>
*units compass backcompass clino backclino grads</programlisting>

<programlisting>
*units dx dy dz 1000 metres ; data given as kilometres</programlisting>

<programlisting>
*units left right up down feet</programlisting>
</Para>
</listitem>

</VarListEntry>

<VarListEntry><Term>Description</Term>

<listitem><Para>
&lt;quantity&gt; is one of the following (grouped entries are just alternative names for the same thing):
TAPE/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
</Para>

<Para>Changes current units of all the quantities listed to [&lt;factor&gt;]
&lt;unit&gt;. Note that quantities can be expressed either as
the instrument (e.g. COMPASS) or the measurement (e.g. BEARING).
</Para>

<Para>&lt;factor&gt; allows you to easy specify situations such as measuring
distance with a diving line knotted every 10cm (*units distance 0.1 metres).
If &lt;factor&gt; is omitted it defaults to 1.0.  If specified, it must be
non-zero.
</Para>

<Para>Valid units for listed quantities are:
</Para>

<Para>TAPE/LENGTH, BACKTAPE/BACKLENGTH, COUNTER/COUNT, DEPTH, DX/EASTING, DY/NORTHING, DZ/ALTITUDE
in YARDS|FEET|METRIC|METRES|METERS (default: METRES)
</Para>

<Para>CLINO/GRADIENT, BACKCLINO/BACKGRADIENT
in DEGS|DEGREES|GRADS|MINUTES|PERCENT|PERCENTAGE (default: DEGREES)
</Para>

<Para>COMPASS/BEARING, BACKCOMPASS/BACKBEARING, DECLINATION
in DEGS|DEGREES|GRADS|MINUTES|QUADS|QUADRANTS (default: DEGREES)
</Para>

<Para>(360 degrees = 400 grads)
</Para>

<Para>
QUADRANTS are a style of bearing used predominantly in land survey, and occasionally
in survey with handheld instruments. All bearings are N or S, a numeric from 0 to
90, followed by E or W. For example S34E to refer to 146 degrees, or 34 degrees in
the SE quadrant. In this format, exact cardinal directions may be simply alphabetic.
E.g. N is equivalent to N0E and E is equivalent to N90E. This unit was added in Survex
1.2.44.
</Para>

<Para>
Survex has long support MILS as an alias for GRADS.  However, this seems to
be a bogus definition of a "mil" which is unique to Survex (except that Therion
has since copied it) - there are several different definitions of a "mil" but
they vary from 6000 to 6400 in a full circle, not 400.  Because of this we
deprecated MILS in Survex 1.2.38 - you can still process data which uses them
but you'll now get a warning, and we recommend you update your data.
</Para>

<Para>
For example, if your data uses

<programlisting>
*units compass mils</programlisting>

then you need to determine what the intended units actually are.  If there
are 400 in a full circle, then instead use this (which will work with older
Survex versions too):

<programlisting>
*units compass grads</programlisting>

If the units are actually mils, you can specify that in terms of degrees.
For example, for NATO mils (6400 in a full circle) one mil is 360/6400
degrees, and 360/6400=0.05625 so you can use this (which also works with older
Survex versions):

<programlisting>
*units compass 0.05625 degrees</programlisting>
</Para>
</listitem>
</VarListEntry>

<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->

<VarListEntry><Term>See Also</Term>

<listitem><Para>*calibrate</Para></listitem>

</VarListEntry>

</VariableList>

</Sect3>

</Sect2>

</Sect1>

<!-- FIXME rename to "Cookbook"? -->
<Sect1><Title>Contents of <filename>.svx</filename> files: How do I?</Title>
<?dbhtml filename="svxhowto.htm">

<Para>
Here is some example <Application>Survex</Application> data (a very small cave numbered 1623/163):
</Para>

<programlisting>
2 1 26.60 222  17.5
2 3 10.85 014   7
2 4  7.89 254 -11
4 5  2.98  - DOWN
5 6  9.29 271 -28.5</programlisting>

<Para>
You can vary the data ordering.  The default is:
</Para>

<Para>
from-station to-station tape compass clino
</Para>

<Para>
This data demonstrates a number of useful features of <Application>Survex</Application>:
</Para>

<Para>
Legs can be measured either way round, which allows the use of
techniques like "leap-frogging" (which is where legs
alternate forwards and backwards).
</Para>

<Para>
Also notice that there is a spur in the survey (2 to 3).  You
do not need to specify this specially.
</Para>

<Para>
<Application>Survex</Application> places few restrictions on station naming (see "Survey
Station Names" in the previous section), so you can number the stations
as they were in the original survey notes.  Although not apparent from
this example, there is no requirement for each leg to connect to an
existing station.  <Application>Survex</Application> can accept data in any order, and will
check for connectedness once all the data has been read in.
</Para>

<Para>
Each survey is also likely to have other information associated
with it, such as instrument calibrations, etc.  This has been
omitted from this example to keep things simple.
</Para>

<Para>
Most caves will take more than just one survey trip to map.  Commonly
the numbering in each survey will begin at 1, so we need to be
able to tell apart stations with the same number in different
surveys.
</Para>

<Para>
To accomplish this, <Application>Survex</Application> has a very flexible system of hierarchical
prefixes.  All you need do is give each survey a unique name or
number, and enter the data like so:
</Para>

<programlisting>
*begin 163
*export 1
2 1 26.60 222  17.5
2 3 10.85 014   7
2 4  7.89 254 -11
4 5  2.98  - DOWN
5 6  9.29 271 -28.5
*end 163</programlisting>

<Para><Application>Survex</Application> will name the stations by attaching the current prefix.
In this case, the stations will be named 163.1, 163.2, etc.
</Para>

<Para>We have a convention with the CUCC Austria data that the entrance survey
station of a cave is named P&lt;cave number&gt;, P163 in this case. We
can accomplish this like so:
</Para>

<programlisting>
*equate P163 163.1
*entrance P163
*begin 163
*export 1
2 1 26.60 222  17.5
2 3 10.85 014   7
2 4  7.89 254 -11
4 5  2.98  - DOWN
5 6  9.29 271 -28.5
*end 163</programlisting>

<Sect2><Title>Specify surface survey data</Title>

<Para>
Say you have 2 underground surveys and 2 surface ones with 2 fixed reference
points.  You want to mark the surface surveys so that their length isn't
included in length statistics, and so that Aven knows to display them
differently.  To do this you mark surface data with the "surface" flag
- this is set with "*flags surface" like so:
</Para>

<programlisting>
; fixed reference points
*fix fix_a 12345 56789 1234
*fix fix_b 23456 67890 1111                                                     
                                                                                
; surface data (enclosed in *begin ... *end to stop the *flags command
; from "leaking" out)
*begin
*flags surface
*include surface1
*include surface2
*end                                                                            
                                                                                
; underground data
*include cave1
*include cave2</programlisting>

<Para>
You might also have a survey which starts on the surface and heads into a
cave.  This can be easily handled too - here's an example which goes in
one entrance, through the cave, and out of another entrance:
</Para>

<programlisting>
*begin BtoC
*title "161b to 161c"
*date 1990.08.06 ; trip 1990-161c-3 in 1990 logbook

*begin
*flags surface
02    01      3.09   249    -08.5
02    03      4.13   252.5  -26
*end

04    03      6.00   020    +37
04    05      3.07   329    -31
06    05      2.67   203    -40.5
06    07      2.20   014    +04
07    08      2.98   032    +04
08    09      2.73   063.5  +21
09    10     12.35   059    +15

*begin
*flags surface
11    10      4.20   221.5  -11.5
11    12      5.05   215    +03.5
11    13      6.14   205    +12.5
13    14     15.40   221    -14
*end

*end BtoC</programlisting>

<Para>
Note that to avoid needless complication, Survex regards each leg as
being either "surface" or "not surface" - if a leg spans the boundary you'll
have to call it one or the other.  It's good surveying practice to
deliberately put a station at the surface/underground interface
(typically the highest closed contour or drip line) so this generally
isn't an onerous restriction.
</Para>

</Sect2>

<Sect2><Title>Specify the ordering and type of data</Title>

<Para>The *DATA command is used to specify the data style, and the
order in which the readings are given.</Para>

</Sect2>

<Sect2><Title>Deal with Plumbs or Legs Across Static Water</Title>

<!-- FIXME
<Para>
They can be given
as +90, or -90, but as they are not usually measured with the
clino, but with a plumb of some sort, then it is useful to distinguish
them in this way so that any clino adjustment is not applied to
these values.
</Para>

FIXME: paste in section from mail to list

<Para>
Note that a similar effect can be achieved by using the "*infer plumbs" command
to stop clino corrections being applied to -90 and +90 clino readings.
</Para>
-->

<Para>
Plumbed legs should be given using 'UP' or 'DOWN' in place of the
clino reading and a dash (or a different specified 'OMIT' character)
in place of the compass reading.  This distinguishes
them from legs measured with a compass and clino.  Here's an example:
</Para>

<programlisting>
1 2 21.54 - UP
3 2 7.36 017 +17
3 4 1.62 091 +08
5 4 10.38 - DOWN</programlisting>

<Para>
U/D or +V/-V may be used instead of UP/DOWN; the check is not case
sensitive.
</Para>

<Para>
Legs surveyed across the surface of a static body of water where no
clino reading is taken (since the surface of the water can be assumed
to be flat) can be indicated by using LEVEL in place of a clino reading.
This prevents the clino correction being applied.  Here's an example:
</Para>

<programlisting>
1 2 11.37 190 -12
3 2  7.36 017 LEVEL
3 4  1.62 091 LEVEL</programlisting>

</Sect2>

<Sect2><Title>Specify a BCRA grade</Title>

<Para>The *SD command can be used to specify the standard deviations of the
various measurements (tape, compass, clino, etc).  Examples files are
supplied which define BCRA Grade 3 and BCRA Grade 5 using a number of *sd
commands. You can use these by simply including them at the relevant point,
as follows:
</Para>

<programlisting>
*begin somewhere
; This survey is only grade 3
*include grade3
2 1 26.60 222  17.5
2 3 10.85 014   7
; etc
*end somewhere</programlisting>

<Para>The default values for the standard deviations are those for
BCRA grade 5. Note that it is good practice to keep the *include
Grade3 within *Begin and *End commands otherwise it will apply
to following survey data, which may not be what you intended.
</Para>

</Sect2>

<Sect2><Title>Specify different accuracy for a leg</Title>

<Para>For example, suppose the tape on the plumbed leg in this survey
is suspected of being less accurate than the rest of the survey because
the length was obtained by measuring the length of the rope used to rig
the pitch.  We can set a higher sd for this one measurement and use a
*begin/*end block to make sure this setting only applies to the one
leg:
</Para>

<programlisting>
2 1 26.60 222  17.5
2 3 10.85 014   7
2 4  7.89 254 -11
*begin
; tape measurement was taken from the rope length
*sd tape 0.5 metres
4 5  34.50 - DOWN
*end
5 6  9.29 271 -28.5</programlisting>

<!-- FIXME also *calibrate and *instrument? Except rope is measure with the
tape... -->
</Sect2>

<Sect2><Title>Enter Repeated Readings</Title>

<Para>If your survey data contains multiple versions of each leg (for example,
pockettopo produces such data), then provided these are adjacent to one another
Survex 1.2.17 and later will automatically average these and treat them as a
single leg.
</Para>

</Sect2>

<Sect2><Title>Enter Radiolocation Data</Title>

<!-- FIXME comments from David Gibson here -->
<Para>This is done by using the *SD command to specify the appropriate
errors for the radiolocation `survey leg' so that the loop closure
algorithm knows how to distribute errors if it forms part of a loop.
</Para>

<Para>The best approach for a radiolocation where the underground station
is vertically below the surface station is to represent it as a
plumbed leg, giving suitable SDs for the length and plumb angle. The
horizontal positioning of this is generally quite accurate, but the
vertical positioning may be much less well known. E.g: we have a
radiolocation of about 50m depth +/- 20m and horizontal accuracy of
+/- 8m. Over 50m the +/-8m is equivalent to an angle of 9 degrees, so
that is the expected plumb error. 20m is the expected error in the
length. To get the equivalent SD we assume that 99.74% of readings will
be within 3 standard deviations of the error value. Thus we divide the
expected errors by 3 to get the SD we should specify:
</Para> <!-- 3 SD? or same as BCRA3.SVX, etc -->

<programlisting>
*begin
*sd length 6.67 metres
*sd plumb 3 degrees
surface underground 50 - down
*end</programlisting>

<Para>
We wrap the radiolocation leg in a *begin/*end block to make
sure that the special *sd settings only apply to this one leg.
</Para>

<Para>For more information on the expected errors from radiolocations
see Compass Points Issue 10, available online at
<ulink url="http://www.chaos.org.uk/survex/cp/CP10/CPoint10.htm">http://www.chaos.org.uk/survex/cp/CP10/CPoint10.htm</ulink>
</Para>

</Sect2>

<Sect2><Title>Enter Diving Data</Title>

<Para>Surveys made underwater using a diver's depth gauge can be
processed - use the *Data command to specify that the following data
is of this type.
</Para>

</Sect2>

<Sect2><Title>Enter Theodolite data</Title>

<Para>
Theodolite data with turned angles is not yet explicitly catered
for, so for now you will need to convert it into equivalent legs in
another style - normal or cylpolar are likely to be the best choices.
</Para>

<Para>
If there is no vertical info in your theodolite data then you should
use the cylpolar style and use *sd command to specify very low
accuracy (high SD) in the depth so that the points will move in the
vertical plane as required if the end points are fixed or the survey
is part of a loop.
</Para>

</Sect2>

</Sect1>

<Sect1><Title>General: How do I?</Title>
<?dbhtml filename="genhowto.htm">

<Sect2><Title>Create a new survey</Title>

<Para>You simply create a text file containing the relevant survey data,
using a text editor, and save it with a suitable name with a <filename>.svx</filename>
extension. The
easiest way is to look at some of the example data and use that
as a template. Nearly all surveys will need a bit of basic info
as well as the survey data itself: e.g. the date (*date), comments
about where, what cave, a name for the survey (using *begin and *end),
instrument error corrections etc. Here is a typical survey file:
</Para>

<Para>All the lines starting with ';' are comments, which are ignored
by <Application>Survex</Application>. You can also see the use of 'DOWN' for plumbs, and
*calibrate tape for dealing with a tape length error (in this case
the end of the tape had fallen off so measurements were made from the
20cm point).</Para>

<programlisting>
*equate chaos.1 triassic.pt3.8
*equate chaos.2 triassic.pt3.9

*begin chaos
*title "Bottomless Pit of Eternal Chaos to Redemption pitch"
*date 1996.07.11
*team "Nick Proctor" compass clino tape
*team "Anthony Day" notes pictures tape
*instrument compass "CUCC 2"
*instrument clino "CUCC 2"
;Calibration: Cairn-Rock 071 072 071,  -22 -22 -22
;       Rock-Cairn 252 251 252,  +21 +21 +21
;Calibration at 161d entrance from cairn nr entrance to
;prominent rock edge lower down. This is different from
;calibration used for thighs survey of 5 July 1996

*export 1 2

;Tape is 20cm too short
*calibrate tape +0.2

1 2 9.48 208 +08
2 3 9.30 179 -23
3 4 2.17 057 +09
5 4 10.13 263 +78
5 6 2.10 171 -73
7 6 7.93 291 +75
*begin
*calibrate tape 0
8 7 35.64 262 +86 ;true length measured for this leg
*end
8 9 24.90 - DOWN
10 9 8.61 031 -43
10 11 2.53 008 -34
11 12 2.70 286 -20
13 12 5.36 135 +23
14 13 1.52 119 -12
15 14 2.00 036 +13
16 15 2.10 103 +12
17 16 1.40 068 -07
17 18 1.53 285 -42
19 18 5.20 057 -36
19 20 2.41 161 -67
20 21 27.47 - DOWN
21 22 9.30 192 -29
*end chaos</programlisting>

</Sect2>

<Sect2><Title>Join surveys together</Title>

<Para>Once you have more than one survey you need to specify how they
link together. To do this use *export to make the stations to be
joined accessible in the enclosing survey, then *equate in the
enclosing survey to join them together.
<!-- FIXME example -->
</Para>

</Sect2>

<Sect2><Title>Organise my surveys</Title>

<Para>This is actually a large subject. There are many ways you can
organise your data using <Application>Survex</Application>. Take a look at the example dataset
for some ideas of ways to go about it.
</Para>

<Sect3><Title>Fixed Points (Control Points)</Title>

<Para>The *fix command is used to specify fixed points (also know as control
points).  See the description of this command in the "Cavern Commands"
section of this manual.
</Para>

</Sect3>

<Sect3><Title>More than one survey per trip</Title>

<Para>Suppose you have two separate bits of surveying which were done on the
same trip.  So the calibration details, etc. are the same for both.  But you
want to give a different survey name to the two sections.  This is easily
achieved like so:
</Para>

<programlisting>
*begin
*calibrate compass 1.0
*calibrate clino 0.5
*begin altroute
; first survey
*end altroute
*begin faraway
; second survey
*end faraway
*end</programlisting>

</Sect3>

</Sect2>

<Sect2><Title>Add surface topography</Title>

<Para>Survex 1.2.18 added support for loading terrain data and rendering it as
a transparent surface.  Currently the main documentation for this is maintained
as a <ulink url="https://trac.survex.com/wiki/TerrainData">wiki page</ulink>
as this allows us to update it between releases.
</Para>

<Para>
We recommend using this new code in preference, but previously the simplest
approach was to generate a <filename>.svx</filename> file with the surface mesh
in and display it with the survey data.
</Para>

<Para>
It is possible to generate
a mesh or contours overlaying your area by various means.  NASA have made
1 arc-second (approximately 30m) terrain data available for the USA for
some years, with only 3 arc-second data available for other countries.
However, starting in 2014 they're gradually making 1 arc-second data
available for more countries.
</Para>

<Para>
If you want a better resolution that this, reading heights from the
contours on a map is one approach.  It's laborious, but feasible for
a small area.
</Para>

<Para>
Details of several methods are given in the BCRA Cave Surveying
Group magazine Compass Points issue 11, available online at
<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>
</Para>

<Para>If you're using another program to generate a <filename>.svx</filename> file for the surface
mesh, it's best to use the NOSURVEY data style.
Simply fix all the grid intersections at the correct
coordinates and height, and put legs between them using the NOSURVEY style.
Here's a grid of 4 squares and 9 intersections:
</Para>

<programlisting>
*fix 00 000 000 1070
*fix 01 000 100 1089
*fix 02 000 200 1093

*fix 10 100 000 1062
*fix 11 100 100 1080
*fix 12 100 200 1089

*fix 20 200 000 1050
*fix 21 200 100 1065
*fix 22 200 200 1077

*data nosurvey station

00
01
02

10
11
12

20
21
22

00
10
20

01
11
21

02
12
22</programlisting>

<Para>
This is far simpler than trying to create fake tape/compass/clino legs of
the right length for each line in the mesh.  It's also very fast to process
with cavern.
</Para>

</Sect2>

<Sect2><Title>Overlay a grid</Title>

<Para>Aven is able to display a grid, but this functionality isn't currently
available in printouts.
You can achieve a similar effect for now by creating a <filename>.svx</filename> file
where the survey legs form a grid.
</Para>

</Sect2>

<Sect2><Title>Import data from other programs</Title>

<Para><Application>Survex</Application> supports a number of features to help with importing
existing data.</Para>

<Para>
Survey data in Compass or Walls format can be processed directly. Processed
survey data in Compass or CMAP formats can be viewed.
</Para>

<Para>For other formats, you may be able to read the data by renaming the file to have
a .svx extension and adding a few Survex commands at the start of the file so Survex
can read the data which follows.  For example, you can specify the ordering of items on a line using *Data
(see <Application>Survex</Application> Keywords above), and you can specify the characters used
to mean different things using *Set (see <Application>Survex</Application> Keywords above).
</Para>

<Para>The Ignore and Ignoreall options to the *Data command are often
particularly useful, e.g. if you have a dataset with LRUD info or comments
on the ends of lines.
</Para>

<Sect3><Title>Changing Meanings of Characters</Title>

<Para>e.g. if you have some data with station names containing the 
characters '?' and '+' (which are not permitted in a name by default)
then the command:
</Para>

<programlisting>
*SET NAMES ?+</programlisting>

<Para>
specifies that question marks and plus signs are permitted in station names.
A-Z, a-z, and 0-9 are always permitted. '_' and '-' are also permitted by
default, but aren't in this example.
</Para>

<Para>If your data uses a comma ',' instead of a decimal point, then
you use
</Para>

<programlisting>
*SET DECIMAL ,</programlisting>

<Para>to specify that ',' is now the decimal separator instead of '.'.
</Para>

<!-- FIXME
<Para>Note that there are plenty of ways you can use this facility to
completely confuse the software, as it may not be able to work out what is
going on, or it may simply be ambiguous. It can cope with some ambiguity (e.g.
the '-' character is used both for 'MINUS' and for 'OMIT'), but there are
limits. If you have a dataset that you can not make <Application>Survex</Application>
understand, then send it to us, and we will see what can be done.
</Para>
-->

</Sect3>

<!--
 Nobody seems to have the CfH convertor...
 but it's probably no longer useful anyway

<Sect3><Title>Other Converters</Title>

<Para>We have an Excel 5 macro for converting The Lotus 123 spreadsheets
used by the German survey software Cad F&uuml;r H&ouml;hlen into
<Application>Survex</Application> data files. Other converters may also come to be available.
These will normally be available via the
<ulink url="https://survex.com/"><Application>Survex</Application> Web pages</ulink>.
</Para>

</Sect3>
-->

</Sect2>

<Sect2><Title>See errors and warnings that have gone off the screen</Title>

<Para>When you run <Application>Survex</Application> it will process the specified survey data
files in order, reporting any warnings and errors.  If there are no
errors, the output files are written and various statistics about the
survey are displayed. If there are a lot of warnings or errors, they can
scroll off the screen and it's not always possible to scroll back to
read them.
</Para>

<Para>The easiest way to see all the text is to use <command>cavern
--log</command> to redirect output to a <filename>.log</filename> file,
which you can then inspect with a text editor.
</Para>

<!-- <command>cavern cavename &gt; tmpfile</command> -->

</Sect2>

<Sect2><Title>Create an Extended Elevation</Title>

<Para>Use the Extend program. This takes <filename>.3d</filename> files and
'flattens' them.  See 'Extend' for details.
</Para>

</Sect2>

</Sect1>

<!--
<Sect1><Title>Appendices</Title>
<?dbhtml filename="appendix.htm">

<Para>Files provided
</Para>

<Para>Command specification
</Para>

</Sect1>
-->
<Sect1><Title>Working with Larry Fish's Compass</Title>
<?dbhtml filename="compass.htm">

<Para>
Survex can read Compass survey data - it supports survey data files and
project files (.DAT and .MAK files), closed data files (.CLP), and processed
survey data (.PLT and .PLF files). Survex 1.4.6 made significant improvements to
this support so we recommend using this version or newer if you're working with
Compass data.
</Para>

<Sect2><Title>Compass .DAT support</Title>
<Para>
A Compass .DAT file contains raw survey data. You can process a .DAT file
with cavern or aven as if it were a .svx file.
</Para>

<Para>
You can even use <command>*include compassfile.dat</command> in a
<filename>.svx</filename> file and it'll work, which allows combining
separate cave survey projects maintained in Survex and Compass.
</Para>

<Para>
One point to note when doing so (this tripped us up!) is that station names
in DAT files are case sensitive and so Survex reads DAT files with the
equivalent of <command>*case preserve</command>.  The default in SVX files is
<command>*case lower</command>.  So this won't work

<programlisting>
*fix CE1 0 0 0
*include datfilewhichusesCE1.dat</programlisting>

because the CE1 in the *fix is actually interpreted as ce1.  The solution
is to turn on preserving of case while you fix the point like so:

<programlisting>
*begin
*case preserve
*fix CE1 0 0 0
*end
*include datfilewhichusesCE1.dat</programlisting>

If you want to be able to refer to the fixed point from Survex data too
then you can add in a *equate to achieve that:

<programlisting>
*begin
*case preserve
*fix CE1 0 0 0
*equate CE1 ce1
*end
*include datfilewhichusesCE1.dat
*include svxfilewhichusesce1.svx</programlisting>

Or if you're just wanting to link a Compass survey to a Survex one, you
can use a *equate with *case preserve on:

<programlisting>
*begin
*case preserve
*equate CE1 ce1
*end
*include datfilewhichusesCE1.dat
*include svxfilewhichusesce1.svx</programlisting>
</Para>

<Para>
    Survex understands most DAT file features.  Known current limitations and
    assumptions:

<ItemizedList>
    <ListItem><Para>
        The cave name, survey short name, survey comment and survey team
        information are currently ignored (because this information isn't
        currently saved in the .3d file even for .svx files).
    </Para></ListItem>
    <ListItem><Para>
        Survey date January 1st 1901 is treated as "no date specified", since
        this is the date Compass stores in this situation, and it seems very
        unlikely to occur in real data.
    </Para></ListItem>
    <ListItem><Para>
        Passage dimensions are currently ignored.
    </Para></ListItem>
    <ListItem><Para>
        Shot flag C is currently ignored.
    </Para></ListItem>
    <ListItem><Para>
        Shot flag L is mapped to Survex's "duplicate" leg flag.
    </Para></ListItem>
    <ListItem><Para>
        Shot flag P is mapped to Survex's "surface" leg flag.  The Compass
        documentation describes shot flag P as "Exclude this shot from
        plotting", but the suggested use for it is for surface data, and
        shots flagged P "[do] not support passage modeling". Even if it's
        actually being used for a different purpose, Survex programs don't show
        surface legs by default so the end effect is at least to not plot as
        intended.
    </Para></ListItem>
    <ListItem><Para>
        Shot flag S is mapped to Survex's "splay" leg flag.
    </Para></ListItem>
    <ListItem><Para>
        Surveys which indicate a depth gauge was used for azimuth readings are
        now marked as STYLE_DIVING in the 3d file.
    </Para></ListItem>
</ItemizedList>
</Para>

</Sect2>

<Sect2><Title>Compass .MAK support</Title>

<Para>
    A Compass .MAK file defines a survey project to process, and specifies one or
    more .DAT files to process, along with coordinate systems and fixed points.
    You can process a .MAK file with cavern or aven as if it were a .svx file.
</Para>

<Para>
    Survex understands most MAK file features.  Known current limitations and
    assumptions:

<ItemizedList>
    <ListItem><Para>
        Survex handles the UTM zone and datum provided the combination can be
        expressed as an EPSG code (lack of any EPSG codes for a datum suggests
        it's obsolete; lack of a code for a particular datum+zone combination
        suggests the zone is outside of the defined area of use of the datum).
        Example Compass files we've seen use "North American 1927" outside of
        where it's defined for use, presumably because some users fail to change
        the datum from Compass' default. To enable reading such files we return
        a PROJ4 string of the form "+proj=utm ..." for "North American 1927" and
        "North American 1983" for UTM zones which don't have an EPSG code.
        Please let us know if support for additional cases which aren't
        currently supported would be useful to you.
    </Para></ListItem>
    <ListItem><Para>
        The @ command which specifes a base location to calculate magnetic
        declinations at is handled, provided the datum and UTM zone are
        supported (see previous bullet point). The UTM convergence angle
        specified as part of this command is ignored as Survex knows how to
        calculate it.
    </Para></ListItem>
    <ListItem><Para>
        Link stations are ignored.  These have two uses in Compass.  They were
        a way to allow processing large surveys on computers from last century
        which had limited memory.  Survex can easily handle even the largest
        surveys on current hardware and ignoring them is not a problem in this
        case.
    </Para>
    <Para>
        The other use is they provide a way to process surveys together
        which use the same station names for different stations.  In this
        case we recommend writing a .svx file to replace the MAK file which
        wraps the <command>*include</command> of each DAT file in
        <command>*begin survey1</command>/<command>*end survey1</command>, etc so that
        stations have unique qualified names.  Then the link stations can
        be implementing using e.g. <command>*equate survey1.XX1 survey2.XX1</command>.
        This example from the Compass documentation:

<programlisting>
#FILE1.DAT;                /no links
#FILE2.DAT,A22,A16;
#FILE3.DAT,A16,B14;</programlisting>

        would look like this:

<programlisting>
*begin file1
*include FILE1.DAT
*end file1
*begin file2
*include FILE2.DAT
*end file2
*equate file1.A22 file2.A22
*begin file3
*include FILE3.DAT
*end file3
*equate file1.A16 file3.A16
*equate file2.B14 file3.B14</programlisting>

Note that the .svx version is able to more precisely represent what's actually
required here - in the MAK version "you must carry A16 into FILE2 even though
FILE2 doesn't need it for its own processing".  If you want the exact analog of
the MAK version you can change the A16 equate to:

<programlisting>
*equate file1.A16 file2.A16 file3.A16</programlisting>
    </Para></ListItem>

    <ListItem><Para>
        The following commands (and any other unknown commands) are currently
        ignored:
            % (Convergence angle (file-level)),
            * (Convergence angle (non file-level)),
            ! (Project parameters)
    </Para></ListItem>
</ItemizedList>
</Para>
</Sect2>

<Sect2><Title>Compass .CLP support</Title>
<Para>
A Compass .CLP file contains raw survey data after adjusting for loop closure.
The actual format is otherwise identical to a Compass .DAT file, and Survex
1.4.6 and later support processing a .CLP file with cavern or aven as if it
were a .svx file (the extra support is to recognise the .CLP extension, and
to not apply the instrument corrections a second time).
</Para>

<Para>
You can even use <command>*include compassfile.clp</command> in a
<filename>.svx</filename> file and it'll work, which allows combining
separate cave survey projects maintained in Survex and Compass.
</Para>

<Para>
Usually it is preferable to process the survey data without loop closure
adjustments (i.e. .DAT) so that when new data is added errors get
distributed appropriately across old and new data, but it might be
useful to use the .CLP file if you want to keep existing stations at the same
adjusted positions, for example to be able to draw extensions on an existing
drawn-up survey which was processed with Compass.
</Para>

<Para>
Another possible reason to use the data from a .CLP file is if that's all
you have because the original .DAT file has been lost.
</Para>
</Sect2>

<Sect2><Title>Compass .PLF/.PLT support</Title>
<Para>
A Compass .PLT file contains processed survey data.  The extension .PLF is
also used for "special feature files" which have essentially the same format.
You can load these files with <command>aven</command> as if they were .3d
files, and similarly for other Survex tools which expect a .3d file such as
<command>survexport</command>, <command>extend</command>,
<command>diffpos</command>, <command>3dtopos</command> and
<command>dump3d</command>.  (This support is actually provided by Survex's img
library, so other programs which use this library should also be able to read
Compass .PLT files without much extra work.)
</Para>

<Para>
    Survex understands most PLT file features.  Known current limitations and
    assumptions:

<ItemizedList>
    <ListItem><Para>
        Survey date January 1st 1901 is treated as "no date specified", since
        this is the date Compass stores in this situation, and it seems very
        unlikely to occur in real data.
    </Para></ListItem>
    <ListItem><Para>
        Passage dimensions are translated to passage tubes, but Survex may
        interpret them differently from Compass.
    </Para></ListItem>
    <ListItem><Para>
        Shot flag C is currently ignored.
    </Para></ListItem>
    <ListItem><Para>
        Shot flag L is mapped to Survex's "duplicate" leg flag.
    </Para></ListItem>
    <ListItem><Para>
        Shot flag P and plot command d are mapped to Survex's "surface" leg
        flag. The Compass documentation describes shot flag P as "Exclude this
        shot from plotting", but the suggested use for it is for surface data,
        and shots flagged P "[do] not support passage modeling". Even if it's
        actually being used for a different purpose, Survex programs don't show
        surface legs by default so the end effect is at least to not plot as
        intended.  Stations are flagged as surface and/or underground based
        on whether they are at the ends of legs flagged surface or non-surface
        (a station at the boundary can be flagged as both).
    </Para></ListItem>
    <ListItem><Para>
        Shot flag S is mapped to Survex's "splay" leg flag.  A station at the
        far end of a shot flagged S gets the "station on wall" flag set since
        the Compass PLT format specification says:
        <quote>
            The shot is a "splay" shot, which is a shot from a station to the
            wall to define the passage shape.
        </quote>
    </Para></ListItem>
    <ListItem><Para>
        Stations with "distance from entrance" of zero are flagged as entrances.
    </Para></ListItem>
    <ListItem><Para>
        Stations which are present in multiple surveys are flagged as exported
        (like when <command>*infer exports</command> is in effect in .svx files).
    </Para></ListItem>
    <ListItem><Para>
        Stations listed as fixed points are flagged as fixed points.
    </Para></ListItem>
    <ListItem><Para>
        If a PLT file only uses one datum and UTM zone combination and it is
        supported (the same combinations are supported as for MAK files) then
        they are converted to the appropriate EPSG code or PROJ4 string and this
        is reported as the coordinate system.  Please let us know if support for
        additional cases which aren't currently supported would be useful to you.
        Files with multiple datums could be handled too, but we'd need to convert
        coordinates to a common coordinate system in the img library, which would
        need it to depend on PROJ.  Please let us know if support for mixed
        datums would be useful to you.
    </Para></ListItem>
</ItemizedList>
</Para>

</Sect2>

</Sect1>

<Sect1><Title>Mailing List</Title>
<?dbhtml filename="maillist.htm">

<Para>The best way to contact the authors and other Survex users is the
Survex mailing list - for details visit:
<ulink url="https://survex.com/maillist.html">https://survex.com/maillist.html</ulink>
</Para>

<Para>We'd be delighted to hear how you get on with <Application>Survex</Application> and
welcome comments and suggestions for improvements.</Para>

<Para>
And we'd love you to contribute your skills to help make <Application>Survex</Application> even
better.  Point out areas of the documentation which could be made clearer, or
sections which are missing entirely.  Download test releases, try them out, and
let us know if you find problems or have suggestions for improvements.
If there's no translation to your language, you could provide one.
Or if you're a developer, <emphasis>"Say it with code"</emphasis>.  There's
plenty to do, so feel free to join in.
</Para>

</Sect1>

<Sect1><Title>Working with David McKenzie's Walls</Title>
<?dbhtml filename="walls.htm">

<Para>
Survex 1.4.9 and later can read Walls unprocessed survey data (.SRV and .WPJ
files).  The support is currently somewhat experimental, as the documentation
of the SRV format is incomplete and incorrect in places, while the WPJ format
seems to be largely undocumented, and David is sadly no longer around to ask.
</Para>

<Para>
The current status is that most .SRV files should process individually (but
see details below of features which are not handled), while there are still some
known issues which cause problems with some .WPJ files.
</Para>

<Para>
Walls is no longer being developed, so the focus of support for Walls
formats is primarily to help people with existing Walls data to migrate.
If you are in this situation and the incomplete WPJ support is a problem, you
should be able to write a .svx file to replace your WPJ file - you can use
"*include somedata.srv" to include a Walls .srv from a .svx file.
</Para>

<Para>
<ItemizedList>
    <ListItem><Para>
        Walls allows hanging surveys, whereas these are currently treated as an
        error by Survex.  This is probably the current top priority to address.
    </Para></ListItem>
    <ListItem><Para>
        Survex reports warnings in some suspect situations which Walls quietly
        accepts.  In general this seems helpful, but if there are particular
        instances which are noisy and not useful, let us know.
    </Para></ListItem>
    <ListItem><Para>
        #FIX - currently Survex does not support horizontal-only or vertical
        only fixes. These are currently given an SD of 1000m in that direction
        instead, but that is not the same as completely decoupling the fix in
        that direction.
    </Para></ListItem>
    <ListItem><Para>
        #FIX - degree:minute:second fixes (e.g. W97:43:52.5) are not currently
        supported.
    </Para></ListItem>
    <ListItem><Para>
        Walls FLAG values seems to be arbitrary text strings.  We try to infer
        appropriate Survex station flags by checking for certain key words in
        that text (currently we map words ENTRANCE and FIX to the corresponding
        Survex station flags) and otherwise ignore FLAG values.
    </Para></ListItem>
    <ListItem><Para>
        We don't currently support all the datum names which Walls does because
        we haven't managed to find an EPSG code for any UTM zones in some of
        these datums.  This probably means they're not actually in current
        use.
    </Para></ListItem>
    <ListItem><Para>
        We currently assume all two digit years are 19xx (Walls documents
        it 'also accepts "some date formats common in the U.S. (mm/dd/yy,
        mm-dd-yyyy, etc.)' but doesn't say how it interprets 'yy'.
    </Para></ListItem>
    <ListItem><Para>
        The documentation specifies that the SAVE and RESTORE options should be
        processed before other options.  Currently Survex just processes all
        options in the order specified, which makes no difference to any
        real-world data we've seen. We need to test with Walls32.exe to
        determine exactly how this works (and if RESET is also special).
    </Para></ListItem>
    <ListItem><Para>
        LRUD data is currently ignored.
    </Para></ListItem>
    <ListItem><Para>
        The TAPE= option is currently quietly skipped, and tape measurements
        are assumed to be station to station.
    </Para></ListItem>
    <ListItem><Para>
        In TYPEAB= and TYPEVB=, the threshold is ignored, as is the X meaning to
        only use foresights (but still check backsights). Survex uses a
        threshold based on the specified instrument SDs, and averages foresights
        and backsights.
    </Para></ListItem>
    <ListItem><Para>
        FLAG= is quietly skipped.
    </Para></ListItem>
    <ListItem><Para>
        UV=, UVH= and UVV= are all quietly skipped.
    </Para></ListItem>
    <ListItem><Para>
        The GRID= option currently gives an "Unknown command" warning, and is
        skipped.  If your Walls data specifies a UTM zone then Survex will
        automatically correct for grid convergence.
    </Para></ListItem>
    <ListItem><Para>
        The INCH= option currently gives an "Unknown command" warning, and is
        skipped.
    </Para></ListItem>
    <ListItem><Para>
        The RECT= option currently gives an "Unknown command" warning, and is
        skipped (this option specifies how much to orient cartesian style data
        relative to true North, not to be confused with the RECT option which
        is upported).
    </Para></ListItem>
    <ListItem><Para>
        Walls documents allowing a "maxiumum of eight characters" in unprefixed
        names - we don't bother trying to enforce this restriction, but this
        should not make a difference in valid data.
    </Para></ListItem>
    <ListItem><Para>
        Walls seems to allow \ in place of / in some places (e.g. #FLAG).  We
        aim to support this too, but it doesn't seem to be documented so may
        not currently be supported in the correct places.
    </Para></ListItem>
    <ListItem><Para>
        The inheritance of settings in WPJ files is probably not correctly
        implemented currently.
    </Para></ListItem>
    <ListItem><Para>
        The Walls documentation mentions a NOTE= option, but doesn't document
        what it does, and testing with Walls32.exe it doesn't seem to actually
        be supported!
    </Para></ListItem>
    <ListItem><Para>
        The two UPS zones for the polar regions (specified as UTM zone values
        of -61 and 61 in Walls) are supported with datum WGS84, but we do not
        have any real data to test this support with.
    </Para></ListItem>
</ItemizedList>
</Para>

<Para>
If you find some Walls data which Survex doesn't handle or handles incorrectly,
and it is not already noted above, please let us know. If you can provide some
data demonstrating the problem, that's really helpful. It's also useful to know
if there are things listed above that are problematic to help prioritise
efforts.
</Para>

<Sect1><Title>Working with Bob Thrun's CMAP</Title>
<?dbhtml filename="walls.htm">

<Para>
Survex can read CMAP processed survey data, commonly known as CMAP XYZ files.
CMAP no longer seems to be used, but we've kept the support in place so
it's there if anyone finds old data and wants to view it.
</Para>

<Para>
Support was added long ago (Survex 1.0.4) but you really want to use Survex
1.4.9 or later due to a feet to metres conversion bug in all versions before
this, which scaled all returned coordinates from CMAP XYZ files by a factor of
about 10.76.
</Para>

<Para>
CMAP XYZ files contain a timestamp.  CMAP was originally written for computers
where the clock was just set to localtime so it seems likely this timestamp is
in localtime, but it does not specify a timezone. Survex assumes it's in UTC,
which is at least fairly central in the possibilities, but may mean timestamps
are off by up to about half a day. The timestamps in example files all use two
digit years. It's not documented how CMAP handles years 2000 and later, so we
assume 4 digit years are correct, years &lt; 50 are 20xx, and other years get
1900 added to them (so year 101 is 2001).
</Para>

<Para>
CMAP XYZ files don't seem to contain any stations flags.  There's a single
character "type" which acts as a leg flag of sorts, but it seems the
meaning is up to the user so we don't try to interpret it.  We assume all
the data is underground (so all stations get the "underground" flag).
</Para>

<Para>
There are two variants of CMAP XYZ files.  CMAP v16 and later produce
the "shot" variant (with extension ".sht"), which is well supported by
Survex.
</Para>

<Para>
Older CMAP versions produced the "station" variant (with extension ".adj" for
adjusted data and ".una" for unadjusted data).  Survex only supports
reading stations from these - the survey legs linking them are currently
ignored.
</Para>

<Sect1><Title>Future Developments</Title>
<?dbhtml filename="future.htm">

<Para>
Now that <Application>Survex</Application> has reached version 1.0, we are continuing progress
towards version 2, in a series of steps, evolving out of 
Survex 1.0.  The GUI framework is being based on aven, with
the printer drivers and other utility programs being pulled in
and integrated into the menus.</Para>

<Para>Aven is built on <Application>wxWidgets</Application>, which means that it can easily support
Unix, Microsoft Windows, and macOS.</Para>

<Para>More information on our plans is on the <ulink
url="https://survex.com/">web site</ulink>.
</Para>

</Sect1>

</article>