doc/manual.sgml

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