# HG changeset patch
# User Paul Crowley <paul@lshift.net>
# Date 1255530356 -3600
# Node ID fc5b8fc1040ebcdee3ffb63816abd3226a5e5578
# Parent  6836769f51347498d2ea4f1a5fce5fbc52c5e8d6
Explain why we configure access twice

diff -r 6836769f5134 -r fc5b8fc1040e doc/manual.docbook
--- a/doc/manual.docbook	Wed Oct 14 15:22:51 2009 +0100
+++ b/doc/manual.docbook	Wed Oct 14 15:25:56 2009 +0100
@@ -291,6 +291,43 @@
 while "**" matches zero or more characters including "/".
 </para>
 <section>
+<title>/etc/mercurial-server and hgadmin</title>
+<para>
+mercurial-server consults two distinct locations to collect information about what to allow: <filename
+class='directory'>/etc/mercurial-server</filename> and its own <literal>hgadmin</literal> repository.  This is useful for several reasons:
+</para>
+<itemizedlist>
+<listitem>
+Users may not need the sophistication of access control via mercurial; for these users updating <filename
+class='directory'>/etc/mercurial-server</filename> may offer a simpler route.
+</listitem>
+<listitem>
+<filename
+class='directory'>/etc/mercurial-server</filename> is suitable for management by some other route, such as with  <link
+xlink:href="http://reductivelabs.com/products/puppet">Puppet</link>
+</listitem>
+<listitem>
+If a change to <literal>hgadmin</literal> leaves you "locked out", <filename
+class='directory'>/etc/mercurial-server</filename> allows you a way back in.
+</listitem>
+<listitem>
+At install time, all users are "locked out", and so some mechanism to allow some users in is needed.
+</listitem>
+</itemizedlist>
+<para>
+Rules in <filename>/etc/mercurial-server/access.conf</filename> take precedence over those in <literal>hgadmin</literal>, and obviously keys in <filename class='directory'>/etc/mercurial-server/keys</filename> cannot be affected by changes to <literal>hgadmin</literal>.
+</para>
+<para>
+We anticipate that once mercurial-server is successfully installed and
+working most users will want to use <literal>hgadmin</literal> for most
+access control tasks. Once you have the right keys and
+<filename>access.conf</filename> set up in <literal>hgadmin</literal>, you
+can delete <filename>/etc/mercurial-server/access.conf</filename> and all
+of <filename class='directory'>/etc/mercurial-server/keys</filename>,
+turning control entirely over to <literal>hgadmin</literal>.
+</para>
+</section>
+<section>
 <title>File and branch conditions</title>
 <para>
 mercurial-server supports file and branch conditions, which restrict an