--- a/doc/configuring-access	Tue Oct 13 12:03:23 2009 +0100
+++ b/doc/configuring-access	Tue Oct 13 12:22:30 2009 +0100
@@ -1,10 +1,10 @@
 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.
+"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 access.conf has the following syntax:
 
@@ -23,13 +23,14 @@
     user=<globpattern> - user's key
     repo=<globpattern> - repo (as the user supplies it)
 
-The first rule in the file which has all its conditions satisfied is used to
-determine whether an action is allowed.
+The first rule in the file which has all its conditions satisfied is used
+to determine whether an action is allowed. If no rule is matched the
+request is denied.
 
-Paths cannot contain any special characters except "/"; glob patterns cannot
-contain any special characters except "/" and "*". "*" matches zero or more
-characters not including "/" while "**" matches zero or more characters
-including "/".
+Paths cannot contain any special characters except "/"; glob patterns
+cannot contain any special characters except "/" and "*". "*" matches zero
+or more characters not including "/" while "**" matches zero or more
+characters including "/".
 
 Blank lines and lines that start with "#" are ignored.
 
@@ -40,8 +41,8 @@
     write user=users/**
 
 This means: keys in "root" can do anything; keys in "users" cannot create
-repositories, cannot even read the hgadmin repository, but can read and write
-any other repository; no other key has any access.
+repositories, cannot even read the hgadmin repository, but can read and
+write any other repository; no other key has any access.
 
 More advanced access configuration is covered in file-conditions.
 

--- a/doc/file-conditions	Tue Oct 13 12:03:23 2009 +0100
+++ b/doc/file-conditions	Tue Oct 13 12:22:30 2009 +0100
@@ -3,10 +3,11 @@
 Read configuring-access before you read this.
 
 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.
+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.
 
 File and branch conditions are added to the conditions against which a rule
 matches, just like user and repo conditions; they have this form:
@@ -14,8 +15,8 @@
     file=<globpattern> - file in the repo
     branch=<globpattern> - name of the branch
 
-However, in order to understand what effect adding these conditions will have,
-it helps to understand how and when these rules are applied.
+However, in order to understand what effect adding these conditions will
+have, it helps to understand how and when these rules are applied.
 
 The rules file is used to make four decisions:
 
@@ -24,35 +25,35 @@
 - Whether to allow a changeset on a particular branch at all
 - Whether to allow a changeset to change a particular file
 
-When the first two of these decisions are being made, nothing is known about
-what files might be changed, and so all file conditions automatically succeed
-for the purpose of such decisions. This means that doing tricky things with
-file conditions can have counterintuitive consequences:
+When the first two of these decisions are being made, nothing is known
+about what files might be changed, and so all file conditions automatically
+succeed for the purpose of such decisions. This means that doing tricky
+things with file conditions can have counterintuitive consequences:
 
-- You cannot limit read access to a subset of a repository with a "read" rule
-and a file condition: any user who has access to a repository can read all of
-it and its full history. Such a rule can only have the effect of masking a
-later "write" rule, as in this example:
+- You cannot limit read access to a subset of a repository with a "read"
+rule and a file condition: any user who has access to a repository can read
+all of it and its full history. Such a rule can only have the effect of
+masking a later "write" rule, as in this example:
 
    read repo=specialrepo file=dontwritethis
    write repo=specialrepo
 
-allows all users to read specialrepo, and to write to all files *except* that
-any changeset which writes to "dontwritethis" will be rejected.
+allows all users to read specialrepo, and to write to all files *except*
+that any changeset which writes to "dontwritethis" will be rejected.
 
 - For similar reasons, don't give "init" rules file conditions.
 
-- Don't try to deny write access to a particular file on a particular branch -
-a developer can write to the file on another branch and then merge it in.
-Either deny all writes to the branch from that user, or allow them to write to
-all the files they can write to on any branch. In other words, something like
-this will have the intended effect:
+- Don't try to deny write access to a particular file on a particular
+branch - a developer can write to the file on another branch and then merge
+it in. Either deny all writes to the branch from that user, or allow them
+to write to all the files they can write to on any branch. In other words,
+something like this will have the intended effect:
 
   write user=docs/* branch=docs file=docs/*
 
-But something like this will not have the intended effect; it will effectively
-allow these users to write to any file on any branch, by writing it to "docs"
-first:
+But something like this will not have the intended effect; it will
+effectively allow these users to write to any file on any branch, by
+writing it to "docs" first:
 
   write user=docs/* branch=docs
   write user=docs/* file=docs/*

--- a/doc/how-it-works	Tue Oct 13 12:03:23 2009 +0100
+++ b/doc/how-it-works	Tue Oct 13 12:22:30 2009 +0100
@@ -18,6 +18,7 @@
 repository called "hgadmin". A hook in this repository re-runs
 "refresh-auth" on the most recent version after every push.
 
-Finally, hook in an extension is run for each changeset that is remotely
-committed, which uses the rules file to determine whether to allow the
-changeset.
+When users try to commit new changesets, a hook is run which consults the
+rules file to decide whether to allow the changeset into the repository.
+This can depend not only on the user and the repository, but also the
+branch and files in the changeset.