mirror of
https://expo.survex.com/repositories/expoweb/.git/
synced 2024-11-25 08:41:54 +00:00
459 lines
20 KiB
HTML
459 lines
20 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<title>Handbook Troggle NOTES</title>
|
|
<link rel="stylesheet" type="text/css" href="../../css/main2.css" />
|
|
</head>
|
|
<body><style>body { background: #fff url(/images/style/bg-system.png) repeat-x 0 0 }</style>
|
|
<h2 id="tophead">CUCC Expedition Handbook</h2>
|
|
<h1>Troggle - TO BE RESTRUCTURED</h1>
|
|
<p>Troggle runs much of the the cave survey data management, presents the data on the website and manages the Expo Handbook.
|
|
|
|
<h2>NOTES - taken from elsewhere</h2>
|
|
|
|
<p>This part of the handbook is intended for people maintaining the troggle software. Day to day cave recording and surveying tasks are documented in the expo "survey handbook"
|
|
|
|
<p>This troggle manual describes these:
|
|
<ul>
|
|
<li>Annual tasks: preparing for next year, finishing last year (troggle & scripts)
|
|
<li>Architectural documentation of how it all fits together & list of active scripts
|
|
<li>How to edit and maintain troggle itself. The code is public on repository <a href="../computing/repos.html">:troggle:</a>
|
|
</ul>
|
|
|
|
<p>This page is mostly an index to other records of what troggle is and what plans have been made - but never implemented - to improve it.
|
|
|
|
Today troggle is used for only three things:
|
|
<ol>
|
|
<li>Reformatting all the visible webpages such that they have a coherent style and have a contents list at the top-left
|
|
hand corner. This is particularly true of the handbook you are reading now and the historic records of past expeditions.
|
|
<li>Publishing the "guidebook descriptions" of caves. The user who is creating a new guidebook description
|
|
can do this by filling-in some online forms. (And managing all the cave suvey data to produce this.)
|
|
|
|
<li>Providing a secondary way of editing individual pages of the handbook and historic records pages
|
|
for very quick and urgent changes.
|
|
This is the "Edit this page" capability; see <a href="../computing/onlinesystems.html#editthispage"> for
|
|
how to use it</a> and <em>how to tidy up afterwards</em>.
|
|
</ol>
|
|
|
|
|
|
<p>[Note that /survey_scans/ is generated by troggle and is not the same thing as /expofiles/surveyscans/ at all.]
|
|
<p>Only a small part of troggle's original plan was fully implemented and deployed.
|
|
Many of the things it was intended to replace are still operating as a motley collection written by many different people in
|
|
several languages (but mostly perl and python; we won't talk about the person who likes to use OCamL).
|
|
Today troggle is used for only three things:
|
|
<ol>
|
|
<li>Reformatting all the visible webpages such that they have a coherent style and have a contents list at the top-left
|
|
hand corner. This is particularly true of the handbook you are reading now and the historic records of past expeditions.
|
|
<li>Publishing the "guidebook descriptions" of caves. The user who is creating a new guidebook description
|
|
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>
|
|
|
|
<h3>Future Developments: Preamble</h3>
|
|
<p><em>Assumptions</em> (points to necessarily agree upon)
|
|
<ol>
|
|
<li>Let's NOT try to design a generic catalogue for storing all kind of data about caves of the whole world, intended for every kind of user (sports, exploration, science). Let's just settle for a generic framework. Let geeks in individual countries or individual communities write their tools operating within this framework.
|
|
<li>Let's try make it available for the layman, but still well-playable for the geeks.
|
|
<li>Let's rely on already existing, popular technologies. Let's keep it open source and multiplatform. Let's try not to reinvent the wheel.
|
|
<li>Let's not assume everyone has an Internet connection while working with their data.
|
|
<li>Let's version-control as much as possible.
|
|
<li>Let's support i18n - let's use UTF-8 everywhere and cater for data in many languages(entrance names, cave descriptions, location descriptions etc.)
|
|
</ol>
|
|
|
|
<tt><em>Everything here should be updated or replaced - this page just records a lot of unfinished ideas.
|
|
Most people will not want to read this at all. This is for speleosoftwarearcheologists only.</em>
|
|
</tt>
|
|
|
|
<p>Two page preliminary design document for <a href="../../documents/caca_arch2.pdf">'caca' (Cave Catalogue) rev.2 2013-07-26</a> by Wookey (copied from http://wookware.org/software/cavearchive/caca_arch2.pdf)
|
|
|
|
<h3>stroggle</h3>
|
|
<p>At one time Martin Green attempted to reimplement troggle as "stroggle" using <a href="https://www.fullstackpython.com/flask.html">flask</a> instead of Django at
|
|
<a href="https://en.wikipedia.org/wiki/Gitorious">git@gitorious.org:stroggle/stroggle.git</a> (but gitorious has been deleted).</p>
|
|
<p>A copy of this project is archived by Wookey on <a href="http://wookware.org/software/cavearchive/stroggle/">wookware.org/software/cavearchive/stroggle/</a>.
|
|
<p>There is also a copy of stroggle on the backed-up, read-only copy of gitorious on "<a href="https://gitorious.org/">gitorious valhalla</a>"<br />
|
|
<a href="https://gitorious.org/stroggle/stroggle.git/">stroggle code</a></br>
|
|
<a href="https://gitorious.org/stroggle/stroggle-gitorious-wiki.git/">stroggle-gitorious-wiki</a></br>
|
|
but note that this domain has an expired ertificate so https:// complains.
|
|
|
|
<h3 id="automation">Automation on expo.survex.com</h3>
|
|
|
|
<p>Ths section is entirely out of date (June 2014), and moved here for historic interest</p>.
|
|
|
|
<p>The way things normally work, python or perl scripts turn CSV input into HTML for the data management system. Note that:</p>
|
|
<p>The CSV files are actually tab-separated, not comma-separated despite the extension.</p>
|
|
<p>The scripts can be very picky and editing the CSVs with microsoft excel has broken them in the past- not sure if this is still the case.</p>
|
|
<p>Overview of the automagical scripts on the expo data management system</p>
|
|
[Clearly very out of date is it is assuming the version control is svn whereas we changed to mercurial years ago.]
|
|
<pre>
|
|
Script location Input file Output file Purpose
|
|
/svn/trunk/expoweb/noinfo/make-indxal4.pl /svn/trunk/expoweb/noinfo/CAVETAB2.CSV many produces all cave description pages
|
|
/svn/trunk/expoweb/scripts/make-folklist.py /svn/trunk/expoweb/folk/folk.csv http://expo.survex.com/folk/index.htm Table of all expo members
|
|
|
|
/svn/trunk/surveys/tablize-csv.pl /svn/trunk/surveys/tablizebyname-csv.pl
|
|
/svn/trunk/surveys/Surveys.csv
|
|
|
|
http://expo.survex.com/expo/surveys/surveytable.html http://expo.survex.com/surveys/surtabnam.html
|
|
Survey status page: "wall of shame" to keep track of who still needs to draw which surveys
|
|
|
|
</pre>
|
|
|
|
<h3><a id="arch">Archived updates</a></h3>
|
|
<p>Since 2008 we have been keeping detailed records of all data management system updates in the version control system.
|
|
Before then we manually maintained <a href="../update.htm">a list of updates</a> which are now only of historical interest.
|
|
<p>A history of the expo website and software was published in Cambridge Underground 1996. A copy of this article <a href="c21bs.html">Taking Expo Bullshit into the 21st Century</a> is archived here.
|
|
|
|
<h2>The data management system conventions bit</h2>
|
|
<p>This is likely to change with structural change to the site, with style changes which we expect to implement and with the method by which the info is actually stored and served up.</p>
|
|
<p>... and it's not written yet, either :-)</p>
|
|
<ul>
|
|
|
|
<li>Structure</li>
|
|
<li>Info for each cave – automatically generated by <tt>make-indxal4.pl</tt></li>
|
|
<li>Contents lists & relative links for multi-article publications like journals. Complicated by expo articles being in a separate hierarchy from journals.</li>
|
|
<li>Translations</li>
|
|
<li>Other people's work - the noinfo hierarchy.</li>
|
|
<li>Style guide for writing cave descriptions: correct use of boldface (<em>once</em> for each passage name, at the primary definition thereof; other uses of the name should be links to this, and certainly should not be bold.) </li>
|
|
</ul>
|
|
|
|
<h3>CUCC wiki on troggle</h3>
|
|
|
|
<p>CUCC still has an archive list of things that at one time were live tasks:
|
|
from <a href="https://camcaving.uk/Documents/Expo/Legacy/Misc/Troggle%20-%20Cambridge%20University%20Caving%20Club.htm">camcaving.uk/Documents/Expo/Legacy/Misc/...</a> and that page is reproduced in the table below (so don't worry if the URL link goes dark when CUCC reorganise their legacy pages).
|
|
<p>Troggle is a system under development for keeping track of all expo data in a logical and accessible way, and displaying it on the web. At the moment, it is [no longer] under development at <u>http://troggle.cavingexpedition.com/</u>
|
|
|
|
<tt>But note that this is Aaron's version of troggle, forked from the version of troggle we use. Aaron uses this for the <a href="https://expeditionwriter.com/new-expedition-to-mount-erebus-antarctica/">Erebus expedition</a>.</tt>
|
|
</p>
|
|
<p>Note that the information there is incomplete and editing is not yet enabled.
|
|
</p>
|
|
<table border="1" cellspacing="0">
|
|
<tr>
|
|
<th><p>Feature</p></th>
|
|
<th><p>Old expo website</p></th>
|
|
<th><p>Troggle: planned</p></th>
|
|
<th><p>Troggle: progress so far</p></th>
|
|
</tr>
|
|
<tr>
|
|
<td><p>Logbook</p></td>
|
|
<td><p>Yes; manually formatted each year</p></td>
|
|
<td><p>Yes; wiki-style</p></td>
|
|
<td><p>Start at the front page, <a rel="nofollow" class="external autonumber" href="http://expo.survex.com/expedition/2007">troggle.cavingexpedition.com/ [1]</a> and click to logbook for year. The logbooks have been parsed back to 1997. </p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><p>Cave index and stats generated from survex file</p></td>
|
|
<td><p>Yes</p></td>
|
|
<td><p>Yes</p></td>
|
|
<td><p>Done; see <a rel="nofollow" class="external autonumber" href="http://expo.survex.com/survexfile/caves/264">troggle.cavingexpedition.com/survey/caves/264 [2]</a> </p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><p>Survey workflow helper</p></td>
|
|
<td><p>Yes; minimal. surveys.csv produced an html table of whose surveys were not marked “finished”</p></td>
|
|
<td><p>Yes. Makes table of surveys per expo which shows exactly what needs doing. Displays scans. Integrated with survex, scanner software, and tunnel.</p></td>
|
|
<td><p>See it at <a rel="nofollow" class="external free" href="http://expo.survex.com/survey_scans/">troggle.cavingexpedition.com/survey</a> . Be sure to try a recent year when we should have data. Survex, scanner, and tunnel integration still needs doing.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><p>QM lists generated automatically</p></td>
|
|
<td><p>Depends on the cave. Each cave had a different system.</p></td>
|
|
<td><p>Yes; unified system.</p></td>
|
|
<td><p>Done, but only 204 and 234 Qms have been imported from old system so far. No view yet.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><p>Automatic calendar for each year of who will be on expo when</p></td>
|
|
<td><p>No, manually produced some years</p></td>
|
|
<td><p>Yes</p></td>
|
|
<td><p>Done; see <a rel="nofollow" class="external free" href="http://expo.survex.com/expedition/2007">troggle.cavingexpedition.com/calendar/2007</a> (replace 2007 with year in question)</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><p>Web browser used to enter data</p></td>
|
|
<td><p>No</p></td>
|
|
<td><p>Yes</p></td>
|
|
<td><p>Everything can be edited through admin, at <a rel="nofollow" class="external free" href="http://expo.survex.com/admin/">troggle.cavingexpedition.com/admin</a> . Ask aaron, martin, or julian for the password if you want to have a look / play around with the admin site. Any changes you make will be overwritten. Eventually, data entry will probably be done using custom forms.
|
|
</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><p>Cave and passage descriptions</p></td>
|
|
<td><p>Yes, manually html coded.</p></td>
|
|
<td><p>Yes, wiki-style.</p></td>
|
|
<td><p>Not done yet.<br />
|
|
</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><p>Expo handbook</p></td>
|
|
<td><p>Yes, manually html coded.<br />
|
|
</p>Maybe. Needs to be discussed further.</td>
|
|
<td><p><br />
|
|
</p></td>
|
|
<td><p>Not done yet.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><p>Table of who was on which expo</p></td>
|
|
<td><p>Yes</p></td>
|
|
<td><p>Yes</p></td>
|
|
<td><p>Data has been parsed, this view hasn't been written yet. </p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><p>Signup form, System for keeping contact, medical and next of kin info</p></td>
|
|
<td><p>No</p></td>
|
|
<td><p>Yes</p></td>
|
|
<td><p>Signup form should be ready by 20 Jan.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><p>Automated photo upload and gallery</p></td>
|
|
<td><p>No; some manual photo galleries put together with lots of effort</p></td>
|
|
<td><p>Yes</p></td>
|
|
<td><p>Photo upload done, gallery needs writing.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><p>Search</p></td>
|
|
<td><p>No</p></td>
|
|
<td><p>Yes</p></td>
|
|
<td><p></p></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3>List of cave database software</h3>
|
|
from <a href="http://wookware.org/software/cavearchive/databasesoftwarelist">wookware.org/software/cavearchive/databasesoftwarelist</a>
|
|
|
|
<pre>
|
|
ckan is something like this - could we use it?
|
|
esri online
|
|
|
|
CUCC (troggle) http://cucc.survex.com/ - this site.
|
|
virgina caves database (access+arcgis) (futrell)
|
|
each country database
|
|
Austria (spelix) ( <a href="https://www.spelix.at/">www.spelix.at/</a>
|
|
UK cave registry
|
|
mendip cave registry: (access) <a href="http://www.mcra.org.uk/wiki/doku.php">www.mcra.org.uk/wiki/doku.php</a>
|
|
White mountains database (gpx + google earth)
|
|
Matienzo (?)
|
|
Fisher ridge (stephen cladiux)
|
|
hong meigui (erin) <a href="http://www.hongmeigui.net/"http://www.hongmeigui.net/</a> (ask erin later)
|
|
Wikicaves <a href="http://www.grottocenter.org/">www.grottocenter.org/</a>
|
|
multilingual, slippymap, wiki data entry. includes coordinate-free caves.
|
|
focus on sport-caving type info (access, basic gear list, overall description, bibliography)
|
|
e.g. australians only publish coordinates to nearest 10km
|
|
turkey <a href="http://www.tayproject.org">www.tayproject.org</a>.
|
|
|
|
<a href="http://www.uisic.uis-speleo.org/contacts.html">www.uisic.uis-speleo.org/contacts.html</a> change link. no-one looks for list of databases under 'contacts'
|
|
|
|
graziano ferrari northern italy list (access + google earth)
|
|
</pre>
|
|
|
|
<h3>Wookey's notes on things to do</h3>
|
|
from <a href="http://wookware.org/software/cavearchive/goliczmail">wookware.org/software/cavearchive/goliczmail</a>
|
|
<pre>
|
|
Generally I'd like to find some people (geeks) that share these technical
|
|
ideas: (1) store things in a file system, (2) use XML, (3) do not aim too high
|
|
(do not try designing a general system for handling all caving-related data
|
|
for the whole world).
|
|
|
|
If I could find some people that agree with this, then we could try to reach a
|
|
compromise on:
|
|
(1) how do we store our data in a file system,
|
|
(2) how do we use this XML (let's do a common spec, but keep it simple)
|
|
(3) how do we aim not too high and not end up dead like CaveXML :)
|
|
|
|
After we do that, everyone goes away to do their own projects and write their
|
|
own code. Or maybe we have some degree of co-operation in actually writing the
|
|
code. Normal life. But the idea is that all geeks working on "cave inventory"
|
|
and systems making extensive use of cave inventories try to adhere to this
|
|
framework as much as possible. So that we can then exchange our tools.
|
|
|
|
I think things like "which revision system do we use" or "do we use web or
|
|
Python" are really secondary. Everyone has their own views, habits,
|
|
backgrounds.
|
|
|
|
My idea is to work on this in a small group (no more than a few persons) - to
|
|
get things going fast, even if they are not perfect from the beginning. If it
|
|
works, we try to convince others to use it and maybe push it through UIS.
|
|
</pre>
|
|
|
|
<h3>Wookey's other notes on things to do</h3>
|
|
from <a href="http://wookware.org/software/cavearchive/troggle2design">wookware.org/software/cavearchive/troggle2design</a>
|
|
<pre>
|
|
forms
|
|
-----
|
|
1) members read/write folk.csv and year/members
|
|
2) cave read/write cave_data, entrance_data, surveys/pics
|
|
3) trips -> logbook , QMs, or surveys (more than one survey or location possible)
|
|
4) logbook reads/write year/logbook
|
|
5) survey
|
|
6) prospecting app
|
|
|
|
forms show who is logged in.
|
|
|
|
databases
|
|
---------
|
|
trips, read from
|
|
logbook entry
|
|
folder year#index
|
|
.svx files
|
|
description
|
|
QMs
|
|
|
|
members (cache from form)
|
|
|
|
caves
|
|
caves_data
|
|
entrance_data
|
|
|
|
storage:
|
|
expoweb
|
|
data/
|
|
cave_entrances
|
|
caves
|
|
descriptions
|
|
|
|
loser
|
|
foo.svx
|
|
</pre>
|
|
|
|
|
|
<h3>Yet more of Wookey's notes</h3>
|
|
from <a href="http://wookware.org/software/cavearchive/expoweb-design">wookware.org/software/cavearchive/expoweb-design</a>
|
|
<pre>
|
|
frontpage
|
|
---------
|
|
quick to load:
|
|
Links:
|
|
Caves number, name, location
|
|
Years
|
|
Handbook
|
|
Data Entry
|
|
Main Index
|
|
|
|
Slippy map:
|
|
Indexes to cave page
|
|
|
|
Cave page:
|
|
Access, description, photos, QMs, Survey
|
|
|
|
Years:
|
|
Logbooks/surveynotes/survexdata/people matrix
|
|
Documents
|
|
|
|
Data Entry:
|
|
Logbook entry
|
|
Survey data
|
|
Survey Notes
|
|
Cave description
|
|
QMs
|
|
Photos
|
|
New cave
|
|
|
|
Backend datafiles:
|
|
caves/
|
|
cave_entrance
|
|
cave_data
|
|
directory of info
|
|
|
|
years/
|
|
year/
|
|
logbook
|
|
pubs/
|
|
reports
|
|
admin/
|
|
lists
|
|
who_and_when
|
|
travel
|
|
jobs
|
|
|
|
surveyscans/
|
|
year/
|
|
index
|
|
#num
|
|
handbook/
|
|
(all static info)
|
|
|
|
Storage:
|
|
non-html or > 280K go in 'files' (PDF, PNG, JPEG, DOC, ODF, SVG)
|
|
convert small 1024x768 version into website by default. (matching structure?
|
|
</pre>
|
|
|
|
<hr />
|
|
|
|
<h3 Radost's proposal</h3>
|
|
|
|
<p>Radost Waszkiewicz (CUCC member 2016-2019) proposed a plan for superceding troggle</p>
|
|
|
|
<pre>
|
|
Hey,
|
|
|
|
on the design sesh we've looked a bit on the way data is organised in the
|
|
loser repo and how to access it via troggle.
|
|
|
|
A proposal arised that all this database shannaingans is essentially
|
|
unnecessary - we have about 200 caves, about 250 entrances, about 200
|
|
people and couple dozen expos. We don't need efficient lookups at all. We
|
|
can write something which will be 'slow' and make only things we actually
|
|
care about. Similarly I see little gain from doing the html - python himera
|
|
template pages. These contain mainly nested for loops which could just as
|
|
well be written in e.g. python.
|
|
|
|
I'd advocate following solution:
|
|
- give up on fixing things in troggle
|
|
- have a small number of .py scripts which generate static webpages with
|
|
content we want
|
|
|
|
Why do this:
|
|
- we don't have multiple intermediate layers all of which are difficult to
|
|
maintain
|
|
- anyone can run this on their machine without need for local vm's
|
|
- to change something there is one thing you change - script that generates
|
|
pages belonging to particular pattern. currently you need to take care of
|
|
parsers, view script, url script, and template
|
|
- it runs offline (just like that as pages are just blocks of literal text
|
|
+ some javascript)
|
|
- we never end up with no working copy during expo - run scripts once
|
|
before expedition and put results in /backup and just leave it there till
|
|
next year. Something goes wrong on the daily updated version - we have a
|
|
very easy fallback
|
|
- just one (or very close to it) programming language
|
|
- change to python3 to parse silly chars
|
|
- wayyyy fewer lines of code and substantially better code to comment ratio
|
|
(if this is us writing this now)
|
|
- compatible with all the already existing static pages
|
|
- we can host this on a potato hosting as we're not running anything fancy
|
|
anymore
|
|
- get's rid of the horrifying url rewrites that correspond to no files that
|
|
exist
|
|
|
|
How much work would this actually take:
|
|
- most likely one script per page type, so far page types that are
|
|
obviously needed:
|
|
--cave index
|
|
--individual cave descriptions
|
|
--logbooks
|
|
- more than half of the parsers are already rewriten by me and can be
|
|
changed to do this instead of modifying SQL database with minimal effort
|
|
- html/css side of things already exists, but it would be nice to go for a
|
|
more modern look there as well
|
|
|
|
Things this solution doesn't solve:
|
|
- no webpage-based 'wizzard' for creating caves and such (did people use it
|
|
much? do we care?) -> maybe 'send an email to this address' is the ultimate
|
|
solution to this
|
|
- uploading photos is still difficult (in the sense that they don't get
|
|
minified automatically)
|
|
|
|
Rad
|
|
|
|
</pre>
|
|
</body>
|
|
</html>
|