Philip software installaiton documentaiton updates

This commit is contained in:
PhilipSargent 2017-08-18 23:43:16 +01:00
parent 0c55164112
commit 0da5138fb1
4 changed files with 62 additions and 108 deletions

View File

@ -6,7 +6,7 @@
<body>
<h1>'Easy' guide to mercurial</h1>
<h2>Before you start</h2>
cd ~/expofiles/loser</br>
cd ~loser</br>
hg diff</br>
<b>If any changes are displayed, commit them:</b></br>
&nbsp;&nbsp;&nbsp;&nbsp;hg commit -m "<i>surveys in Pooh Passage which John did</i>" -u "<i>YourName</i>"</br>

View File

@ -1,76 +0,0 @@
<html>
<head>
<title>Cambridge University Caving Club Expedition Handbook.</title>
</head>
<body>
<h1>Windows 7 How-to No.1:<br>TortoiseHg and Putty</h1>
<p>Struggling to get TortoiseHg to work on Windows (Service Pack 1,
32-bit)? Heres a quick guide which I hope explains how to sort it all
out.</p>
<p>You first want to ascertain that both <a href="http://tortoisehg.bitbucket.org/">TortoiseHg</a> and <a href="http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html">Putty</a> are nicely installed. Then run Putty;</p>
<h2>Putty:</h2>
<p>Upon opening putty, youll be greeted with a screen similar to this;</p>
<div style="text-align: center">
<img src="expoPuttyscreen.png" alt="Putty Configuration Screen" />
<p class="caption">Putty Configuration Screen</p></div>
<p>Type <tt>expo@expo.survex.com</tt> into the box under Host Name, and type a
name into the box under 'Saved Sessions' then click 'Save' (in the
above case called 'Expo' this means you dont have to type in
expo@expo.survex.com each time you use Putty. You simply click on
'Expo' then 'Load'). Then click 'Open'.</p>
<p><b>Please note that when connecting to the tatty hut in Austria, you will need to log onto a different server. In this case, type:<tt>expo@expo.potato.hut</tt>, and follow the instructions above.</b></p>
<p>You will then see the following screen:</p>
<div style="text-align: center">
<img src="expoPuttyscreen2b.png" alt="Putty Login Screen" />
<p class="caption">Putty Login Screen</p></div>
<p>Dont worry if you cant see anything happening onscreen as you type in the password, this is whats supposed to happen; so just type in the password and press the return/enter key.</p>
<p>Done! At some point you may come across a Windows popup which asks
you to verify the address you're attempting to log into (at which
point you select 'hells-to-the-yeah', or equivalent). You have now made sure that your computer is happy to log on using TortoiseHg. To log out of Putty, type 'logout', then press the return/enter key.</p>
<h2>TortoiseHg:</h2>
<p>To open up TortoiseHg, simply open a folder somewhere on your desktop (you can make a new folder if you want, to keep things neat), and right click in the folder and select “Hg Workbench”</p>
<div style="text-align: center">
<img src="expoWorkbenchopen.png" alt="Accessing the Workbench" />
<p class="caption">Accessing the Hg Workbench</p></div>
<p>Once this opens up, go to File>Clone Repository, and you should get the following;</p>
<div style="text-align: center">
<img src="expoRepositoryScreen.png" width="75%" height="50%" alt="Hg Workbench" />
<p class="caption">Hg Workbench</p></div>
<p>At which point type <tt>ssh://expo@expo.survex.com/loser</tt> into
the 'Source' box (in this case I have specified a particular folder on
the server; 'loser', I suggest you do the same for now). You may also
choose where you want the repository to be created by clicking
'Browse' next to the 'Destination' box. As far as I recall, you don't
need to edit anything in the box where it says 'Hg command'. Click 'Clone'!</p>
<p><b>Again, if logging on from the tatty hut, type:<tt>ssh://expo@expo/loser</tt>to get things to work.</b></p>
<p>Voila! If you're now looking at the following screen or similar,</p>
<div style="text-align: center">
<img src="expoRepositoryScreen2.png" width="75%" height="50%" alt="Hg Workbench Linked" />
<p class="caption">Hg Workbench Linked</p></div>
<p>All is well.</p>
<p>If anything seems unclear, please email me at elmo2058@gmail.com, and I will reinstall things on my own machine to see where things get confusing. Watch this space for another webpage/update with how to install/use WINSCP for straightforward file transfers.</p>
<hr />
</body>
</html>

