source: git/doc/manual.sgml @ bfd5706

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

doc/manual.sgml: Add complete list of quantities you can set SDs
for. Thanks for Wookey for highlighting that the previous list was
incomplete.

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