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

troggle documentation move para

Browse Source
This commit is contained in:
Philip Sargent 2020-07-09 23:48:02 +01:00
parent fc250d1b68
commit 63bc4103a7
3 changed files with 37 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
handbook/troggle/trogintro.html
View File

@ -37,9 +37,30 @@ The troggle software is written and maintained by expo members.
<li><a href="/survey_scans/2018%252343/">expo.survex.com/survey_scans/2018%252343/</a> - list of links to scanned notes for wallet #43 during the 2018 expo. <li><a href="/survey_scans/2018%252343/">expo.survex.com/survey_scans/2018%252343/</a> - list of links to scanned notes for wallet #43 during the 2018 expo.
</ul> </ul>
<h3 id="troggle">Troggle - why we developed it</a></h3>
<p>Troggle..
<ol>
<li>Coherently publishes expo data by cave, by expedition, by person, by trip or by survey - without requiring duplicate data entry.
<li>Manages and safely archives the typed and scanned survey data, entrance data, trip records (logbooks) and expo records.
<li>Enforces consistency - making it easier to detect mistakes and omissions
<li>Publishes the "guidebook descriptions" of caves by a combination of online forms and uploading files.
<li>Supports the process of turning scribbled notes into finished cave surveys
<li>Generates prospecting guides so that we don't waste time looking at holes which have already been explored
<li>Reformats the webpages such that they have a coherent style and have a small menu at the top-left
hand corner. These are the handbook you are reading now and the historic records of past expeditions.
<li>Provides a way of editing individual pages of the handbook
for very quick and urgent changes.
[This is the "Edit this page" capability; see <a href="../computing/manual.html#editthispage"> for
how to use it</a> and <em>how to tidy up afterwards</em>].
</ol>
<h3 id="where">Troggle - where it gets the data</a></h3> <h3 id="where">Troggle - where it gets the data</a></h3>
<p> <p>
All the data of all kinds is stored in files. When troggle starts up it imports that data from the files. There are other scripts doing useful things (folk, wallets) and these too get their data from files. Troggle is completely unlike any other django installation: it has a database, but the database is rebuilt from files. All the data of all kinds is stored in files. When troggle starts up it imports that data from the files. There are other scripts doing useful things (folk, wallets) and these too get their data from files.
<p>There is never any need to back up or archive the database as it is rebuilt from files. Rebuilding troggle and re-importing all the data takes about half an hour. <p>There is never any need to back up or archive the database as it is rebuilt from files. Rebuilding troggle and re-importing all the data takes about half an hour.

27
handbook/troggle/trogmanual.html
View File

@ -12,7 +12,8 @@
<p>This part of the handbook is intended for people maintaining the troggle software: <p>This part of the handbook is intended for people maintaining the troggle software:
<a href="https://www.goodreads.com/book/show/1155986.The_Tricky_Troggle">
<img border="1" class="onright" width="150px" src='tricky-troggle.jpg' alt='git logo'/></a>
<ul> <ul>
<li><a href="../computing/newyear.html">Annual tasks</a>: preparing for next year, finishing last year. <li><a href="../computing/newyear.html">Annual tasks</a>: preparing for next year, finishing last year.
<li><a href="../computing/regular.html">Regular tasks</a>: housekeeping as surveys are digitised. <li><a href="../computing/regular.html">Regular tasks</a>: housekeeping as surveys are digitised.
@ -22,29 +23,11 @@
<li><a href="trogdocm.html">Maintain troggle</a> itself. The code is public on repository <a href="../computing/repos.html">:troggle:</a> <li><a href="trogdocm.html">Maintain troggle</a> itself. The code is public on repository <a href="../computing/repos.html">:troggle:</a>
<li><a href="trognotes.html">Uncategorised notes</a> and past speculations <li><a href="trognotes.html">Uncategorised notes</a> and past speculations
</ul> </ul>
<p>Troggle is completely unlike any other django installation: it has a database, but the database is rebuilt from files every time it starts.
<h3 id="troggle">Troggle - why we developed it</a></h3> <p>Most of the data entry into troggle happens during or just after the expedition.
<a href="https://www.goodreads.com/book/show/1155986.The_Tricky_Troggle">
<img border="1" class="onright" width="150px" src='tricky-troggle.jpg' alt='git logo'/></a>
<p>Troggle..
<ol>
<li>Coherently publishes expo data by cave, by expedition, by person, by trip or by survey - without requiring duplicate data entry.
<li>Manages and safely archives the typed and scanned survey data, entrance data, trip records (logbooks) and expo records.
<li>Enforces consistency - making it easier to detect mistakes and omissions
<li>Publishes the "guidebook descriptions" of caves by a combination of online forms and uploading files.
<li>Supports the process of turning scribbled notes into finished cave surveys
<li>Generates prospecting guides so that we don't waste time looking at holes which have already been explored
<li>Reformats the webpages such that they have a coherent style and have a small menu at the top-left
hand corner. These are the handbook you are reading now and the historic records of past expeditions.
<li>Provides a way of editing individual pages of the handbook
for very quick and urgent changes.
[This is the "Edit this page" capability; see <a href="../computing/manual.html#editthispage"> for
how to use it</a> and <em>how to tidy up afterwards</em>].
</ol>
<p>* "Troggle eats just one very big meal a year." <p>* "Troggle eats just one very big meal a year."
<hr /> <hr />
Go on to: <a href="trogarch.html">Troggle architecture</a><br /> Go on to: <a href="trogarch.html">Troggle architecture</a><br />
Return to: <a href="trogintro.html">Troggle intro</a><br /> Return to: <a href="trogintro.html">Troggle intro</a><br />