View File

@ -7,9 +7,10 @@
<body>
<h2 id="tophead">CUCC Expedition Handbook</h2>
<h1>Expo Website</h1>
<p>The website is now large and complicated with a lot of (too many!) moving parts. This handbook section contains info at various levels: simple 'Howto 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>
<p>The website is now large and complicated with a lot of (too many!) moving parts. This handbook section contains info at various levels: simple 'Howto 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. [This page is now so big that it needs to be split up.]</p>
<ul>
<li><a href="#photos">Uploading your photos and GPS tracks</a></li>
<li><a href="#update">Updating the website</a></li>
<li><a href="#checkout">Expo Website manual</a></li>
<li><a href="expodata.html">Expo website developer info</a></li>
@ -20,9 +21,9 @@
<p>Simple <a href="checkin.htm">instructions</a> for updating the website
(on the expo machine).</p>
<p>You can update the site via the troggle pages, by editing pages online via a browser, by editing them locally on disk, or by checking out the relevant part to your computer and editing it there. Which is best depends on your knowledge and what you want to do. For simple addition of cave or survey data troggle is recommended. For other edits it's best if you can edit the files directly rather than using the 'edit this page' button, but that means you either need to be on expo with the expo computer, or be able to check out a local copy. If neither of these apply then using the 'edit this page' button is fine.</p>
<p>You can update the site via the troggle pages, by editing pages online via a browser ("Edit this page" on the menu on the left), by editing them locally on disk, or by checking out the relevant part to your computer and editing it there. Which is best depends on your knowledge and what you want to do. For simple addition of cave or survey data troggle is recommended. For other edits it's best if you can edit the files directly rather than using the 'edit this page' button, but that means you either need to be on expo with the expo computer, or be able to check out a local copy. If neither of these apply then using the 'edit this page' button is fine.</p>
<p>It's important to understand that everything on the site is stored in a distributed version control system (DVCS) (called 'mercurial'), which means that every edited file needs to be 'checked in' at some point. The Expo website manual goes into more detail about this, 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>
<p>It's important to understand that everything on the site is stored in a distributed version control system (DVCS) (called '<a href=#mercurial>Mercurial</a>' and accessed by most people using software called 'TortoiseHg'), which means that every edited file needs to be 'checked in' at some point. The Expo website manual goes into more detail about this, 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>
<p>Increasing amounts of the site are autogenerated, not just files, so you have to edit the base data, not the generated file. 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>
@ -40,7 +41,7 @@
<li><a href="#howitworks">How the website works</a></li>
<li><a href="#quickstart">Quick start</a></li>
<li><a href="#editingthewebsite">Editing the website</a></li>
<li><a href="#mercurialinwindows">Using Mercurial/TortoiseHg in Windows</a></li>
<li><a href="#Mercurialinwindows">Using Mercurial/TortoiseHg in Windows</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>
@ -63,7 +64,7 @@
<h3><a id="repositories">The repositories</a></h3>
<p>All the expo data is contained in 4 'mercurial' repositories at
<p>All the expo data is contained in 4 Mercurial repositories at
expo.survex.com. This is currently hosted on a server at the university. Mercurial* is a distributed version control system which allows collaborative editing and keeps track of all changes so we can roll back and have branches if needed.</p>
<p>The site has been split into four parts:</p>
@ -83,11 +84,13 @@ stored just as files (not in version control). See below for details on that.</p
<p>Part of the website is static HTML, but quite a lot is generated by scripts. So anything you check in which affects cave data or descriptions won't appear on the site until the website update scripts are run. This happens automatically every 30 mins, but you can also kick off a manual update. See 'The expoweb-update script' below for details.</p>
<p>Also note that the website you see is its own mercurial checkout (just like your local one) so that has to be 'pulled' from the server before your changes are reflected.</p>
<p>Also note that the website you see is its own Mercurial checkout (just like your local one) so that has to be 'pulled' from the server before your changes are reflected.</p>
<h3><a id="quickstart">Quick start</a></h3>
<p>If you know what you are doing here is the basic info on what's where:</p>
<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="#editingthewebsite">Editing the website</a> below.)
<dl>
<dt>expoweb (The Website)</dt>
@ -115,26 +118,30 @@ stored just as files (not in version control). See below for details on that.</p
</dd>
</dl>
<p>Photos, scans (logbooks, drawn-up cave segments) (This is about
16GB of stuff which you probably don't actually need locally) To sync
<p>Photos, scans (logbooks, drawn-up cave segments) (This was about
60GB of stuff in 2017 which you probably don't actually need locally) To sync
the files from the server to local expofiles directory:</p>
<p><tt>rsync -av expo@expo.survex.com:expofiles /home/expo</tt></p>
<p>To sync the local expoimage directory back to the server:</p>
<p>To sync the local expofiles directory back to the server:</p>
<p><tt>rsync -av /home/expo/expofiles expo@expo.survex.com:</tt></p>
<p>(do be careful not to delete piles of stuff then rsync back - as it'll all get deleted on the server too, and we may not have backups!). Use rsync --dry-run --delete-after -a to check what would be deleted.</p>
<p>(do be careful not to delete piles of stuff then rsync back - as it'll all get deleted on the server too, and we may not have backups!). Use rsync --dry-run --delete-after -a to check what would be deleted. If you are using rsync from a Windows machine you will <em>not</em> get all the files as some filenames are incompatible with Windows: see more detail under <a href="Mercurialinwindows">Using Mercurial/TortoiseHg in Windows</a> below.</p>
<p>(We have an issue with rsync not using the appropriate user:group attributes for files pushed back to the server. This may not cause any problems, but watch out for it.)</p>
<h3><a id="editingthewebsite">Editing the website</a></h3>
<p>To edit the website fully, you need a mercurial client. 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 dynamically-generated pages can not be edited in this way, but forms are provided for some page-types like 'caves'.</p>
<p>To edit the website fully, you need a Mercurial client such as TortoiseHg. 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 dynamically-generated pages can not be edited in this way, but forms are provided for some page-types like 'caves'.</p>
<p>Mercurial can be used from the command line, but if you prefer a GUI, tourtoisehg is highly recommended on all OSes.</p>
<p>What follows is for Linux. If you are running Windows then see below <a href="#Mercurialinwindows">Using Mercurial/TortoiseHg in Windows</a>.
<p>Mercurial can be used from the command line, but if you prefer a GUI, TourtoiseHg is highly recommended on all OSes.</p>
<p>Linux: Install mercurial and tortoisehg-nautilus from synaptic,
then restart nautilus <tt>nautilus -q</tt>. If it works, you'll be able to see the menus of Tortoise within your Nautilus windows. </p>
then restart nautilus <tt>nautilus -q</tt>. If it works, you'll be able to see the menus of tortoise within your Nautilus windows. </p>
<p>Once you've downloaded and installed a client, the first step is to create what is called a checkout of the website. This creates a copy on your machine which you can edit to your heart's content. The command to initially check out ('clone') the entire expo website is:</p>
@ -154,13 +161,13 @@ then restart nautilus <tt>nautilus -q</tt>. If it works, you'll be able to see t
<p><tt>hg commit</tt> (you can specify filenames to be specific)</p>
<p>or right clicking on the folder and going to commit in TortoiseHG. Mercurial can't always work out who you are. If you see a message like "abort: no username supplied" it was probably not set up to deduce that from your environment. It's easiest to give it the info in a config file at ~/.hgrc (create it if it doesn't exist, or add these lines if it already does) containing something like</p>
<p>or right clicking on the folder and going to commit in TortoiseHg. Mercurial can't always work out who you are. If you see a message like "abort: no username supplied" it was probably not set up to deduce that from your environment. It's easiest to give it the info in a config file at ~/.hgrc (create it if it doesn't exist, or add these lines if it already does) containing something like</p>
<p><tt>
[ui]<br/>username = Firstname Lastname &lt;myemail@example.com&gt;
</tt></p>
<p>The commit has stored the changes in your local mercurial DVCS, but it has not sent anything back to the server. To do that you need to:</p>
<p>The commit has stored the changes in your local Mercurial DVCS, but it has not sent anything back to the server. To do that you need to:</p>
<p><tt>hg push</tt></p>
@ -172,17 +179,18 @@ then restart nautilus <tt>nautilus -q</tt>. If it works, you'll be able to see t
<p>Simple changes to static files will take effect immediately, but changes to dynamically-generated files (cave descriptions, QM lists etc) will not take effect, until the server runs the expoweb-update script.</p>
<h3><a id="mercurialinwindows">Using Mercurial/TortoiseHg in Windows</a></h3>
<h3><a id="Mercurialinwindows">Using Mercurial/TortoiseHg in Windows</a></h3>
<p>In Windows: install Mercurial and TortoiseHg of the relevant flavour from http://mercurial.selenic.com/downloads/ (ignoring antivirus/Windows warnings).</p>
<p>Read the instructions for setting up TortoiseHG in <a href="tortoise/tortoise-win.htm">Aled's Windows 101</a>.
<p>In Windows: install Mercurial and TortoiseHg of the relevant flavour from <a href="https://TortoiseHg.bitbucket.io/">https://TortoiseHg.bitbucket.io/</a> (ignoring antivirus/Windows warnings). This will install a submenu in your Programs menu)</p>
<p>To start cloning a repository: start TortoiseHg Workbench, click File -> Clone repository, a dialogue box will appear. In the Source box type</p>
<p>To start cloning a repository: first create the folders you need for the repositories you are going to use, e.g. D:\CUCC-Expo\loser and D:\CUCC-Expo\expoweb. Then start TortoiseHg Workbench from your Programs menu, click File -> Clone repository, a dialogue box will appear. In the Source box type</p>
<p><tt>ssh://expo@expo.survex.com/expoweb</tt></p>
<p>or similar for the other repositories. In the Destination box type whatever destination you want your local copies to live in. Hit Clone, and it should hopefully prompt you for the usual beery password.
<p>for expoweb (or similar for the other repositories). In the Destination box type whatever destination you want your local copies to live in on your laptop e.g. D:\CUCC-Expo\expoweb. Hit Clone, and it should hopefully prompt you for the usual beery password.
<p>The first time you do this it will probably not work as it does not recognise the server. Fix this by running putty, and connecting to the server 'expo@expo.survex.com' (on port 22). Confirm that this is the right server. If you succeed in getting a shell prompt then ssh connection are working and tortoisehg should be able to clone the repo, and send changes back.</p>
<p>The first time you do this it will probably not work as it does not recognise the server. Fix this by running putty (downloading it from <a href="https://www.chiark.greenend.org.uk/~sgtatham/putty/">https://www.chiark.greenend.org.uk/~sgtatham/putty/</a>), and connecting to the server 'expo@expo.survex.com' (on port 22). Confirm that this is the right server. If you succeed in getting a shell prompt then ssh connection are working and TortoiseHg should be able to clone the repo, and send changes back.</p>
<h3><a id="expowebupdate">The expoweb-update script</a></h3>
@ -245,17 +253,24 @@ T/U: Jess 1 hr, Emma 0.5 hr
</pre>
<hr>
<h3><a id="photos">Uploading photos</a></h3>
<h3><a id="photos">Uploading photos and GPS tracks</a></h3>
<p>Photos are stored in the general file area of the site under <a
href="http://expo.survex.com/expofiles/photos/">http://expo.survex.com/expofiles/photos/</a>
They are organised by year, and by photographer. Please use directory
href="http://expo.survex.com/expofiles/photos/">http://expo.survex.com/expofiles/photos/</a></p>
<p>GPS tracks over the surface of the plateau (GPX files from your handheld GPS or phone) are stored in the general file area of the site under <a
href="http://expo.survex.com/expofiles/gpslogs/">http://expo.survex.com/expofiles/gpslogs/</a></p>
<p>
They are each organised by year, and by photographer (walker). Please use directory
names like 2014/YourName (i.e no spaces, CamelCase for names).</p>
<p>They are viewed at <a
href="http://expo.survex.com/photos/">http://expo.survex.com/photos/</a></p>
href="http://expo.survex.com/photos/">http://expo.survex.com/photos/</a><br />
or<br />
<a href="http://expo.survex.com/gpslogs/">http://expo.survex.com/gpslogs/</a><br />
</p>
<p>Photos can be uploaded in 2 basic ways:
<p>Photos and GPS tracks can be uploaded in 2 basic ways:
<ol>
<li>Rsync,scp,sftp as user 'expo' to expo.survex.com, into the directory expofiles/photos/&lt;year&gt;/&lt;PhotographerName&gt;</li>
<li>Webdav upload to special dir http://expo.survex.com/expofiles/uploads/&lt;year&gt;/&lt;PhotographerName&gt;</li>
@ -314,7 +329,7 @@ http://expo.survex.com/expo/surveys/surveytable.html http://expo.survex.com/surv
<p>Mercurial is a distributed revision control system. On expo this means that many people can edit and merge their changes with each other either when they can access the internet. Mercurial 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.</p>
<h2>The website conventions bit</h2>
<p>This is likely to change with structural change to the site, with style changes which we expect to implement and with the method by which the info is actually stored and served up.</p>
@ -329,6 +344,13 @@ http://expo.survex.com/expo/surveys/surveytable.html http://expo.survex.com/surv
<li>Style guide for writing cave descriptions: correct use of boldface (<em>once</em> for each passage name, at the primary definition thereof; other uses of the name should be links to this, and certainly should not be bold.) </li>
</ul>
<hr />
<h2><a id="mercurial">Mercurial and TortoiseHG</a></h2>
<p>Mercurial is a distributed revision control system. On expo this means that many people can edit and merge their changes with the Mercurial server in the Tatty Hut even if there is no Internet access. Also anyone who is up to date with the Tatty Hut can take their laptop somewhere where there is Internet access and update expo.survex.com - which will then get all the updates done by everyone on expo.
</p>
<p>In principle, survey notes can be typed into a laptop up on the plateau which is then synchronised with the Tatty Hut on returning to base.
</p>
<p>Mercurial 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'.</p>
<hr />
</body>
</html>

View File

@ -7,9 +7,9 @@
</head>
<body>
<h2 id="tophead">CUCC Expedition Handbook</h2>
<h1>Uploading photos and files</h1>
<h1>Uploading photos, GPS tracks and files</h1>
<p>The expo website has a big section under 'expofiles' that is not part of the repositories. This section describes how to move files into that area. It supports 2 basic methods of upload:
<p>The expo website has a big section under 'expofiles' that is not part of the version control repositories. This section describes how to move files into that area. It supports 2 basic methods of upload:
<ol>
<li>Uploading directly to the file store using scp/sftp/rsync</li>
<li>Uploading to a special 'uploads' directory using Webdav</li>
@ -58,18 +58,26 @@ on the centre of the screen.</li>
<h2>Using scp</h2>
<p>Works on Windows (using winscp), Linux (using scp), and no doubt
mac and android with other tools.</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 bash</a>, then you can use scp.</p>
<p>The above FireFTP is just one example of a tool that does this job</p>
<pre>
directory: /home/expo/expofiles/photos/2015/YourName
directory: /home/expo/expofiles/photos/2017/YourName
server: expo.survex.com
user: expo
with the usual expo password
protocol: sftp or scp
</pre>
Or for GPS tracks, do
<pre>
directory: /home/expo/expofiles/gpslogs/2017/YourName
server: expo.survex.com
user: expo
with the usual expo password
protocol: sftp or scp
</pre>
<p>Obviously replace 'YourName' with your actual name (no spaces!)</p>
<p>If you don't have winscp installed you can get it from here: