[PATCH 2 of 2] acl: improve help

[Cédric Duval]

# HG changeset patch
# User Cédric Duval <cedricduval at free.fr>
# Date 1245304193 -7200
# Node ID 5c82387e3aba862c18d5c0c1806fc9faa5af638f
# Parent  aaa05a8e68797269527ceb54e1d52af23e0815fe
acl: improve help

diff --git a/hgext/acl.py b/hgext/acl.py
--- a/hgext/acl.py
+++ b/hgext/acl.py
@@ -5,20 +5,23 @@
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2, incorporated herein by reference.
 
-'''this hook allows to allow or deny access to parts of a repo
-when taking incoming changesets.
+'''control access to portions of a repository
 
-authorization is against local user name on system where hook is
-run, not committer of original changeset (since that is easy to
-spoof).
+This hook makes it possible to allow or deny access to portions of
+a repository when receiving incoming changesets.
 
-acl hook is best to use if you use hgsh to set up restricted shells
-for authenticated users to only push to / pull from.  not safe if
-user has interactive shell access, because they can disable hook.
-also not safe if remote users share one local account, because then
-no way to tell remote users apart.
+The authorization is matched against the local user name on the
+system where the hook is run, and not the committer of the original
+changeset (since that one can be easily spoofed).
 
-to use, configure acl extension in hgrc like this:
+The acl hook is best used along with a restricted shell like hgsh,
+preventing authenticating users to do anything beside pushing to
+or pulling from. The hook is not safe to use if users have
+interactive shell access, as they can then disable the hook. Neither
+is it safe if remote users share an account, because there is then
+no way to tell them apart.
+
+To use this hook, configure the acl extension in your hgrc like this:
 
   [extensions]
   hgext.acl =
@@ -27,22 +30,24 @@
   pretxnchangegroup.acl = python:hgext.acl.hook
 
   [acl]
-  # check if source of incoming changes in this list
+  # check if the source of incoming changes is in this list
   # ("serve" == ssh or http, "push", "pull", "bundle")
   sources = serve
 
-allow and deny lists have subtree pattern (default syntax is glob)
-on left, user names on right. deny list checked before allow list.
+The allow and deny sections take a subtree pattern as key (with a
+glob syntax by default), and a comma separated list of users as
+the corresponding value. The deny list is checked before the allow
+list is.
 
   [acl.allow]
-  # if acl.allow not present, all users allowed by default
-  # empty acl.allow = no users allowed
+  # If acl.allow is not present, all users are allowed by default
+  # An empty acl.allow section means no users allowed
   docs/** = doc_writer
   .hgtags = release_engineer
 
   [acl.deny]
-  # if acl.deny not present, no users denied by default
-  # empty acl.deny = all users allowed
+  # If acl.deny is not present, no users are denied by default
+  # An empty acl.deny section means all users allowed
   glob pattern = user4, user5
   ** = user6
 '''