--- a/README	Fri Apr 18 09:13:37 2008 +0100
+++ b/README	Fri Apr 18 10:18:35 2008 +0100
@@ -10,23 +10,25 @@
 
 WHAT IT GIVES YOU
 
-You maintain a local Mercurial repository called "hgadmin" which
-controls what access is allowed to whom.  When you push a new version
-of this repository to the repository host, changes take effect
-immediately, so familiar "hg" commands are all that are needed to
-maintain it.  A "keys" directory contains the SSH keys of all the
-developers who have access, while "hg-ssh-access.conf" gives a set of
-rules defining who can do what to what.
+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.
 
 HOW IT WORKS
 
-The repository is owned by a single user (the "hg" user in what
-follows), but many remote users can act on it.  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.
+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.  When a developer attempts to connect to
@@ -40,39 +42,40 @@
 developer is allowed to perform that action on that repository.  The
 bulk of the work of the restricted shell is done by the Python program
 "hg-ssh", but the shell script "hg-ssh-wrapper" sets up some
-configuration so that you can change it to suit your local installation.
+configuration so that you can change it to suit your local
+installation.
 
 The file ~hg/.ssh/authorized_keys is generated by "refresh-auth",
 which recurses through a directory of files containing SSH keys and
 generates an entry in authorized_keys for each one, using the name of
 the key file as the identifier for the developer.  These keys will
-live in the "keys" subdirectory of a repository, "hgadmin".  A hook in
-this repository re-runs "refresh-auth" on the most recent version
-after every push.
+live in the "keys" subdirectory of a repository called "hgadmin".  A
+hook in this repository re-runs "refresh-auth" on the most recent
+version after every push.
 
 GETTING STARTED
 
 This is only one setup - it can be tweaked in many ways, and is as
 specific as it is only in the interests of brevity.
 
-You, and all users of your Hg repository, will need SSH public key
+You, and all users of this repository host, will need SSH public key
 authentication set up, preferably working with ssh-agent so you don't
 have to type in your passphrase all the time.  I assume you've done
 that in what follows, so if you've done something different you'll
 need to change it appropriately.
 
-Create a user called "hg" on the machine where the repository will
-live.  I used the command
-
-  sudo adduser --system --shell /bin/sh --group --disabled-password \
-    --gecos "Mercural repository" hg
+Issue these commands to get the repository host started.  These are
+written out here rather than encapsulated in a script because many of
+them may need to be different for your local setup.  You will need
+root access on the repository host, because you need to create a new
+user.
 
-Issue these commands to become the hg user and set up the repository.
-Use your own name in place of "myname".
-
+   ssh -A repository-host
    ssh-add -L >> /tmp/my-ssh-public-key
-   sudo -u hg -s
-   cd ~hg
+   sudo adduser --system --shell /bin/sh --group --disabled-password \
+     --gecos "Mercurial repositories" hg
+   sudo -u hg -H -s
+   cd
    mkdir -p admin repos/hgadmin/keys/admin
    cd admin
    hg clone http://hg.opensource.lshift.net/hg-admin-tools
@@ -86,19 +89,25 @@
    cp ~/admin/hg-admin-tools/hgadmin-hgrc .hg/hgrc
    ../../admin/hg-admin-tools/refresh-auth
    exit
+   exit
 
-You should now have SSH access to this repository and full control.
-To administer these controls (and test your access), check out hgadmin:
+You are now the sole user able to change and create repositories on
+this repository host.  To administer these controls (and test your
+access), check out hgadmin:
 
    mkdir ~/hg
    cd ~/hg
-   hg clone ssh://hg@repository-host-name/hgadmin
+   hg clone ssh://hg@repository-host/hgadmin
    cd hgadmin
 
 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 the remote repository.
+push them to "ssh://hg@repository-host/hgadmin".
+
+Users authorized to do so can now also create new repositories on this host with "clone":
+
+  hg clone . ssh://hg@repository-host/my-project-name
 
 HG-SSH-ACCESS.CONF