17
handbook/troggle/trogspeculate.html
View File

@ -12,7 +12,7 @@
<pre> <pre>
From: Philip Sargent (Gmail) [mailto:philip.sargent@gmail.com] From: Philip Sargent (Gmail) [mailto:philip.sargent@gmail.com]
Sent: 19 April 2020 01:28 Sent: 19 April 2020 01:28 [original - since edited with extra refs.]
To: expo-tech@lists.wookware.org To: expo-tech@lists.wookware.org
Subject: vague thoughts about future troggle architecture Subject: vague thoughts about future troggle architecture
</pre> </pre>
@ -23,14 +23,17 @@ re-partition troggle with all the user interface in the user's browser would
be utterly horrible using current tools (javascript frameworks: react, be utterly horrible using current tools (javascript frameworks: react,
angular etc.). angular etc.).
<p> <p>
These frameworks get out of date in couple of years or so. So they don't These front-end frameworks get out of date in couple of years or so. So they don't
give us the decade-long stability we need to match available maintenance give us the decade-long stability we need to match available maintenance
effort. effort. [ See <a href="https://en.wikipedia.org/wiki/Comparison_of_JavaScript_frameworks">
Wikipedia list of javascript frameworks</a>.] With our deep historical perspective ("cough"),
we can expect this menagerie to sort itself out into a stable, standardised foundation
within the next 10 years.
<p> <p>
A web API to expose the troggle database (read-only) would allow some keen A web API to expose the troggle database (read-only) would allow some keen
person to write a special-purpose app on a phone, e.g. an entrance-locator person to write a special-purpose app on a phone, e.g. an entrance-locator
app, talking directly to the database. But replacing the whole user app, talking directly to the database. But replacing the whole user
interface does not seem feasible yet. interface does not seem feasible yet. In 10 years: probably.
<p> <p>
It did occur to me that we are missing a trick: 99+% of the database doesn't It did occur to me that we are missing a trick: 99+% of the database doesn't
change except for survey data updates which, apart from during expo, happen change except for survey data updates which, apart from during expo, happen
@ -74,7 +77,7 @@ directories in reality, not 1:1]
<p> <p>
<h3>troggle now</h3> <h3>troggle now</h3>
Troggle is very nearly fully working (not with as many functions as Troggle is very nearly fully working (not with as many functions as
originally envisaged admittedly) but very nearly. originally envisaged admittedly) but very nearly [it is now: 8 July 2020].
The QM data display needs writing; but other than that it's in pretty good The QM data display needs writing; but other than that it's in pretty good
shape. [Ah, yes, we should really add "drawings" as a core concept as well shape. [Ah, yes, we should really add "drawings" as a core concept as well
as "surveyscans". That will be a bit of work.] as "surveyscans". That will be a bit of work.]
@ -87,8 +90,7 @@ survex *ref paths.
<h3>Non-django troggle</h3> <h3>Non-django troggle</h3>
<p>Another possibility is ripping django out of troggle and leaving bare python <p>Another possibility is ripping django out of troggle and leaving bare python
plus a SQL database. This means that programmers would need to understand more SQL plus a SQL database [see <a href="trog2030.html">Trog2030 proposal</a>]. This means that programmers would need to understand more SQL but would not need to understand "django". Arguably this
but would not need to understand "django". Arguably this
could mean that we could gain. could mean that we could gain.
<p>Writing our own multi-user code would not be sensible, hence the database. <p>Writing our own multi-user code would not be sensible, hence the database.
But we could move to a read-only system where the only writing happens on data-import. But we could move to a read-only system where the only writing happens on data-import.
@ -107,6 +109,7 @@ not a function within the python codebase.
<p>There is a templating engine <a href="https://mozilla.github.io/nunjucks/">Nunjucks</a> <p>There is a templating engine <a href="https://mozilla.github.io/nunjucks/">Nunjucks</a>
which is a port to JavaScript of the Django templating system we use which is a port to JavaScript of the Django templating system we use
(via <a href="https://palletsprojects.com/p/jinja/">Jinja</a> - these are the same people who do Flask). This would be an obvious thing to use if we needed to go in that direction. (via <a href="https://palletsprojects.com/p/jinja/">Jinja</a> - these are the same people who do Flask). This would be an obvious thing to use if we needed to go in that direction.
<p>We need a templating engine because so much of the troggle coorindation output is in tables of data from diffrerent sources, e.g. see <a href=/survexfile/264">all survey data for 264</a>.
<p>Several organisations have moved their user-interface layer to the browser using <p>Several organisations have moved their user-interface layer to the browser using
Nunjucks including <a href="https://service-manual.nhs.uk/design-system/prototyping"> Nunjucks including <a href="https://service-manual.nhs.uk/design-system/prototyping">
the NHS digital service</a> and Firefox. the NHS digital service</a> and Firefox.