expo/expoweb
1
0
Fork 0
mirror of https://expo.survex.com/repositories/expoweb/.git/ synced 2024-11-22 07:11:55 +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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
handbook/computing/hbmanual1.html Normal file
View File

@ -0,0 +1,99 @@
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>CUCC Expedition Handbook: editing the handbook</title>
<link rel="stylesheet" type="text/css" href="../css/main2.css" />
</head>
<body>
<h2 id="tophead">CUCC Expedition Manuals - Editing the Handbook</h2>
<h1>Editing the Handbook (1)</h1>
<h2>Handbook editing manual</h2>
<p>These pages are for cavers wanting to:
<ol>
<li>quickly edit a correction using "Edit this Page", or
<li>edit several pages while sitting at the <em>expo laptop</em>
<li>edit several pages using their own laptop
</ol>
<h3 id="editthispage">"Edit this page"</h3>
<p>You can update a single webpage
online via a browser. This is best 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.
<p>You can edit web pages without installing any software or doing any configuration. It even works if your laptop is a Mac.
To use it you need to <a href="/accounts/login/">log in to troggle</a> using the well-known "cavey:beery" password. You generally only need to do this once.
<p>When you are a logged-on user you will see "Edit this page" at the bottom of the menu on the top-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 content of the page.
<img class="onright" alt="gosser bier" src="../i/editthispage.jpg" />
<p>The image shows what it looks like when editing the "bierbook" page. There is a menu bar along the top of the panel where you can select the usual word-processing commands to make text <b>bold</b> or <em>italic</em> and to select syles such as headings or plain text.
<p>After editing the page you save your work by clicking on the "Submit" button at the bottom (see it at the bottom-left of the image).
<p>There is nothing to stop you editing lots of pages by this method but you will find it extremely tedious. It is especially tedious creating the links between pages.
<p><b>Footnote:</b> Currently this process does not properly tidy up after itself. Everyone can see your new edited page on the website immediately but you will need to ask a nerd to finish the process to make sure that your changes become persistent and don't get overwritten. [See the explanation at <a href="#tidy">the bottom of this page</a> if you want to know more.]
<h3>Autogenerated pages</h3>
<p>Some key sections of the online webpages are autogenerated from cave survey data
so you cannot use "Edit this page". These pages will not show "Edit this page" in the top-left menu even when you are logged in. If you need to change any of these you will need to <a href="manual.html">correct the underlying cave survey data</a></p>
<h3>Creating New Pages</h3>
<p>If you type in the name of a new webapge into the address bar of your browser, e.g. <a href="http://expo.survex.com/handbook/festering/spa.html">http://expo.survex.com/handbook/festering/spa.html</a> (e.g. if you want to document how to find a hot-tub in Altaussee) then troggle will offer to create the page for you. Just click on the blue text that says "Create this page":<br />
<img src="../i/createpage.jpg"/>
<p>Then once created, you can edit it the same way that you edit a pre-existing page.
<h3>Linking in New Pages</h3>
<p>You link your new page into the handbook by editing another page in which you want to create a link. For example if you have created a new page describing your wonderful new sleeping bag/hammock technique, then you might want to add a link in to <a href="../kitlist.html">Expo Personal Gear List</a>. Unfortunately the "create link" icon (a picture of 3 links of a chain) is disabled in the on-line editor so you would have to click on the HTML icon and insert the link by editing the HTML directly.
<h3>Conventions</h3>
<h4>Encoding</h4>
<ul>
<li>We specify that pages are encoded using <a href="https://www.w3schools.com/charsets/ref_html_utf8.asp">UTF-8</a> for all content.
<li>When editing webpages, use <a href="https://www.freeformatter.com/html-entities.html">HTML entities</a> for characters with umlauts, e.g. <em>&amp;ouml;</em> for &ouml;.
<li>Only use a UTF-8 encoding if there is no HTML entity, e.g. biohazard: <span style='font-size:30px;'>&#9763;</span>
</ul>
<h4>Filenames</h4>
<ul>
<li>No spaces in filenames. Use underscores or hyphens.
<li>No filenames starting with "-" or "!" (Mac users beware)
<lI>All filenames to start with an alphabetic letter.
<li>All filenames to be in lower case, must not use umlauts, must not have extra full-stops in the name.
<li>Don't use capitals in any sort of identifier. If you have to, make _sure_ that they are used exactly the same everywhere.
Otherwise it's easy to make pages that work on Windows, but which don't on Linux.
<li>When you use "Edit this page" you are editing on the server which is a Linux machine.
<li> Never create two files spelt the same except for capitalisation. They will overwrite each other if edited on a Windows machine <em>without any warning</em>. This is particularly a problem for the filenames generated on phones for photographs.
</ul>
<hr />
<h3 id="tidy">Tidying up and commiting the edits</h3>
<p>'Edit This Page' edits the file served on the web but it does not update the file in the version control
repository. To properly finish the job you need to get a nerd to
<ul>
<li>
ssh into expo@expo.survex.com from a machine already configured to do this
<li>cd to the directory containing the repo you want, i.e. "cd expoweb" for the handbook, which takes you to /home/expo/expoweb
<li>Run "<a href="https://www.selenic.com/mercurial/hg.1.html">hg status</a>" (to check what
changes are pending),
<li>then "<a href="https://www.selenic.com/mercurial/hg.1.html">hg diff</a>" to see the changes in detail
(or "hg diff|less" if you know how to use "less") and
<li>then DO NOT just run '<a href="https://www.selenic.com/mercurial/hg.1.html">hg commit</a>' unless you know how <em>emacs</em> works as it would dump
you into an emacs editing window (C-x C-C is the way to exit emacs). Instead, use the "-m" option:
<code>hg commit -m "changed topcamp phone number - myName" </code>
which submits the obligatory comment with the commit operation. You should write something informative and brief about your changes between the quotation marks and also give your full name.
</ul>
<p>We intend to make this issue go away when we migrate the expoweb repo from mercurial to git during 2020.
<hr />
<p>Go on to <a href="hbmanual2.html">Editing several pages</a><br />
Return to <a href="onlinesystems.html">Online systems overview</a>
<hr />
</body>
</html>

