source: git/doc/manual.sgml @ ce15637

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

doc/manual.sgml,src/commands.c,tests/cmd_dummy.svx,
tests/doubleinc.out: Add *ref command to allow specifying an external
reference.

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