mirror of
https://expo.survex.com/repositories/expoweb/.git/
synced 2024-11-22 07:11:55 +00:00
144 lines
9.5 KiB
HTML
144 lines
9.5 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<title>CUCC Expedition Handbook: Logbook internal format</title>
|
|
<link rel="stylesheet" type="text/css" href="/css/main2.css" />
|
|
</head>
|
|
<body>
|
|
<style>body { background: #fff url(/images/style/bg-system.png) repeat-x 0 0 }</style>
|
|
<h2 id="tophead">CUCC Expedition Handbook</h2>
|
|
<h1>Logbooks internal format</h1>
|
|
|
|
<h3 id="format">Format</h3>
|
|
|
|
<p>All these scanned handwritten logbook entries are typed into a laptop (often the expo laptop)
|
|
which is then synchronised the version control system.
|
|
|
|
<h3 id="format">Format of the online logbooks</a></h3>
|
|
|
|
|
|
<p>Do whatever you like to try and represent the logbook in html but do keep is <em>simple</em>. Don't try any clever HTML stuff. See the <a href="hbmanual1.html#images">"Edit this Page"</a> instructions for how to insert images and figures.
|
|
|
|
<p>Logbooks are typed up and kept in the [expoweb]/years/[nnnn]/ directory as 'logbook.html'.</p>
|
|
|
|
<p>When writing logbook entries, just use <a href="hbmanual1.html#images">relative URLs</a> to the same folder as your text, e.g. <var>href="mynicepic.jpg"</var> and the image and the logbook HTML will, for a 2017 expo, be put into <var>/years/2017/</var>.
|
|
|
|
<p>One special suggestion: do not use <P> 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 <P> 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 <a href="survey/caveentry.html">"Edit this Cave"</a>.]
|
|
|
|
<h3>How it all works - editing and archiving</h3>
|
|
<p>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).
|
|
<p>So when you click on any of the links to see the whole logbook, your edited entry will be there for all to see.
|
|
|
|
<p>
|
|
<em>Implementation note</em>: 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.
|
|
|
|
<h4> Logbook-specific HTML</h4>
|
|
<p>
|
|
The only rigid structure is the markup to allow troggle to parse the logbook files into 'trips':</p>
|
|
<code><pre>
|
|
<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></pre></code>
|
|
<p>When using the online form all this complexity is handled automatically:
|
|
<ul>
|
|
<li>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.
|
|
<li>The entire <var><span style="color:red">editentry</span></var> 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.
|
|
<li>The identification of the author as the person between underline tags is done by the form.
|
|
<li>The identification of the place, as the first item in the title, is done by the form.
|
|
<li>The entry separator <var><span style="color:red"><hr /></span></var> is inserted correctly.
|
|
</ul>
|
|
<p>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).</p>
|
|
<p>Note: <var><span style="color:red">T/U</span></var> stands for "Time Underground" in decimal hours, e.g. "0.2" for 12 minutes (approx.) . We do not parse or collate this information currently.
|
|
<p>Note: the <var><span style="color:red"><hr /></span></var> is significant and used in parsing, it is not just prettiness.
|
|
<p>Note: follow this format exactly. No HTML comments or tabs or newlines.
|
|
|
|
<p>Note this special format <var>"<span style="color:red">Top Camp - </span>"</var> in the triptitle line:
|
|
<code><pre><div class="triptitle"><span style="color:red">Top Camp - </span>Setting up 76 bivi</div></pre></code>
|
|
It denotes the <var>cave</var> or <var>area</var> the trip or activity happened in. It is a word or two separated from the rest of the triptitle with "<var> - </var>" (space-dash-space). Usual values
|
|
for this are "Plateau", "Base camp", "264", "Balkon", "Tunnocks", "Travel" etc.
|
|
|
|
<p>Note this special format <var>"<span style="color:red"><u>Jenny Black</u></span>"</var> in the trip-people line:
|
|
<code><pre><div class="trippeople"><span style="color:red"><u>Jenny Black</u></span>, Olly Betts</div>
|
|
</pre></code>
|
|
It is necessary that one (and only one) of the people on the trip is set in <span style="color:red"><u></u></span> 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.
|
|
|
|
<p>If you like, you can put non-expo people in the trip-people line: <var>"<span style="color:red">*Ol's Mum</span>"</var> with a <span style="color:red">*</span> prefix and they will be totally ignored by troggle:
|
|
<code><pre><div class="trippeople"><u>Jenny Black</u>, Olly Betts, <span style="color:red">*Ol's Mum</span></div>
|
|
</pre></code>
|
|
or
|
|
<code><pre><div class="trippeople"><u>Jenny Black</u>, Olly Betts, <span style="color:red">*4 Hungarian Cavers</span></div>
|
|
</pre></code>
|
|
|
|
|
|
<h3 id="history">The logbooks format over the years</h3>
|
|
|
|
<p>Very old logbooks were simply typed up text documents with no formatting.
|
|
|
|
<p>Old logbooks (prior to 2007) were stored as logbook.txt with just a bit of consistent markup to allow troggle parsing.</p>
|
|
|
|
<p>The formatting was largely freeform, with a bit of markup ('===' around header, bars separating date, <place> - <description>, and who) which (later) allowed the troggle import script to read it correctly. The underlines show who wrote the entry. </p>
|
|
<p>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.
|
|
<p>However, we missed one. The logbook for 1979 needs to be hand-edited to use the new format.
|
|
|
|
<!--
|
|
<p>So the format should be:</p>
|
|
|
|
<code>
|
|
===2009-07-21|204 - Rigging entrance series| Becka Lawson, Emma Wilson ===
|
|
</br>
|
|
{Text of logbook entry}
|
|
</br>
|
|
T/U: Jess 1 hr, Emma 0.5 hr
|
|
</code>
|
|
-->
|
|
|
|
<!--
|
|
<h4>How we used to do it: Adding your trip to the logbook online file</h4>
|
|
<p><b>DO NOT DO ANY OF THIS ANYMORE</b>. Left here pending archiving.
|
|
|
|
<p>If you are using the <em>expo laptop</em> just edit this file (if you are on expo in 2019):
|
|
|
|
<code>
|
|
/home/expo/expoweb/years/2019/logbook.html
|
|
</code>
|
|
|
|
copy the format you can see other people have used; <em>tell a nerd that you have done this</em>
|
|
so that they can take care of synchronising it with the version control system.
|
|
|
|
<p>
|
|
DO NOT take a copy of the logbook.html file from the expo laptop,
|
|
copy it by email or USB stick to another laptop, edit it there and then copy it back. That will
|
|
<em>delete other people's work</em>.
|
|
|
|
<p>If you are using your own laptop then you will need to either:
|
|
<ul>
|
|
<li>Just type up your trip as a separate file with a useful filename e.g. "logbook-myname-2018-08-03.txt", or just write it in an email, and send it to someone nerdish, or
|
|
<li>Install and learn how to use the version control software. (This requires a <var><a href="bulkupdatelaptop.html">Bulk Update Laptop</a></var>).
|
|
And you will need to synchronise regularly (every day) to
|
|
ensure that the updates from all the people entering trip data are OK and don't get overwritten by ignorant use of this software. Not recommended until you have been on a previous expo and have helped do the post-expo data tidy afterwards.
|
|
</ul>
|
|
|
|
|
|
<h3 id="another">Typing on another machine</h3>
|
|
<p>
|
|
Rather than editing logbook.html when you type up your trip, it is a much better
|
|
idea to type up <i>just your trip(s)</i> in a separate file, e.g. "logbook-mynewtrip.txt", and email it to a nerd if you are sitting at a different laptop.
|
|
|
|
-->
|
|
|
|
|
|
<hr />
|
|
<p>
|
|
Back to <a href="../logbooks.html">Logbooks for Cavers</a> documentation.<br>
|
|
Go on to <a href="logbooks-parsing.html">Importing logbooks into troggle</a>.<br>
|
|
Go on to <a href="log-blog-parsing.html">Importing the UK Caving Blog</a>.
|
|
<hr /></body>
|
|
</html>
|
|
|