<p>The website is now large and complicated with a lot (too many!) of 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>
<ul>
<li><ahref="#update">Updating the website</a></li>
<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>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>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>
<h2>Expo website manual</h2>
<p>Editing the expo website is an adventure. Until now, there was no guide which explains the whole thing as a functioning system. Learning it by trial and error is non-trivial. There are lots of things we could improve about the system, and anyone with some computer nous is very welcome to muck in. It is slowly getting better organised</p>
<p>This manual is organized in a how-to sort of style. The categories, rather than referring to specific elements of the website, refer to processes that a maintainer would want to do.</p>
<h3>Contents</h3>
<ol>
<li><ahref="#usernamepassword">Getting a username and password</a></li>
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>
<h3><aid="howitworks">How the website works</a></h3>
<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>
<h3><aid="quickstart">Quick start</a></h3>
<p>If you know what you are doing here is the basic info on what's where:</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!)</p>
<h3><aid="editingthewebsite">Editing the website</a></h3>
<p>To edit the website, you need a mercurial client. If you are using Windows, [1] is highly recommended. Lots of tools for Linux and mac exist too [2], both GUI and command-line:</p>
<p>Once you've downloaded and installed a client, the first step is to create what is called a checkout of the website or section of the website which you want to work on. 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>
<p>After you've made a change, commit it to you local copy with:</p>
<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 TortoiseSVN.</p>
<p>That 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>
<p>If someone else is editing the same bit at the same time you may also need to:</p>
<p><tt>hg merge</tt></p>
<p>None of your changes will take effect, however, until the server checks out your changes and runs the expoweb-update script.</p>
<h3><aid="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>To start cloning a repository: start TortoiseHg Workbench, click File -> Clone repository, a dialogue box will appear. In the Source box type</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. (to be continued) --Zucca 14:25, 25 January 2012 (UTC)</p>
<p>The script at the heart of the website update mechanism is a makefile that runs the various generation scripts. It (along with an update from the repository) 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 here: [Wooknote - this is</p>
<p>The scripts are generally under the 'noinfo' section of the site just because that has some access control. This will get changed to something more sensible at some point</p>
<p>Logbooks are typed up and put under the years/nnnn/ directory as 'logbook.html'.</p>
<p>Do whatever you like to try and represent the logbook in html. The only rigid structure is the markup to allow troggle to parse the files into 'trips':</p>
<p>Older logbooks (prior to 2007) were stored as logbook.txt with just a bit of consistent markup to allow troggle parsing.</p>
<p>The formatting was largely freeform, with a bit of markup ('===' around header, bars separating date, <place> - <description>, and who) which allows the troggle import script to read it correctly. The underlines show who wrote the entry. There is also a format for time-underground info so it can be automagically tabulated.</p>
<p>So the format should be:</p>
<p><tt>===2009-07-21|204 - Rigging entrance series| Becka Lawson, Emma Wilson, Jess Stirrups, Tony Rooke===</tt></p>
<h3><aid="surveystatus">Maintaining the survey status table</a></h3>
<p>At [3] there is a table which has a list of all the surveys and whether or not they have been drawn up, and some other info.</p>
<p>This is generated by the script tablizebyname-csv.pl from the input file Surveys.csv</p>
<h3><aid="history">History</a></h3>
<p>The CUCC Website was originally created by Andy Waddington in the early 1990s and was hosted by Wookey. The VCS was CVS. The whole site was just static HTML, carefully designed to be RISCOS-compatible (hence the short 10-character filenames) as both Wadders and Wookey were RISCOS people then. Wadders wrote a huge amount of info collecting expo history, photos, cave data etc.</p>
<p>Martin Green added the SURVTAB.CSV file to contain tabulated data for many caves around 1999, and a script to generate the index pages from it. Dave Loeffler added scripts and programs to generate the prospecting maps in 2004. The server moved to Mark Shinwell's machine in the early 2000s, and the VCS was updated to subversion.</p>
<p>In 2006 Aaron Curtis decided that a more modern set of generated, database-based pages made sense, and so wrote Troggle. This uses Django to generate pages. This reads in all the logbooks and surveys and provides a nice way to access them, and enter new data. It was separate for a while until Martin Green added code to merge the old static pages and new troggle dynamic pages into the same site. Work on Troggle still continues sporadically.</p>
<p>After expo 2009 the VCS was updated to hg, because a DVCS makes a great deal of sense for expo (where it goes offline for a month or two and nearly all the year's edits happen).</p>
</br>/svn/trunk/expoweb/noinfo/make-folklist.py /svn/trunk/expoweb/noinfo/folk.csv http://cucc.survex.com/expo/folk/index.htm Table of all expo members
<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 over the top for scanned survey notes, which do not get modified, so they are kept as a plain directory of files.</p>
<p>If you run windows, you are recommended to install <ahref="http://bitbucket.org/tortoisehg/stable/wiki/Home">Tortoise Hg</a>, which nicely interfaces with windows explorer.</p>
<p>Install<ahref="http://bitbucket.org/tortoisehg/stable/wiki/Home">Tortoise Hg</a>. In windows explorer right click, select Tortoise Hg .. and click Clone repository. <br/>Set the source path to RepositoryURL <br/>Set the destination to somewhere on your local harddisk. <br/>Press clone.</p>
<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>
<li>Info for each cave – automatically generated by <tt>make-indxal4.pl</tt></li>
<li>Contents lists & relative links for multi-article publications like journals. Complicated by expo articles being in a separate hierarchy.</li>
<li>Translations</li>
<li>Other people's work - the noinfo hierarchy.</li>
<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>
