# HG changeset patch
# User Paul Crowley <paul@lshift.net>
# Date 1255603994 -3600
# Node ID 45dac87ae794233124bc73433b011b7fbfd281c2
# Parent  aa57f48c758580c009a8cb967ffa5bcc8057e893
Repository names are directories

diff -r aa57f48c7585 -r 45dac87ae794 doc/manual.docbook
--- a/doc/manual.docbook	Thu Oct 15 11:50:06 2009 +0100
+++ b/doc/manual.docbook	Thu Oct 15 11:53:14 2009 +0100
@@ -99,7 +99,8 @@
 At this stage, no-one but you has any access to any repositories you
 create on this system. In order to give anyone else access, you'll need a
 copy of their SSH public key; we'll assume you have that key in
-<filename>~/sam-key.pub</filename>.  To manage access, you make changes to the special <literal>hgadmin</literal> repository.
+<filename>~/sam-key.pub</filename>.  To manage access, you make changes to the special <filename
+class='directory'>hgadmin</filename> repository.
 </para>
 <screen><computeroutput>jay@my-workstation:~$ </computeroutput><userinput>hg clone ssh://hg@repository-host/hgadmin</userinput>
 <computeroutput>destination directory: hgadmin
@@ -124,7 +125,8 @@
 Sam can now read and write to your
 <literal>ssh://hg@repository-host/repository/name</literal> repository.
 Most other changes to access control can be made simply by making and
-pushing changes to <literal>hgadmin</literal>, and you can use Mercurial to
+pushing changes to <filename
+class='directory'>hgadmin</filename>, and you can use Mercurial to
 cooperate with other root users in the normal way.
 </para>
 <para>
@@ -133,7 +135,8 @@
 putting the key in the right place under <filename
 class='directory'>/etc/mercurial-server/keys</filename>, and re-running
 <userinput>sudo -u hg /usr/share/mercurial-server/refresh-auth</userinput>.
-However, using <literal>hgadmin</literal> is usually more convenient if you need to make more than a very few changes; it also makes it easier to share administration with others and provides a log of all changes.
+However, using <filename
+class='directory'>hgadmin</filename> is usually more convenient if you need to make more than a very few changes; it also makes it easier to share administration with others and provides a log of all changes.
 </para>
 </section>
 </section>
@@ -143,20 +146,26 @@
 Out of the box, mercurial-server supports two kinds of users: "root" users and normal users.  If you followed the steps above, you are a "root" user because your key is under <filename class='directory'>keys/root</filename>, while the other user you gave access to is a normal user since their key is under <filename class='directory'>keys/users</filename>.  Keys that are not in either of these directories will by default have no access to anything.
 </para>
 <para>
-Root users can edit <literal>hgadmin</literal>, create new repositories and read and write to existing ones.  Normal users cannot access <literal>hgadmin</literal> or create new repositories, but they can read and write to any other repository.
+Root users can edit <filename
+class='directory'>hgadmin</filename>, create new repositories and read and write to existing ones.  Normal users cannot access <filename
+class='directory'>hgadmin</filename> or create new repositories, but they can read and write to any other repository.
 </para>
 <section>
 <title>Using access.conf</title>
 <para>
-mercurial-server offers much more fine-grained access control than this division into two classes of users.  Let's suppose you wish to give Pat access to the <literal>widget</literal> repository, but no other.  We first copy Pat's SSH public key into the <filename
-class='directory'>keys/pat</filename> directory in <literal>hgadmin</literal>.  This tells mercurial-server about Pat's key, but gives Pat no access to anything because the key is not under either <filename
+mercurial-server offers much more fine-grained access control than this division into two classes of users.  Let's suppose you wish to give Pat access to the <filename
+class='directory'>widget</filename> repository, but no other.  We first copy Pat's SSH public key into the <filename
+class='directory'>keys/pat</filename> directory in <filename
+class='directory'>hgadmin</filename>.  This tells mercurial-server about Pat's key, but gives Pat no access to anything because the key is not under either <filename
 class='directory'>keys/root</filename> or <filename
