mirror of
https://expo.survex.com/repositories/expoweb/.git/
synced 2024-11-22 07:11:55 +00:00
Simplifying the systems overview, restructing long documents more sensibly
This commit is contained in:
parent
6a05848060
commit
ab6ec0e5ff
@ -11,7 +11,7 @@
|
||||
<h1>Setting up a minimal Expo laptop</h1>
|
||||
|
||||
<h2>Overview</h2>
|
||||
|
||||
<p>If you are new to expo please use the <em>expo laptop</em> first. You don't <em>need</em> to use your own laptop - which takes most of a day to do it properly.
|
||||
<p>To set up your own laptop you need to do this:</p>
|
||||
<ol>
|
||||
<li>Register an SSH key</a> with an expo nerd i.e 'get a login'. (see "Key Configuration" below)</li>
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -6,108 +6,50 @@
|
||||
<link rel="stylesheet" type="text/css" href="../../css/main2.css" />
|
||||
</head>
|
||||
<body>
|
||||
<h2 id="tophead">CUCC Expedition Handbook - Online systems</h2>
|
||||
<h2 id="tophead">CUCC Expedition Handbook - Online overview</h2>
|
||||
<h1>Expo Online Systems Overview</h1>
|
||||
<p>The online data and web publishing system (i.e. "the website") is now large and complicated.
|
||||
The handbook 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.
|
||||
|
||||
<p>The cave data and online publishing system (aka "the website") is now large and complicated.
|
||||
|
||||
<p>We have <a href="http://wookware.org/talks/expocomputer/#/">an Overview Presentation</a> (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.
|
||||
|
||||
<p>These pages listed below have been reviewed recently (2019), and a
|
||||
fuller list of "How do I..." instruction pages are on <a href="../index.htm">the handbook opening page</a>.
|
||||
This page is the overview. The online systems manuals are split into these sections:
|
||||
<ul>
|
||||
<li><a href="manual.html"><b>Data maintenance</b></a> - for cavers finding and updating cave survey data using the software tools.
|
||||
<ul>
|
||||
<li><a href="../treasurer.html">Accounts</a> - the Bank of Expo, the bier book
|
||||
<li><a href="newyear.html">the next expo</a> - preparing for next year
|
||||
</ul>
|
||||
<li><a href="../survey/index.htm"><b>Survey handbook</b></a> - how to input cave survey data.
|
||||
<li><a href="manual.html"><b>Handbook maintenance</b></a> - how to improve and update what you are reading now.
|
||||
<li><a href="../troggle/trogintro.html"><b>System maintenance</b></a> - how to fix and enhance the software tools we have written:
|
||||
<ul>
|
||||
<li><a href="../troggle/trogmanual.html">Troggle</a> - the system framework
|
||||
<li><a href="../troggle/otherscripts.html">Other scripts</a>
|
||||
<li><a href="../troggle/serverconfig.html">Server configuration</a>
|
||||
</ul>
|
||||
<img class="onright" alt="gosser bier" src="../i/gosser-panorama.jpg" />
|
||||
</ul>
|
||||
|
||||
<p>How to use basecamp computers and networks, how to configure your phone for GPS, how to use your own laptop and "how to expo" in general are all part of the <em>handbook content</em>:
|
||||
<ul>
|
||||
<li><a href="../uploading.html">Uploading your photos</a></li>
|
||||
<li><a href="../logbooks.html">Uploading typed logbooks</a></li>
|
||||
<li><a href="../gpxupload.html">Uploading GPS tracks</a></li>
|
||||
<li><a href="../survey/newcave.html">Recording a new cave discovery</a></li>
|
||||
<li><a href="../survey/status.html">Monitoring the status of the cave survey workflow during and after expo</a></li>
|
||||
<li><a href="../survey/status.html">Monitoring the cave survey workflow status</a></li>
|
||||
</ul>
|
||||
<p>The systems manual is being actively edited to extract and simplify documentation.
|
||||
<ul>
|
||||
<li><a href="newyear.html">Manual: Creating a new 'year' in the system</a></li>
|
||||
<li><a href="manual.html">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>
|
||||
<p>Surveying and recording survey data is the primary reason all this exists. The "survey handbook" part of this handbook gives instructions to beginners for how to record discoveries and surveys. The "data maintenance" manual is where to look for help when things go wrong: the data has been entered incorrectly, or software has crashed due to corrupt input data.
|
||||
<p>The "system maintenance" manual may of interest to a caver who wonders how it is all put together but should not be needed by most people.
|
||||
<p>
|
||||
A fuller list of "How do I..." instruction pages are on <a href="../index.htm">the handbook opening page</a>. If you are new to this you may need a beer.
|
||||
<hr />
|
||||
|
||||
<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.
|
||||
<p>We have <a href="http://wookware.org/talks/expocomputer/#/">an Overview Presentation</a> (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 these online manuals.
|
||||
|
||||
<p>Return to <a href="../index.htm">the handbook index</a>.<br />
|
||||
Return to <a href="../../infodx.htm">Expo published reports, Austrian caving area, handbooks and main index</a>.
|
||||
|
||||
<hr />
|
||||
</body>
|
||||
|
||||
BIN
handbook/i/gosser-panorama.jpg
Normal file
BIN
handbook/i/gosser-panorama.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 31 KiB |
@ -44,8 +44,7 @@ Need to get in touch with someone? Look here.
|
||||
<h2>Computing and Cave Surveying</h2>
|
||||
This is a scientific expedition - the Austrian government allows us to wander around the plateau <em>in exchange for</em> cave surveys. Learn how to contribute!
|
||||
<ul>
|
||||
<li><a href="onlinesystems.html">Expo online systems</a> - Overview of expo server capabilites.</li>
|
||||
<li><a href="computer.html">Basecamp computers</a> - What's the network setup, how to use it.</li>
|
||||
<li><a href="computing/onlinesystems.html">Expo online systems</a> - Overview of expo server capabilites.</li>
|
||||
|
||||
<li><a href="uploading.html">Uploading photos</a> - More detailed description on photos management.</li>
|
||||
<li><a href="gpxupload.html">Phone GPS</a> - How to record the location of the cave you've found.</li>
|
||||
@ -54,7 +53,6 @@ This is a scientific expedition - the Austrian government allows us to wander ar
|
||||
<li><a href="logbooks.html">Logbook</a> - Adding trip notes and cave descriptions.</li>
|
||||
|
||||
<li><a href="computing/basiclaptop.html">Using your own laptop</a> - Minimal setup to download and upload stuff.</li>
|
||||
<li><a href="computing/yourlaptop.html">Configuring everything on a new laptop</a> - It's a lot. This is not the place to start</li>
|
||||
|
||||
|
||||
<br />
|
||||
|
||||
@ -72,7 +72,7 @@ detailed topics.</p>
|
||||
|
||||
|
||||
<hr />
|
||||
|
||||
<div id="menu">
|
||||
<ul id="links">
|
||||
<li><a href="../index.htm">Expedition Handbook</a>
|
||||
<ul>
|
||||
@ -90,6 +90,6 @@ detailed topics.</p>
|
||||
<li><a href="../../index.htm">Back to Expedition Intro page</a></li>
|
||||
<li><a href="../../../index.htm">Back to CUCC Home page</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@ -47,7 +47,7 @@ actually do these things.
|
||||
<li>Write up your trip in the <a href="../logbooks.html">logbook</a> including rigging sketches<br /><br />
|
||||
<li>Put notes in a new wallet
|
||||
<li>Scan the notes (see <a href="newwallet.html#onlinew">"new wallet"</a> for the filenames to use and <a href="newwallet.html#scan">how to use the scanner</a>)
|
||||
<li>Type in survey data (in the right place in the file system) in <a href="#survexformat">survex format</a>.<br />
|
||||
<li>Type in survey data (in the right place in the file system) in survex format.<br />
|
||||
(This includes passage descriptions and open leads known as QMs: Question Marks).
|
||||
<li>Run survex to create a centre-line printout
|
||||
<li>Transcribe your sketches onto centre-line paper
|
||||
|
||||
@ -32,7 +32,7 @@ This page outlines step 2 of the survey production process. Each step is documen
|
||||
<h3 id="newwallet">Starting a new wallet</h3>
|
||||
<ol>
|
||||
<li>Put all your written notes into the next empty "wallet":
|
||||
(a transparent folder/envelope) in this year's lever-arch file labelled
|
||||
(a transparent folder/envelope, also sometimes known as a "pocket") in this year's lever-arch file (the "wallet binder") labelled
|
||||
e.g. "Expo Survey 2018" in the potato hut*.
|
||||
<li>The wallet has a paper sticky label on it with the wallet-identifier,
|
||||
e.g. <b>2018#22</b>, already printed on the label.
|
||||
|
||||
34
handbook/troggle/serverconfig.html
Normal file
34
handbook/troggle/serverconfig.html
Normal file
@ -0,0 +1,34 @@
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<title>Handbook - Expo Server</title>
|
||||
<link rel="stylesheet" type="text/css" href="../../css/main2.css" />
|
||||
</head>
|
||||
<body>
|
||||
<h2 id="tophead">CUCC Expedition Handbook</h2>
|
||||
<h1>The Expo server</h1>
|
||||
<p>Troggle is the software which runs the the expo cave survey data management and website. It is not the only thing running on the expo server.
|
||||
|
||||
<h3 id="what">Server configuration</a></h3>
|
||||
|
||||
<br />apache webserver
|
||||
<br />MySQL database
|
||||
<br />cgit
|
||||
<br />boe
|
||||
<br />cron
|
||||
<br />Makefile
|
||||
<br />bins
|
||||
<br />expofiles
|
||||
<br />ssh
|
||||
|
||||
<p>[2020-04-10] <em>To be written...</em>
|
||||
|
||||
<hr />
|
||||
Go on to:
|
||||
<a href="trogintro.html">troggle introduction</a><br />
|
||||
Return to:
|
||||
<a href="../computing/onlinesystems.html">expo online systems overview</a><br />
|
||||
<hr />
|
||||
</body>
|
||||
</html>
|
||||
@ -38,7 +38,7 @@ hand corner. These are the handbook you are reading now and the historic records
|
||||
|
||||
<li>Provides a way of editing individual pages of the handbook
|
||||
for very quick and urgent changes.
|
||||
[This is the "Edit this page" capability; see <a href="../computing/onlinesystems.html#editthispage"> for
|
||||
[This is the "Edit this page" capability; see <a href="../computing/manual.html#editthispage"> for
|
||||
how to use it</a> and <em>how to tidy up afterwards</em>].
|
||||
</ol>
|
||||
<hr />
|
||||
|
||||
Loading…
Reference in New Issue
Block a user