97
handbook/computing/hbmanual2.html Normal file
View File

@ -0,0 +1,97 @@
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>CUCC Expedition Handbook: editing the handbook</title>
<link rel="stylesheet" type="text/css" href="../css/main2.css" />
</head>
<body>
<h2 id="tophead">CUCC Expedition Manuals - Editing the Handbook</h2>
<h1>Editing the Handbook (2)</h1>
<h2>Handbook and Repository editing</h2>
<p>These pages are for cavers wanting to:
<ol>
<li>quickly edit a correction using "<a href="hbmanual1.html">Edit this page</a>", or
<li>edit several pages in repositories using the <em>expo laptop</em>
<li>edit several pages using your own laptop
</ol>
<h3 id="edithandbook">2. Editing this handbook and files in repositories</h3>
<p>The primary and recommended way of editing this handbook, historic expo files and survey data is to use
a laptop which has the version control software installed and configured. 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.
<ul>
<li>The expo server is on a machine far, far away that we only access remotely.
<li>These instructions apply to editing all files in the version-controlled repositories
<li>The <em>:expoweb:</em> repository holds this handbook and templates used to display most cave data
<li>The <em>:loser:</em> repository holds the cave survey data in survex files
<li>The <em>:drawings:</em> repository holds cave survey drawings files (therion, tunnel)
</ul>
<p>The <em>Expo laptop</em> has the necessary 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 ("pull" from the server); (b) edit a set of .html files on your laptop so that all links between them are consistent,
(c) save the files locally, and (d) "commit" them locally;
(e) "push" the collection of changes to the expo server.
<p>See the <a href="manual.html#manual">Expo data management manual</a> for a fuller description of the version control software
repositories and how to install and use the software.
<h4>What you can't do</h4>
<p>All the scans, photos, presentations, fat documents and videos are
not stored in the version control repositories so you cannot edit or change them using the method described here.</p>
<h3><a id="yourownlaptop">3. Your own laptop</a></h3>
<p>Setting up 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 ssh
<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>Cheat lists and quick reminders</h3>
<p>If you know what you are doing here is the basic info on what's where:<br />
<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, see below),
but changes to dynamically-generated files - cave descriptions, QM lists etc. -
will not take effect, until the troggle <a href="../troggle/trogintro.html">import/update scripts</a> are run on the server. These should <a href="../troggle/otherscripts.html">run automatically and frequently</a> but currently they are run manually by nerds as the expo server is undergoing heavy software maintenance. </p>
<hr/>
<h4>Mercurial Website Hack 2019</h4>
<p> Currently [April 2020] after commiting and pushing your changes to the <em>:expoweb:</em> or <em>:loser:</em> respositories, you will need to
login to expo.survex.com using ssh, cd to ~/expoweb/ (or ~/loser/) 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 during 2020 when Wookey finishes migrating these repos from mercurial to git.
<hr />
<p>Back to to "<a href="hbmanual1.html">Edit this page</a>"<br />
Forwards to <a href="manual.html">Data Management Manual</a>
<hr />
</body>
</html>

