source: git/doc/manual.sgml @ fbf7fa0

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

doc/manual.sgml: Document averaging of a group of repeated readings.

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