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

handbooksystems overview rearrangement and updates

Browse Source
This commit is contained in:
Philip Sargent 2018-08-28 23:03:05 +01:00
parent e4d2875063
commit 4042d63071
1 changed files with 63 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
handbook/update.htm
View File

@ -6,7 +6,7 @@
<body>
<h2 id="tophead">CUCC Expedition Handbook - Online systems</h2>
<h1>Expo Online Systems Overview</h1>
<p>The online data system and webinterface is now large and complicated with a lot of aspects.
<p>The online data and web publishing system (i.e. "the website") is now large and complicated with a lot of aspects.
This handbook section contains info at various levels:
simple 'How to add stuff' information for the typical expoer,
more detailed info for cloning it onto your own machine for more significant edits,
@ -18,14 +18,23 @@ on how the cave data,
handbook and public website are constructed and managed.
It contains material which will be merged into this online systems manual.
<p>These pages listed below have been reviewed recently (2018), and a
fuller list of "How do I..." instruction pages are on <a href="index.html">the handbook opening page</a>.
<ul>
<li><a href="uploading.html">Uploading your photos</a></li>
<li><a href="logbooks.html">Uploading typed logbooks</a></li>
<li><a href="gpxupload.html">Uploading GPS tracks</a></li>
<li><a href="manual.html#update">Updating the guidebook descriptions and handbook</a></li>
<li><a href="manual.html#manual">Expo software and server maintenance manual</a></li>
<li><a href="survey/newcave.html">Recording a new cave discovery</a></li>
<li><a href="survey/status.html">Monitoring the status cave survey workflow during and after expo</a></li>
</ul>
<p>But the systems Manual is still being actively edited to extract and simplify documentaiton. At the moment
it is the only documentation we have for:
<ul>
<li><a href="manual.html#update">Manual: Creating a new 'year' in the system</a></li>
<li><a href="manual.html#update">Manual: Updating the cave guidebook descriptions</a></li>
<li><a href="manual.html#manual">Manual: Expo software and server maintenance manual</a></li>
</ul>
<h2><a id="update">Updating the online systems - overview</a></h2>
<h3>Experts short cut</h3>
@ -34,8 +43,9 @@ It contains material which will be merged into this online systems manual.
data on the server
(using the <em>expo laptop</em>). This is a memory jog for experts, not beginners.</p>
<h3>Autogenerated pages</h3>
<p>Some key sections of the online webpages are autogenerated by
<p>Some key sections of the online webpages are autogenerated by scripts or by
<a href="#troggle">troggle</a>, and are not static files,
so you have to edit the base data, not the generated file (e.g cave
pages, QM (question mark) lists, expo members list, prospecting pages). All
@ -43,18 +53,14 @@ autogenerated files say 'This file is autogenerated - do not edit' at
the top - so check for that before wasting time on changes that will
just be overwritten</p>
<h3>Using "Edit this page"</h3>
<h3 id="edithandbook">Editing this handbook and historic expo documentation</h3>
<p>The primary and recommended way of editing this handbook (and the website generally) is to use
a laptop which has the <a href="#mercurial">Distributed Version Control System</a> software installed. The
person editing needs to know how to use this software, and also needs to know how to edit raw HTML files
using a text editor.
<p>You can update the site via the troggle pages, by editing pages
online via a browser ("Edit this page" on the menu on the left), by
editing them on the server remotely, or by checking out the relevant part to
your computer and editing it there. Which is best depends on your
knowledge and what you want to do. For simple addition of cave or
survey data troggle ("edit this page") is recommended. (For other edits it's best if you
can edit the files directly but that means you either need to be on expo with the expo
computer, or be able to check out a local copy using the version control system -
see the <a href="manual.html#manual">Expo software and server maintenance manual</a>. If neither of these
apply then using the 'edit this page' button is fine.</p>
<p>The <em>Expo laptop</em> has the software installed, so it is best to learn how to do this
when sitting at that laptop.
<p>It's important to understand that the pages you can edit by this method
are stored in a distributed version control system (see below). This stops us losing data and
@ -64,32 +70,42 @@ problem. It also means that several people can work on the site on
different computers at once and normally merge their changes
easily.
<p>After doing this, you need to ask a nerd to finish the process fairly soon as the "Edit this page"
<p>The recommended editing workflow is to (a) use the DVCM to synchronise your local laptop copy of the
website files with that on the server; (b) edit a set of .html files on your laptop so that all links between them are consistent,
save the files locally, and "commit" them locally;
(c) "push" the collection of changes to the expo online server as a single action.
<p>See the <a href="manual.html#manual">Expo data management systems manual</a> for a fuller description of the DVCM
repositories and how to install and use the software.
<h3 id="editthispage">Using "Edit this page"</h3>
<p>You can update a single webpage
online via a browser. This is best used for urgent edits to a single page, e.g.
if the emergency phone at top-camp has to use a new SIM with a different phone number.
If you are a logged-on user you will see "Edit this page" on the menu on the left of this page. It appears on
nearly all pages in this website. If you click on it you will be able to edit the raw HTML of the page - so you need
to know how to do that.
<p>After doing the page editing and saving your work, you need to ask a nerd to finish the process fairly soon as the "Edit this page"
mechanism does not tidy-up after itself properly.
See <a href="manual.html#editthispage">these instructions for this tidy-up</a>
<h3><a id="surveystatus">Maintaining the status of new surveys being drawn up</a></h3>
<p>This is managed in this years' folder in e.g.
<pre>
expofiles/surveyscans/2018/
</pre>
and is documented in the <a href="survey/newcave.html">New Cave survey data entry</a>
manual pages.
<h3 id="mercurial">DVCS - version control</a></h3>
<p>We use a distributed revision control system (DVCS) for all the important data.
On expo this means that many people can edit and merge their changes with the expo
server in the Tatty Hut even if there is no internet access. Also anyone who is up
to date with the Tatty Hut can take their laptop somewhere where there is internet
access and update expo.survex.com - which will then get all the updates done by everyone on expo.
This means that many people can edit and merge their changes with the expo
server in Cambridge at the same time: inlcuding people still on expo in the Tatty Hut
and those who have returned to the UK. Also anyone who is up
to date can take their laptop somewhere and enter data even if they have no internet access,
and the updates will be merged when they get back to civilization.
</p>
<p>In principle, survey notes can be typed into a laptop up on the plateau which is
then synchronised with the Tatty Hut on returning to base.
<p>In principle, survey notes can be typed into a laptop up on the plateau which would
then get synchronised when it next gets internet access.
</p>
<p>A DVCS is inefficient for scanned survey notes, which are large files that
do not get modified, so they are kept as a plain directory of files 'expofiles'.
@ -104,16 +120,22 @@ The same goes for holiday photographs and GPS logs.</p>
<p>
Troggle is the software collection (not really a "package") based on <a href="https://www.djangoproject.com/">Django</a>
originally intended to manage all expo data in a logical and accessible way
and displaying it on the web.
<p>Only a small part of troggle's original plan was fully implemented and deployed: that bit which
re-formats HTML web pages (such as the Expo Handbook). Troggle creates the contents index on every page
and provides the
"Edit this page" capability and provides some help in creating online guidebook descriptions
for the caves. (You can see "Edit this page" in the left hand menu of this
page that you are reading if you are a logged-on user.)
<p> Once you have edited the page you need to
update the server's local repo copies, by ssh into the server and running hg update in the expoweb folder.
Otherwise nobody else can use your changes via the repo mechanism even though they are pubished by the webserver</p>
and publish it on the web.
<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.
<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="#editthispage">above for
how to use it</a> and how to tidy up afterwards.
</ol>
<p>See the outdated <a href="http://www.srcf.ucam.org/caving/wiki/Troggle">Troggle page
</a> for a snapshot of development some years ago.