CUCC Expedition Handbook

Troggle - the beginnings of a manual

Troggle runs much of the the cave survey data management, presents the data on the website and manages the Expo Handbook.

Who needs to know What and When

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"

We have several quite different sorts of cavers who interact with troggle:

• The youthful hard caver, who is trained in underground survey techniques but whose interest is limited to handing over the grubby survey notes when she emerges into daylight. Is keen to know how many km of cave she surveyed each year and to see pretty drawn-up surveys (done by someone else). Walks through walls.
• The surface walker who is happy to do route-finding over the plateau, takes lots of photos of cave entrances and cavers enjoying sunshine and may sometimes be able to provide GPS tracks of where he has been. He needs a prospecting guide to find previously identified entrances and be able to find photos of caves in past years. Writes up his explorations in execrable handwriting in the logbook. Looks at walls.
• The diligent student who types up the survey notes into survex file format, transcribes sketch notes onto survex centre-lines, and uses Therion to produce beautiful survey graphics of the caves he has digitised - but who is not a computer geek and whose brain oozes out of his ears when Wookey explains what git is. Applies artistic graffiti to walls.
• The archivist who takes the survex files, the therion files, the GPS files, the scanned survex centrelines and files them in the right places on the expo laptop, uses the troggle reports to help ensure that these are consistent and are filed correctly. Uses troggle input forms to "create new cave" in the system and adds to the directory structures to match the recently discovered caves. Is learning git. When transcribing bad handwriting in logbook (or struggling with git), climbs walls.
• Nerdus maximus: talks python in his sleep and can rebase a hairy git branch without error after 7 bottles of Gosser. Painfully averse to writing documentation. Overstressed, over-caffeinated and with a tendency to mutter that it's all obvious. Oblivious to walls.

These are some of the "use cases" for which troggle needs to be (re)designed to cope with.

Rewrite from here on...

This troggle manual describes these:

• Annual tasks: preparing for next year, finishing last year (troggle & scripts)
• Architectural documentation of how it all fits together & list of active scripts
• How to edit and maintain troggle itself. The code is public on repository :troggle:

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:

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. (And managing all the cave suvey data to produce this.)
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 for how to use it and how to tidy up afterwards.

[Note that /survey_scans/ is generated by troggle and is not the same thing as /expofiles/surveyscans/ at all.]

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.

Troggle Login

Yes you can log in to the troggle control panel: expo.survex.com/troggle.

Archived updates

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 list of updates which are now only of historical interest.

A history of the expo website and software was published in Cambridge Underground 1996. A copy of this article Taking Expo Bullshit into the 21st Century is archived here.