From 23d29d455f5eddc1d1a6a39a297326b46f6ef5ed Mon Sep 17 00:00:00 2001
From: Philip Sargent <philip.sargent@gmail.com>
Date: Tue, 14 Mar 2023 16:43:27 +0000
Subject: [PATCH] QM TICK documentaiton

---
 handbook/survey/qmentry.html     | 54 +++++++++++++++++++++++++++-----
 handbook/troggle/scriptsqms.html | 19 -----------
 2 files changed, 46 insertions(+), 27 deletions(-)

diff --git a/handbook/survey/qmentry.html b/handbook/survey/qmentry.html
index c4ea1075f..0f3d7a63b 100644
--- a/handbook/survey/qmentry.html
+++ b/handbook/survey/qmentry.html
@@ -55,7 +55,9 @@ Near to the end of the text in the file, you will see a section that looks like
 This is where the action is! You literally just follow the instructions in the file to create QM and cave
 description data, replacing the template text with your own as you would with the cave passage data.
 <p style="margin:4%">
-<em>Technical Note:</em> The syntax for a QM includes a leading semi-colon. So it is syntactically a "comment" so far as the survex software is concerned. But we have other software and scripts in the Expo online system which inderstand just fine that these are QMs.
+<em>Technical Note:</em> The syntax for a QM includes a leading semi-colon. So it is syntactically a "comment" so far 
+as the survex software is concerned. But we have other software and scripts in the Expo online system which inderstand 
+just fine that these are QMs.
 
 <p>
 Here is an example from the last bit of bipedalpassage.svx in 264. Note that each QM description is all on one line.
@@ -73,7 +75,11 @@ Here is an example from the last bit of bipedalpassage.svx in 264. Note that eac
 <p>
 The format for question mark lists is <br>
 <ul>
-<li>QM identifier, <li><a href="qm.html">Quality Grade</a>, <li>Area indicator, <li>description of QM. 
+<li>QM identifier, 
+<li><a href="qm.html">Quality Grade</a>, 
+<li>nearest survey station, (which should be in the same survex file)
+<li>resolution survey station, initially a "-", explained in <a href="#tick">Ticking off a QM</a> below
+<li>description of QM. 
 </ul>
 <p>The QM numbers themselves used to be in the format <br>
 <ul>
@@ -93,15 +99,16 @@ but today, with the QMs inside the survex files, the identifiers are  QM1, QM2 e
 </figcaption>
 </figure>
 </div>
-<h4>Cave Descriptions</h4>
+<h3>Cave Descriptions</h3>
 <p>The description of the passage is written in  the same way as you write QMs, but as free text without 
 formatting. See the single line at the bottom of the figure below and 
 in more detail on the <a href="cavedescription.html">Cave Description"</a> handbook page.
 
-<h4 id="example">Full QMs example</h4>
+<h3 id="example">Full QMs example - initial data entry</h3>
 <p>
-The example below demonstrates correct and effective use of the QM list referring back to earlier elements in the svx file.
-Cave descriptions are done in a similar way, see the <a href="cavedescription.html">Cave Description"</a> handbook page.
+The example below demonstrates correct and effective use of the QM list referring back to earlier elements in the svx 
+file. Cave descriptions are done in a similar way, see the <a href="cavedescription.html">Cave Description"</a> 
+handbook page.
 <p>
 <img src="wob-svx-edit-pic3.jpg"  width=900>
 <p>
@@ -109,8 +116,39 @@ If these data are not entered along with the rest of the survey data, it is as i
 some of the actual passage data you surveyed: information is being lost and someone will have to
 trawl back through all the survey data at a later time to keep it up-to-date, a very tedious task which
 is a very inefficient use of time. 
