source: git/doc/cavern.sgml @ a4ae909

<refmeta>
<refentrytitle>cavern</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>

<refnamediv>
<refname>cavern</refname>
<refpurpose>process raw survey data
</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>cavern</command>
<arg choice="opt">options</arg>
<arg choice="req" rep="repeat">survex data file</arg> <!--FIXME-->
</cmdsynopsis>
</refsynopsisdiv>
  
<refsect1><title>Description</title>

<Para>Cavern is the &survexsuite; data processing engine.</Para>

<Para>If multiple survey data files are listed on the command line,
they are processed in order from left to right.  Settings are reset to
their defaults before processing each file.
</Para>

</refsect1>

<refsect1><Title>Options</Title>

<VariableList>
<VarListEntry>
<Term>-p, --percentage</Term>
<ListItem>
<Para>You can get cavern to display the percentage progress through the
current file.  As of &survexsuite; 0.90 this is disabled by default, but you
can enable it if you want.  Because the value given is for the
<emphasis/current/ file, the values jump around for a multi-file survey
project. Also note that displaying this information slows down processing
a little.
<!-- FIXME: on a slow machine you'd probably rather it ran faster, and on a
fast machine you can't follow the change percentages.-->
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-o, --output=OUTPUT</Term>
<ListItem>
<Para>Sets location for output files.
<!--FIXME elaborate this and other option descriptions.-->
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-q, --quiet</Term>
<ListItem>
<Para>Only show a brief summary (--quiet --quiet or -qq will display
warnings and errors only).
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-s, --no-auxiliary-files</Term>
<ListItem>
<Para>do not create .err file.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-w, --warnings-are-errors</Term>
<ListItem>
<Para>turn warnings into errors.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>--log</Term>
<ListItem>
<Para>Send screen output to a .log file.
</Para>
</ListItem>
</VarListEntry>

</VariableList>

</refsect1>

<refsect1><Title>Output</Title>

<Para>Cavern reads in text files containing the survey data
&svx;) and outputs two files, with the extensions
&x3d; and &err;.
By default these files are put in the current directory, 
with the same base filename as the first &svx; file read,
but a different extension.
You can change the directory and/or base filename using the --output
command line option.
<!-- FIXME: link --> 
</Para>

<Para>E.g. if you process the data file <filename>entrance.svx</filename>
with the command <userinput>cavern entrance</userinput> then the files
<filename>entrance.3d</filename> and <filename>entrance.err</filename>
will be created.
</Para>

<!-- mention .log FIXME -->

<Para>
Cavern also gives a range of statistics at the end of a successful run:
</Para>

<itemizedlist>
<listitem><para>The highest and lowest stations and the height difference
between them
</para></listitem>

<listitem><para>The total length of the survey (before and after
adjustment).  This total excludes survey legs flagged as SURFACE,
DUPLICATE, or SPLAY.
</para></listitem>

<listitem><para>The number of stations and legs.  Note that a *EQUATE
is counted as a leg in this statistic.
</para></listitem>

<!-- FIXME loops, components, anything else -->

<listitem><para>The East-West and North-South ranges, and the North-most,
South-most, East-most, and West-most stations.
</para></listitem>

<listitem><para>The number of each size of node in the network (where size
is number of connections to a station) i.e. a one node is the end of a
dead-end traverse, a two-node is a typical station in the middle of a
traverse, a three-node is a T-junction etc.
</para></listitem>

<listitem><para>How long the processing took and how much CPU time was
used.
</para></listitem>
</itemizedlist>

<refsect2><Title>&x3d; - data describing the loop-closed centre line</Title>

<Para>This file contains details of the stations and legs, and any
flags associated with them.
</Para>

</refsect2>

<refsect2><Title>&err; - loop closure statistics (%age errors, etc)</Title>

<Para>This file contains statistics about each traverse in the survey
which is part of a loop. It includes various statistics for each
traverse, such as the percentage error per leg.
You should study this information to determine if any parts of the survey
are of lower quality or contain gross errors.

<!-- FIXME explain the various statistics -->
</Para>

</refsect2>

</refsect1>

<refsect1><Title>Error Messages</Title>

<Para>
There are a number of error messages that you may get when processing
data.  Most of these are self explanatory, and will be caused by such
problems as typing mistakes, or by your survey data not being attached
to fixed points (in this situation, &survexsuite; will
list some of the stations that are not connected).
</Para>

<Para>
Along with the error message, the filename and line number of the offending
line will be printed (or the filename for errors such as `file not
found').  The format of the filename and line number is that used by
gcc, so if your editor can parse errors from gcc, you should be able to
set it to allow you to jump to the file and line of each error.
</Para>

<Para>
Cavern will stop after more than 50 errors.  This usually indicates
something like the incorrect data order being specified.  Deluging
the user with error messages makes the actual problem less clear.
</Para>

</refsect1>