150
handbook/computing/manual.html
View File

@ -2,14 +2,17 @@
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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" /> <link rel="stylesheet" type="text/css" href="../css/main2.css" />
</head> </head>
<body> <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> <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> <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> <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> <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>. <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> <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>.) <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 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. <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. The intention is to move entirely to git before the 2020 expo.
<h3>Contents of this manual</h3> <h3>Contents </h3>
<ol> <ol>
<li><a href="#usernamepassword">Getting a username, password and key</a></li> <li><a href="#usernamepassword">Getting a username, password and key</a></li>
<li><a href="#repositories">The repositories</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="#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="#cavepages">Updating cave pages</a></li>
<li><a href="#updatingyears">Updating expo year pages</a></li> <li><a href="#updatingyears">Updating expo year pages</a></li>
<li><a href="#surveystatus">Maintaining the survey status table</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> </ul>
<p>We have migrated two of these to git but the other two still use mercurial. <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> <h3><a id="cavepages">Updating cave pages</a></h3>
<span style="color:red">
<p>Cave description pages are automatically generated from a set of <p>Cave description pages are automatically generated from a set of
cave files in noinfo/cave_data/ and noinfo/entrance_data/. These files cave files in noinfo/cave_data/ and noinfo/entrance_data/. These files
are named <area>-<cavenumber>.html (where area is 1623 or 1626). These 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> <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> <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. page on where we are and what we might do to improveand fix menus.
</span>
<hr /> <hr />
</body> </body>

2
handbook/computing/onlinesystems.html
View File

@ -19,7 +19,7 @@ This page is the overview. The online systems manuals are split into these secti
<li><a href="newyear.html">the next expo</a> - preparing for next year <li><a href="newyear.html">the next expo</a> - preparing for next year
</ul> </ul>
<li><a href="../survey/index.htm"><b>Survey handbook</b></a> - how to input cave survey data. <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="hbmanual1.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: <li><a href="../troggle/trogintro.html"><b>System maintenance</b></a> - how to fix and enhance the software tools we have written:
<ul> <ul>
<li><a href="../troggle/trogmanual.html">Troggle</a> - the system framework <li><a href="../troggle/trogmanual.html">Troggle</a> - the system framework

5
handbook/computing/x-todo-styles.css → handbook/computing/todo-styles.css
View File

