CUCC Expedition Handbook

Logbooks internal format

Format

All these scanned handwritten logbook entries are typed into a laptop (often the expo laptop) which is then synchronised the version control system.

Format of the online logbooks

Do whatever you like to try and represent the logbook in html but do keep is simple. Don't try any clever HTML stuff. See the "Edit this Page" instructions for how to insert images and figures.

Logbooks are typed up and kept in the [expoweb]/years/[nnnn]/ directory as 'logbook.html'.

When writing logbook entries, just use relative URLs to the same folder as your text, e.g. href="mynicepic.jpg" and the image and the logbook HTML will, for a 2017 expo, be put into /years/2017/.

One special suggestion: do not use paragraph tags. Well, you can if you like, but they will be stripped out and replaced by double-newlines when the file is parsed. This is because paragraph tags cannot be nested - that is not allowed in HTML - and the fragment you are writing will be merged with other fragments and may be put inside a higher-level paragraph. [This is also true for Cave Description text in "Edit this Cave".]

How it all works - editing and archiving

When you use the online form to create a new logbook entry or to edit an old one, when you click the button the changes are made immediately to the online database on the server and you can see the results immediately (except for the list of logbook entry titles in the Expo webpage). Also, when you click the button the entire database of logbook entries is written out to disc, with your new entry in the right place by date, and this file 'logbook.html' is registered with the version control system (git add and git commit).

So when you click on any of the links to see the whole logbook, your edited entry will be there for all to see.

Implementation note: the logbook.html file is not, at that time, re-parsed and re-imported into the database. This is unnecessary and would also expose us to potential loss of data if two people were editing the logbook of the same year at the same time. So the software doesn't do that.

Logbook-specific HTML

The only rigid structure is the markup to allow troggle to parse the logbook files into 'trips':

<hr />
<div class="tripdate" id="2007-07-12b">2007-07-12</div>
<div class="trippeople"><u>Jenny Black</u>, Olly Betts</div>
<div class="triptitle">Top Camp - Setting up 76 bivi</div>
...text of the logbook entry...
<div class="timeug">T/U 0.2 hrs</div>
<div class="editentry"><br /><a href="/logbookedit/2007-07-12b">Edit this entry</a≷>br /></div>

When using the online form all this complexity is handled automatically:

The IDs are generated automatically and guaranteed to be unique, and they are rechecked each time there is a database reset. (They are now the Django slugs which uniquely identify each entry.) You never need to touch them. If you are hand-editing a logbook.html file just leave them alone and everything will get fixed up after a reset and the first edit/save.
The entire editentry line is generated automatically for all the entries when any entry is saved, and is carefully ignored by the parser when there is next a database reset. However it does need to be there for the parser to work properly during a database reset.
The identification of the author as the person between underline tags is done by the form.
The identification of the place, as the first item in the title, is done by the form.
The entry separator <hr /> is inserted correctly.

Note: the ID's must be unique, so are generated from the trip date plus a,b,c etc. when there is more than one trip on a day (if more than 26 on one day, then it uses a cyptographic hash of the content as a suffix).

Note: T/U stands for "Time Underground" in decimal hours, e.g. "0.2" for 12 minutes (approx.) . We do not parse or collate this information currently.

Note: the <hr /> is significant and used in parsing, it is not just prettiness.

Note: follow this format exactly. No HTML comments or tabs or newlines.

Note this special format "Top Camp - " in the triptitle line:

<div class="triptitle">Top Camp - Setting up 76 bivi</div>

It denotes the cave or area the trip or activity happened in. It is a word or two separated from the rest of the triptitle with " - " (space-dash-space). Usual values for this are "Plateau", "Base camp", "264", "Balkon", "Tunnocks", "Travel" etc.

Note this special format "Jenny Black" in the trip-people line:

<div class="trippeople"><u>Jenny Black</u>, Olly Betts</div>

It is necessary that one (and only one) of the people on the trip is set in underline format. This is interpreted to mean that this is the author of the logbook entry. If there is no author set, then this is an error and the entry is ignored.

If you like, you can put non-expo people in the trip-people line: "*Ol's Mum" with a * prefix and they will be totally ignored by troggle:

<div class="trippeople"><u>Jenny Black</u>, Olly Betts, *Ol's Mum</div>

<div class="trippeople"><u>Jenny Black</u>, Olly Betts, *4 Hungarian Cavers</div>

The logbooks format over the years

Very old logbooks were simply typed up text documents with no formatting.

Old logbooks (prior to 2007) were stored as logbook.txt with just a bit of consistent markup to allow troggle parsing.

The formatting was largely freeform, with a bit of markup ('===' around header, bars separating date, - , and who) which (later) allowed the troggle import script to read it correctly. The underlines show who wrote the entry.

There were also several previous (different) styles of using HTML. The one we are using now is the 5th variant. These older variants were eventually all reformatted into the current HTML format so that now (Jan. 2023) we only need to maintain the code for one parser.

However, we missed one. The logbook for 1979 needs to be hand-edited to use the new format [now fixed 2024].

Back to Logbooks for Cavers documentation.
Go on to Importing logbooks into troggle.
Go on to Importing the UK Caving Blog.