source: git/doc/manual.sgml @ 6340494

line_contentsstereotravis-osx
Last change on this file since 6340494 was 6340494, checked in by Olly Betts <olly@…>, 5 years ago
  • .gitignore,doc/manual.sgml,lib/Makefile.am,src/message.c: There's no

need to duplicate de.msg to de_DE.msg, as the code will fall-back to
de from de_DE anyway.

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