From af7e727dc50f3c8ebadcbe04767bdd4b9c1ff8f2 Mon Sep 17 00:00:00 2001
From: Philip Sargent <philip.sargent@klebos.com>
Date: Tue, 11 Oct 2022 00:30:47 +0300
Subject: [PATCH] handbook edits to better describe new wallets system
---
handbook/l/life-wallet.html | 1 +
handbook/survey/newwallet.html | 6 +++---
handbook/survey/onlinewallet.html | 16 +++++++++-------
handbook/troggle/trogstatus.html | 6 +++++-
4 files changed, 18 insertions(+), 11 deletions(-)
diff --git a/handbook/l/life-wallet.html b/handbook/l/life-wallet.html
index 54bd97238..7f1e68ff2 100644
--- a/handbook/l/life-wallet.html
+++ b/handbook/l/life-wallet.html
@@ -20,6 +20,7 @@ You can edit your own version to revise this when it becomes outdated.
<p>We also have a "<a href="seq-wallet.html">sequence diagram</a> which shows clearly the sequence of wallet actions in a time-line.
+<p>[UPDATE: The bit in the lower left corner is out of date. We don't use wallets.py or svx-ref.sh any more. Those capabilities are now built into troggle itself (since July 2022).]
<p>Both "activity" and "sequence" diagrams are part of the UML software specifiction system. We also have a "<a href="trogclass-1.html">class</a>" diagram for troggle.
That page also defines the "essential", "specification" and "implementation" levels at which troggle is designed and maintained.
diff --git a/handbook/survey/newwallet.html b/handbook/survey/newwallet.html
index 107f98ddc..eda6964b8 100644
--- a/handbook/survey/newwallet.html
+++ b/handbook/survey/newwallet.html
@@ -177,9 +177,9 @@ to understand the <a href="onlinewallet.html">online wallet maintenance process<
<p>If your initial backup photos of your notes were poor quality, use the
scanner in the potato hut to make better copies. Scan to JPEG format as .jpg files.
-<p>Name the scanned pages "<em>notes-1.jpg</em>, or <em>notes-cavepassagename.jpg</em>" etc. This is important as a script detects
-whether these files exist (with names beginning "notes..", "plan.." and "elev..") and if you name them something else it will hassle
-you unnecessarily.
+<p>Name the scanned pages "<em>notes-cavepassagename.jpg</em>" etc., (or <em>notes-1.jpg</em> if you must, but self-describing filenames
+are much better). This is important as a script detects whether these files exist (with names beginning "notes..", "plan.." and "elev..")
+and if you name them something else it will hassle you unnecessarily. (Or you can use this format <em>cavepassagename-notes.jpg</em> if you like.)
<p style="margin-left:20px">[ Note to maintainers: do not rename these files even if they have been created with the wrong names.
They are permanently referred to by the tunnel/therion/troggle system !]
diff --git a/handbook/survey/onlinewallet.html b/handbook/survey/onlinewallet.html
index 734344bdb..84bebe879 100644
--- a/handbook/survey/onlinewallet.html
+++ b/handbook/survey/onlinewallet.html
@@ -27,7 +27,7 @@
<ol>
<li>The scans of the survey notebook pages are the ultimate original raw survey data and completely irreplaceable.
<li>The other files in the wallet are part of the process of producing a survey of the cave as a whole.
-<li>Individual to-do lists are produced automatically for each caver, each cave, and each year. These
+<li>Individual online to-do lists are produced automatically for each caver, each cave, and each year. These
have a colour-coded table showing what survey processing tasks they haven't finished yet.
</ol>
@@ -54,7 +54,9 @@ to change anything <font color=red><b>can overwrite everyone else's work</b></fo
<h3 id="scans">The scanned images</h3>
<p>These are simply the scanned images (or digital photographs) of each page of the original survey notes.
They should be named <em><span style="font-family:monospace">notesXXX.jpg</span></em> where "XXX" can be
-anything you like. Typically we have the scanned pages called notes1.jpg, notes2.jpg, notes3.jpg.
+anything you like. In the past we have had scanned pages called notes1.jpg, notes2.jpg, notes3.jpg; but <em>don't
+do this</em>, instead give descriptive names, e.g. <span style="font-family:monospace">notes-twentyseconddropdronesurvey.jpg</span> or whatever,
+but do put "notes-.." at the beginning or "..-notes" at the end of the filename (or "plan-.." or "elev-.." as appropriate).
<p>It is important that you use use the .jpg (JPEG) file format, and definitely not PNG (very voluminous)
or PDF (very hard to re-use elsewhere). Set the scanner at 300 dpi and adjust the contrast of the image after scanning
by using photo-editing software to enhance the writing. Also please crop each image to just the area containing
@@ -82,7 +84,7 @@ without damange.
<h3 id="status">Progress status</h3>
<p>The illustration shows the lower half of the <a href="/scanupload/2019:01">Upload Scans</a> form.
-This is the information about the wallet itself.
+This is the information about the wallet itself (this is called 'metadata').
<p>Once you are logged on as user 'expo', you can edit all the data. If you use the right runes for the survex files (as shown in the image),
a clickable-list of the survex files will appear on the upper-left which will take you directly to the survex files - which you can edit
there online too.
@@ -119,7 +121,7 @@ will find and list all the wallets which contain survey data for cave 1623-264.
</pre>
But sometime in mid-Expo 2015 everyone stopped using the survex template file and copied from a friend instead,
and so this information was not properly recorded. This will be fixed by hand-editing in due course.
-(Note that many old .svx files were processed with an older version of survex which did not suppport this feature and so a comment was used instead.)
+(Note that many old .svx files were processed with an older version of survex which did not support this feature and so a comment was used instead.)
<h2>Much more detail - more than you want</h2>
<p>Troggle produces very useful auto-generated reports of the status of the wallets and the survex files
@@ -159,7 +161,7 @@ These troggle reports are invaluable for finding data entry errors or other mist
<p>(where the "json file updated" step only refers to the initial editing of the json file to ensure
that it has the right people, date and cave identifier and name).
-<p>A fully-populated and complete <em><span style="font-family:monospace">contents.json</span></em> file
+<p>A fully-populated and complete <em><span style="font-family:monospace">contents.json</span></em> file (this is the 'metadata')
looks like this:
<pre>
{
@@ -217,8 +219,8 @@ as soon as you upload a new scan for a new year.
<h3>Maintaining the online wallets</h3>
-<p>Ideally the cavers who are scanning their notes and typing in the survey data will also be updating the
-<span style="font-family:monospace; size=x-small; background-color: lightgray">contents.json</span> data in their wallet using the tick-boxes on the upload form. In your dreams.
+<p>Ideally the cavers who are scanning their notes and typing in the survey data will also be updating the 'metadata' (in the
+<span style="font-family:monospace; size=x-small; background-color: lightgray">contents.json</span> file) using the tick-boxes on the upload form. In your dreams.
<p>The first difficulty when editing the data
for a newly-created wallet is finding out which cave the wallet describes.
diff --git a/handbook/troggle/trogstatus.html b/handbook/troggle/trogstatus.html
index ff44f144d..e37532495 100644
--- a/handbook/troggle/trogstatus.html
+++ b/handbook/troggle/trogstatus.html
@@ -45,7 +45,11 @@ and possible <a href="trog2030.html">migration from Django</a>.
<p>We should not need to anything until we move from django 3.2 LTS to 4.2 LTS before April 2024.
<h4>July 2022</h4>
-<p>Wookey at last, after much effort, got the loser repository converted from mercurial to git, with much tidying and history-reconfabulation. He says this will need to be done again, but it was good enough for the 2022 Expo. Also the troggle code was changed: survex files edited on a webpage now automatically commit to git with no user involvement.
+<p>Wookey at last, after much effort, got the loser repository converted from mercurial to git, with much tidying and
+history-reconfabulation. He says this will need to be done again, but it was good enough for the 2022 Expo. Also the troggle code was
+changed: survex files edited on a webpage now automatically commit to git with no user involvement.
+<p>Just before expo, we finished integrating the formerly-separate 'wallets' script.
+So now the progress of scanning and tunneling survey data can be managed more easily. And it works on the data back to 1999 too.
<hr />
<img border="1" class="onright" width="150px" src='tricky-troggle.jpg' alt='git logo'/></a>
Return to: <br />