expo/expoweb
1
0
Fork 0
mirror of https://expo.survex.com/repositories/expoweb/.git/ synced 2024-11-22 07:11:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

Tidying and extending troggle documentation

Browse Source
This commit is contained in:
Philip Sargent 2020-07-10 02:51:53 +01:00
parent 63bc4103a7
commit d495e0f0d9
3 changed files with 36 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
handbook/troggle/trogdocm.html
View File

@ -11,19 +11,31 @@
<h1>Troggle - Fixing things that break</h1>
<p>The guide to the parser-model-view architecture is in the architecture document.
<p><em>This page will describe the usual things that go wrong: the parsers that break when
faced with user-generated data and how to fix them. Common error messages. How to set up troggle on a new machine. Copies of the older material where that is illuminating.</em>
faced with user-generated data and how to fix them. Common error messages. </em>
<p>It concentrates on showing how to find and fix import errors so that the troggle-generated webpages are complete and not full of gaps.
<p>Intended audience: Ideally someone who is not a python programmer will be able to use this page to help them fix import errors.
<p>Also here we will explain the useful diagnostic pages such as <br>
<a href="http://expo.survex.com/experimental">experimental</a><br>
<a href="http://expo.survex.com/pathsreport">pathsreport</a><br>
<a href="http://expo.survex.com/survey_scans">survey_scans</a><br>
<a href="http://expo.survex.com//admin/core/dataissue/l">/admin/core/dataissue/</a><br>
<a href="http://expo.survex.com/tunneldata">tunneldata</a><br>
<a href="http://expo.survex.com/statistics">statistics</a><br>
<a href="http://expo.survex.com/people">people</a><br>
<p><b>Intended audience:</b> Ideally someone who is not a python programmer will be able to use this page to help them
fix import errors by re-editing the input files: survex, tunnel, or logbook.
<p>Here we will explain the useful diagnostic detailed data pages for finding mis-matched files:<br>
<img border="1" class="onright" width="150px" src='tricky-troggle.jpg' alt='git logo'/></a>
<var>These do not work until the server is updated in July 2020 to run the python3 version of troggle</var><br>
<a href="http://expo.survex.com/statistics">statistics</a> - survey legs and distances for each expo<br>
<a href="/survexfile/161">all data one cave</a> - all the survex data for one cave and who was on each trip<br>
<a href="/personexpedition/MartinGreen/2002">per-person caving</a> - list of logbook trips and surveys for one person<br>
<a href="/people">people</a> - who caved when and how much did they survey<br>
<a href="/logbookentry/2018-07-19/balkon-to-honeycomb-hangmans">logbook entry</a> - who, where and what<br>
<a href="/survey_scans">survey_scans</a> - all wallets of scanned surveys and corresponding survex files<br>
<a href="/survey_scans/2014%252347/">per-wallet links</a> - links to scan files and survex files from one wallet<br>
<a href="/tunneldata">tunneldata</a> - all the tunnel drawings and the wallets and scanned images they derive from<br>
<br>
<var>These do not work until the server is updated in July 2020 to run the python3 version of troggle</var><br>
<a href="/admin/core/dataissue/l">/admin/core/dataissue/</a> - where the data import errors and warnings are recorded<br>
<br>
Configuration aids when setting up on a new machine (move to main manual):<br>
<a href="/pathsreport">pathsreport</a> - debugging aid<br>
<em>How to set up troggle on a new machine. <br>
Copies of the older material where that is illuminating.</em>
<hr />
Go on to: <a href="trogarch.html">Troggle architecture</a><br />
Go on to: <a href="trognotes.html">Troggle notes to be restructured</a><br />
Return to: <a href="trogintro.html">Troggle intro</a><br />

14
handbook/troggle/trognotes.html
View File

@ -25,6 +25,7 @@
<p>These are some of the "use cases" for which troggle needs to be (re)designed to cope with.
<h3>Rewrite from here on...</h3>
<img border="1" class="onright" width="150px" src='tricky-troggle.jpg' alt='git logo'/></a>
<p>This troggle manual describes these:
<ul>
<li>Annual tasks: preparing for next year, finishing last year (troggle & scripts)
@ -60,21 +61,10 @@ hand corner. This is particularly true of the handbook you are reading now and t
can do this by filling-in some online forms.
</ol>
<h3>The first thing to do</h3>
<p>The first thing to do is to read: "<a href="/expofiles/documents/troggle/troggle_paper.pdf" download>Troggle: a novel system for cave exploration information management</a>", by Aaron Curtis, CUCC.</em>
<p>Two things to remember are
<ul>
<li>that troggle is just one of several cave-survey management online software systems. CUCC EXPO is not the only caving expedition with a substantial nerd community.<br /><br />
<li>that troggle is part of a 40-year ongoing project and lives in a soup of several disparate scripts all working on the same data
</ul>
<h3>Troggle Login</h3>
<p>Yes you can log in to the troggle control panel: <a href="http://expo.survex.com/troggle">expo.survex.com/troggle</a>.
</p>
<p>It has this menu of commands:
<pre>
All Survex | Scans | Tunneldata | 107 | 161 | 204 | 258 | 264 | Expo2016 | Expo2017 | Expo2018 | Django admin
</pre>
<hr />
<h3><a id="arch">Archived updates</a></h3>

12
handbook/troggle/trogstatus.html
View File

@ -54,8 +54,18 @@ tackling the next step: thinking deeply about when we migrate from django
</p>
<p>
Enforced time at home is giving us a new impetus to writing and restructuring the documentation for everything.
<h4>end of June 2020</h4>
<p>Sam was a bit overworked in trying to get an entire university to work remotely and Philip got troggle on django 1.7 to work on python 3.5 and then 3.8. He then did the slog of migrating it through the django versions up to 1.11.29 - the last version before django 2.0 when a new URL routing architecture becomes available. 1.11.29 is an LTS (long term support) version of django. In doing this we had to retreat to python3.7 due to a django incompatibility; which is fine because the server will run python3.7 when it is updated to debian 10 (buster) [Wookey to do].
<p>
In the course of these migrations several unused or partly-used django plugins were dropped as they caused migration problems (notably staticfiles) and the plug-ins pillow, django-registration, six and sqlparse were brought up to recent versions. This was all done with pip in a python venv (virtual environment) on a Windows 10 machine running ubuntu 20.04 under WSL (Windows Systems for Linux) v1. Also missing troggle functions were repaired and partly-implemented pages, such as the list of all cavers and their surveyed passages, were finished and made to work. The survex file parsing was completely rebuilt to reduce the excessive memory footprint while parsing.
<p>We plan to stick with debian 10 (buster), django 1.11.29 and python 3.7.7 (the standard on buster) until spring 2021 when we will upgrade debian to the forthcoming stable release 11. At that point debian will have python 3.8 as standard and we will migrate to django 2.x, hopefully getting as far as django 2.2 which is an LTS and actually in support until April 2022.
<p>With any luck that will be the last of our involvement with django migrations as we will keep using django 2.2 until we stop using django altogether, see <a href="trogspeculate.html">troggle architecture speculations</a>.
<hr />
Go on to: <a href="trogmanual.html">Troggle maintenance manual</a><br />
<img border="1" class="onright" width="150px" src='tricky-troggle.jpg' alt='git logo'/></a>
Go on to: <br>
<a href="trogmanual.html">Troggle maintenance manual</a><br />
<a href="trogspeculate.html">Troggle architecture speculations</a><br />
<a href="trogdesign.html">Troggle design decisions</a><br />
<br />
Return to:<br />
<a href="trogintro.html">Troggle intro</a><br />