--- a/README	Fri Feb 20 11:38:19 2009 +0000
+++ b/README	Fri Feb 20 12:44:16 2009 +0000
@@ -12,57 +12,111 @@
 
 These tools make it easier to provide a centralized repository host
 with read/write access to many repositories for many developers.
-Access control is managed with a special repository on the server
-called "hgadmin"; pushes to this repository immediately change the
-rules that are in effect.
 
-Inside "hgadmin" is a "keys" directory containing the SSH keys of all
-developers who have access, and a file "hg-ssh-access.conf" which
-gives a set of rules defining who can do what to what.
+All of the repositories controlled by these tools are owned by a single user
+(the "hg" user in what follows), but many remote users can act on them, and
+different users can have different permissions. We don't use file permissions to
+achieve that - instead, developers log in as the "hg" user when they connect to
+the repository host using ssh, using ssh URLs of the form
+"ssh://hg@repository-host/repository-name". A restricted shell prevents them
+from using this access for unauthorized purposes. Developers are authenticated
+only using SSH keys; no other form of authentication is supported. 
 
-All of the repositories controlled by these tools are owned by a
-single user (the "hg" user in what follows), but many remote users can
-act on them.  We don't use file permissions to achieve that - instead,
-developers log in as the "hg" user when they connect to the repository
-host using ssh, using ssh URLs of the form
-"ssh://hg@repository-host/repository-name".  A restricted shell
-prevents them from using this access for unauthorized purposes.
-Developers are authenticated only using SSH keys; no other form of
-authentication is supported.
+To give a user access to the repository, place their key in an
+appropriately-named subdirectory of "/etc/mercurial-server/keys" and run
+"/etc/mercurial-server/refresh-auth". You can then control what access they have
+to what repositories by editing the control file
+"/etc/mercurial-server/access.conf", which can match the names of these keys
+against a glob pattern. 
+
+For convenient remote control of access, you can instead (if you have the
+privileges) make changes to a special repository called "hgadmin", which
+contains its own "access.conf" file and "keys" directory. Changes pushed to this
+repository take effect immediately. The two "access.conf" files are
+concatenated, and the keys directories merged.
 
 QUICK START
 
-You will need 
+You and all developers using this system will need an SSH public key, and will
+almost certainly want to be running ssh-agent (or its equivalent, eg Pageant
+under Windows). If you're not familiar with ssh-agent, you should learn about
+that before using this.
 
-- "sudo" installed
-- "sudo" root privileges
-- an ssh-key set up with ssh-agent
+In what follows, certain operations (eg installing mercurial-server itself) have
+to be done on the repository server (which we call "repository-host"), but any
+operation that involves checking in or out of Mercurial can be done wherever is
+most convenient to you; the most usual arrangment would be that you'd do these
+things at the machine you sit at, and on which you run ssh-agent, which is what
+authenticates you when you talk to the repository server.
+
+Ensure there is no user called "hg" on the repository host, and run "./install".
+This installs the mercurial-server files and control files, and creates and sets
+up the "hg" user.
 
-Ensure there is no user called "hg" on the repository host, and run
-"./install" to create them. You are now the sole user able to change
-and create repositories on this repository host.  To give access to
-others, check out hgadmin - as yourself, and on whichever host is most
-convenient, but using the ssh-key with which you set up the
-repository:
+Place your SSH public key in the directory "/etc/mercurial-server/keys/root". I
+suggest creating yourself a directory and naming the key after your hostname (ie
+the file is called something like
+"/etc/mercurial-server/keys/root/yourname/yourhostname") so that you can easily
+manage users who have a different key on each host they use. Then run
+"/etc/mercurial-server/refresh-auth".
+
+The repository is now ready to use, and you are now the sole user able to change
+and create repositories on this repository host.  
+
+CREATING REPOSITORIES
+
+To create a new repository, you clone a local repository onto the remote server.
+So if you want a new empty repository called "myproject", you can do (as
+yourself):
+
+    hg init myproject
+    hg clone myproject ssh://hg@repository-host/myproject
+
+ADDING OTHER USERS
 
