# HG changeset patch
# User Paul Crowley <paul@lshift.net>
# Date 1255603806 -3600
# Node ID aa57f48c758580c009a8cb967ffa5bcc8057e893
# Parent  f4688940fe15e288d849cba50cc67b7948388888
replace generalities with specific examples

diff -r f4688940fe15 -r aa57f48c7585 doc/manual.docbook
--- a/doc/manual.docbook	Thu Oct 15 11:23:38 2009 +0100
+++ b/doc/manual.docbook	Thu Oct 15 11:50:06 2009 +0100
@@ -222,39 +222,42 @@
 that no other users can access the <literal>hgadmin</literal> repository,
 and that those with keys in <filename
 class='directory'>keys/users</filename> can read or write to any repository
-but not create repositories. If these are the only rules in effect, they
-have the following consequences:
+but not create repositories.  Some examples of how these rules work:
 </para>
 <itemizedlist>
 <listitem>
-Any request from a user with a key under <filename
-class='directory'>keys/root</filename> will match the first rule; since
-this rule is <literal>init</literal> the request will always be allowed.
+User <filename class='directory'>root/jay</filename> creates a repository
+<filename class='directory'>foo/bar/baz</filename>. This matches the first
+rule and so will be allowed.
 </listitem>
 <listitem>
-Any request to access the <literal>hgadmin</literal> by any other user will
-not match the first rule, but will match the second rule, and so will be
-denied.
+User <filename class='directory'>root/jay</filename> changes repository
+<filename class='directory'>hgadmin</filename>. Again, this matches the
+first rule and so will be allowed; later rules have no effect.
+</listitem>
+<listitem>
+User <filename class='directory'>users/sam</filename> tries to read
+repository <filename class='directory'>hgadmin</filename>. This does not
+match the first rule, but matches the second, and so will be denied.
 </listitem>
 <listitem>
-Any request to create a repository from a user with a key in <filename
-class='directory'>keys/users</filename> will not match the first or second
-rules, but will match the third rule. This is a <literal>write</literal>
-rule, which doesn't grant the privilege to create repositories, so the
-request will be denied.
+User <filename class='directory'>users/sam</filename> tries to create
+repository <filename class='directory'>sams-project</filename>. This does
+not match the first two rules, but matches the third; this is a
+<literal>write</literal> rule, which doesn't grant the privilege to create
+repositories, so the request will be denied.
 </listitem>
 <listitem>
-Any request to access an existing repository from a user with a key in
-<filename class='directory'>keys/users</filename> will not match the first
-or second rules, but will match the third rule, which grants
-<literal>write</literal> privilege, so the request will be allowed.
+User <filename class='directory'>users/sam</filename> writes to existing
+repository <filename class='directory'>projects/main</filename>. Again,
+this matches the third rule, which allows the request.
 </listitem>
 <listitem>
-Any request from any user whose key is in neither <filename
-class='directory'>keys/root</filename> nor <filename
-class='directory'>keys/users</filename> will not match any rule and so will
-be denied. Unless it matches the second rule, in which case it will still
-be denied.  Changes to the <filename>access.conf</filename> in <literal>hgadmin</literal> will change that, as the example at the start of this section shows.
+User <filename class='directory'>pat</filename> tries to write to existing
+repository <filename class='directory'>widget</filename>. Until we change
+the <filename>access.conf</filename> file in <filename
+class='directory'>hgadmin</filename>, this will match no rule, and so will
+be denied.
 </listitem>
 <listitem>
 Any request from a user whose key not under the <filename