mirror of
https://expo.survex.com/repositories/expoweb/.git/
synced 2024-11-25 16:52:00 +00:00
366 lines
17 KiB
HTML
366 lines
17 KiB
HTML
<!DOCTYPE html PUBLIC "-//IETF//DTD HTML 3.0//EN">
|
|
<html lang="en">
|
|
<head>
|
|
<title>CUCC Expedition Handbook - Updating</title>
|
|
</head>
|
|
<body>
|
|
<H1>Updating the website - HOWTO
|
|
</H1>
|
|
<H2>Rationale for having a system at all:
|
|
</H2>
|
|
<P>For years, the website has been built by hand-editing html pages,
|
|
"traditionally" by one or two people, in constant email contact. Obviously
|
|
those people were thoroughly familiar with the locations of all the pages,
|
|
the conventions used for naming files, the style used throughout the site and
|
|
a few conventions for adding things which made the site easier to maintain.
|
|
There are also a few odd tools written to hack from one format (such as a
|
|
scanned journal page) to another which those users were happy with (but which
|
|
may not be useful for anyone else - typically written in BBC Basic on an
|
|
Acorn machine :-). The survey dataset was maintained in much the same way,
|
|
though a lot more of that work was done actually on expedition, and therefore
|
|
by a lot more people.</p>
|
|
|
|
<p>This work becomes quite onerous when neither of the two usual maintainers
|
|
went on expo this year, and in any case, it is usually far better for the
|
|
people who actually explored the cave to integrate their stuff into the
|
|
existing cave descriptions. To make this easier (indeed, possible !), both
|
|
the web pages and the survey data are now held in a CVS repository, which
|
|
means lots of people can edit different parts (even different parts of the
|
|
same file) at the same time without causing chaos, and a record is kept of
|
|
who changed what, and why.
|
|
|
|
<p>This how-to guide is split into two parts - one for those who have never used
|
|
CVS before, and one for everyone, outlining the structure of the site and the
|
|
few conventions used within it. It is still possible for you to contribute to
|
|
the updating of the site without learning CVS, by sending changes or fault
|
|
reports (as plain text) to one of the regular maintainers - it is not one of
|
|
the aims of this system to exclude non-computer-nerds, just to reduce the
|
|
computer-nerds' workload :-)
|
|
|
|
<H2>The CVS bit</H2>
|
|
|
|
<!-- Written 2001-10-08 to 2001-10-12, Andy Waddington -->
|
|
|
|
<p>This bit should not change significantly with structural change to the
|
|
website (such as serving it all via PHP from a database). I hope it is all
|
|
clear - it was written in parallel with my own learning how to use CVS. It
|
|
may be verbose, but I hope that writing it this way means that it is low on
|
|
omissions.
|
|
|
|
<H3>CVS Rationale:</H3>
|
|
|
|
<p>The problem with having more than one or two people do the work is that it
|
|
generates increasing amounts of email to ensure that people don't update old
|
|
versions of pages, and throw away someone else's recent work. The solution to
|
|
all this is to put the entire site into a system called "Concurrent Version
|
|
System" under which lots of people can make changes, all of which are safely
|
|
merged together without losing any changes. Just occasionally, the system
|
|
will detect that two people have changed the same bit of text in conflicting
|
|
ways, and it is then up to them to sort it out, but this is a great
|
|
improvement over what has gone before.
|
|
|
|
<H3>How does it work ?</H3>
|
|
|
|
<p>There is a central CVS repository, from which someone needing to do updates
|
|
can "check out" a copy of the page they want to change. They then make the
|
|
changes or additions required, and "commit" the new page back into the
|
|
system. The system keeps a record of all such changes, with a log message
|
|
in which you should say why the change was made (the system knows who you
|
|
are and when you commited the change, so you don't need to tell it that).
|
|
|
|
<p>In order to join in the work, the central CVS repository needs to know
|
|
about you, so it can allow you to commit changes into the system (and thus
|
|
to stop random hackers replacing cave surveys with redirects to a porn
|
|
site, or whatever).
|
|
|
|
<H2>Becoming a website updater</H2>
|
|
|
|
<H3>Software requirements</H3>
|
|
|
|
<p>You need a system which has a CVS client and supports SSL, so that you can
|
|
log in without sending a password in clear text over the internet. You need
|
|
an editor with which you are happy to edit web pages. Ideally this will
|
|
NOT be one of the commercial WYSIWYG web editors which add whole loads of
|
|
guff to your webpage in a manner that you don't see (and which, incidentally,
|
|
makes the pages vastly harder to maintain for the next person who comes
|
|
along with a basic html editor, not to mention making the pages load more
|
|
slowly and typically work in fewer browsers). Most of us use basic
|
|
text editors with extensions that make editing html easier. The easiest
|
|
way to get all this is to have a Linux machine, since most distributions
|
|
have all the tools you need ready built in. The rest of this page assumes
|
|
that you are doing all this on a recent Linux system. There are a few
|
|
useful links for those using Mac, RISC OS or even Windows machines along
|
|
with the links to more detailed documentation <a href="#links">at the end of
|
|
this page.</a> The cvs machine itself is a Linux box, and some of the
|
|
commands you need to use involve typing at the command line on that machine,
|
|
so some familiarity with Unix/Linux will make you feel more at home.
|
|
|
|
<p>The CVS repository is on a machine called cvs.survex.com, so you need to get
|
|
(from Mark Shinwell, at present) a username and password. If you are told
|
|
these via email, the first thing you will need to do is change the password,
|
|
using ssh:<br>
|
|
|
|
<TT>ssh <username>@cvs.survex.com passwd</TT>
|
|
|
|
<p>this is three parts "ssh" says to open an SSL connection
|
|
"<username>@cvs.survex.com" says which user on what machine to connect to
|
|
"passwd" is the command you are going to execute on that machine, as that user,
|
|
in this case a command to change your password.
|
|
|
|
<p>this will ask for the existing password to open the connection to the cvs
|
|
machine (this allows the "ssh <username>@cvs.survex.com" to happen), then
|
|
ask for it again (to validate the passwd command). Then you need to type
|
|
your new password twice (second time to confirm that you really typed what
|
|
you thought the first time), and should then tell you that the password was
|
|
updated OK. You will need a password made up of mixed uppercase and
|
|
lowercase letters, digits and punctuation, and not apparently based on any
|
|
dictionary word. This will make it a real pain to remember and type, but we
|
|
get round that in the next step:
|
|
|
|
<p>Generate a public/private keypair to do authentication automatically.
|
|
With recent versions of openssh, you need to type<br>
|
|
|
|
<TT>ssh-keygen -t dsa</TT>
|
|
|
|
<p>doeswith older versions, you may find that "-t" is not a valid option, in
|
|
which case<br>
|
|
|
|
<TT>ssh-keygen -d
|
|
</TT>
|
|
<p>does the same thing. Either way, it will suggest a place to store the
|
|
keypair (~/.ssh/id-dsa) which you should accept. This needs to be kept
|
|
secure (so don't generate the keypair and keep it on a publically
|
|
accessible machine, for example).
|
|
|
|
<p>We want to force ssh to use protocol 2, but in a typical distribution,
|
|
it tries protocol 1 first - this will oblige you to type your password
|
|
every time, which is a pain. You can change this globally, for everyone,
|
|
by altering /etc/ssh/ssh_config but it is probably best to alter it for
|
|
just the user you will be when doing the CVS commands. Create a file
|
|
~/.ssh/config containing the lines<br>
|
|
|
|
<TT># Make sure we use protocol 2 to avoid tedious password typing:<br>
|
|
Host cvs.survex.com<br>
|
|
Protocol 2</TT>
|
|
|
|
<p>Now copy the public key to the server. One thing that might trip you up is
|
|
that the directory ~/.ssh may not exist on the remote machine. To create it
|
|
and copy the key:<br>
|
|
|
|
<TT>ssh <username>@cvs.survex.com mkdir ~/.ssh<br>
|
|
scp ~/.ssh/id_dsa.pub <username>@cvs.survex.com:.ssh/authorized_keys2<br>
|
|
</TT>
|
|
<p>(note the nasty American spelling here - easy to mistype if you're English)-:
|
|
Those commands will ask for your password again, but that should be the last
|
|
time you'll need to enter it on that machine. Having done all that, you
|
|
should now be able to do<br>
|
|
|
|
<TT>ssh cvs.survex.com</TT>
|
|
|
|
<p>without being asked for a password. That would get you a command line to do
|
|
things on the cvs machine, but for most jobs, you only need to do CVS
|
|
commands on your own machine, so get out of that command line with<br>
|
|
|
|
<tt>exit</tt>
|
|
|
|
<p>To use the CVS commands on your local machine (for checking out pages
|
|
to edit and commiting them back) you need to tell cvs where the archive
|
|
is. You can include a "-d <username>@cvs.survex.com:/export/cvs" with
|
|
cvs commands (useful if you use cvs on more than one repository), but
|
|
it is usually easier to add<br>
|
|
|
|
<TT>export CVSROOT=<username>@cvs.survex.com:/export/cvs</TT>
|
|
|
|
<p>to some script that will be executed before you want to use cvs. Easiest
|
|
would usually be ~/.bashrc (assuming your default shell is bash). Also
|
|
add<br>
|
|
|
|
<TT>export CVS_RSH=ssh</TT>
|
|
|
|
<p>You are now ready to get a copy of the page(s) you want to edit. If you
|
|
don't have a copy of the site on CD, it may be easiest to download the
|
|
whole site - having the other pages for context makes life much easier
|
|
if you are maintaining links between pages. Move into a local directory
|
|
where you will edit the pages, I use a tree in my own home directory,
|
|
which, for historical reasons, is called chaos, but you can choose any
|
|
directory where you will have the write-access needed to edit pages:<br>
|
|
|
|
<TT>cd ~/chaos</TT><br>
|
|
|
|
<TT>cvs checkout expo-www</TT>
|
|
|
|
<p>and then move into the directory tree to make your changes. Thus far,
|
|
everything has been at the command line, but often doing the editing
|
|
will be more convenient through a desktop interface. You might find that
|
|
you want to set your file browser *not* to display an html view of the
|
|
files, otherwise you will end up browsing the pages, rather than the
|
|
file tree, which makes editing much harder :-(
|
|
|
|
<p>When you have made your changes, you need to check that no-one else
|
|
has changed things in a way which clashes. Its also a good idea to
|
|
keep your own copies of the pages as up-to-date as possible, so at
|
|
the top level of your copy ( ~/chaos in my case ):<br>
|
|
|
|
<TT>cvs update</TT>
|
|
|
|
<p>If you are unlucky (most likely if you made changes a long time after you
|
|
last ran update) this will tell you about conflicts which you'll need to
|
|
resolve with the other person(s) who made changes. Make sure you do
|
|
resolve these changes, since just committing your version throws away
|
|
the other person's changes from the current version (CVS keeps a record
|
|
of all the changes, so they can be recovered, but it is easier and much
|
|
more polite to resolve the problem through dialogue). Once all is OK<br>
|
|
|
|
<TT>cvs commit</TT>
|
|
|
|
<p>If you are updating the whole tree like this, it is a good idea to make
|
|
sure you get any new directories and remove any old ones (which doesn't
|
|
happen by default). To do this specify<br>
|
|
|
|
<TT>cvs update -Pd</TT>
|
|
|
|
<p>You can just update one subdirectory (and everything under it) or an
|
|
individual file by adding its name to the end of the command, such as<br>
|
|
|
|
<TT>cvs update expo/smkridge/161</TT><br>
|
|
<TT>cvs commit expo/smkridge/161/france.htm</TT>
|
|
|
|
<p>if you create a new page, lets say for a description of a new cave on
|
|
the plateau, 1623/505, it would probably be called 505.htm in the
|
|
plateau subdir. "cvs commit" will not work on files that cvs does not
|
|
know about, so to let cvs know it is there use<br>
|
|
|
|
<TT>cvs add expo/plateau/505.htm</TT><br>
|
|
<TT>cvs commit expo/plateau/505.htm</TT>
|
|
|
|
<p>cvs works by maintaining DIFFerences between files as they are updated.
|
|
This works on text files, and cvs can convert the line-ending conventions
|
|
on different platforms. If you add a binary file, that sort of translation
|
|
can be extremely bad news, so use "-kb" to tell cvs when adding a binary
|
|
file:
|
|
|
|
<TT>cvs add -kb expo/plateau/others/505.png</TT>
|
|
|
|
<!-- there is a way to tell the repository to know about some standard
|
|
filename extensions, like .png, .gif, .jpg, and always treat them as
|
|
binaries - we should do this !! -->
|
|
|
|
<p>Sometimes, you may find that an unwieldy chunk of cave description needs
|
|
to be split into two or more pages (this happened quite often with 161).
|
|
It is usually clearer to everyone if none of the new files have the same
|
|
name as the old one. So in addition to using "cvs add" to add the new
|
|
pages, you need<br>
|
|
|
|
<TT>rm expo/smkridge/161/nowsplit.htm</TT><br>
|
|
<TT>cvs remove expo/smkridge/161/nowsplit.htm<br>
|
|
cvs commit expo/smkridge/161/nowsplit.htm</TT>
|
|
|
|
<p>Whenever you do a "cvs commit" you will be asked for a log message, which
|
|
is just some text to help others know what sort of update you were doing.
|
|
So something like "correcting typos" or "added new passages off Puerile
|
|
Humour", "fixing broken links" are the minimum sort of level you need to
|
|
add. It is a good idea to commit files back to the repository one or two
|
|
at a time, so the comments can be relevant to each particular file. It
|
|
is often worth while committing unrelated changes separately, even if
|
|
they affect the same file. For instance, if you correct some typos in one
|
|
page, and link a new photo to several pages, including that same one, it
|
|
is better to commit each set of changes separately. This does take some
|
|
discipline, however, as it is usually just whilst you are making one set of
|
|
changes that you notice the typo, and if you don't change it then and there,
|
|
it gets forgotten. Your call.
|
|
|
|
<p>Of course, if you did some major overhaul to a lot of files (like changing
|
|
lots of links after some sort of reorganisation) you'd want to commit them
|
|
all together with a suitable log message. It really is a good idea to
|
|
avoid doing this whilst other people might be editing some of the files,
|
|
as you could spend ages resolving conflicts...
|
|
|
|
<H3>Avoiding cocks-up.</H3>
|
|
|
|
<p>Running cvs update just before you start editing saves you making changes to
|
|
out-of-date stuff, and committing changes soon after editing saves everyone
|
|
else from working on out-of-date pages. Both of which will save you work
|
|
resolving conflicts later on - but only if *everyone* remembers to do this.
|
|
|
|
<p>If you had to leave some editing part way through, and came back to it later,
|
|
its easy to forget what you have finished and what you haven't. Running<br>
|
|
|
|
<TT>cvs diff -u</TT>
|
|
|
|
<p>will tell you what you changed *from the copy you checked out* (so you
|
|
don't get confused by a list of things which other people have changed in
|
|
the meantime). This helps to avoid leaving things like notes to yourself
|
|
lying around in the file, and should help to avoid failing to update
|
|
links, though that is harder, since you have to notice that a change you
|
|
meant to make hasn't appeared in the list of changes.<br>
|
|
|
|
<TT>cvs -n update
|
|
</TT>
|
|
<p>doesn't actually update anything, but tells you what would have happened.
|
|
This is useful at various times, such as for spotting conflicts early on
|
|
whilst you are part way through doing a big update. Changing it to<br>
|
|
|
|
<TT>cvs -nq update</TT>
|
|
|
|
<p>suppresses some of the less useful output. Files which are marked with
|
|
a "?" are ones which cvs doesn't know about - maybe you haven't "cvs add"ed
|
|
them yet.
|
|
|
|
<H3>CVS documentation</H3>
|
|
|
|
<p>Obviously, CVS has lots of bells and whistles that you don't need just to
|
|
edit a few web pages. Here are a few links which you might care to look at.
|
|
Many more are accessible via <a href="http://www.cvshome.org/">CVS' home
|
|
page</a>.
|
|
|
|
<P>OK, that's how to use CVS. You might now like to read a bit about editing
|
|
the web pages you checked out - there are a few conventions to help to
|
|
maintain a consistent style (although we might change that style soon, as
|
|
soon as we can agree about a new look). Just as in programming, there are
|
|
also a lot of useful things you can do by adding comments (which the end
|
|
reader of the pages won't see).
|
|
|
|
<a name="links">Further reading</a>
|
|
|
|
<ul>
|
|
|
|
<li><a href="http://www.cvshome.org/new_users.html">CVS for new users</a>
|
|
|
|
<li><a href="http://www.cvshome.org/docs/manual">Version Management with
|
|
CVS</a> (the official manual)
|
|
|
|
<li><a href="http://cvsbook.red-bean.com/">Open Source development with
|
|
CVS</a> (chapters from a book, aimed at programmers, but almost all
|
|
applicable to open source document authors too)
|
|
|
|
<li><a href="http://www.cvshome.org/dev/addons.html">CVS Add-ons</a> page
|
|
includes graphical CVS clients for Mac, Windows and, of course, Linux.
|
|
|
|
<li>And a <a href="http://gallery.uunet.be/John.Tytgat/cvs/">CVS client
|
|
for RISC OS</a> (but note that this didn't appear to support ssh when this
|
|
page was written (2001-10-12)).
|
|
|
|
<li><a href="http://www.durak.org/cvswebsites/">CVS for websites</a>:
|
|
most manuals assume you are using CVS to develop software - this site is
|
|
specific to using CVS to maintain web pages.
|
|
|
|
</ul>
|
|
|
|
<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>... and it's not written yet, either :-)
|
|
|
|
<ul>
|
|
<li>Structure
|
|
<li>Info for each cave
|
|
<li>Contents lists & relative links for multi-article publications like
|
|
journals. Complicated by expo articles being in a separate hierarchy.
|
|
<li>Translations
|
|
<li>Other people's work - the noinfo hierarchy.
|
|
</ul>
|
|
</body>
|
|
</html> |