-<p>Also if the person reading it hasn't been to the bit of cave (which is, like, <em>the whole point</em>, then the data has a higher chance of being incorrect. It is not always easy to interpret Tunnel or Therion 
-drawings correctly with this sort of thing. 
+<p>Also if the person reading it hasn't been to the bit of cave (which is, like, <em>the whole point</em>, then the 
+data has a higher chance of being incorrect. It is not always easy to interpret Tunnel or Therion drawings correctly 
+with this sort of thing. 
+
+<h4 id="tick">Ticking off a QM</h4>
+<p>Since 2015 we have had no generally-agreed, well-documented or widely-practiced way of recording whether a QM has been ticked-off or not. 
+
+<p>In the past, this was done by 
+<ol>
+<li>surveying into the passage beyond the QM, 
+<li>creating a new survex file for that survey, 
+and then 
+<li>editing the original survex file using the name of one of those new survey stations as the "resolution-station", replacing the "-" previously there. 
+</ol>This meant that a QM 
+could only be ticked-off if there was, in fact, surveyable passage beyond it, and if it was worth surveying, and if 
+someone did so.
+
+<p>In 2022 we had a proposal  to add an extra line to the original survex file, now that survex files can be edited 
+easily on-line (and the version control happens invisibly and automatically):
+
+<code>
+QM<em>nn</em> TICK <em>date comment</em>
+</code>
+e.g.<code>
+QM15 TICK 2022-07-20 This is a dummy ticked QM</code>
+
+<p>as illustrated  in 
+<a href="/cave/qms/1623-258/2015-15Aflashh2">2015-15A</a>
+in <a href="/survexfile/caves-1623/258/flashhard2.svx">258/flashhard2.svx</a>. <br>
+The TICKed QM appears at the end of the report <a href="/cave/qms/1623-258">/cave/qms/1623-258</a> at the bottom of the page.</p>
+
+<p>The <var>date</var> field is sufficient to tie the tick-off event to one of a small number of logbook entries and survex files, which is where the actual exploration would be documented. If it was a rapid dead-end, or if later parties can't find it at all, then there should be just a logbook entry.
+
 
 <h3>Programming note</h3>
 <p>Better handling of historic QMs is a current, occasionally active, area of
diff --git a/handbook/troggle/scriptsqms.html b/handbook/troggle/scriptsqms.html
index c5dbcdac6..6b6792ef8 100644
--- a/handbook/troggle/scriptsqms.html
+++ b/handbook/troggle/scriptsqms.html
@@ -68,11 +68,6 @@ It has been retired because the mapping software packages it used were terminall
 <p>Each cave has a report listing all the extant and ticked-off QMs, e.g. 
 <a href="/cave/qms/1623-264/">/cave/qms/1623-264/</a> or <a href="/cave/qms/1623-161/">/cave/qms/1623-161/</a>. The 161 report includes both old (spreadhseet-era) QMs and modern (2015 survex file) QMs.
 
-<h2>QMs - recording progress</h2>
-<p>Since 2015 we have had no generally agreed way of recording whether a QM has been ticked-off or not. 
-
-<p>In 2022 we developed a proposal (see "<a href="#ticking">Ticking them off</a>" below) to add an extra line to the original survex file, now that survex files can be edited easily on-line (and the version control happens invisibly and automatically). 
-
 <h2>QMs - how we first record them</h2>
 <p>Today we write the QM into the survex file: see <a href="../survey/qmentry.html">documenting newly found QMs</a>.
 <p>We used to write them into a spreadsheet file (pre-2015). These old files are today still parsed by troggle to produce reports.
@@ -82,20 +77,6 @@ It has been retired because the mapping software packages it used were terminall
 is put are listed in <a href="datamodel.html">the current data model</a>. 
 
 
-<h5 id="ticking">Ticking them off</h5>
-For ticking them off we have only protoype code: adding an extra line
-in the survex file of the format
-
-<code>
-QM<em>nn</em> TICK <em>date comment</em>
-</code>
-e.g.<code>
-QM15 TICK 2022-07-20 This is a dummy ticked QM</code>
-
-<p>as illustrated  in 
-<a href="/cave/qms/1623-258/2015-15Aflashh2">2015-15A</a>
-in <a href="/survexfile/caves-1623/258/flashhard2.svx">258/flashhard2.svx</a>. <br>
-The TICKed QM appears at the end of the report <a href="/cave/qms/1623-258">/cave/qms/1623-258</a> at the bottom of the page.</p>
 
 
 <h4 id="qms.py">troggle/parsers/qms.py</a></h4>