CUCC Expedition Handbook - Online systems

Expo Online Systems Overview

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, and structural info on how it's all put together for people who want/need to change things.

We have an Overview Presentation (many parts out of date) 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.

These pages listed below have been reviewed recently (2018), and a fuller list of "How do I..." instruction pages are on the handbook opening page.

But the systems Manual is still being actively edited to extract and simplify documentation. At the moment it is the only documentation we have for:

Updating the online systems - overview

Autogenerated pages

Some key sections of the online webpages are autogenerated by scripts or by troggle, 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 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

Editing this handbook and historic expo documentation

The primary and recommended way of editing this handbook (and the website generally) is to use a laptop which has the Distributed Version Control System 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.

The Expo laptop has the software installed, so it is best to learn how to do this when sitting at that laptop.

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 makes it very hard for you to screw anything up permanently, so don't worry about making changes - they can always be reverted if there is a problem. It also means that several people can work on the site on different computers at once and normally merge their changes easily.

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.

See the Expo data management systems manual for a fuller description of the DVCM repositories and how to install and use the software.

Using "Edit this page"

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.

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 these instructions for this tidy-up

DVCS - version control

We use a distributed revision control system (DVCS) for all the important data. 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.

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.

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'. The same goes for holiday photographs and GPS logs.

Troggle - what it is

Troggle is the software collection (not really a "package") based on Django originally intended to manage all expo data in a logical and accessible way and publish it on the web.

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:

  1. 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.
  2. Publishing the "guidebook descriptions" of caves. The user who is creating a new guidebook description can do this by filling-in some online forms.
  3. 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 above for how to use it and how to tidy up afterwards.

See the notes on troggle page for how and why it was developed and what needs to be done.