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.
The website needs improvement, perhaps a complete overhaul. However, it is impossible to go about fixing it properly until we know how the whole thing works.
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.
Contents
How to update things on cucc.survex.com
Getting a username and password
Contact Wookey or Julian Todd
Version control
No changes should be made directly to any files on the server. Instead, we use a version control system to allow collaborative editing and so that any changes can be rolled back if necessary. That system is mercurial (the command is 'hg'), which is a distributed VCS.
To edit the website, you need a mercurial client. If you are using windows, [1] is highly recommended. Once you've downloaded and installed it, 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 check out the entire expo website is
svn co svn+ssh://cucc.survex.com/home/cucc/svn/trunk/expoweb
In TortoiseSVN, merely right-click on a folder you want to check out to, choose "SVN checkout," and enter
svn+ssh://cucc.survex.com/home/cucc/svn/trunk/expoweb
After you've made your changes, check them back in using
svn ci
or right clicking on the folder and going to check in in TortoiseSVN.
None of your changes will take effect, however, until you've run the expoweb-update script.
The expoweb-update script
The script at the heart of the website update mechanism is a shell script at
/cucc.survex.com/home/cucc/bin/expoweb-update
To run scripts on the server, you need to log in via SSH. The best way to do this in windows is to download PuTTY.
Updating cave pages
Cave description pages are automatically generated from a comma separated values (CSV) table named CAVETAB2.CSV by a perl script called make-indxal4.pl . make-indxal4.pl is called automatically.
The first step is to check out, edit, and check in CAVETAB2.CSV, which is at
/home/cucc/www/expo/noinfo/CAVETAB2.CSV
You need to be somewhat careful with the formatting; each cell needs to be only one line long (i.e. no newlines) or the script will get confused.
And then run expoweb-update as above.
Updating expo year pages
Each year's expo has a documentation index which is in the folder
/home/cucc/www/expo/years
, so to checkout the 2007 page, for example, you would use
svn co svn+ssh://cucc.survex.com/home/cucc/svn/trunk/expoweb/years/2007
Adding typed logbooks
To be written.
Ticking off QMs
To be written.
Maintaining the survey status table
At [2] 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.
This is generated by the script /home/cucc/www/tablizebyname-csv.pl from the input file /home/cucc/www/Surveys.csv
History
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 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.
Martin Green added the SURVTAB.CSV file to contain tabulated data for many caves, and a script to generate the index pages from it. Dave Loeffler added scripts and programs to generate the prospecting maps. The server moved to Mark Shinwell's machine in the early 2000s, and the VCS was updated to subversion.
After expo 2009 the VCS was updated to hg, because a DVCS makes a great deal of sense for expo. The site was moved to Julian Todd's seagrass server, but the change from 32-bit to 64-bit machines broke the website autogeneration code, which was only fixed in early 2011, allowing the move to complete. The data has been split into 3 separate repositories: the website, the survey data, the tunnel data.
Automation on cucc.survex.com/expo
The way things normally work, python or perl scripts turn CSV input into HTML for the website. Note that:
- The CSV files are actually tab-separated, not comma-separated despite the extension.
- The scripts can be very picky and editing the CSVs with microsoft excel has broken them in the past- not sure if this is still the case.
| Script location | Input file | Output file | Purpose |
|---|---|---|---|
| /svn/trunk/expoweb/noinfo/make-indxal4.pl | /svn/trunk/expoweb/noinfo/CAVETAB2.CSV | many | produces all cave description pages |
| /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 |
|
/svn/trunk/surveys/tablize-csv.pl /svn/trunk/surveys/tablizebyname-csv.pl |
/svn/trunk/surveys/Surveys.csv |
http://cucc.survex.com/expo/surveys/surveytable.html http://cucc.survex.com/expo/surveys/surtabnam.html |
Survey status page: "wall of shame" to keep track of who still needs to draw which surveys |
| Prospecting guide | |||
Website mysteries
The following are questions for people who know the expo website well, which stumped Aaron.
- Why is there a /home/cucc/www/expo/surveys as well as a /home/cucc/www/surveys , and is there any difference?