acl: help improvements

Thanks to timeless for the review.

hgext/acl.py

@@ -8,16 +8,21 b''
 
 '''provide simple hooks for access control
 
-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 write access to portions
+of a repository when receiving incoming changesets.
+
+The authorization is matched based on the local user name on the
+system where the hook runs, and not the committer of the original
+changeset (since the latter is merely informative).
 
-The acl hook is best to use if you use hgsh to set up restricted shells for
-authenticated users to only push to / pull from. It's not safe if user has
-interactive shell access, because they can disable the hook. It's also not
-safe if remote users share one local account, because then there's no way to
-tell remote users apart.
+The acl hook is best used along with a restricted shell like hgsh,
+preventing authenticating users from doing anything other than
+pushing or pulling. The hook is not safe to use if users have
+interactive shell access, as they can then disable the hook.
+Nor is it safe if remote users share an account, because then there
+is no way to distinguish them.
 
-To use, configure the acl extension in hgrc like this:
+To use this hook, configure the acl extension in your hgrc like this:
 
   [extensions]
   hgext.acl =
@@ -26,21 +31,24 b' To use, configure the acl extension in h'
   pretxnchangegroup.acl = python:hgext.acl.hook
 
   [acl]
-  sources = serve        # check if source of incoming changes in this list
-                         # ("serve" == ssh or http, "push", "pull", "bundle")
+  # Check whether the source of incoming changes is in this list
+  # ("serve" == ssh or http, "push", "pull", "bundle")
+  sources = serve
 
-Allow and deny lists have a subtree pattern (default syntax is glob) on the
-left and user names on right. The deny list is checked before the 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 refused by default.
+  # An empty acl.deny section means all users allowed.
   glob pattern = user4, user5
    ** = user6
 '''