source: git/doc/manual.sgml @ 22c8c00

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

doc/manual.sgml: Note what coordinate systems *cs currently actually
supports.

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