diff --git a/README.mkd b/README.mkd
index b60683c..e33a581 100644
--- a/README.mkd
+++ b/README.mkd
@@ -94,8 +94,9 @@ But there are several disadvantages here:
     impossible without extraneous tools
   * errors or omissions in setting the permissions exactly can cause problems
     of either kind: false accepts or false rejects
-  * without going into ACLs it is not possible to give someone read-only
-    access to a repo; they either get read-write access or no access
+  * without going into ACLs it is not possible to give some people read-only
+    access while some others have read-write access to a repo (unless you make
+    it world-readable).  Group access just doesn't have enough granularity
   * it is absolutely impossible to restrict pushing by branch name or tag
     name.
 
diff --git a/doc/2-admin.mkd b/doc/2-admin.mkd
index e749d81..5e3ca81 100644
--- a/doc/2-admin.mkd
+++ b/doc/2-admin.mkd
@@ -62,10 +62,11 @@ Once you've cloned it, you're ready to add users and repos.
     if you wish, since the entire tree is searched.
 
   * edit the config file (`conf/gitolite.conf` in your admin repo clone).  See
-    `doc/gitolite.conf.mkd` in the gitolite source for details on what goes in
-    that file, syntax, etc.  Just add new repos as needed, and add new users
-    and give them permissions as required.  The users names should be exactly
-    the same as their keyfile names, but without the `.pub` extension
+    [doc/gitolite.conf.mkd][confmkd] in the gitolite source for details on
+    what goes in that file, syntax, etc.  Just add new repos as needed, and
+    add new users and give them permissions as required.  The users names
+    should be exactly the same as their keyfile names, but without the `.pub`
+    extension
 
   * when done, commit your changes and push.  Any new repos you specified will
     automatically be created (empty, but clonable) and users' access will be
@@ -380,4 +381,4 @@ It does not (currently) support other options like `--add`, the `value_regex`,
 etc.
 
 [genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key
-
+[confmkd]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html
diff --git a/doc/gitolite-gitweb-http-backend.mkd b/doc/gitolite-gitweb-http-backend.mkd
index c7005b7..cfe489a 100644
--- a/doc/gitolite-gitweb-http-backend.mkd
+++ b/doc/gitolite-gitweb-http-backend.mkd
@@ -1,4 +1,4 @@
-# how to set up gitolite+gitweb+ssh+http-backend
+## how to set up gitolite+gitweb+ssh+http-backend
 
 In this document:
 
diff --git a/doc/gitolite-without-ssh.mkd b/doc/gitolite-without-ssh.mkd
index bb1a194..4463363 100644
--- a/doc/gitolite-without-ssh.mkd
+++ b/doc/gitolite-without-ssh.mkd
@@ -11,6 +11,8 @@ be, and usually *isn't*, an actual *unix* username).
 
 [gas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
 
+<a name="_sidebar_authentication_versus_authorisation"></a>
+
 ### sidebar: authentication versus authorisation
 
 >   Just for completeness, I'd like to loosely define these two animals.
@@ -23,6 +25,8 @@ be, and usually *isn't*, an actual *unix* username).
 >   **Authorisation** is the process of asking what you want to do and
 >   deciding if you're allowed to do it or not.
 
+<a name="_what_does_gitolite_actually_do"></a>
+
 ### what does gitolite actually do
 
 With that background, here's the truth about gitolite:
@@ -43,6 +47,8 @@ It is also why I often ignore emails and IRC messages that seem like just ssh
 issues if I am too busy.  I will never ignore core gitolite issues like that,
 of course!]
 
+<a name="_using_other_authentication_systems_with_gitolite"></a>
+
 ### using other authentication systems with gitolite
 
 The bottom line in terms of how to invoke gitolite has been described up at
diff --git a/doc/report-output.mkd b/doc/report-output.mkd
index 4f91579..9aa5475 100644
--- a/doc/report-output.mkd
+++ b/doc/report-output.mkd
@@ -115,9 +115,9 @@ It used to be that the gitolite documentation would say "just use `ssh
 git@server`" in the past, because gitolite defaults to the "info" command if
 no command is passed.
 
-However, starting with [openssh 5.6][openssh56], this won't work.  Openssh
-will now "Kill channel when pty allocation requests fail".  This means that
-gitolite is not even invoked; you only get a message about pty allocation
+However, starting with [openssh 5.6][openssh56], this won't work.  The ssh
+client will now "Kill channel when pty allocation requests fail".  This means
+that gitolite is not even invoked; you only get a message about pty allocation
 failure, followed by "connection closed".
 
 So now you have to use an explicit "info" command, (`ssh git@server info`) or