source: git/doc/manual.sgml @ 42607d0

line_contentsstereotravis-osx
Last change on this file since 42607d0 was 42607d0, checked in by Olly Betts <olly@…>, 5 years ago

doc/manual.sgml,lib/Makefile.am,lib/hu.po,src/message.c,
survex.iss.in: Add start of Hungarian translation from Imre Balogh.

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