From 3a176a3255e2270b8b500d2fb229f723a0227ee6 Mon Sep 17 00:00:00 2001
From: Philip Sargent <philip.sargent@klebos.com>
Date: Sat, 5 Mar 2022 01:03:47 +0000
Subject: [PATCH] How to make essentials.gpx

---
 handbook/essentials.html                   |  8 ++++-
 handbook/troggle/make-essentialsREADME.txt | 35 ++++++++++++++++++++++
 handbook/troggle/scriptscurrent.html       |  3 ++
 3 files changed, 45 insertions(+), 1 deletion(-)
 create mode 100644 handbook/troggle/make-essentialsREADME.txt

diff --git a/handbook/essentials.html b/handbook/essentials.html
index b1b2dd17b..8fcf3787e 100644
--- a/handbook/essentials.html
+++ b/handbook/essentials.html
@@ -138,7 +138,13 @@ by the script which has been hand-edited in. It also has the kataster boundaries
 can be downloaded from here : <a href="essentials.gpx" download>essentials.gpx</a> (190K). 
 (This is a symlink to loser/gpx/essentials.gpx). This works fine on laptops but most phones don't like this sort of link.
 
-
+<h3>Regenerating the essentials.gpx file</h3>
+<p>There are two scripts needed for this: 
+<a href="troggle/scriptscurrent.html#gps">make_essentials.sh</a> and 
+<a href="troggle/scriptscurrent.html#surface">make_svx.sh</a> 
+both of which are stored in the <var>:loser:</var> repository in :loser:/gpx/ .
+<p>Read the <a href="troggle/make-essentialsREADME.txt">README</a> file in that directory.
+<p>They are documented in the long list of <a href="troggle/scriptsother.html">Other scripts</a>.
 <hr />
 
 <ul id="links">
diff --git a/handbook/troggle/make-essentialsREADME.txt b/handbook/troggle/make-essentialsREADME.txt
new file mode 100644
index 000000000..0f5bbb66c
--- /dev/null
+++ b/handbook/troggle/make-essentialsREADME.txt
@@ -0,0 +1,35 @@
+The folders for each year are for general gpx files from recorded tracks, 
+which will be included as surface legs in all.svx.
+gpx_publish is for creating exportable files to personal gps devices or smart phones.
+
+The master copy of this file is kept at :loser:/gpx/README
+
+To add a new GPS tracklog or waypoint file:
+
+0. Read the Handbook on this http://expo.survex.com/handbook/essentials.html
+which may be more up to date than this README
+
+1. Download the .gpx file(s) from your GPS.  (On modern Garmin GPSes this is done
+by connecting the GPS using a USB cable and then copying the relevant files
+from the "GPX" directory inside the "Garmin" directory on the USB disk.)
+
+2. Create a new directory for the year if required (following the "2018"
+example) in the "gpx" subdirectory of the dataset.  Put the .gpx file(s) in the
+year directory.  They need to be renamed so as to follow our naming convention
+(see the "2018" directory).  No formal distinction needs to be made between
+files containing tracklogs and files containing waypoints (or a mix of the
+two).
+
+3. Update (or create if currently absent) the additional_info.svx file in
+the year directory following the 2018 example.  This is the place to rename
+stations to follow normal conventions and to mark waypoints as entrances,
+etc.  The file must be present even if empty.
+
+4. Open a terminal in this directory and run the make_svx.sh script.  This
+requires the gpx2survex program (https://github.com/mshinwell/gps2survex;
+installation instructions to follow).
+
+5. Run "cavern all.svx" at the toplevel then "aven all.3d".  Check that the
+tracks appear as expected when fixed points / surface surveys are enabled.
+
+6. Commit everything to hg and push.
diff --git a/handbook/troggle/scriptscurrent.html b/handbook/troggle/scriptscurrent.html
index 46090d99c..346858be5 100644
--- a/handbook/troggle/scriptscurrent.html
+++ b/handbook/troggle/scriptscurrent.html
@@ -58,6 +58,9 @@ The design of these files is intended to confine all changes year to year to the
 <h4 id="gps">make_essentials.sh</h4>
 <p>In :loser:/gpx/
 <p>Makes essentials.gpx - see <a href="../essentials.html">GPS on expo</a>. 
+This requires the gpx2survex program. 
+Get this from GitHub <a href="https://github.com/mshinwell/gps2survex">https://github.com/mshinwell/gps2survex;</a>
+<p>Read the <a href="troggle/make-essentialsREADME.txt">README</a> file in :loser:/gpx/y.
 <p>Someone needs to document this and and make_svx.sh properly.
 
 <h4 id="surface">make_svx.sh</h4>