-class='directory'>keys/users</filename>.  To grant this key access, we must give mercurial-server a new access rule, so we create a file in <literal>hgadmin</literal> called <filename>access.conf</filename>, with the following contents:</para>
+class='directory'>keys/users</filename>.  To grant this key access, we must give mercurial-server a new access rule, so we create a file in <filename
+class='directory'>hgadmin</filename> called <filename>access.conf</filename>, with the following contents:</para>
 <programlisting># Give Pat access to the "widget" repository
 write repo=widget user=pat
 </programlisting>
 <para>
-Pat will have read and write access to the <literal>widget</literal> repository as soon as we add, commit, and push these files.
+Pat will have read and write access to the <filename
+class='directory'>widget</filename> repository as soon as we add, commit, and push these files.
 </para>
 <para>
 Each line of <filename>access.conf</filename> has the following syntax:
@@ -204,7 +213,8 @@
 <para>
 When considering a request, mercurial-server steps through all the rules in
 <filename>/etc/mercurial-server/access.conf</filename> and then all the
-rules in <filename>access.conf</filename> in <literal>hgadmin</literal>
+rules in <filename>access.conf</filename> in <filename
+class='directory'>hgadmin</filename>
 looking for a rule which matches on every condition. The first match
 determines whether the request will be allowed; if there is no match in
 either file, the request will be denied.
@@ -219,7 +229,8 @@
 </programlisting>
 <para>
 These rules ensure that root users can do any operation on any repository,
-that no other users can access the <literal>hgadmin</literal> repository,
+that no other users can access the <filename
+class='directory'>hgadmin</filename> repository,
 and that those with keys in <filename
 class='directory'>keys/users</filename> can read or write to any repository
 but not create repositories.  Some examples of how these rules work:
@@ -272,7 +283,8 @@
 <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:
+class='directory'>/etc/mercurial-server</filename> and its own <filename
+class='directory'>hgadmin</filename> repository.  This is useful for several reasons:
 </para>
 <itemizedlist>
 <listitem>
@@ -285,7 +297,8 @@
 xlink:href="http://reductivelabs.com/products/puppet">Puppet</link>
 </listitem>
 <listitem>
-If a change to <literal>hgadmin</literal> leaves you "locked out", <filename
+If a change to <filename
+class='directory'>hgadmin</filename> leaves you "locked out", <filename
 class='directory'>/etc/mercurial-server</filename> allows you a way back in.
 </listitem>
 <listitem>
@@ -293,16 +306,21 @@
 </listitem>
 </itemizedlist>
 <para>
-Rules in <filename>/etc/mercurial-server/access.conf</filename> are checked before those in <literal>hgadmin</literal>, and keys in <filename class='directory'>/etc/mercurial-server/keys</filename> will be present no matter how <literal>hgadmin</literal> changes.
+Rules in <filename>/etc/mercurial-server/access.conf</filename> are checked before those in <filename
+class='directory'>hgadmin</filename>, and keys in <filename class='directory'>/etc/mercurial-server/keys</filename> will be present no matter how <filename
+class='directory'>hgadmin</filename> changes.
 </para>
 <para>
 We anticipate that once mercurial-server is successfully installed and
-working you will usually want to use <literal>hgadmin</literal> for most
+working you will usually want to use <filename
+class='directory'>hgadmin</filename> for most
 access control tasks. Once you have the right keys and
-<filename>access.conf</filename> set up in <literal>hgadmin</literal>, you
+<filename>access.conf</filename> set up in <filename
+class='directory'>hgadmin</filename>, 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>.
+turning control entirely over to <filename
+class='directory'>hgadmin</filename>.
 </para>
 <para>
 <filename>/etc/mercurial-server/remote-hgrc</filename> is in the
@@ -438,9 +456,11 @@
 <command>refresh-auth</command> recurses through the <filename
 class='directory'>/etc/mercurial-server/keys</filename> and the <filename
 class='directory'>keys</filename> directory in the
-<literal>hgadmin</literal> repository, creating an entry in
+<filename
+class='directory'>hgadmin</filename> repository, creating an entry in
 <filename>~hg/.ssh/authorized_keys</filename> for each one. This is redone
-automatically whenever a change is pushed to <literal>hgadmin</literal>.
+automatically whenever a change is pushed to <filename
+class='directory'>hgadmin</filename>.
 </para>
 </section>
 <section>