expo/expoweb
1
0
Fork 0
mirror of https://expo.survex.com/repositories/expoweb/.git/ synced 2025-12-08 23:04:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Simplifying the systems overview, restructing long documents more sensibly

Browse Source
This commit is contained in:
Philip Sargent
2020-04-09 21:58:40 +01:00
parent 6a05848060
commit ab6ec0e5ff
10 changed files with 149 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
handbook/computing/manual.html
View File

@@ -37,6 +37,82 @@ processes that a maintainer would want to do.</p>
<li><a href="../index.htm">List of "How to" pages for everything else</a></li>
</ul>
<ul>
<li><a href="newyear.html">Manual: Creating a new 'year' in the system</a></li>
<li><a href="">Manual: Expo survey data maintenance manual</a></li>
<li><a href="manual.html#update">Manual: Updating the cave guidebook descriptions</a></li>
</ul>
<h2><a id="update">Updating the online systems - overview</a></h2>
<h3 id="troggle">Troggle - what it is</a></h3>
<p>Troggle runs the expo cave survey data management, presents the data on the website and manages the Expo Handbook. See the <a href="../troggle/trogintro.html">troggle intro</a>.
<h3>Autogenerated pages</h3>
<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
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 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 version control 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 public <a href="../exposerver.html">expo server</a> is on a machine far, far away that we only access remotely.
<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 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.
<p>The recommended editing workflow is to (a) use the version control software 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 version control software
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 id="git">Version control system</a></h3>
<p>We use a distributed revision control system (<a href="https://git-scm.com/about/distributed">git</a>, and formerly mercurial) for all the important data. (Note that we just use git: not GitHub, not GitLab, just <a href="https://git-scm.com/about/distributed">git</a>.)
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 would
then get synchronised when it next gets internet access.
</p>
<p>A version control system 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.</p>
<p>In 2019 we had half our <a href="manual.html#repositories">version-controlled repositories</a> under mercurial and half under git.
The intention is to move entirely to git before the 2020 expo.
<h3>Contents of this manual</h3>
<ol>