diff --git a/handbook/computing/basiclaptop.html b/handbook/computing/basiclaptop.html new file mode 100644 index 000000000..2d0d1e8f1 --- /dev/null +++ b/handbook/computing/basiclaptop.html @@ -0,0 +1,73 @@ +<!DOCTYPE html> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<title>CUCC Expedition Handbook: Programmers manual</title> +<link rel="stylesheet" type="text/css" href="../../css/main2.css" /> +</head> +<body> +<h2 id="tophead">CUCC Expedition Handbook - Minimal laptop</h2> + +<h1>Setting up a minimal machine to work with Expo data</h1> + +<h2>Overview</h2> + +<p>You need to do this:</p> +<ol> + <li><a href="#configuration">Register an SSH key</a> with an expo nerd (i.e 'get a login').</li> + <li>Install <a href="#software">git version control software</a> to download ("clone"), view and edit caving data.</li> + <li>Clone three <a href="../manual.html#repositories">expo repositories</a> so you have the files on your machine.</li> + <li>Install survex, and therion or tunnel for editing cave data. +</ol> + +<p>Once you have got this working, and if it doesn't do what you want or you don't understand how to use it, +look at the <a href="yourlaptop.html">full laptop configuration</a> for everything else. +And please <b>write some documentation for the next person</b> in your situation. + +<h3>Cheat lists and quick reminders</h3> +<ul> +<li>Quick <a href="qstart-git.html">reminders for using git</a> at the command line. +<li>Quick <a href="../manual.html#quickstart">reminders for using rsync</a> at the command line. +</ul> + +<h2 id="software">Software</h2> +<p>Download this software (short list): +<ul> +<li><a href="https://git-scm.com/">git</a> - version control system</li> +<li><a href="https://survex.com/download.html">Survex</a>, including the Aven visualisation tool. +<li><a href="https://github.com/CaveSurveying/tunnelx">Tunnel</a>: 2.5D cave drawing program based on Survex-compatible data which can also read PocketTopo files. (Generally called 'tunnel' even though the project and executable is actually 'tunnelx'.) +<li><a href="https://therion.speleo.sk/">Therion</a> - Therion processes survey data and generates maps or 3D models of caves. +</ul> + +<h2 id="configuration">Configuration</h2> + +<p>Follow this link to <a href="keyexchange.html">register a key with the expo server</a> to get upload (i.e. read/write) access. +Do this first, Without it none of git, mercurial, scp, ftp or rsync will work. + +<p>On a Windows machine you will need to configure pageant (the putty authentication agent) +to <a href="https://blog.shvetsov.com/2010/03/making-pageant-automatically-load-keys.html">run at startup to load your key</a>. +Note that you are loading your <em>private</em> key, the .ppk file, into pageant and that this key never leaves your laptop.</p> + +<ul> + +<li><a href="../tortoise/tortoise-win.htm">Installing PuTTy</a>.</li> +<li><a href="winlaptop.html#hard">A Windows laptop for expo</a> - PuTTy and WSL here.</li> +</ul> +<p>When using Windows please, please be <a href="http://expo.survex.com/handbook/survey/getin.htm#filenames">excessively +careful when naming files and survex names</a> and be <a href="../manual.html#quickstart">exceptionally careful when using rsync</a>. + +<h3>Learning how to use this software</h3> + +<ul> +<li>Using Survex, Tunnel and Therion, see the <a href="http://expo.survex.com/handbook/survey/">Expo Handbook - Surveying section</a>. +<li>For more detailed configuration, explanations and help see the <a href="yourlaptop.html#configuration">full laptop</a> instructions +</ul> + + + + + +<hr /> + +</body> +</html> diff --git a/handbook/computing/qstart-git.html b/handbook/computing/qstart-git.html new file mode 100644 index 000000000..06f4212d7 --- /dev/null +++ b/handbook/computing/qstart-git.html @@ -0,0 +1,75 @@ +<!DOCTYPE html> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<title>Handbook placeholder page</title> +<link rel="stylesheet" type="text/css" href="../../css/main2.css" /> +</head> +<body> +<h2 id="tophead">CUCC Expedition Handbook - Git Quick</h2> + +<h1>Quick Reminder - Git</h1> +<h2>Version Control Software Reminders</h2> +<p>This is NOT a tutorial. This is a set of reminders for people who already know all this stuff. + +<p>Since 2019 all use of version control software requires that you +have <a href="keyexchange.html">key-pair setup</a> already set up before any of this will work on your own machine. + +<p><font style="font-size: big; color:red"><b>NOT CHECKED _ TO BE EDITED BY A git NERD TO MAKE IT WORK. DO NOT DO THIS UNTIL THAT HAS BEEN DONE</b> +- check that you can get ssh working before trying to run git too</font> + +<p>If you can get to the <i>expo laptop</i> try these commands on that first as the key exchange has already been done. +<dl> + <dt>expoweb (The data management system)</dt> + <dd> + <tt>git clone ssh://expo@expo.survex.com/expoweb</tt> (read/write)<br /> + <tt>git clone http://expo.survex.com/repositories/home/expo/expoweb/</tt> (read-only checkout) + </dd> + + <dt>troggle (The data management system backend)</dt> + <dd> + <tt>git clone ssh://expo@expo.survex.com/troggle</tt> (read/write)<br /> + <tt>git clone http://expo.survex.com/repositories/home/expo/troggle/</tt> (read-only checkout) + </dd> + + <dt>loser (The survey data)</dt> + <dd> + <tt>git clone ssh://expo@expo.survex.com/loser</tt> (read/write)<br /> + <tt>git clone http://expo.survex.com/repositories/home/expo/loser/</tt> (read-only) + </dd> + + <dt>drawings</dt> + <dd> + <tt>git clone ssh://expo@expo.survex.com/drawings</tt> (read/write)<br /> + <tt>git clone http://expo.survex.com/repositories/home/expo/drawings/</tt> (read-only) + </dd> +</dl> +<h3><a id="gitwindows">Using git in Windows</a></h3> + + +<p>Once you've downloaded and installed a git client, the first step is to create what is called a checkout of the data management system. 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 data management system is:</p> + +<p><tt>git clone ssh://expo@expo.survex.com/expoweb</tt></p> + +<p>for subsequent updates</p> + +<p><tt>git update</tt></p> + +<p>will generally do the trick.</p> + +<p><tt>ssh://expo@expo.survex.com/expoweb</tt></p> + +<p>After you've made a change, commit it to you local copy with:</p> + +<p><tt>git commit</tt> (you can specify filenames to be specific)</p> + +<p>The first time you do this on a Windows machineit 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 git should be able to clone the repo, and send changes back.</p> + + +<hr /> +</ul> +</div> +</body> +</html> diff --git a/handbook/computing/qstart-hg.html b/handbook/computing/qstart-hg.html index 6297c0ce2..42ddeddcd 100644 --- a/handbook/computing/qstart-hg.html +++ b/handbook/computing/qstart-hg.html @@ -35,10 +35,10 @@ have <a href="keyexchange.html">key-pair setup</a> already set up before any of <tt>hg clone http://expo.survex.com/repositories/home/expo/loser/</tt> (read-only) </dd> - <dt>tunneldata (The Tunnel drawings)</dt> + <dt>drawings</dt> <dd> - <tt>hg clone ssh://expo@expo.survex.com/tunneldata</tt> (read/write)<br /> - <tt>hg clone http://expo.survex.com/repositories/home/expo/expoweb/</tt> (read-only) + <tt>hg clone ssh://expo@expo.survex.com/drawings</tt> (read/write)<br /> + <tt>hg clone http://expo.survex.com/repositories/home/expo/drawings/</tt> (read-only) </dd> </dl> <h3><a id="Mercurialinwindows">Using Mercurial/TortoiseHg in Windows</a></h3> @@ -84,13 +84,6 @@ then restart nautilus <tt>nautilus -q</tt>. If it works, you'll be able to see t <hr /> - -<div id="menu"> -<ul id="links"> -<li><a href="index.htm">Expedition Handbook</a> -</li> -<li><a href="../../infodx.htm">Main index</a></li> - </ul> </div> </body> diff --git a/handbook/computing/yourlaptop.html b/handbook/computing/yourlaptop.html index 2ad4471f5..ce70c3f02 100644 --- a/handbook/computing/yourlaptop.html +++ b/handbook/computing/yourlaptop.html @@ -176,12 +176,5 @@ a wiki on github discussing workflows to generate centerlines, GEOTIFF and QGIS <hr /> -<div id="menu"> -<ul id="links"> -<li><a href="../index.htm">Handbook</a> - -<li><a href="../../infodx.htm">Main index</a></li> -</ul> -</div> </body> </html> diff --git a/handbook/index.htm b/handbook/index.htm index 998e24ace..df7260d89 100644 --- a/handbook/index.htm +++ b/handbook/index.htm @@ -53,7 +53,8 @@ This is a scientific expedition - the Austrian government allows us to wander ar <li><a href="survey/newcave.html">Recording newly found caves</a> - What and how to record. (important!)</li> <li><a href="logbooks.html">Logbook</a> - Adding trip notes and cave descriptions.</li> - <li><a href="computing/yourlaptop.html">Configuring a new laptop</a> - Experts only: software and configuration.</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> diff --git a/handbook/manual.html b/handbook/manual.html index d98da954d..8d9ae6c95 100644 --- a/handbook/manual.html +++ b/handbook/manual.html @@ -130,7 +130,8 @@ complicated process. At a minimum you will be an experienced software nerd alrea You will have done the <a href="computing/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="computing/yourlaptop.html">setting up your own laptop</a> for the full list of software we use and where to get it. +<p>See <a href="computing/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="computing/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. @@ -209,31 +210,21 @@ see if you are logged into troggle. In general the dynamically-generated pages, 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> -<p><tt> -[ui]<br/>username = Firstname Lastname <myemail@example.com> -</tt></p> +<h3>Cheat lists and quick reminders</h3> +<ul> +<li>Quick <a href="computing/qstart-git.html">reminders for using git</a> at the command line. +<li>Quick <a href="computing/qstart-hg.html">reminders for using mercurial</a> at the command line. +<li>Quick <a href="../manual.html#quickstart">reminders for using rsync</a> at the command line. +</ul> -<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>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> -<p><tt>hg push</tt></p> +<h3><a id="expowebupdate">The expoweb & drawings import scripts</a></h3> -<p>Before pushing, you should do an <tt>hg pull</tt> to sync with upstream first. If someone else has edited the same files you may also need to do:</p> - -<p><tt>hg merge</tt></p> - -<p>(and sort out any conflicts if you've both edited the same file) before pushing again</p> - -<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="expowebupdate">The expoweb-update script</a></h3> - -<p>The script at the heart of the data management system update mechanism is a makefile that runs the various generation scripts. It is run every 15 minutes as a cron job (at 0,15,30 and 45 past the hour), but if you want to force an update more quickly you can run it he</p> - -<p>The scripts are generally under the 'noinfo' section of the site just because that has (had) some access control. This will get changed to something more sensible at some point</p> +<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> @@ -243,7 +234,9 @@ cave files in noinfo/cave_data/ and noinfo/entrance_data/. These files are named <area>-<cavenumber>.html (where area is 1623 or 1626). These files are processed by troggle. Use <tt>python databaseReset.py caves</tt> in /expofiles/troggle/ to update the site/database after -editing these files.</p> +editing these files. +Use <tt>python databaseReset.py +</tt> on its own to get a list of command options and brief explanations.</p> <p>Clicking on 'New cave' (at the bottom of the cave index) lets you enter a new cave. <a href="caveentry.html">Info on how to enter new caves has been split into its own page</a>.</p> @@ -258,7 +251,9 @@ superseded in 2012).</p> <tt>/expoweb/years/</tt> -<p>which contains a number of files used to manage and record that year's expo. Have a look at expoweb/years/2018/ for a recent well-documented expo (the weather was good). Files are added and edited using the version control system for the expoweb repository.</p> +<p>which contains a number of files used to manage and record that year's expo. Have a look at +expoweb/years/2018/ for a recent well-documented expo (the weather was good). +Files are added and edited using the version control system for the expoweb repository.</p> <p>To create a new 'year' for next year's expo see <a href="computing/newyear.html">adding a new year</a>. @@ -267,13 +262,6 @@ superseded in 2012).</p> <h3><a id="surveystatus">Maintaining the survey status table</a></h3> <p>See the <a href="survey/onlinewallet.html">documentation</a> on updating the online surveyscans folders using the lever-arch file of plastic wallets. -<p> This below is obsolete: -<ul> -<li>There was a table in the survey book which has a list of all the surveys and whether or not they have been drawn up, and some other info. - -<li>This used to be generated by the script tablizebyname-csv.pl from the input file Surveys.csv -</ul> - <h3><a id="menu">Cave pages and handbook menu design</a></h3> <p>See the <a href="computing/menudesign.html">menu design history and proposals</a> page on where we are and what we might do to improveand fix menus. diff --git a/handbook/tortoise/tortoise-win.htm b/handbook/tortoise/tortoise-win.htm index 3e467ab43..b37040e02 100644 --- a/handbook/tortoise/tortoise-win.htm +++ b/handbook/tortoise/tortoise-win.htm @@ -11,6 +11,7 @@ <body> <h1>Windows: TortoiseHg and PuTTy</h1> +<p> THIS ARTICLE TO BE SPLIT - PuTTy STUFF VALID BUT Hg SHORTLY TO BE OBSOLETE</p? <p>Struggling to get TortoiseHg to work on Windows (v10)? Here’s a quick guide which I hope explains how to sort it all out.</p>