expo/expoweb
1
0
Fork 0
mirror of https://expo.survex.com/repositories/expoweb/.git/ synced 2026-03-22 18:56:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

handbook editing manual

Browse Source
This commit is contained in:
Philip Sargent
2020-04-10 13:09:12 +01:00
parent ab6ec0e5ff
commit abade360f4
12 changed files with 502 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files

150
handbook/computing/manual.html
View File

@@ -2,14 +2,17 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>CUCC Expedition Handbook: Programmers manual</title>
<title>CUCC Expedition: Data Maintenance Manual</title>
<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: Data Maintenance Manual</h2>
<h1>Expo Data Maintenance Manual</h1>
<h2><a id="manual">Expo data management programmers' manual</a></h2>
<p><span style="color:red">[This page currently being restructured and edited to make it more appropriate to the task. Many fragments have been moved here but not yet properly edited together. Also there are no links to other pages which will be needed.]
</span>
<h2><a id="manual">Expo data maintenance manual</a></h2>
<ul>
<li>This page is for cavers wanting to edit any expo data on their own machine. So that's the website, survey data, or drawn up surveys</li>
@@ -47,55 +50,6 @@ processes that a maintainer would want to do.</p>
<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
@@ -113,16 +67,12 @@ 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>
<h3>Contents </h3>
<ol>
<li><a href="#usernamepassword">Getting a username, password and key</a></li>
<li><a href="#repositories">The repositories</a></li>
<li><a href="#howitworks">How the data management system works</a></li>
<li><a href="#yourownlaptop">Your own laptop</a></li>
<li><a href="#quickstart">Quick start</a></li>
<li><a href="#editingthedata management system">Modifying the data management system</a></li>
<li><a href="#expowebupdate">The expoweb-update script</a></li>
<li><a href="#cavepages">Updating cave pages</a></li>
<li><a href="#updatingyears">Updating expo year pages</a></li>
<li><a href="#surveystatus">Maintaining the survey status table</a></li>
@@ -169,91 +119,9 @@ editing and keeps track of all changes so we can roll back and have branches if
</ul>
<p>We have migrated two of these to git but the other two still use mercurial.
<h4>Mercurial Website Hack 2019</h4>
<p> Currently (December 2019) after commiting and pushing your changes to expoweb to the mercurial server, you will need to
login to expo.survex.com using ssh, cd to /expoweb/ and issue a "<a href="https://www.selenic.com/mercurial/hg.1.html">hg update</a>" command to make your changes noticed by the webserver. This problem will go away before Expo 2020 - we hope - when we finish migrating from mercurial to git.
<p>All the scans, photos, presentations, fat documents and videos are
stored just as files (not in version control) in 'expofiles'. See
below for details on that.</p>
<h3><a id="howitworks">How the data management system works</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>.
<p>Anything you check in which affects cave data or descriptions won't appear on the site until
the data management system update scripts are run.
This <em>should</em> happen automatically every 30 mins (not since 2017), but you can also kick off a manual update.
See 'The expoweb-update script' below for details.</p>
<p>Also note that the ::expoweb:: web pages and cave data reports you see on the visible website
are not the same as the version-controlled "master" expoweb repo.
So in order that your committed and pushed changes become visible on the website,
they have to be 'pulled' from the repo (on teh server machine) onto the webserver (another place on the same server machine) before your changes are reflected.</p>
<h3><a id="yourownlaptop">Your own laptop</a></h3>
<p>Setting your own laptop so that it can do everything the <i>expo laptop</i> can do is quite a
complicated process. At a minimum you will be an experienced software nerd already and will have git, mercurial and a text editor installed and you will know how to use them.
You will have done the
<a href="keyexchange.html">key-pair setup</a> process - which you can only do entirely on your own if
you have access to the <i>expo laptop</i>.
<p>See <a href="basiclaptop.html">setting up a minimal laptop</a> for a short list of software. This assumes you know how to use it all.
<br />See <a href="yourlaptop.html">setting up your own laptop</a> for the full list of software we use and where to get it.
<p>Note that the instructions are primarily for people using Linux with some help for those using Windows. If you are a Mac user then you are on your own.
<h3><a id="editthispage">Using 'Edit This Page'</a></h3>
<p>This can be used to edit web pages without installing any software or doing any key-pair setup. It even works if your laptop is a Mac.
<p>This is the capability that you can see in the top-left-hand menu on any website page if you <a href="/accounts/login/">log in to troggle</a> using the <a href="#usernamepassword">cavey:beery password</a>.
<p>'Edit This Page' is a troggle capability edits the file served by the webserver but it does not update the copy of the file in the
repository (the invese of the problem described above as 'Mercurial Website Hack'). To properly finish the job you need to
<ul>
<li>
ssh into expo@expo.survex.com (use putty on a Windows machine)
<li>cd to the directory containing the repo you want, i.e. "cd loser" for
cave data or "cd expoweb" for the handbook and visible data management system, which takes you to /home/expo/expoweb
<li>Then run "<a href="https://www.selenic.com/mercurial/hg.1.html">hg status</a>" (to check what
changes are pending),
<li>then "hg diff" to see the changes in detail
(or "hg diff|less" if you know how to use "less" or "more") and
<li>then DO NOT just run '<a href="https://www.selenic.com/mercurial/hg.1.html">hg commit</a>' unless you know how emacs works as it will dump
you into an emacs editing window (C-x C-C is the way to exit emacs). Instead, do
'hg commit -m "found files left over - myName" '
which submits the obligatory comment witht he commit operation.
</ul>
<p>Again, we hope that this issue will go away when we migrate the expoweb repo from mercurial to git before the 2020 Expo.
<h3><a id="../manual/#editingthedata management system">Editing the data management system</a></h3>
<p>To edit the data management system fully, you need to use the version control system
software which is currently git and mercurial.
Some (static text) pages can be edited directly on-line using the 'edit this page link' which you'll
see if you are logged into troggle. In general the dynamically-generated pages, such as those describing
caves which are generated from the cave survey data, can not be edited in this way, but forms are provided
for some types of these like 'caves'.</p>
<h3>Cheat lists and quick reminders</h3>
<p>If you know what you are doing here is the basic info on what's where:<br />
(if you don't know what you're doing, skip to <a href="#editingthedata management system">Editing the data management system</a> below.)
<ul>
<li>Quick <a href="qstart-git.html">reminders for using git</a> at the command line.
<li>Quick <a href="qstart-hg.html">reminders for using mercurial</a> at the command line. (to be removed)
<li>Quick <a href="manual.html#quickstart">reminders for using rsync</a> at the command line.
</ul>
<p>Simple changes to static HTML files will take effect immediately (or as soon as the hg update hack is done, but this will disappear when we move entirely to git),
but changes to dynamically-generated files - cave descriptions, QM lists etc. -
will not take effect, until a nerd runs the expoweb-update script on the server.</p>
<h3><a id="expowebupdate">The expoweb & drawings import scripts</a></h3>
<p>The import scripts for the cave data are currently (Feb.2020) run manually by a nerd. So if you enter cave data,logbooks or survey scans you won't see the result
until a nerd has been placated.</p>
<h3><a id="cavepages">Updating cave pages</a></h3>
<span style="color:red">
<p>Cave description pages are automatically generated from a set of
cave files in noinfo/cave_data/ and noinfo/entrance_data/. These files
are named <area>-<cavenumber>.html (where area is 1623 or 1626). These
@@ -290,7 +158,7 @@ Files are added and edited using the version control system for the expoweb repo
<h3><a id="menu">Cave pages and handbook menu design</a></h3>
<p>See the <a href="menudesign.html">menu design history and proposals</a>
page on where we are and what we might do to improveand fix menus.
</span>
<hr />
</body>