diff --git a/doc/1-INSTALL.mkd b/doc/1-INSTALL.mkd
index cbafc59..9885013 100644
--- a/doc/1-INSTALL.mkd
+++ b/doc/1-INSTALL.mkd
@@ -38,8 +38,9 @@ In this document:
 
 Please make sure you understand the following points first.
 
-  * gitolite runs as a single (real) user on a server, and is invoked via ssh.
-    Traditionally, this "hosting user" is "git" or "gitolite".
+  * gitolite runs as a single (real) user on a server, and is invoked via ssh
+    (or, less commonly, via http).  Traditionally, this "hosting user" is
+    "git" or "gitolite".
 
       * there is *usually* only one hosting user per server (machine), but
         gitolite makes it trivial to have as many as you want.  In fact, every
@@ -111,6 +112,7 @@ don't know ssh it'll be a nightmare to support you.
         normally; see the `$GIT_PATH` variable in the "rc" file
   * perl (but since git requires it anyway, you probably have it)
   * openssh or any ssh that can understand the `authorized_keys` file format
+    (probably optional if you're using the http backend)
 
 <a name="_technical_skills"></a>
 
diff --git a/doc/admin-defined-commands.mkd b/doc/admin-defined-commands.mkd
index 9f0fca1..fb1dca7 100644
--- a/doc/admin-defined-commands.mkd
+++ b/doc/admin-defined-commands.mkd
@@ -13,6 +13,7 @@ In this document:
 
   * <a href="#_background">background</a>
   * <a href="#_setting_it_up">setting it up</a>
+      * <a href="#_configuring_ADCs">configuring ADCs</a>
   * <a href="#_anatomy_of_a_command">anatomy of a command</a>
   * <a href="#_example_uses_and_sample_commands_in_contrib">example uses and sample commands in contrib</a>
       * <a href="#_fork">fork</a>
@@ -77,6 +78,8 @@ to inadvertently *hide* some of the "official" commands (like "info",
 executable files with those names in this directory.  So don't do that -- you
 have been warned!**
 
+<a name="_configuring_ADCs"></a>
+
 #### configuring ADCs
 
 I didn't want to put configuration variables for ADCs also into the main 'rc'
diff --git a/doc/gitolite-without-ssh.mkd b/doc/gitolite-without-ssh.mkd
index 4f61405..bb1a194 100644
--- a/doc/gitolite-without-ssh.mkd
+++ b/doc/gitolite-without-ssh.mkd
@@ -38,6 +38,11 @@ involved if you setup [smart http][sh] mode.
 
 In other words, authentication is the job of `sshd` or `httpd`, not gitolite.
 
+[**SIDE NOTE**: This is why an "ssh issue" is almost never a "gitolite issue".
+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!]
+
 ### 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/http-backend.mkd b/doc/http-backend.mkd
index c1ed32f..54ec56b 100644
--- a/doc/http-backend.mkd
+++ b/doc/http-backend.mkd
@@ -64,6 +64,12 @@ I assume you've installed apache 2.x and git on the server.
 I assume your httpd runs under the "apache" userid; adjust instructions below
 if it does not.  Similarly for "/var/www" and other file names/locations.
 
+I assume you have read the "[please read this first][1rtf]" section of the
+main install document to get an idea of the general concepts and terminology
+(just ignore anything that is specific to ssh).
+
+[1rtf]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html#_please_read_this_first
+
 <a name="_install_gitolite_under_apache_"></a>
 
 #### install gitolite under "apache"
diff --git a/doc/ssh-troubleshooting.mkd b/doc/ssh-troubleshooting.mkd
index 594950e..a992a11 100644
--- a/doc/ssh-troubleshooting.mkd
+++ b/doc/ssh-troubleshooting.mkd
@@ -133,6 +133,9 @@ This is a quick checklist:
     these components are correct.  `ls -ald ~ ~/.ssh ~/.ssh/authorized_keys`
     will tell you what they are.
 
+  * some OSs/distributions require that the "git" user should have a password
+    and/or not be a locked account.  You may want to check that as well.
+
   * if all that fails, log onto the server as root, `cd /var/log`, and look
     for a file called `auth.log` or `secure` or some such name.  Look inside
     this file for messages matching the approximate time of your last attempt
diff --git a/doc/wildcard-repositories.mkd b/doc/wildcard-repositories.mkd
index ff196f0..5d986aa 100644
--- a/doc/wildcard-repositories.mkd
+++ b/doc/wildcard-repositories.mkd
@@ -25,6 +25,7 @@ In this document:
       * <a href="#_IMPORTANT_WARNING_ABOUT_THIS_FEATURE_">**IMPORTANT WARNING ABOUT THIS FEATURE**</a>
   * <a href="#_setting_a_gitweb_description_for_a_wildcard_matched_repo">setting a gitweb description for a wildcard-matched repo</a>
   * <a href="#_reporting">reporting</a>
+  * <a href="#_deleting_a_wild_repo">deleting a wild repo</a>
   * <a href="#_how_it_actually_works">how it actually works</a>
 
 ----
@@ -263,6 +264,8 @@ commands, thanks to Teemu.
 In order to see what repositories were created from a wildcard, use the
 "expand" command, described briefly in [doc/report-output.mkd][repout].
 
+<a name="_deleting_a_wild_repo"></a>
+
 ### deleting a wild repo
 
 See [repo deletion][rmr] for more on this.  Note that this requires you to
diff --git a/t/README.mkd b/t/README.mkd
index 2bbf0f8..f10688e 100644
--- a/t/README.mkd
+++ b/t/README.mkd
@@ -2,19 +2,19 @@
 
 In this document:
 
-  * <a href="#terminology">terminology</a>
-  * <a href="#notes_and_background">notes and background</a>
-  * <a href="#quick_instructions_for_running_the_test_suite">quick instructions for running the test suite</a>
-  * <a href="#instructions_for_adding_new_tests">instructions for adding new tests</a>
+  * <a href="#_terminology">terminology</a>
+  * <a href="#_notes_and_background">notes and background</a>
+  * <a href="#_quick_instructions_for_running_the_test_suite">quick instructions for running the test suite</a>
+  * <a href="#_instructions_for_adding_new_tests">instructions for adding new tests</a>
 
-<a name="terminology"></a>
+<a name="_terminology"></a>
 
 ### terminology
 
     #define PW "patches welcome!"
     #define TODO PW
 
-<a name="notes_and_background"></a>
+<a name="_notes_and_background"></a>
 
 ### notes and background
 
@@ -33,7 +33,7 @@ In this document:
   * the test driver has evolved as new scripts were added; you will see that
     older scripts are a little less sophisticated.
 
-<a name="quick_instructions_for_running_the_test_suite"></a>
+<a name="_quick_instructions_for_running_the_test_suite"></a>
 
 ### quick instructions for running the test suite
 
@@ -80,7 +80,7 @@ In this document:
         # or
         prove ./test-driver.sh :: t51
 
-<a name="instructions_for_adding_new_tests"></a>
+<a name="_instructions_for_adding_new_tests"></a>
 
 ### instructions for adding new tests