# HG changeset patch
# User Paul Crowley <paul@lshift.net>
# Date 1255600645 -3600
# Node ID dc4ed4edb458f0ebd64c4c40aef92901f89127f4
# Parent  5da43b596bacd32f155eab26f0d703b07ff955be
Improvements to file conditions section

diff -r 5da43b596bac -r dc4ed4edb458 doc/manual.docbook
--- a/doc/manual.docbook	Thu Oct 15 10:45:08 2009 +0100
+++ b/doc/manual.docbook	Thu Oct 15 10:57:25 2009 +0100
@@ -312,15 +312,15 @@
 </para>
 <itemizedlist>
 <listitem>
-<para>You cannot limit read access to a subset of a repository with a "read"
+<para>You cannot limit read access to a subset of a repository with a <literal>read</literal>
 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:</para>
+masking a later <literal>write</literal> rule, as in this example:</para>
 <programlisting>read repo=specialrepo file=dontwritethis
 write repo=specialrepo
 </programlisting>
 <para>
-allows all users to read specialrepo, and to write to all files
+allows all users to read <literal>specialrepo</literal>, and to write to all files
 <emphasis>except</emphasis> that any changeset which writes to
 <filename>dontwritethis</filename> will be rejected.
 </para>
@@ -330,22 +330,28 @@
 </listitem>
 <listitem>
 <para>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
+branch&#x2014;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:
+to write to all the files they can write to on any branch.
 </para>
 <programlisting>write user=docs/* branch=docs file=docs/*
 </programlisting>
 <para>
-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:
+This rule grants users whose keys are in the <filename
+class='directory'>docs</filename> subdirectory the power to push changesets
+into any repository only if those changesets are on the
+<literal>docs</literal> branch and they affect only those files directly
+under the <filename class='directory'>docs</filename> directory. However,
+the rules below have more counterintuitive consequences.
 </para>
 <programlisting>write user=docs/* branch=docs
 write user=docs/* file=docs/*
 read user=docs/*
 </programlisting>
+<para>
+These rules grant users whose keys are in the <filename
+class='directory'>docs</filename> subdirectory the power to change any file directly under the <filename class='directory'>docs</filename> directory, or any file at all in the <literal>docs</literal> branch.  Indirectly, however, this adds up to the power to change any file on any branch, simply by making the change on the docs branch and then merging the change into another branch.
+</para>
 </listitem>
 </itemizedlist>
 </section>