source: git/doc/manual.sgml @ d959ab2

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

buildmacosx.sh,configure.ac,doc/manual.sgml: Update references to
Survex 1.1 which should be to 1.2.

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