@ -60,7 +60,7 @@ dd {
font: 18px Calibri, sanserif; font: 18px Calibri, sanserif;
font-weight: normal; font-weight: normal;
color: 6083BF; color: 6083BF;
display: block; display: none;
#list-style-type: disc; #list-style-type: disc;
line-height: 1.3; line-height: 1.3;
margin-left: 1.0em; margin-left: 1.0em;
@ -80,6 +80,7 @@ dt {
margin-right: 5em; margin-right: 5em;
#list-style-type: none; #list-style-type: none;
line-height: 1.4; line-height: 1.4;
font-style: italic;
} }
@ -87,7 +88,7 @@ dt {
input[type=checkbox] ~ dl dd { input[type=checkbox] ~ dl dd {
display: block; display: block;
} }
input[type=checkbox]:checked ~ dl dd { input[type=checkbox]:checked ~ dl dd {
display: none; display: none;
} }

286
handbook/computing/todo.html Normal file
View File

@ -0,0 +1,286 @@
<!DOCTYPE html>
<html>
<head>
<title>Expo Systems - To-Do List</title>
<meta charset="utf-8">
<meta name="keywords" content="NOEDIT">
</head>
<body>
<h1>Expo To-Do List</h1>
<link rel="stylesheet" type="text/css" href="todo-styles.css" />
<button onclick="window.location.href = 'todo.html_edit';">Edit this to-do list</button>
<!--
<button onclick="window.location.href = 'x-todo.html_edit';">Update this to-do list</button>
-->
<!--
<label for="toggle-1">Toggle visibility of all sub-items</label>
<input type="checkbox" id="toggle-1">
-->
<!-- ------------------- Don't touch anything above this line --------------------------->
<h2>How this works</h2>
<p><b>Click twice on a sub-heading to reveal</b> the individual to-do items. Click again to hide.<br />
If a heading is in italics, then there are hidden items.
<p>Printing this page uses a much smaller font. Complain to <a href="mailto:expo-tech@lists.wookware.org">the nerd list</a> if you don't like this behaviour.
<p>Edit this page by clicking on the big blue button. It uses the same "Edit this page" function that you may have used before. Just be careful not to touch the code at the top and bottom of the page.
<p>We are working on a more capable and easier-to-use system (see <a href="x-todo.html">x-todo.html</a>) which will mimic how <a href="https://github.com/CaveSurveying/CUCCexposurveyissues/issues">GitHub Issues</a> do this sort of thing.
<h3>Process Documentation</h3>
<dl>
<dt><!--2020-03-26 psargent-->Wallets and new-cave</dt>
<dd><!--2020-03-26 psargent-->Explain (in the wallets process) how to view the surveys
online so that <br>&nbsp;&nbsp;(1) you can see an example of how to do your new one,
and <br>&nbsp;&nbsp;(2) so that you can check that you have done it properly when you
have finished.</dd>
<dd><!--2020-03-26 psargent-->Explain how to link a new cave into the other caves in
troggle filesystem</dd>
<dd><!--2020-03-26 psargent-->Explain how to add photos with the correct URL format to sub-HTML files attached to New Caves</dd>
<dt><!--2020-04-11 psargent-->svx check</dt>
<dd>explain command line to run on newly typed survex file to check for format errors '$cavern xxxx.svx'
</dl>
<h3>Surveys data entry</h3>
<dl>
<dt>Write code to automatically extract ref info about wallets from tunnel xml files
<dd><!--2020-04-03 psargent-->This will replace :drawings:chk-xml.txt as used by :drawings:check-xml.sh
<dd><!--2020-04-03 psargent-->Do similar for Therion files when people start using #REF comments
<dt><!--2020-03-26 psargent-->2019 surveyscans
<dd><!--2020-03-26 psargent-->edit all the content.json</dd>
<dd><!--2020-03-26 psargent-->try to autocomplete the content.json by parsing .svx files</dd>
<dd><!--2020-03-26 psargent-->Put personal names into canonical form</dd>
<dt>2014 contents.json
<dd><!--2020-04-03 psargent-->parse all the svx files to extract people, dates & svx references
</dl>
<h3>Logbook fettling</h3>
<dl>
<dt>2019 Logbook</dt>
<dd>
transcribe the rest of those UKcaving blog entries into expoweb/years/2019/logbook.html</dd>
<dd><!--2020-04-03 psargent-->
copy the photos from the UKCaving blog into expofiles/photos/2019/<MyName>/ -- in fact many of those photos are already there</dd>
<dd><!--2020-04-03 psargent-->edit in the links to those photos in the right place in 2019/logbook.html</dd>
<dt>Garlic cave
<dd> edit logbook entries 2018, 2019 to link to extensive photos of Garlic cave area {Withnall 2018} , {Becka 2019}
<dt>Past logbooks - missing images?
<dd><!--2020-04-03 psargent-->Which previous years HTML logbooks are missing images extracted from scanned PDF copies of the logbooks?
<dt>imagemagick convert
<dd><!--2020-04-03 psargent-->Not working for PDFs on current version of xubuntu ! Fix & document. Also not working on WSL ubuntu. Needed to work with logbook images easily.
<dt>2018 Logbook</dt>
<dd>Check Natalie Uomini's typed entries and extensive photos are minimized and linked in properly to the HTML logbook
<dt>Add missing images to logbooks</dt>
<dd>
2000, 2008, 2009, 2011</dd>
<dd>
fix corrupted image in 2001 log</dd>
<dt>2011 logbook:</dt>
<dd>type up via-ferrate & bolt-testing writeups (In paper book, not in scan or HTML)</dd>
<dt>200? logbook:</dt>
<dd>
Type up "list of GPS locations still to type"</dd>
</dl>
<h3>Handbook</h3>
<dl>
<dt><!--2020-04-11 psargent-->Desperately needs Navigation - Location Context, Situational Awareness
<dd><!--2020-04-11 psargent-->No overall view of what there is: need a user-friendly diagrammatic overview <a href="https://en.wikipedia.org/wiki/Site_map">sitemap</a>. There are 4,869 files in :expoweb:</dd>
<dd><!--2020-04-11 psargent-->Not fixed by menus - breadcrumbs needed?</dd>
<dd><!--2020-04-11 psargent-->Diagrams of major sections: survey handbook, rigging handbook, computing handbook, Areas, cave data..</dd>
<dd><!--2020-04-11 psargent-->Chase Airoa to help fix <a href="../troggle/menudesign.html">the menus for phones</a></dd>
<dd><!--2020-04-11 psargent-->Look at <a href="https://www.gov.uk/guidance/government-design-principles">gov.uk guidelines</a> for inspiration</dd>
<dt><!--2020-04-11 psargent-->When git migration done
<dd>Edit out all mercurial
<dd>Split the TortoiseHg/PuTTy documentationa nd retain only PuTTy
<dt><!--2020-04-11 psargent-->Wookey Overview presentation
<dd>extract content from <a href="http://wookware.org/talks/expocomputer/#/10">Troggle</a> which does not render properly and extract the HTML not in slide format - correcting things now outdated.
</dl>
<h3>Photos</h3>
<dl>
<dt><!--2020-04-03 psargent-->Fix the BINS package
<dd><!--2020-04-03 psargent-->set up git on the BINS software? Fix base url sautret.org</dd>
<dd><!--2020-04-03 psargent-->set up a cron / Makefile job to run BINS</dd>
<dd><!--2020-04-03 psargent-->why is 'updatephotos' script in expofiles? </dd>
<dd>Document the ~expo/webphotos/ directory and how it works
<dd>Why does expofiles/photos/xml/ get created containing all the generated xml files? Fix this.
</dl>
<h3>System Documentation</h3>
<dl>
<dt><!--2020-04-11 psargent-->Document how we generate the SMK overall lengths and stats</dt>
<dd><!--2020-04-11 psargent-->scripts and manual actions in cavern
<dt><!--2020-03-26 psargent-->Troggle architecture</dt>
<dd><!--2020-03-26 psargent-->Handbook: add more to the new troggle architecture documentation. For future system maintainers</dd>
<dd><!--2020-04-10 psargent-->Regenerate the diagram of the tables in the database & document</dd>
<dd><!--2020-04-10 psargent-->Describe the parsing/import procedures so non-nerds can do it</dd>
<dd><!--2020-03-26 psargent-->Copy [some of] the .wiki material into the documentation somewhere</dd>
<dt><!--2020-03-26 psargent-->Surveyscans</dt>
<dd><!--2020-03-26 psargent-->explain where the image files are referenced from: svx, tunnel/therion, and </dd>
<dd>why there are so many broken links</dd>
<dt>Apache & MySQL configuration
<dd><!--2020-04-03 psargent-->DOCUMENT How to set up a server
<dd><!--2020-04-10 psargent-->Explain why Docker containers can be a maintenance nightmare
<dt>non-troggle scripts
<dd><!--2020-04-03 psargent-->DOCUMENT them all - have we got <a href="../troggle/otherscripts.html">a full list</a>?
</dl>
<h3>Troggle</h3>
<dl>
<dt>Better import error messages
<dd><!--2020-04-03 psargent-->REPORT if import surveyscan file failure
<dd><!--2020-04-03 psargent-->Why are so many surveyscan foolder missing after import?
<dd><!--2020-04-03 psargent-->WHY are total lengths of surveyed cave different between expo server and WSL server for 2019 and a few other years only ?
<dt>Logbook data model: unfilled fields?
<dd><!--2020-04-03 psargent-->'cave' of location field missing on nearly all logbook entroies. Missing from logbook templates. Where is this used and how can we fill it it in? Is it useful?
</dl>
<h3>Expo Server</h3>
<dl>
<dt><!--2020-03-26 psargent--> document directory structure
<dd><!--2020-04-03 psargent-->as per Julian's GitHub list - then close that issue</dd>
<dt>permissions
<dd><!--2020-04-03 psargent-->do we need a cron job or has the group membership fix fixed it ? either way, document it.
</dd>
</dl>
<h3><font color="fuchsia">Tackle Store Records</font></h3>
<dl>
<dt>No authoritative list of where the expo paper records are!
<dd><!--2020-04-03 psargent-->NO expo paperwork at all prior to 2008 in Tackle Store - where is it ?
<dd><!--2020-04-03 psargent-->FIND where all the wallet binders are, and the logbooks.
< <dd><!--2020-04-03 psargent--> BUY A4 plastic boxes for filing cabinet for logbooks getting damp there.
<dd>2017, 2018, 2019 wallet binders are in Philip S.'s house.
</dl>
<h3>
<font color="fuchsia">This to-do-list gadget itself</font>
</h3>
<dl>
<dt>Status
<dd>Try the <a href="x-todo.html"><em>Experimental</em> to-do list</a> - no extra display capabilities yet.
<dd>Fix the "click twice" on startup. Make it only click once to change display state of the DT tag
<dt><!--2020-03-26 psargent-->Eventual aim
<dd><!--2020-03-26 psargent-->to replace GitHub <a href="https://github.com/CaveSurveying/CUCCexposurveyissues/issues">
CUCCexposurveyissues</a> for non-tunnel, non-GIS issues.</dd>
<dd><!--2020-03-26 psargent-->We need two of these: <br>1.for expo systems work (troggle & scripts) - the current priority as we have nowhere currently that Wookey is willing to use
<br>2.for survey data progress/issues (though troggle itself can be used for some of this if cleaned up a bit)
</dd>
<dt><!--2020-03-26 psargent-->Try to automate simple functions in javascript
<dd><!--2020-03-26 psargent-->to control this document
in-place (tick, delete) instead of using the <a
href="https://www.tiny.cloud/docs/general-configuration-guide/use-tinymce-inline/">
tinymce</a> HTML editor in Django</dd>
<dd><!--2020-03-26 psargent-->Maybe restructure whole page as JSON and use
javascript editor to create (edit), re-order and demote items. </dd>
<dd><!--2020-03-26 psargent-->if using tinymcs, use the INLINE mode. </dd>
<dd><!--2020-03-26 psargent-->Implement comments on an issue, mimicking GitHub issues wiki</dd>
<dd><!--2020-03-26 psargent-->Use javascript to skip over the _edit page and submit changes
direct to server when updating. Needs direct POST and include the javascript in the posted content.</dd>
<dd><!--2020-03-26 psargent-->checkboxes so that items can be ticked (which also does strike-through)</dd>
<dd><!--2020-04-03 psargent-->promotion/demotion options?</dd>
<dd><!--2020-03-26 psargent-->bin icon to delete an item? Better to have an archive process.</dd>
<dt>Local WSL server
<dd><!--2020-04-03 psargent-->Why is it using recuced-capability tinymce, a paths problem ?
<dt>Italics management
<dd><!--2020-04-03 psargent-->Hide ALL DD if any Heading clicked.
<dd><!--2020-04-03 psargent-->Put DL into italics when *any* DD is hidden
</dl>
<hr>
<!-- ------------------- Do not touch anything below here either ------------------------>
<!--2020-03-26--> Testing area..
<div id="demo">Demonstation text as initially read from disc</div>
<script>
document.getElementById("demo").innerHTML = "Demonstation innerHTML change CONFIRMED";
</script>
<!--Bother. The DOM is not carried across to the _edit page. It looks like the _edit page just re-reads
the original file from disc. So storing changes done by js will mean working directly with the POST action and a form. -->
<script>
// TO DO - make the <dt> italic when any of the <dd> following it are hidden.
// Set up the click handlers:
var itemlist = document.getElementsByTagName('dd');
for (i = 0; i < itemlist.length; i++) {
itemlist[i].onclick = hideable;
}
var itemlist = document.getElementsByTagName('dt');
for (i = 0; i < itemlist.length; i++) {
itemlist[i].onclick = showable;
}
function showable () {
// When clicking on a <dt> item, show or not all the following <dd> elements
if (this.style.fontStyle !== "italic") {
this.style.fontStyle = "italic";
} else {
this.style.fontStyle = "normal";
}
var ddO = this.nextElementSibling;
while((ddO !== null) && (ddO.nodeName.toLowerCase() == 'dd')){
if (this.style.fontStyle === "italic") {
ddO.style.display = 'none';
} else {
ddO.style.display = 'block';
}
ddO = ddO.nextElementSibling;
}
}
function hideable () {
// When clicking on a <dd> item, show or not itself
var x = this;
if (x.style.display === "none") {
x.style.display = "block";
} else {
x.style.display = "none";
}
}
</script>
<hr /></body>
</html>

3
handbook/computing/x-todo.html
View File

@ -3,10 +3,11 @@
<head> <head>
<title>Expo Systems - Experimental To-Do List</title> <title>Expo Systems - Experimental To-Do List</title>
<meta charset="utf-8"> <meta charset="utf-8">
<meta name="keywords" content="NOEDIT">
</head> </head>
<body> <body>
<h1>Experimental expo To-Do List</h1> <h1>Experimental expo To-Do List</h1>
<link rel="stylesheet" type="text/css" href="x-todo-styles.css" /> <link rel="stylesheet" type="text/css" href="todo-styles.css" />
<button onclick="window.location.href = 'x-todo.html';">Update this to-do list</button> <button onclick="window.location.href = 'x-todo.html';">Update this to-do list</button>
<!-- <!--
<button onclick="window.location.href = 'x-todo.html_edit';">Update this to-do list</button> <button onclick="window.location.href = 'x-todo.html_edit';">Update this to-do list</button>

BIN
handbook/i/createpage.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
handbook/i/editthispage.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 65 KiB

1
handbook/survey/newcave.html
View File

@ -56,6 +56,7 @@ actually do these things.
</ul> </ul>
<p>and either later or at the same time, you will be doing these other tasks <p>and either later or at the same time, you will be doing these other tasks
<ul> <ul>
<li>Upload your <a href="../gpxupload.html">GPS track</a> to the cave and file photos of the entrance
<li>Create a new folder in the file system for the wallet data <li>Create a new folder in the file system for the wallet data
<li>Create a new folder in the file system for the survex data <li>Create a new folder in the file system for the survex data
<li>Create a "new cave entry" for the guidebook description <li>Create a "new cave entry" for the guidebook description

6
handbook/upload-expert.html
View File

@ -24,7 +24,7 @@ See <a href="computing/keyexchange.html">key-pair setup instructions</a> for how
<h3>Using scp - requires key-pair setup for the device</h3> <h3>Using scp - requires key-pair setup for the device</h3>
<p>Works on Windows (using winscp), Linux (using scp), and no doubt <p>Works on Windows (using winscp), Linux (using scp), and no doubt
mac and android with other tools. If you have Windows 10 and <a href="https://msdn.microsoft.com/en-gb/commandline/wsl/about">have installed bash</a>, then you can use scp.</p> mac and android with other tools. If you have Windows 10 and <a href="https://msdn.microsoft.com/en-gb/commandline/wsl/about">have installed WSL</a>, then you can use scp and don't need winscp.</p>
<p>If you don't have winscp installed you can get it from here: <p>If you don't have winscp installed you can get it from here:
<a href="http://winscp.net/eng/index.php">http://winscp.net/eng/</a>.</p> <a href="http://winscp.net/eng/index.php">http://winscp.net/eng/</a>.</p>
@ -54,7 +54,7 @@ give you a norton-commander-style 2-pane UI as well).</p>
<li>Download and install <b>Filezilla</b>. <li>Download and install <b>Filezilla</b>.
<li>Or learn to use <b><a href="https://www.computerhope.com/unix/scp.htm">scp</a></b>. <li>Or learn to use <b><a href="https://www.computerhope.com/unix/scp.htm">scp</a></b>.
<li>Or on a Windows machine try Winscp. <li>Or on a Windows machine try Winscp.
<li>Or if you are using an Android mobile phone, follow <a href="computing/ftpusage.html">Radost's instructions</a> which also cover Winscp briefly. <li>Or if you are using an Android mobile phone, follow <a href="computing/ftpusage.html">Radost's instructions</a> which also cover Winscp briefly (though the app he recommends is no longer available).
</ol> </ol>
@ -70,7 +70,7 @@ This no longer works as we had to change the folder permissions for /uploads/. S
<h3>Regenerating photos albums</h3> <h3>Regenerating photos albums</h3>
<p>ssh in to the server, cd to /expofiles/ and <p>ssh in to the server, cd to /expofiles/ and
<pre> <pre>
make photos $ ./updatephotos
</pre> </pre>
will regenerate it all using the installation of bins on the server will regenerate it all using the installation of bins on the server
using the config in /home/expo/config/bins/binsrc using the config in /home/expo/config/bins/binsrc

1
scripts/make-folklist.py
View File

@ -111,6 +111,7 @@ table.fancy td { border: 1px solid black; padding: 2pt }
table.fancy td.nonempty { background: #eee } table.fancy td.nonempty { background: #eee }
--> -->
</style> </style>
<meta name="keywords" content="NOEDIT">
</head> </head>
<body> <body>