-   mkdir ~/hg
-   cd ~/hg
-   hg clone ssh://hg@repository-host/hgadmin
-   cd hgadmin
+Because your key is in the "keys/root" subdirectory, you have the equivalent of
+"root privileges" over mercurial-server (not the whole computer, just
+mercurial-server). You can add other root users by putting their keys next to
+yours, or you can make less privileged users by putting their keys in the
+"keys/users" subdirectory - these users will be able to read and write to any
+repository (except one - see below) but will not be able to create new
+repositories. As always, when you change "/etc/mercurial-server/keys" you need
+to re-run "/etc/mercurial-server/refresh-auth".
+
+USING HGADMIN
+
+It can be inconvenient to log on to the repository server, become root, copy
+keys around, and run "refresh-auth" every time you want to change user
+privileges. This is where mercurial-server shines :-) Suppose you have another
+user's SSH public key in the file "/tmp/theirkey" (on the machine you sit at,
+not necessarily the repository server) and you want to give them user-level
+access to the repository server. Run these commands:
 
-You can now add other users by putting their keys in an appropriate
-subdirectory of the "keys" directory, and control their access by
-editing hg-ssh-access.conf.  Changes will take effect as soon as you
-push them to "ssh://hg@repository-host/hgadmin".
+    hg clone ssh://hg@repository-server/hgadmin
+    cd hgadmin
+    mkdir keys/user/thatuser
+    cp /tmp/theirkey keys/user/thatuser/theirhostname
+    hg add
+    hg commit -m "Added key for thatuser"
+    hg push
 
-Users authorized to do so can now also create new repositories on this
-host with "clone":
+In other words, hgadmin is a version controlled version of
+"/etc/mercurial-server/keys", and changes to it take effect immediately. Only
+"keys/root" users can act on "hgadmin" - those with keys in "keys/users" are
+locked out. Multiple admins can use Mercurial's version control to cooperate on
+controlling access to the repository server in a natural way. You can also add
+"root" users by putting their key in the "keys/root" directory in just the same
+way - these users will now be able to control hgadmin and create new
+repositories just as you can.
 
-  hg clone . ssh://hg@repository-host/my-project-name
+ACCESS.CONF
 
-HG-SSH-ACCESS.CONF
+Out of the box, there are just two kinds of users: the ones with keys in
+"keys/root" and those in "keys/users". However, you can change this by editing
+"access.conf". There are two "access.conf" files, one in "/etc/mercurial-server"
+and one in "hgadmin"; the two are simply concatenated before being read.
 
-Each line of hg-ssh-access.conf has the following syntax:
+Each line of access.conf has the following syntax:
 
 <rule> <condition> <condition> ...
 
@@ -92,6 +146,12 @@
 
 FILE CONDITIONS
 
+mercurial-server supports file and branch conditions, which restrict an
+operation depending on what files it modifies and what branch the work is on.
+However, the way these conditions work is subtle and can be counterintuitive -
+if you want to keep things simple, stick to user and repo conditions, and then
+things are likely to work the way you would expect.
+
 The rules file is used to make four decisions:
 
 - Whether to allow a repository to be created
@@ -163,19 +223,15 @@
 remotely committed, which uses the rules file to determine whether to
 allow the changeset.
 
-LOCKING YOURSELF OUT
+LOCKED OUT?
 
-If you find yourself "locked out" - that is, that you no longer have
-the permissions needed in hgadmin - you can break back in again if
-you're able to become the "hg" user on the repository host.  Once you
-are that user, delete ~hg/.ssh/authorized_keys (to stop any user who
-might have access but shouldn't from using the repository while you
-fix things).  Then go into ~hg/repos/hgadmin, do an "hg update", edit
-things to your satisfaction, and commit the change.  Finally, run
-
-~hg/admin/mercurial-server/refresh-auth ~hg/.ssh/authorized_keys ./hg-ssh-wrapper
-
-to regenerate ~hg/.ssh/authorized_keys. 
+Once you're working with "hgadmin", it can be convenient to remove all the keys
+in "/etc/mercurial-server/keys" and all the entries in
+"/etc/mercurial-server/access.conf" and use hgadmin to control everything. If
+you find yourself locked out, you can get back in again by restoring some of the
+entries you removed from these files - remember,
+"/etc/mercurial-server/access.conf" takes precedence over the "access.conf" in
+"hgadmin".
 
 THANKS