diff --git a/README.mkd b/README.mkd
index b0793d4..1f6c93e 100644
--- a/README.mkd
+++ b/README.mkd
@@ -1,60 +1,92 @@
 # gitolite
 
->   [Update 2009-10-28: apart from all the nifty new features, there's now an
->   "easy install" script in the src directory.  This script can be used to
->   install as well as upgrade a gitolite install.  Please see the INSTALL
->   document for details]
+Gitolite is an access control layer on top of git, which allows access control
+down to the branch level, including specifying who can and cannot *rewind* a
+given branch.
 
 ----
 
-Gitolite is a rewrite of gitosis, with a completely different config file that
-allows (at last!) access control down to the branch level, including
-specifying who can and cannot *rewind* a given branch.
-
 In this document:
 
-  * what
-  * why
-  * extra features
-  * security
-  * contact and license
+  * <a href="#A1">what</a>
+  * <a href="#A2">why</a>
+  * <a href="#A3">other features</a>
+  * <a href="#A4">security</a>
+  * <a href="#A5">contact and license</a>
 
 ----
 
+<a name="A1"></a>
+
 ### what
 
 Gitolite allows a server to host many git repositories and provide access to
-many developers, without having to give them real userids on the server.  The
-essential magic in doing this is ssh's pubkey access and the `authorized_keys`
-file, and the inspiration was an older program called gitosis.
+many developers, without having to give them real userids on or shell access
+to the server.  The essential magic in doing this is ssh's pubkey access and
+the `authorized_keys` file, and the inspiration was an older program called
+gitosis.
 
 Gitolite can restrict who can read from (clone/fetch) or write to (push) a
 repository.  It can also restrict who can push to what branch or tag, which is
 very important in a corporate environment.  Gitolite can be installed without
 requiring root permissions, and with no additional software than git itself
 and perl.  It also has several other neat features described below and
-elsewhere in the `doc/` directory.
+elsewhere in the [doc/][docs] directory.
+
+<a name="A2"></a>
 
 ### why
 
-I have been using gitosis for a while, and have learnt a lot from it.  But in
-a typical $DAYJOB setting, there are some issues:
+Gitolite is separate from git, and needs to be installed and configured.  So...
+why do we bother?
 
-  * it's not always Linux; you can't just "urpmi gitosis" (or yum or apt-get)
-    and be done
-  * often, "python-setuptools" isn't installed (and on a Solaris9 I was trying
-    to help remotely, we never did manage to install it eventually)
-  * you don't have root access, or the ability to add users (this is also true
-    for people who have just one userid on a hosting provider)
-  * the most requested feature (see below) had to be written anyway
+Gitolite is useful in any server that is going to host multiple git
+repositories, each with many developers, where some sort of access control is
+required.
 
-All of this pointed to a rewrite.  In perl, naturally :-)
+In theory, this can be done with plain old Unix permissions: each user is a
+member of one or more groups, each group "owns" one or more repositories, and
+using unix permissions (especially the setgid bit -- `chmod g+s`) you can
+allow/disallow users access to repos.
 
-### extra features
+But there are several disadvantages here:
+
+  * every user needs a userid and password on the server.  This is usually a
+    killer...!
+  * adding/removing access rights involves complex `usermod -G ...` mumblings
+    which most admins would rather not deal with, thanks to you-know-who
+  * *viewing* (aka auditing) the current set of permissions requires running
+    multiple commands to list directories and their permissions/ownerships,
+    users and their group memberships, and then correlating all these manually
+  * auditing historical permissions or permission changes is pretty much
+    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
+  * it is absolutely impossible to restrict pushing by branch name or tag
+    name.
+
+Gitolite does away with all this:
+
+  * it uses ssh magic to remove the need to give actual unix userids to
+    developers
+  * it uses a simple but powerful config file format to specify access rights
+  * access control changes are affected by modifying this file, adding or
+    removing user's public keys, and "compiling" the configuration
+  * this also makes auditing trivial -- all the data is in one place, and
+    changes to the configuration are also logged, so you can audit them.
+  * finally, the config file allows distinguishing between read-only and
+    read-write access, not only at the repository level, but at the branch
+    level within repositories.
+
+<a name="A3"></a>
+
+### other features
 
 The most important feature I needed was **per-branch permissions**.  This is
 pretty much mandatory in a corporate environment, and is almost the single
-reason I started *thinking* about rolling my own gitosis in the first place.
+reason I started *thinking* about writing gitolite.
 
 It's not just "read-only" versus "read-write".  Rewinding a branch (aka "non
 fast forward push") is potentially dangerous, but sometimes needed.  So is
@@ -63,28 +95,27 @@ something in between allowing anyone to do it (the default) and disabling it
 completely (`receive.denyNonFastForwards` or `receive.denyDeletes`).
 
 Here're **some more features**.  All of them, and more, are documented in
-detail [here][gsdiff].
+detail somewhere in gitolite's [doc/][docs] subdirectory.
 
-[gsdiff]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#diff
-
-  * simpler, yet far more powerful, config file syntax, including specifying
+  * simple, yet powerful, config file syntax, including specifying
     gitweb/daemon access.  You'll need this power if you manage lots of
     users+repos+combinations of access
   * apart from branch-name based restrictions, you can also restrict by
     file/dir name changed (i.e., output of `git diff --name-only`)
-  * config file syntax gets checked upfront, and much more thoroughly
   * if your requirements are still too complex, you can split up the config
     file and delegate authority over parts of it
-  * easier to specify gitweb owner, description and gitweb/daemon access
-  * easier to sync gitweb (http) authorisation with gitolite's access config
-  * more comprehensive logging [aka: management does not think "blame" is just
-    a synonym for "annotate" :-)]
+  * easy to specify gitweb owner, description and gitweb/daemon access
+  * easy to sync gitweb (http) authorisation with gitolite's access config
+  * comprehensive logging [aka: management does not think "blame" is just a
+    synonym for "annotate" :-)]
   * "personal namespace" prefix for each dev
   * migration guide and simple converter for gitosis conf file
   * "exclude" (or "deny") rights at the branch/tag level
   * specify repos using patterns (patterns may include creator's name)
   * define powerful operations on the server side, even github-like forking
 
+<a name="A4"></a>
+
 ### security
 
 Due to the environment in which this was created and the need it fills, I
@@ -105,9 +136,13 @@ details, looking for the word "security".
 
 ----
 
+<a name="A5"></a>
+
 ### contact and license
 
 Gitolite is released under GPL v2.  See COPYING for details.
 
 sitaramc@gmail.com
 mailing list: gitolite@googlegroups.com
+
+[docs]: http://github.com/sitaramc/gitolite/blob/pu/doc
diff --git a/contrib/autotoc b/contrib/autotoc
new file mode 100755
index 0000000..36a6f61
--- /dev/null
+++ b/contrib/autotoc
@@ -0,0 +1,28 @@
+#!/usr/bin/perl -w
+
+# filter gitolite's mkd files through this; it's designed to be idempotent of
+# course
+
+undef $/;
+$doc = <>;
+
+$doc =~ s/^<a name="A\d+"><\/a>\n\n//mg;
+
+@toc = $doc =~ /^###.*/mg;
+$i = 0;
+$doc =~ s/^###/$i++; "<a name=\"A$i\"><\/a>\n\n###"/mge;
+
+$i = 0;
+for (@toc) {
+    $i++;
+    s/### (.*)/  * <a href="#A$i">$1<\/a>/;
+    s/^(#+)/'    ' x length($1)/e;
+}
+
+$toc  = "In this document:\n\n";
+$toc .= join("\n", @toc);
+$toc .= "\n\n";
+
+$doc =~ s/^In this document:\n\n.*?\n\n/$toc/sm;
+
+print $doc;
diff --git a/doc/0-INSTALL.mkd b/doc/0-INSTALL.mkd
index a110431..c21d03c 100644
--- a/doc/0-INSTALL.mkd
+++ b/doc/0-INSTALL.mkd
@@ -1,193 +1,174 @@
-# installing gitolite
-
-[Update 2009-11-18: easy install now works from msysgit also!]
-
-Gitolite is somewhat unusual as far as "server" software goes -- every userid
-on the server is a potential "gitolite host".
-
-This document tells you how to install gitolite.  After the install is done,
-you may want to see [doc/2-admin.mkd][admin] for adding users, repos, etc.
-
-**Please note** that gitolite depends heavily on proper ssh setup and pubkey
-based access.  Sadly, most people don't know ssh as well as they think they
-do.  To make matters worse, ssh problems in gitolite don't always look like
-ssh problems.  Please read about [ssh troubleshooting][doc6] if you have *any*
-kind of trouble installing gitolite!
-
-[admin]: http://github.com/sitaramc/gitolite/blob/pu/doc/2-admin.mkd
-[doc6]: http://github.com/sitaramc/gitolite/blob/pu/doc/6-ssh-troubleshooting.mkd
+# gitolite installatation
 
 In this document:
 
-  * install methods
-  * user install
-      * typical example run
-      * advantages over the older install methods
-      * disadvantages
-      * upgrades
-      * other notes
-  * system install / user setup
-      * multiple gitolite instances
-  * next steps
-  * appendix A: server and client requirements for user install
-      * server
-      * install workstation
-      * admin workstation(s)
-  * appendix B: uninstalling gitolite
-  * appendix C: NOTE TO PACKAGE MAINTAINERS
+  * <a href="#A1">please read this first</a>
+      * <a href="#A2">important notes</a>
+      * <a href="#A3">conventions used</a>
+      * <a href="#A4">requirements</a>
+          * <a href="#A5">client side</a>
+          * <a href="#A6">server side</a>
+  * <a href="#A7">installation and setup</a>
+      * <a href="#A8">(package method) directly on the server, using RPM/DEB</a>
+      * <a href="#A9">(root method) directly on the server, manually, with root access</a>
+      * <a href="#A10">(non-root method) directly on the server, manually, without root access</a>
+      * <a href="#A11">(from-client method) install from the client to the server</a>
+  * <a href="#A12">special cases -- multiple gitolite instances</a>
+  * <a href="#A13">upgrading</a>
+  * <a href="#A14">uninstalling</a>
+      * <a href="#A15">cleaning out a botched install</a>
+      * <a href="#A16">uninstalling gitolite completely</a>
 
 ----
 
-### install methods
+<a name="A1"></a>
 
-There are 2 ways to install gitolite: The **user-install** mode was the
-traditional way, and is used when *any* of the following is true:
+### please read this first
 
-  * you don't have root on your "server" (some types of hosting setups, many
-    corporate paranoia setups ;-)
-  * your server distro does not have gitolite in its package repositories
-  * your server distro's package repositories have an old version of gitolite
-  * you want to stay current with the latest gitolite versions
-  * your server is not Linux (maybe AIX, or Solaris, etc.)
+<a name="A2"></a>
 
-The "user install" section describes this method.
+#### important notes
 
-The **system-install followed by user-setup** mode is used when you (or
-someone who has root) has installed an RPM or DEB of gitolite and you intend
-to use that version.  [Update 2010-04-27: there is now a script called
-`gl-system-install` that helps you do a system-install if your distribution
-does not yet have a package for gitolite; details below].
+Please make sure you understand the following points first.
 
-The "system install / user setup" section describes this method.
+  * gitolite is somewhat unusual as far as "server" software goes -- every
+    userid on the server is a potential "gitolite host".
 
-----
+  * gitolite depends **heavily** on ssh pubkey (passwordless) access.  Do not
+    assume you know all about ssh -- most people **don't**.  If in doubt, use
+    a dedicated userid on both client and server for installation and
+    administration of gitolite.
 
-### user install
+    To make matters worse, ssh problems in gitolite don't always look like ssh
+    problems.  See [doc/6-ssh-troubleshooting.mkd][doc6] for help.
 
-The `gl-easy-install` script makes installing very easy for this case.  **This
-script will setup everything on the server, but you have to run it on your
-workstation, NOT on the server!**
+<a name="A3"></a>
 
-Assumptions/pre-requisites:
+#### conventions used
 
-  * you have a server to host gitolite
-  * git is installed on that server (and so is perl)
-  * you have a userid on that server
-  * you have ssh-pubkey (**password-less**) login to that userid
-      * if you have only password access, run `ssh-keygen -t rsa` to create a
-        new keypair if needed, then run `ssh-copy-id user@host`.  If you do
-        not have `ssh-copy-id`, read doc/3-faq-tips-etc.mkd and look for
-        `ssh-copy-id` in that file for instructions
-  * you have a clone or an archive of gitolite somewhere on your workstation
-      * if you don't have one, just run `git clone git://github.com/sitaramc/gitolite`
-  * your workstation has bash (even msysgit bash will do)
+We assume the admin user is "sitaram", and his workstation is called "client".
+The hosting user is "git", and the server is called "server".  Substitute your
+values as needed.
 
-Once you have all this, just `cd` to that clone and run `src/gl-easy-install`
-and follow the prompts!  (Running it without any arguments shows you usage
-plus other useful info).
+<a name="A4"></a>
 
-#### typical example run
+#### requirements
 
-A typical run for me is:
+<a name="A5"></a>
 
-    src/gl-easy-install -q git my.git.server sitaram
+##### client side
 
-`-q` stands for "quiet" mode -- very minimal output, no verbose descriptions
-of what it is going to do, and no pauses unless absolutely needed.  However,
-if you're doing this for the first time or you appreciate knowing what it is
-actually doing, I suggest you skip the `-q`.
+  * git version 1.6.2 or greater
+      * even msysgit on Windows is fine; please don't ask me for help if
+        you're using putty, plink, puttygen, etc., for ssh; I recommend
+        msysgit for Windows and the openssh that comes with it
+  * if you're using the "from-client" method of install (see below), the bash
+    shell is needed
+      * again, msysgit on Windows is fine
 
-A detailed transcript of an install done using this method can be found in
-[doc/7-install-transcript.mkd][7it].
+<a name="A6"></a>
 
-[7it]: http://github.com/sitaramc/gitolite/blob/pu/doc/7-install-transcript.mkd
+##### server side
 
-#### advantages over the older install methods
+  * any Unix system with a posix compatible "sh".
+      * people using "csh" or derivatives please don't ask me for help -- tell
+        your admin csh is not posix compatible
+  * git version 1.6.2 or greater
+      * can be in a non-PATH location if you are unable to install it
+        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
 
-  * all ssh problems reduced to **just one pre-requisite**: enable ssh pubkey
-    (password-less) access to the server from your workstation first
-  * the script takes care of all the server side work
-  * when done:
-      * you get two different pubkeys (the original one for command line
-        access as before, plus a new one, created by the script, for gitolite
-        access)
-      * you can admin gitolite by commit+push a "gitolite-admin" repo, just
-        like gitosis (i.e., full "push to admin" power!)
+<a name="A7"></a>
 
-#### disadvantages
+### installation and setup
 
-  * need a recent bash
+<a name="A8"></a>
 
-#### upgrades
+#### (package method) directly on the server, using RPM/DEB
 
-Upgrading gitolite is easy.
+  * from your workstation, copy your `~/.ssh/id_rsa.pub` file to the server.
+    Put it in `/tmp/sitaram.pub`.
 
-To upgrade, pull the latest "master" (or other) branch in your gitolite repo
-clone, then run the same exact command you ran to do the install, except you
-can leave out the last argument.
+  * (U) on the server, as root, do the install (urpmi, yum, apt-get, etc.).
 
-And you might want to add a `-q` to speed things up :-)
+  * on the server, "su - git", then as "git" user, run `gl-setup
+    /tmp/sitaram.pub`.
 
-Note that this only upgrades the software.  Unlike earlier versions, it does
-**not** touch the `conf/gitolite.conf` file or the contents of `keydir` in any
-way.  I decided that it is not possible to **safely** let an upgrade do
-something meaningful with them -- fiddling with existing config files (as
-opposed to merely creating one which did not exist) is best left to a human.
+  * on the client, run `cd; git clone git@server:gitolite-admin`
 
-#### other notes
+<a name="A9"></a>
 
-  * if you run `src/gl-easy-install` without the `-q` option, you will be
-    given a chance to edit `~/.gitolite.rc`.  You can change any options (such
-    as paths, for instance), but be sure to keep the perl syntax -- you
-    *don't* have to know perl to do so, it's fairly easy to guess in this
-    limited case.
+#### (root method) directly on the server, manually, with root access
 
-----
+  * from your workstation, copy your `~/.ssh/id_rsa.pub` file to the server.
+    Put it in `/tmp/sitaram.pub`.
 
-### system install / user setup
+  * (U) on the server, as root, do the following:
 
-(Note: other than getting a public key from the admin's workstation,
-everything in this mode of install happens on the server).
+        cd $HOME
+        git clone git://github.com/sitaramc/gitolite gitolite-source
+        cd gitolite-source
+        mkdir -p /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks
+        src/gl-system-install /usr/local/bin /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks
 
-In this mode, the software is first installed system-wide, then the user runs
-a command to set up the hosting, supplying a public key.
+  * on the server, "su - git", then as "git" user, run `gl-setup
+    /tmp/sitaram.pub`.
 
-The root user can **install the software system-wide**, using either a package
-(rpm, deb, etc.), or by using the `gl-system-install` script.  (Run the script
-without any arguments for a brief usage message.  If that's not clear enough,
-read Appendix C below for details.)
+  * on the client, run `cd; git clone git@server:gitolite-admin`
 
-A normal user can then **set up the hosting** by running a command like this:
+<a name="A10"></a>
 
-    gl-setup adminname.pub
+#### (non-root method) directly on the server, manually, without root access
 
-where adminname.pub is a copy of a public key from that user's workstation.
+WARNING: if you use this method you'd better know enough about ssh to be able
+to keep your keys straight, and you'd also better have password access to the
+server so that if you screw up the keys you can still get on, or be able to
+"su - git" from some other user on the server.
 
-The first time this is run, it will create a "gitolite-admin" repo and
-populate it with the right configuration for whoever has the corresponding
-private key to clone and push it.  In other words, that person is the
-administrator for this particular gitolite instance.
+  * from your workstation, copy your `~/.ssh/id_rsa.pub` file to the server.
+    Put it in `/tmp/sitaram.pub`.
 
-If your system administrator upgrades gitolite itself, things will usually
-just work without any change; you should not normally have to do anything
-special.  However, some new features may require additional settings in your
-`~/.gitolite.rc` file.
+  * (U) on the server, as "git", do the following:
 
-Finally, in the rare case that you managed to lose your keys to the admin repo
-and want to supply a new pubkey, you can use this command to replace any such
-key.  Could be useful in an emergency -- just get your new "yourname.pub" to
-the server and run the same command as above.
+        cd $HOME
+        git clone git://github.com/sitaramc/gitolite gitolite-source
+        cd gitolite-source
+        mkdir -p $HOME/bin $HOME/share/gitolite/conf $HOME/share/gitolite/hooks
+        src/gl-system-install $HOME/bin $HOME/share/gitolite/conf $HOME/share/gitolite/hooks
 
-**IMPORTANT**: there are two variables in the `~/.gitolite.rc` file:
-`$GL_PACKAGE_CONF` and `$GL_PACKAGE_HOOKS`.  If you remove or change either of
-them, expect trouble :-)
+  * on the server, still as "git", run `gl-setup /tmp/sitaram.pub`.
 
-#### multiple gitolite instances
+  * if `$HOME/bin` is not on the default PATH, fiddle with your `.bashrc` or
+    `.bash_profile` files and add it somehow.  You can also try adding
+    `$GIT_PATH = "$ENV{HOME}/bin";` to `~/.gitolite.rc` on the server.
 
-With this mode of install, it's trivial to create multiple gitolite instances
-(say one for each department, on some mega company-wide server).  You can even
-do this without giving shell access to the admins.  Here's an example with
-just two "departments", and their admins Alice and Bob:
+  * on the client, run `cd; git clone git@server:gitolite-admin`
+
+<a name="A11"></a>
+
+#### (from-client method) install from the client to the server
+
+This used to be the most common install method for a long time, and it is
+still the one I use for most of my testing.  The **main advantage** of this
+method is that it **forces you** to solve the ssh pubkey problem **before**
+attempting to install.  Sadly, it also forces the admin to use a **different**
+URL for gitolite repos than normal users, which seems to confuse a heck of a
+lot of people who don't read the prominently displayed messages and/or the
+documentation.
+
+This method is verbosely documented in [doc/7-install-transcript.mkd][doc7],
+including *outputs* of the commands concerned.
+
+<a name="A12"></a>
+
+### special cases -- multiple gitolite instances
+
+With the first two methods (package or root methods) of installation, it's
+trivial to create multiple gitolite instances (say one for each department, on
+some mega company-wide server).  You can even do this without giving shell
+access to the admins.  Here's an example with just two "departments", and
+their admins Alice and Bob:
 
   * create userids `webbrowser_repos` and `webserver_repos`
   * ask Alice and Bob for their pubkeys; copy them to the respective home
@@ -204,195 +185,52 @@ to have a command line on the server, so don't give them the passwords if you
 don't need to -- the pubkey will allow them to be gitolite admins on their
 domain, and that's quite enough for normal operations.
 
-----
+<a name="A13"></a>
 
-### next steps
+### upgrading
 
-If you installed it using "gl-easy-install", the last message produced by that
-script should tell you how to add users, repos, etc.  In any case, you will
-find more details in [doc/2-admin.mkd][admin].
+Upgrading gitolite is easy.  In each method above, just re-do the step that is
+marked "(U)".  Also, if you're using either of the two methods that use the
+`src/gl-system-install` command, please make sure you give it the same
+arguments!
+
+Also, remember that some new features may require additional settings in your
+`~/.gitolite.rc` file.
+
+<a name="A14"></a>
+
+### uninstalling
+
+<a name="A15"></a>
+
+#### cleaning out a botched install
+
+When people have trouble installing gitolite, they often try to change a bunch
+of things manually on the server.  This usually makes things worse ;-) so
+here's how to clean the slate.
+
+  * client-side
+      * edit `~/.ssh/config` and delete the paragraph starting with `host
+        gitolite`, if present.
+      * remove `~/gitolite-admin`
+  * server-side
+      * edit `~/.ssh/authorized_keys` and delete all lines between `# gitolite
+        start` and `# gitolite end` inclusive.
+      * remove `~/.gitolite`, `~/.gitolite.rc` and
+        `~/repositories/gitolite-admin.git`
+
+<a name="A16"></a>
+
+#### uninstalling gitolite completely
+
+There's some duplication between this and the previous section, but
+uninstalling gitolite is described in great detail in
+[doc/9-uninstall.mkd][doc9unin]
 
 ----
 
-<a name="server_reqs"></a>
+[doc6]: http://github.com/sitaramc/gitolite/blob/pu/doc/6-ssh-troubleshooting.mkd
+[doc7]: http://github.com/sitaramc/gitolite/blob/pu/doc/7-install-transcript.mkd
+[doc9unin]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-uninstall.mkd
+[doc9ssh]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-ssh-tips.mkd
 
-### appendix A: server and client requirements for user install
-
-There are 3 machines *potentially* involved in installing and administering
-gitolite.
-
-#### server
-
-This is where gitolite is eventually installed.  You need a *normal* userid
-(typically "git" but can be anything) on this machine; root access is *not*
-needed, but it has to be some sort of Unix (not Windows).
-
-You need the following software on it:
-
-  * git
-      * can be in a non-PATH location if you are unable to install it
-        normally; see the `$GIT_PATH` variable in the "rc" file
-  * perl
-      * default install is fine; no special modules are needed
-      * (a normal install of git also requires/installs perl, so you probably
-        have it already)
-  * openssh server
-      * (I guess any ssh server that can understand the `authorized_keys` file
-        format should work)
-
-#### install workstation
-
-Installing or upgrading the gitolite software itself is best done by running
-the easy-install program from a gitolite clone.
-
-This script is heavily dependent on bash, so you need a machine with a bash
-shell.  Even the bash that comes with msysgit is fine, if you don't have a
-Linux box handy.
-
-If you have neither Linux nor Windows+msysgit, you still have a few
-alternatives:
-
-  * use a different userid on the same server (assuming it has bash)
-  * use the same userid on the same server (same assumption)
-  * manually simulate the script directly on the server (doable, but tedious)
-
-#### admin workstation(s)
-
-When you install gitolite, it creates a repository called "gitolite-admin" and
-gives you permissions on it.
-
-Administering gitolite (adding repos/users, assigning permissions, etc) is
-done by cloning this repo, making changes to a file called
-`conf/gitolite.conf`, adding users' pubkeys to `keydir/`, and pushing the
-changes back to the server.
-
-Which means all this can be done from *any* machine.  You'll normally do it
-from the same machine you used to install gitolite, but it doesn't have to be
-the same one, as long as your pubkey has been added and permissions given to
-allow you to push to the gitolite-admin repo.
-
-<a name="uninstall"></a>
-
-### appendix B: uninstalling gitolite
-
-Sometimes you might find gitolite is overkill -- you have only one user
-(yourself) pushing maybe.  Or maybe gitolite is just not enough -- you want a
-web-based front end that users can use to manage their keys themselves, etc.,
-in which case you'd probably switch to [github][g1], [girocco][g2],
-[indefero][g3] or [gitorious][g4].  [Gerrit][g5] is quite nice too, if you
-want collaborative code review there's nothing like it.  Either way, you'd
-like to uninstall gitolite.
-
-[g1]: http://github.com
-[g2]: http://repo.or.cz/w/girocco.git
-[g3]: http://www.indefero.net/
-[g4]: http://gitorious.com/
-[g5]: http://code.google.com/p/gerrit/
-
-Uninstalling gitolite is fairly easy, although it is manual.  (We'll assume
-`$REPO_BASE` in the rc file was left at its default of `~/repositories`; if
-not, adjust accordingly):
-
-**server side tasks**
-
-  * edit `~/.ssh/authorized_keys` and delete the `# gitolite start` and `#
-    gitolite end` markers and all the lines between them.  This will prevent
-    any of your users from attempting a push while you are doing this.
-
-    If you are the only user, and/or *need* one or more of those keys to
-    continue to access this account (like if one of them is your laptop or
-    your home desktop etc.) then instead of deleting the line you can just
-    delete everything upto but not including the words "ssh-rsa" or "ssh-dss".
-
-  * Now remove (or move aside or rename to something else if you're paranoid)
-    the following files and directories.
-
-        ~/.gitolite
-        ~/.gitolite.rc
-        ~/repositories/gitolite-admin.git
-
-  * You can remove all of `~/repositories` if you have not really started
-    using gitolite properly yet; that's your choice.
-
-    If you *do* need to preserve the other repos and continue to use them,
-    remove all the `update` hooks that git installs on each repository.  The
-    easiest way is:
-
-        find ~/repositories -wholename "*.git/hooks/update" | xargs rm -f
-
-    but you can do it manually if you want to be careful.
-
-**client side tasks**
-
-  * Any remote users that still have access must update their clone's remote
-    URLs (edit `.git/config` in the repo) to prefix `repositories/` before the
-    actual path used, in order for the remote to still work.  This is because
-    you'll now be accessing it through plain ssh, which means you have to give
-    it the full path.
-
-  * Finally, you as the gitolite admin will probably have a host stanza for
-    "gitolite" in your *client*'s `~/.ssh/config`.  Find and delete lines that
-    look like this:
-
-        host gitolite
-            user git
-            hostname your.server
-            port 22
-            identityfile ~/.ssh/your-gitolite-admin-username
-
-### appendix C: NOTE TO PACKAGE MAINTAINERS
-
-Here's how you'd package gitolite.  In the following description, location "X"
-can be, say, `/usr/share/gitolite/conf` or some such, and similarly location
-"Y" can be perhaps `/usr/share/gitolite/hooks`.  It's upto your distro
-policies where they are.
-
-**Step 1**: Clone the gitolite repo and run the make command inside the clone
-
-    git clone git://github.com/sitaramc/gitolite.git
-    cd gitolite
-    make pu.tar     # or "make master.tar" or "make v1.2.tar" etc
-
-Then you explode the tar file in some temporary location.
-
-*Alternatively, you can `git checkout` the tag or branch you want, and run
-this command in the clone directly*:
-
-    git describe --tags --long > conf/VERSION
-
-**Step 2**: Now make the following changes (no trailing slashes in the
-location values please):
-
-  * `src/gl-setup` should have the following line:
-
-        GL_PACKAGE_CONF="X"
-
-  * `conf/example.gitolite.rc` should have the following lines:
-
-        $GL_PACKAGE_CONF="X";
-        $GL_PACKAGE_HOOKS="Y";
-
-  * delete `src/gl-easy-install`; that script is meant for a totally different
-    mode of installation and does *not* play well in this mode :-)
-
-**Step 3**: Move (or arrange to move) the files to their proper locations as
-given below:
-
-  * everything in "src" goes somewhere on the PATH
-  * everything in "conf" goes to location "X"
-  * everything in "hooks" goes to location "Y"
-
-**Step 4**: There is no step 4.  Unless you count telling your users to run
-`gl-setup` as a step :)
-
-On the initial install (urpmi, yum install, or apt-get install), you could
-also choose to setup a userid called "gitolite", and run "gl-setup" as that
-user; however I do not know how you would come up with the initial pubkey that
-is needed.  Anyway, the point is that the "gitolite" user is no more special
-than any other in terms of hosting gitolite.  Any user can host gitolite on
-his userid by just running "gl-setup".
-
-When you upgrade, just overwrite all the files; it'll all just work.  In fact,
-other than the initial "gl-setup" run, the only time a gitolite hosting user
-has to actually do anything is to edit their own `~/.gitolite.rc` file if they
-want to enable or disable specific features.
diff --git a/doc/2-admin.mkd b/doc/2-admin.mkd
index 8eeaf2a..1770453 100644
--- a/doc/2-admin.mkd
+++ b/doc/2-admin.mkd
@@ -5,37 +5,39 @@
 
 In this document:
 
-  * administer
-      * adding users and repos
-      * moving pre-existing repos into gitolite
-      * specifying gitweb and daemon access
-      * custom hooks
-      * hook chaining
-      * custom git config
+  * <a href="#A1">please read this first</a>
+  * <a href="#A2">adding users and repos</a>
+  * <a href="#A3">other features</a>
+      * <a href="#A4">moving pre-existing repos into gitolite</a>
+      * <a href="#A5">specifying gitweb and daemon access</a>
+      * <a href="#A6">custom hooks</a>
+      * <a href="#A7">hook chaining</a>
+      * <a href="#A8">custom git config</a>
 
-### administer
+----
 
-First of all, ***do NOT add new repos manually***, unless you know how to add
-the required hook as well.  Without the hook, branch-level access control will
-not work for that repo, which sorta defeats the idea of using gitolite :-)
+<a name="A1"></a>
 
-Most normal (day-to-day) gitolite admin work is done by cloning the
-gitolite-admin repo from the server to your workstation, making changes to the
-clone, and pushing those changes back.
+### please read this first
 
-If you installed using "gl-easy-install", that script would have already tried
-to clone the repo to your `$HOME`.  Otherwise clone it yourself to any
-convenient location you like.
+  * ***do NOT add new repos manually***, unless you know how to add the
+    required hook as well.  Without the hook, branch-level access control will
+    not work for that repo, which sorta defeats the idea of using gitolite :-)
+
+  * most normal (day-to-day) gitolite admin work is done by cloning the
+    gitolite-admin repo from the server to your workstation, making changes to
+    the clone, and pushing those changes back.  The installation steps in
+    [doc/0-INSTALL.mkd][doc0] include the steps to do this clone if needed.
 
 Once you've cloned it, you're ready to add users and repos.
 
-#### adding users and repos
+<a name="A2"></a>
+
+### adding users and repos
 
   * ask each user who will get access to send you a public key.  See other
     sources (for example [here][genpub]) for how to do this
 
-[genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key
-
   * rename each public key according to the user's name, with a `.pub`
     extension, like `sitaram.pub` or `john-smith.pub`.  You can also use
     periods and underscores
@@ -48,7 +50,15 @@ Once you've cloned it, you're ready to add users and repos.
     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
+  * when done, commit your changes and push.  Any new repos you specified will
+    automatically be created (empty, but clonable) and users' access will be
+    updated as needed.
+
+<a name="A3"></a>
+
+### other features
+
+<a name="A4"></a>
 
 #### moving pre-existing repos into gitolite
 
@@ -69,6 +79,8 @@ gitolite:
     `conf/gitolite.conf` in your gitolite-admin repo clone.  Then add, commit,
     push.
 
+<a name="A5"></a>
+
 #### specifying gitweb and daemon access
 
 This is a feature that I personally do not use (corporate environments don't
@@ -105,6 +117,8 @@ The "compile" script will keep these files consistent with the config settings
 -- this includes removing such settings/files if you remove "read" permissions
 for the special usernames or remove the description line.
 
+<a name="A6"></a>
+
 #### custom hooks
 
 You can supply your own, custom, hook scripts if you wish.  Just put a
@@ -122,6 +136,8 @@ implements all the branch-level permissions in gitolite.  If you fiddle with
 the hooks directory, please make sure you do not mess with this file
 accidentally, or all your fancy per-branch permissions will stop working.**
 
+<a name="A7"></a>
+
 #### hook chaining
 
 Gitolite basically takes over the update hook for all repos, but some setups
@@ -143,6 +159,8 @@ Finally, these names (`update.secondary` and `post-update.secondary`) are
 merely the defaults.  You can change them to anything you want; look in
 conf/example.gitolite.rc for details.
 
+<a name="A8"></a>
+
 #### custom git config
 
 The custom hooks feature is a blunt instrument -- all repos get the hook you
@@ -164,3 +182,7 @@ basic forms of the "git config" command:
 
 It does not (currently) support other options like `--add`, the `value_regex`,
 etc.
+
+[doc0]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd
+[genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key
+
diff --git a/doc/3-faq-tips-etc.mkd b/doc/3-faq-tips-etc.mkd
index 34676aa..19670ce 100644
--- a/doc/3-faq-tips-etc.mkd
+++ b/doc/3-faq-tips-etc.mkd
@@ -2,43 +2,46 @@
 
 In this document:
 
-  * common errors and mistakes
-  * git version dependency
-  * other errors, warnings, notes...
-      * ssh-copy-id
-      * cloning an empty repo
-      * `@all` syntax for repos
-      * umask setting
-  * getting a tar file from a clone
-  * features
-      * syntax and normal usage
-          * simpler syntax
-          * one user, many keys
-      * security, access control, and auditing
-          * two levels of access rights checking
-          * better logging
-          * "exclude" (or "deny") rules
-          * separating delete and rewind rights
-          * file/dir NAME based restrictions
-          * delegating parts of the config file
-      * convenience features
-          * what repos do I have access to?
-          * error checking the config file
-          * including config lines from other files
-          * support for git installed outside default PATH
-          * "personal" branches
-          * custom hooks and custom git config
-      * helping with gitweb
-          * easier to specify gitweb "description" and gitweb/daemon access
-          * easier to link gitweb authorisation with gitolite
-      * advanced features
-          * repos named with wildcards
-          * admin defined commands
-          * access control for external commands
-  * design choices
-      * keeping the parser and the access control separate
+  * <a href="#A1">common errors and mistakes</a>
+  * <a href="#A2">git version dependency</a>
+  * <a href="#A3">other errors, warnings, notes...</a>
+      * <a href="#A4">cloning an empty repo</a>
+      * <a href="#A5">`@all` syntax for repos</a>
+      * <a href="#A6">umask setting</a>
+  * <a href="#A7">getting a tar file from a clone</a>
+  * <a href="#A8">features</a>
+      * <a href="#A9">syntax and normal usage</a>
+          * <a href="#A10">simpler syntax</a>
+          * <a href="#A11">one user, many keys</a>
+      * <a href="#A12">security, access control, and auditing</a>
+          * <a href="#A13">two levels of access rights checking</a>
+          * <a href="#A14">better logging</a>
+          * <a href="#A15">"exclude" (or "deny") rules</a>
+          * <a href="#A16">separating delete and rewind rights</a>
+          * <a href="#A17">file/dir NAME based restrictions</a>
+          * <a href="#A18">delegating parts of the config file</a>
+      * <a href="#A19">convenience features</a>
+          * <a href="#A20">what repos do I have access to?</a>
+          * <a href="#A21">including config lines from other files</a>
+          * <a href="#A22">support for git installed outside default PATH</a>
+          * <a href="#A23">"personal" branches</a>
+          * <a href="#A24">custom hooks and custom git config</a>
+      * <a href="#A25">helping with gitweb</a>
+          * <a href="#A26">easier to specify gitweb "description" and gitweb/daemon access</a>
+          * <a href="#A27">easier to link gitweb authorisation with gitolite</a>
+      * <a href="#A28">advanced features</a>
+          * <a href="#A29">repos named with wildcards</a>
+          * <a href="#A30">admin defined commands</a>
+          * <a href="#A31">access control for external commands</a>
+              * <a href="#A32">svnserve</a>
+  * <a href="#A33">design choices</a>
+      * <a href="#A34">keeping the parser and the access control separate</a>
 
-## common errors and mistakes
+----
+
+<a name="A1"></a>
+
+### common errors and mistakes
 
   * adding `repositories/` at the start of the repo name in the `git clone`.
     This error is typically made by the *admin* himself -- because he knows
@@ -60,36 +63,19 @@ In this document:
 
     Please see doc/6-ssh-troubleshooting.mkd for what all this means.
 
-## git version dependency
+<a name="A2"></a>
+
+### git version dependency
 
 Gitolite (on the server) now refuses to run if git is not at least 1.6.2.
 
-## other errors, warnings, notes...
+<a name="A3"></a>
 
-### ssh-copy-id
+### other errors, warnings, notes...
 
-don't have `ssh-copy-id`?  This is broadly what that command does, if you want
-to replicate it manually.  The input is your pubkey, typically
-`~/.ssh/id_rsa.pub` from your client/workstation.
+<a name="A4"></a>
 
-  * it copies it to the server as some file
-
-  * it appends that file to `~/.ssh/authorized_keys` on the server
-    (creating it if it doesn't already exist)
-
-  * it then makes sure that all these files/directories have go-w perms
-    set (assuming user is "git"):
-
-        /home/git/.ssh/authorized_keys
-        /home/git/.ssh
-        /home/git
-
-[Actually, `sshd` requires that even directories *above* `~` (`/`, `/home`,
-typically) also must be `go-w`, but that needs root.  And typically
-they're already set that way anyway.  (Or if they're not, you've got
-bigger problems than gitolite install not working!)]
-
-### cloning an empty repo
+#### cloning an empty repo
 
 Cloning an empty repo is only possible with clients greater than 1.6.2.  So at
 least one of your clients needs to have a recent git.  Once at least one
@@ -100,7 +86,9 @@ end hung up unexpectedly`.  However, you can ignore this, since it doesn't
 seem to hurt anything.  [Update 2009-09-14; this has been fixed in git
 1.6.4.3]
 
-### `@all` syntax for repos
+<a name="A5"></a>
+
+#### `@all` syntax for repos
 
 There *is* a way to use the `@all` syntax for repos also, as described in
 `conf/example.conf`.  However, there are a couple of minor cautions:
@@ -110,12 +98,16 @@ There *is* a way to use the `@all` syntax for repos also, as described in
     access, we do not support this.
   * don't try giving `@all` users some permission for `@all` repos
 
-### umask setting
+<a name="A6"></a>
+
+#### umask setting
 
 Gitweb not able to read your repos?  You can change the umask for newly
 created repos to something more relaxed -- see the `~/.gitolite.rc` file
 
-## getting a tar file from a clone
+<a name="A7"></a>
+
+### getting a tar file from a clone
 
 You can clone the repo from github or indefero, then execute a make command to
 extract a tar file of the branch you want.  Please use the make command, not a
@@ -131,17 +123,23 @@ plain "git archive", because the Makefile adds a file called
 
 <a name="features"></a>
 
-## features
+<a name="A8"></a>
+
+### features
 
 Apart from the big ones listed in the top level README, and subjective ones
 like "better config file format", gitolite has evolved to have many useful
-fearures than the original goal of "gitosis + branch-level access control".
+features than the original goal of branch-level access control.
 
-### syntax and normal usage
+<a name="A9"></a>
+
+#### syntax and normal usage
 
 <a name="simpler_syntax"></a>
 
-#### simpler syntax
+<a name="A10"></a>
+
+##### simpler syntax
 
 The basic syntax is simpler and cleaner but it goes beyond that: **you can
 specify access in bits and pieces**, even if they overlap.
@@ -186,7 +184,9 @@ See the "specify gitweb/daemon access" section below for one more example.
 
 <a name="multikeys"></a>
 
-#### one user, many keys
+<a name="A11"></a>
+
+##### one user, many keys
 
 I have a laptop and a desktop I need to access the server from.  I have
 different private keys on them, but as far as gitolite is concerned both of
@@ -229,16 +229,19 @@ corresponding derived usernames (which is what goes into the
         sitaramc@gmail.com@laptop.pub           sitaramc@gmail.com
         sitaramc@gmail.com@desktop.pub          sitaramc@gmail.com
 
-### security, access control, and auditing
+<a name="A12"></a>
+
+#### security, access control, and auditing
 
 <a name="two_levels"></a>
 
-#### two levels of access rights checking
+<a name="A13"></a>
+
+##### two levels of access rights checking
 
 Gitolite has two levels of access checks.  The **first check** is what I will
-call the **pre-git** level (this is the only check that gitosis has).  At this
-stage, the `gl-auth-command` has been invoked by `sshd`, and it knows just
-three things:
+call the **pre-git** level.  At this stage, the `gl-auth-command` has been
+invoked by `sshd`, and it knows just three things:
 
   * who,
   * what repository, and
@@ -268,7 +271,9 @@ any of the refexes match, the push succeeds.  If none of them match, it fails.
 Gitolite also allows "exclude" or "deny" rules.  See later in this document
 for details.
 
-#### better logging
+<a name="A14"></a>
+
+##### better logging
 
 If you have been too liberal with the permission to rewind, it has built-in
 logging as an emergency fallback if someone goes too far, or for audit
@@ -294,7 +299,9 @@ The other parts of the log line are the name of the repo, the refname being
 updated, the user updating it, and the refex pattern (from the config file)
 that matched, in case you need to debug the config file itself.
 
-#### "exclude" (or "deny") rules
+<a name="A15"></a>
+
+##### "exclude" (or "deny") rules
 
 Here is an illustrative explanation of "deny" rules.  However, please be sure
 to read the "DENY/EXCLUDE RULES" section in `conf/example.conf` for important
@@ -343,7 +350,9 @@ And here's how it works:
     before the third one, and it has a `-` as the permission, so the push
     fails
 
-#### separating delete and rewind rights
+<a name="A16"></a>
+
+##### separating delete and rewind rights
 
 Since the beginning, `RW+` meant being able to rewind *or* delete a ref.  My
 stand is that these two are fairly similar, and infact a rewind is almost the
@@ -380,7 +389,9 @@ message when you push, a non-existant user.
 
 [sdrr]: http://groups.google.com/group/gitolite/browse_thread/thread/9f2b4358ce406d4c#
 
-#### file/dir NAME based restrictions
+<a name="A17"></a>
+
+##### file/dir NAME based restrictions
 
 In addition to branch-name based restrictions, gitolite also allows you to
 restrict what files or directories can be involved in changes being pushed.
@@ -389,18 +400,24 @@ changed, treating each filename as a "ref" to be matched.
 
 Please see `conf/example.conf` for syntax and examples.
 
-#### delegating parts of the config file
+<a name="A18"></a>
+
+##### delegating parts of the config file
 
 You can now split up the config file and delegate the authority to specify
 access control for their own pieces.  See
 [doc/5-delegation.mkd](http://github.com/sitaramc/gitolite/blob/pu/doc/5-delegation.mkd)
 for details.
 
-### convenience features
+<a name="A19"></a>
+
+#### convenience features
 
 <a name="myrights"></a>
 
-#### what repos do I have access to?
+<a name="A20"></a>
+
+##### what repos do I have access to?
 
 Sometimes there are too many repos, maybe even named similarly, or with the
 potential for typos, confusion about hyphens/underscores or upper/lower case,
@@ -431,20 +448,15 @@ administrator can also say things like:
 
 to get this info for other user(s).
 
-#### error checking the config file
+<a name="A21"></a>
 
-gitosis does not do any.  I just found out that if you mis-spell `members` as
-`member`, gitosis will silently ignore it, and leave you wondering why access
-was denied.
-
-Gitolite "compiles" the config file first and keyword typos *are* caught so
-you know right away.
-
-#### including config lines from other files
+##### including config lines from other files
 
 See the entry under "INCLUDE SOME OTHER FILE" in `conf/example.conf`.
 
-#### support for git installed outside default PATH
+<a name="A22"></a>
+
+##### support for git installed outside default PATH
 
 The normal solution is to add to the system default PATH somehow, either by
 munging `/etc/profile` or by enabling `PermitUserEnvironment` in
@@ -476,7 +488,9 @@ the full PATH in the rc file, like so:
 
     $ENV{PATH} = "/home/sitaram/bin:$ENV{PATH}";
 
-#### "personal" branches
+<a name="A23"></a>
+
+##### "personal" branches
 
 "personal" branches are great for corporate environments, where
 unauthenticated pull/clone is a no-no.  Since a dev workstation cannot do
@@ -498,7 +512,9 @@ important thing is that the "branch" name should contain `/USER/` (including
 the slashes).  At runtime this will match whoever is the current user.  Access
 is still determined by the right hand side of course.
 
-#### custom hooks and custom git config
+<a name="A24"></a>
+
+##### custom hooks and custom git config
 
 You can specify hooks that you want to propagate to all repos, as well as
 per-repo "gitconfig" settings.  Please see `doc/2-admin.mkd` and
@@ -506,13 +522,17 @@ per-repo "gitconfig" settings.  Please see `doc/2-admin.mkd` and
 
 <a name="gitweb"></a>
 
-### helping with gitweb
+<a name="A25"></a>
+
+#### helping with gitweb
 
 Although gitweb is a completely separate program, gitolite can do quite a
 lot to help you manage gitweb access as well; once the initial setup is
 complete, you can do it all from within the gitolite config file!
 
-#### easier to specify gitweb "description" and gitweb/daemon access
+<a name="A26"></a>
+
+##### easier to specify gitweb "description" and gitweb/daemon access
 
 To enable access to a repo via gitweb *and* create a "description" for it to
 show up on the webpage, just add a line like this, anywhere in the config
@@ -561,7 +581,9 @@ Here's an example, using really short reponames because I'm lazy:
 
 <a name="gitwebauth"></a>
 
-#### easier to link gitweb authorisation with gitolite
+<a name="A27"></a>
+
+##### easier to link gitweb authorisation with gitolite
 
 Over and above whether a repo is even *shown* by gitweb, you may want to
 further restrict people, allowing them to view *only* those repos for which
@@ -595,18 +617,26 @@ Gitweb allows you to specify a subroutine to decide on access.  We use that
 feature and tie it to gitolite.  Configuration example can be found in
 `contrib/gitweb/`.
 
-### advanced features
+<a name="A28"></a>
 
-#### repos named with wildcards
+#### advanced features
+
+<a name="A29"></a>
+
+##### repos named with wildcards
 
 Please see `doc/4-wildcard-repositories.mkd` for all the details.
 
-#### admin defined commands
+<a name="A30"></a>
+
+##### admin defined commands
 
 This requires the wildcards feature to be enabled, but is then an extremely
 powerful feature.  See `doc/admin-defined-commands.mkd`.
 
-#### access control for external commands
+<a name="A31"></a>
+
+##### access control for external commands
 
 Gitolite now has a mechanism for allowing access control for arbitrary
 external commands, as long as they are invoked via ssh and present a
@@ -630,7 +660,9 @@ Commands implemented so far are:
 
 <a name="svnserve"></a>
 
-##### svnserve
+<a name="A32"></a>
+
+###### svnserve
 
 If you are transitioning from SVN to gitolite, and have a lot of users using
 public-key authentication with SVN, this feature may be useful to you. Once
@@ -640,9 +672,13 @@ system. Assuming you installed gitolite to the same user as the one you used
 for SVN, SVN connectivity will be retained, and users will be able to use
 both SVN and git using the same SSH configuration.
 
-## design choices
+<a name="A33"></a>
 
-### keeping the parser and the access control separate
+### design choices
+
+<a name="A34"></a>
+
+#### keeping the parser and the access control separate
 
 There are two programs concerned with access control:
 
diff --git a/doc/4-wildcard-repositories.mkd b/doc/4-wildcard-repositories.mkd
index 9837bfc..4393e5a 100644
--- a/doc/4-wildcard-repositories.mkd
+++ b/doc/4-wildcard-repositories.mkd
@@ -19,34 +19,42 @@ workarounds I may not have the time to code it right away.
 
 In this document:
 
-  * rc file setting required
-  * wildcard repos
-      * wildcard repos with creator name in them
-      * wildcard repos without creator name in them
-  * side-note: line-anchored regexes
-      * contrast with refexes
-  * handing out rights to wildcard-matched repos
-  * setting a gitweb description for a wildcard-matched repo
-  * reporting
-  * other issues and discussion
-  * how it actually works
+  * <a href="#A1">rc file setting required</a>
+  * <a href="#A2">Wildcard repos</a>
+      * <a href="#A3">Wildcard repos with creator name in them</a>
+      * <a href="#A4">Wildcard repos without creator name in them</a>
+  * <a href="#A5">Side-note: Line-anchored regexes</a>
+      * <a href="#A6">Contrast with refexes</a>
+  * <a href="#A7">Handing out rights to wildcard-matched repos</a>
+  * <a href="#A8">setting a gitweb description for a wildcard-matched repo</a>
+  * <a href="#A9">reporting</a>
+  * <a href="#A10">other issues and discussion</a>
+  * <a href="#A11">how it actually works</a>
+
+----
 
 This document is mostly "by example".
 
 ----
 
+<a name="A1"></a>
+
 ### rc file setting required
 
 This feature requires that you set `$GL_WILDREPOS` to "1" in `~/.gitolite.rc`
 on the server.  Please search for that variable and see comments around it in
 `conf/example.gitolite.rc` for more information on this.
 
+<a name="A2"></a>
+
 ### Wildcard repos
 
 Which of these alternatives you choose depends on your needs, and the social
 aspects of your environment.  The first one is a little more rigid, making it
 harder to make mistakes, and the second is more flexible and trusting.
 
+<a name="A3"></a>
+
 #### Wildcard repos with creator name in them
 
 Here's an example snippet:
@@ -71,6 +79,8 @@ new repo, as user "u4" (a student):
 
 Notice the *two* empty repo inits, and the order in which they occur ;-)
 
+<a name="A4"></a>
+
 #### Wildcard repos without creator name in them
 
 Here's how the same example would look if you did not want the CREATOR's name
@@ -96,6 +106,8 @@ and have a TA create the repos in advance.
 In either case, they could then use the `setperms` feature to specify which
 users are "READERS" and which are "WRITERS".  See later for details.
 
+<a name="A5"></a>
+
 ### Side-note: Line-anchored regexes
 
 A regex like
@@ -111,6 +123,8 @@ But you may be surprised to find that it does not match even
 `^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending
 metacharacters.
 
+<a name="A6"></a>
+
 #### Contrast with refexes
 
 Just for interest, note that this is in contrast to the refexes for the normal
@@ -121,6 +135,8 @@ if no one will actually push such a branch!  You can anchor both sides if you
 really care, by using `master$` instead of `master`, but that is *not* the
 default for refexes.
 
+<a name="A7"></a>
+
 ### Handing out rights to wildcard-matched repos
 
 In the examples above, we saw two special "user" names: READERS and WRITERS.
@@ -166,11 +182,15 @@ The following points are important:
   * whoever you specify as "R" will match the special user READERS.  "RW" will
     match WRITERS.
 
+<a name="A8"></a>
+
 ### setting a gitweb description for a wildcard-matched repo
 
 Similar to the getperm/setperm commands, there are the getdesc/setdesc
 commands, thanks to Teemu.
 
+<a name="A9"></a>
+
 ### reporting
 
 Remember the cool stuff you see when you just do `ssh git@server` (grep for
@@ -195,6 +215,8 @@ Push the config, then try
 
     ssh gitolite expand
 
+<a name="A10"></a>
+
 ### other issues and discussion
 
   * *what if the repo name being pushed matches more than one pattern*?
@@ -215,6 +237,8 @@ Push the config, then try
     of the time, it won't be difficult; the fixed prefix will usually be
     different anyway so there won't be overlaps.
 
+<a name="A11"></a>
+
 ### how it actually works
 
 This section tells you what is happening inside gitolite so you can understand
diff --git a/doc/5-delegation.mkd b/doc/5-delegation.mkd
index e3403ca..79864c0 100644
--- a/doc/5-delegation.mkd
+++ b/doc/5-delegation.mkd
@@ -2,6 +2,19 @@
 
 [Thanks to jeromeag for forcing me to think through this...]
 
+----
+
+In this document:
+
+  * <a href="#A1">lots of repos, lots of users</a>
+  * <a href="#A2">splitting up the set of repos into groups</a>
+  * <a href="#A3">delegating ownership of groups of repos</a>
+  * <a href="#A4">security/philosophy note</a>
+
+----
+
+<a name="A1"></a>
+
 ### lots of repos, lots of users
 
 Gitolite tries to make it easy to manage access to lots of users and repos,
@@ -34,6 +47,8 @@ access control rules for a set of repos they have been given authority for.
 It's easier to show how it all works with an example instead of long
 descriptions.
 
+<a name="A2"></a>
+
 ### splitting up the set of repos into groups
 
 To start with, recall that gitolite allows you to specify **groups** (of users
@@ -48,6 +63,8 @@ or repos, same syntax).  So the basic idea is that the main config file
     # any other config as usual, including access control lines for any of the
     # above projects or groups
 
+<a name="A3"></a>
+
 ### delegating ownership of groups of repos
 
 Once the repos are grouped, give each person charge of one or more groups.
@@ -100,7 +117,9 @@ to the bottom of the main file.
 
 ----
 
-### Security/Philosophy note
+<a name="A4"></a>
+
+### security/philosophy note
 
 The delegation feature is meant only for access control rules, not pubkeys.
 Adding/removing pubkeys is a much more significant event than changing branch
diff --git a/doc/6-ssh-troubleshooting.mkd b/doc/6-ssh-troubleshooting.mkd
index 83da139..697ed76 100644
--- a/doc/6-ssh-troubleshooting.mkd
+++ b/doc/6-ssh-troubleshooting.mkd
@@ -2,38 +2,44 @@
 
 In this document:
 
-  * the most common problems that an admin will see
-  * basic ssh troubleshooting
-      * passphrases versus passwords
-      * ssh-agent problems
-      * basic ssh troubleshooting for the main admin
-      * basic ssh troubleshooting for a normal user
-  * details
-      * files on the server
-      * files on client
-      * why two keys on client
-  * more complex ssh setups
-      * two gitolite servers to manage?
-  * giving shell access to gitolite users
+  * <a href="#A1">the most common problems that an admin will see</a>
+  * <a href="#A2">basic ssh troubleshooting</a>
+      * <a href="#A3">passphrases versus passwords</a>
+      * <a href="#A4">ssh-agent problems</a>
+      * <a href="#A5">basic ssh troubleshooting for the main admin</a>
+      * <a href="#A6">basic ssh troubleshooting for a normal user</a>
+  * <a href="#A7">details</a>
+      * <a href="#A8">files on the server</a>
+      * <a href="#A9">files on client</a>
+      * <a href="#A10">why two keys on client</a>
+  * <a href="#A11">some other tips and tricks</a>
+      * <a href="#A12">two gitolite servers to manage?</a>
+      * <a href="#A13">giving shell access to gitolite users</a>
+      * <a href="#A14">losing your admin key</a>
+      * <a href="#A15">simulating ssh-copy-id</a>
 
 ----
 
 This document should help you troubleshoot ssh-related problems in accessing
 gitolite *after* the install has completed successfully.
 
-In addition, I **strongly** recommend reading [this document][glb] -- it's a
-very detailed look at how gitolite uses ssh's features on the server side.
-Most people don't know ssh as well as they *think* they do; even if you don't
-have any problems right now, it's worth skimming over.
+In addition, I **strongly** recommend reading
+[doc/9-gitolite-and-ssh.mkd][doc9gas], which is a very detailed look at how
+gitolite uses ssh's features on the server side.  Most people don't know ssh
+as well as they *think* they do; even if you don't have any problems right
+now, it's worth skimming over.
 
 In addition to both these documents, there's now a program called
 `sshkeys-lint` that you can run on your client.  Run it without arguments to
 get help on how to run it and what inputs it needs.
 
+<a name="A1"></a>
+
 ### the most common problems that an admin will see
 
 Ironically, these problems **only** happen to the person who installed
-gitolite using easy-install, and has **utterly failed** to read/heed the
+gitolite using easy-install (the "from-client" method in
+[doc/0-INSTALL.mkd][doc0]), and has **utterly failed** to read/heed the
 message that shows up at the end of running that command.  This is because
 only the admin has *two* ssh keys to the server (see "basic ssh
 troubleshooting for the main admin" section below for more on this).
@@ -44,7 +50,9 @@ completely**:
   * you get `fatal: 'reponame' does not appear to be a git repository`, and
     yet you are sure 'reponame' exists, you haven't mis-spelled it, etc.
 
-  * you are able to clone repositories but are unable to push changes back.
+  * you are able to clone repositories but are unable to push changes back
+    (the error complains about the `GL_RC` environment variable not being set,
+    and the `hooks/update` failing in some way).
 
 Let us recap the message that appears on a successful run of the "easy-install"
 program; it looks something like this (with suitable values substituted for
@@ -77,9 +85,7 @@ the repo and clones ok.  But when you push, gitolite's **update hook** kicks
 in, and fails to run because you some of the environment variables it is
 expecting are not present.
 
-----
-
-<a name="basic"></a>
+<a name="A2"></a>
 
 ### basic ssh troubleshooting
 
@@ -92,6 +98,8 @@ username* of the admin.
 Unless specifically mentioned, all these commands are run on the user's or
 admin's workstation, not on the server.
 
+<a name="A3"></a>
+
 #### passphrases versus passwords
 
 When you create an ssh keypair, you have the option of protecting it with a
@@ -111,6 +119,8 @@ The second is to use `ssh-agent` (or `keychain`, which in turn uses
 `ssh-agent`) or something like that to manage your keys.  Other than the next
 section, further discussion of this is out of scope of this document.
 
+<a name="A4"></a>
+
 #### ssh-agent problems
 
 1.  Run `ssh-add -l`.  If this responds with either "The agent has no
@@ -135,6 +145,8 @@ all, ssh will only use those keys.  Even if you explicitly specify an unlisted
 key using `ssh -i` or an `identityfile` directive in the config file, it won't
 use it.
 
+<a name="A5"></a>
+
 #### basic ssh troubleshooting for the main admin
 
 You're the "main admin" if you're trying to access gitolite from the same
@@ -203,6 +215,8 @@ from scratch:
 
 That's a long sequence but it should work.
 
+<a name="A6"></a>
+
 #### basic ssh troubleshooting for a normal user
 
 For a normal user, life is much simpler.  They should have only one pubkey,
@@ -222,10 +236,14 @@ the admin repo, it won't work.  For reasons why, see below.
 
 <a name="details"></a>
 
+<a name="A7"></a>
+
 ### details
 
 Here's how it all hangs together.
 
+<a name="A8"></a>
+
 #### files on the server
 
   * the authkeys file; this contains one line containing the pubkey of each
@@ -256,6 +274,8 @@ Here's how it all hangs together.
     argument `sitaram`.  This is how gitolite is invoked, (and is told the
     user logging in is "sitaram").
 
+<a name="A9"></a>
+
 #### files on client
 
   * default keypair; used to get shell access to servers.  You would have
@@ -326,8 +346,13 @@ Here's how it all hangs together.
 
 <a name="twokeys"></a>
 
+<a name="A10"></a>
+
 #### why two keys on client
 
+[This section is only applicable to installs done using the "from-client"
+method; see [doc/0-INSTALL.mkd][doc0] for details].
+
 Why do I (the admin) need two **different** keypairs?
 
 There are two types of access the admin will make to the server: a normal
@@ -390,10 +415,11 @@ That should do it.
 
 <a name="complex"></a>
 
-### more complex ssh setups
+<a name="A11"></a>
 
-What do you need to know in order to create more complex ssh setups (for
-instance if you have *two* gitolite servers you are administering)?
+### some other tips and tricks
+
+<a name="A12"></a>
 
 #### two gitolite servers to manage?
 
@@ -415,9 +441,9 @@ instance if you have *two* gitolite servers you are administering)?
   * now access one server's repos as `gitolite:reponame.git` and the other
     server's repos as `gitolite2:reponame.git`.
 
-<a name="shell"></a>
+<a name="A13"></a>
 
-### giving shell access to gitolite users
+#### giving shell access to gitolite users
 
 We've managed (thanks to an idea from Jesse Keating) to make it possible for a
 single key to allow both gitolite access *and* shell access.
@@ -442,3 +468,41 @@ access would not manage to get himself shell access.
 
 Giving someone shell access requires that you should have shell access in the
 first place, so the simplest way is to enable it from the server side only.
+
+<a name="A14"></a>
+
+#### losing your admin key
+
+If you lost the admin key, and need to re-establish ownership of the
+gitolite-admin repository with a fresh key, take a look at the
+`src/gl-emergency-addkey` program.  You will need shell access to the server
+of course.  The top of the script has useful information on how to use it and
+what it needs.
+
+<a name="A15"></a>
+
+#### simulating ssh-copy-id
+
+don't have `ssh-copy-id`?  This is broadly what that command does, if you want
+to replicate it manually.  The input is your pubkey, typically
+`~/.ssh/id_rsa.pub` from your client/workstation.
+
+  * it copies it to the server as some file
+
+  * it appends that file to `~/.ssh/authorized_keys` on the server
+    (creating it if it doesn't already exist)
+
+  * it then makes sure that all these files/directories have go-w perms
+    set (assuming user is "git"):
+
+        /home/git/.ssh/authorized_keys
+        /home/git/.ssh
+        /home/git
+
+[Actually, `sshd` requires that even directories *above* `~` (`/`, `/home`,
+typically) also must be `go-w`, but that needs root.  And typically
+they're already set that way anyway.  (Or if they're not, you've got
+bigger problems than gitolite install not working!)]
+
+[doc0]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd
+[doc9gas]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-gitolite-and-ssh.mkd
diff --git a/doc/7-install-transcript.mkd b/doc/7-install-transcript.mkd
index 0127d46..3b5c6c7 100644
--- a/doc/7-install-transcript.mkd
+++ b/doc/7-install-transcript.mkd
@@ -15,20 +15,21 @@ Please note that this entire transcript can be summarised as:
 ...and only that last step is actually gitolite.  In fact, the bulk of the
 transcript is **non**-gitolite stuff :)
 
-----
+**Please also note that this method will setup everything on the server, but
+you have to run it on your workstation, NOT on the server!**
 
-### (cleaning out a botched install if needed)
+In this document:
 
-When people have trouble installing gitolite, they often try to change a bunch
-of things manually on the server.  This usually makes things worse ;-) so if
-you're reading this document as a follow-up to a failed install, please
-**first** clean out the botched install (instructions [here][appB]) and
-**then** continue with this document.
-
-[appB]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#uninstall
+  * <a href="#A1">create userids on server and client (optional)</a>
+  * <a href="#A2">get pubkey access from client to server</a>
+  * <a href="#A3">get gitolite source</a>
+  * <a href="#A4">install gitolite</a>
+  * <a href="#A5">examine what you have</a>
 
 ----
 
+<a name="A1"></a>
+
 ### create userids on server and client (optional)
 
 Client side: add user, give him a password
@@ -74,6 +75,8 @@ because I'm not showing the actual "vi" session):
 
 ----
 
+<a name="A2"></a>
+
 ### get pubkey access from client to server
 
 This involves creating a keypair for yourself (using `ssh-keygen`), and
@@ -123,6 +126,8 @@ Double check to make sure you can log on to `git@server` without a password:
 
 ----
 
+<a name="A3"></a>
+
 ### get gitolite source
 
     sita@sita-lt:~ $ git clone git://github.com/sitaramc/gitolite gitolite-source
@@ -133,6 +138,8 @@ Double check to make sure you can log on to `git@server` without a password:
     Receiving objects: 100% (1157/1157), 270.08 KiB | 61 KiB/s, done.
     Resolving deltas: 100% (756/756), done.
 
+<a name="A4"></a>
+
 ### install gitolite
 
 Note that gitolite is installed from the *client*.  The `easy-install` script
@@ -145,7 +152,6 @@ install sequence**.  </font> Run it without any arguments to see a usage
 message.  Run it without the `-q` to get a more verbose, pause-at-every-step,
 install mode that allows you to change the defaults etc.
 
-
     sita@sita-lt:src $ ./gl-easy-install -q git server sitaram
     you are upgrading     (or installing first-time)     to v0.95-38-gb0ce84d
     setting up keypair...
@@ -203,6 +209,8 @@ install mode that allows you to change the defaults etc.
 
 ----
 
+<a name="A5"></a>
+
 ### examine what you have
 
     sita@sita-lt:src $ cd ~/gitolite-admin/
diff --git a/doc/9-gitolite-and-ssh.mkd b/doc/9-gitolite-and-ssh.mkd
new file mode 100644
index 0000000..85db02c
--- /dev/null
+++ b/doc/9-gitolite-and-ssh.mkd
@@ -0,0 +1,155 @@
+# how gitolite uses ssh
+
+Here's a secret: ***gitolite uses far more ssh magic than git magic***!
+
+Most people didn't realise this, and even if they did they didn't know ssh
+well enough to help themselves.  If you don't understand how ssh public key
+authentication works, or how the `~/.ssh/authorized_keys` file can be used to
+restrict users, etc., you will have endless amounts of trouble getting
+gitolite to work, because you'll be attacking the wrong problem.
+
+So please please please understand this before tearing your hair out and
+blaming ***git/gitolite*** for whatever is going wrong with your setup :-)
+
+In this document:
+
+  * <a href="#A1">ssh basics</a>
+  * <a href="#A2">how does gitolite use all this ssh magic?</a>
+      * <a href="#A3">restricting shell access/distinguishing one user from another</a>
+      * <a href="#A4">restricting branch level actions</a>
+
+----
+
+<a name="A1"></a>
+
+### ssh basics
+
+Let's start with some basics, focusing *only* on the pieces relevant to
+`gitolite`.  If this is not detailed enough, please use google and learn more
+from somewhere, or maybe buy the OReilly ssh book.
+
+  * You can login to an ssh server by typing a password, but ssh can also use
+    ***public-private keys*** (also called "key pairs") for authentication.
+    `gitolite` *requires* you to use this mechanism for your users -- they
+    cannot log in using passwords.  Hopefully by the time you finish reading
+    this document you will understand why :-)
+
+    The way you set this up is you generate a key pair on your workstation,
+    and give the server the public key.  (I need not add that the "private"
+    key must be, well, kept *private*!)
+
+  * **generating a key pair on your workstation** is done by running the
+    command `ssh-keygen -t rsa`.  This produces two files in `~/.ssh`.  One is
+    `id_rsa`; this is the **private** key -- ***never*** let it out of your
+    machine.  The other is `id_rsa.pub`, which is the corresponding public
+    key.  This public key is usually just one long line of text.
+
+    * on Windows machines with msysgit installed, you should do this from
+      within a "git bash" window.  The command will report the full path where
+      the files have been written; make a note of this, and use those files in
+      any of the description that follows
+
+  * **adding your public key to the server**'s `~/.ssh/authorized_keys`
+    file is how ssh uses pubkeys to authenticate users.  Let's say
+    sita@work.station is trying to log in as git@serv.er.  What you have to do
+    is take the `~/.ssh/id_rsa.pub` file for user sita on work.station and
+    append its contents (remember it's only one line) to
+    `~/.ssh/authorized_keys` for user git on serv.er.
+
+    The `authorized_keys` file can have multiple public keys (from many
+    different people) added to it so any of them can log in to git@serv.er.
+
+    In the normal case (not gitolite, but your normal everyday shell access),
+    there's a command that does this, `ssh-copy-id`, which also fixes up
+    permissions etc., as needed, since sshd is a little picky about allowing
+    pubkey access if permissions on the server are loose.  Or you can do it
+    manually, as long as you know what you're doing and you're careful not to
+    erase or overwrite the existing contents of `~/.ssh/authorized_keys` on
+    the server!
+
+    But in the gitolite case, it's different; we'll get to that in a minute.
+
+    * **troubleshooting pubkey authentication failures**: if you are unable to
+      get ssh access to the server after doing all this, you'll have to look
+      in `/var/log/secure` or `/var/log/auth.log` or some such file on the
+      server to see what specific error `sshd` is complaining about.
+
+  * **restricting users to specific commands** is very important for gitolite.
+    If you read `man sshd` and look for `authorized_keys file format`, you'll
+    see a lot of options you can add to the public key line, which restrict
+    the incoming user in various ways.  In particular, note the `command=`
+    option, which means "regardless of what the incoming user is asking to do,
+    forcibly run this command instead".
+
+    Also note that when there are many public keys (i.e., lines) in the
+    `authorized_keys` file, each line can have a *different* set of options
+    and `command=` values.
+
+    **This is the backbone of what makes gitolite work; please make sure you
+    understand this**
+
+<a name="A2"></a>
+
+### how does gitolite use all this ssh magic?
+
+These are two different questions you ought to be having by now: 
+
+  * how does it distinguish between me and someone else, since we're all
+    logging in as the same remote user "git"
+  * how does it restrict what I can do within a repository
+
+<a name="A3"></a>
+
+#### restricting shell access/distinguishing one user from another
+
+The answer to the first question is the `command=` we talked about before.  If
+you look in the `authorized_keys` file, you'll see entries like this (I chopped
+off the ends of course; they're pretty long lines):
+
+    command="[path]/gl-auth-command sitaram",[more options] ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA18S2t...
+    command="[path]/gl-auth-command usertwo",[more options] ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEArXtCT...
+
+First, it finds out which of the public keys in this file match the incoming
+login.  That's crypto stuff, and I won't go into it.  Once the match has been
+found, it will run the command given on that line; e.g., if I logged in, it
+would run `[path]/gl-auth-command sitaram`.  So the first thing to note is
+that such users do not get "shell access", which is good!
+
+Before running the command, however, sshd sets up an environment variable
+called `SSH_ORIGINAL_COMMAND` which contains the actual git command that your
+workstation sent out.  This is the command that *would have run* if you did
+not have the `command=` part in the authorised keys file.
+
+When `gl-auth-command` gets control, it looks at the first argument
+("sitaram", "usertwo", etc) to determine who you are.  It then looks at the
+`SSH_ORIGINAL_COMMAND` variable to find out which repository you want to
+access, and whether you're reading or writing.
+
+Now is has user, repository, and access requested (read/write), gitolite looks
+at its config file, and either allows or rejects the request.
+
+But this cannot differentiate between different branches within a repo; that
+has to be done separately.
+
+<a name="A4"></a>
+
+#### restricting branch level actions
+
+[If you look inside the git source tree, there's a file among the "howto"s in
+there called `update-hook-example.txt`, which was the inspiration for this
+part of gitolite.]
+
+Git allows you to specify many "hooks", which get control as various events
+happen -- see `git help hooks` for details.  One of those hooks is the
+`update` hook, which, if it is present, is invoked just before a branch or a
+tag is about to be updated.  The hook is passed the name of the branch or tag,
+the old SHA1 value, and the new SHA1 value, as arguments.  Hooks that are
+called *before* an action happens are allowed to prevent that action from
+happening y returning an error code.
+
+When gitolite is told to create a new repository (by the admin), it installs
+a special update hook.  This hook takes all the information presented, looks
+at the config file, and decides to allow or reject the update.
+
+And that's basically it.
+
diff --git a/doc/9-packaging.mkd b/doc/9-packaging.mkd
new file mode 100644
index 0000000..8b51d72
--- /dev/null
+++ b/doc/9-packaging.mkd
@@ -0,0 +1,56 @@
+# packaging gitolite
+
+Here's how you'd package gitolite.  In the following description, location "X"
+can be, say, `/usr/share/gitolite/conf` or some such, and similarly location
+"Y" can be perhaps `/usr/share/gitolite/hooks`.  It's upto your distro
+policies where they are.
+
+**Step 1**: Clone the gitolite repo and run the make command inside the clone
+
+    git clone git://github.com/sitaramc/gitolite.git
+    cd gitolite
+    make pu.tar     # or "make master.tar" or "make v1.2.tar" etc
+
+Then you explode the tar file in some temporary location.
+
+*Alternatively, you can `git checkout` the tag or branch you want, and run
+this command in the clone directly*:
+
+    git describe --tags --long > conf/VERSION
+
+**Step 2**: Now make the following changes (no trailing slashes in the
+location values please):
+
+  * `src/gl-setup` should have the following line:
+
+        GL_PACKAGE_CONF="X"
+
+  * `conf/example.gitolite.rc` should have the following lines:
+
+        $GL_PACKAGE_CONF="X";
+        $GL_PACKAGE_HOOKS="Y";
+
+  * delete `src/gl-easy-install`; that script is meant for a totally different
+    mode of installation and does *not* play well in this mode :-)
+
+**Step 3**: Move (or arrange to move) the files to their proper locations as
+given below:
+
+  * everything in "src" goes somewhere on the PATH
+  * everything in "conf" goes to location "X"
+  * everything in "hooks" goes to location "Y"
+
+**Step 4**: There is no step 4.  Unless you count telling your users to run
+`gl-setup` as a step :)
+
+On the initial install (urpmi, yum install, or apt-get install), you could
+also choose to setup a userid called "gitolite", and run "gl-setup" as that
+user; however I do not know how you would come up with the initial pubkey that
+is needed.  Anyway, the point is that the "gitolite" user is no more special
+than any other in terms of hosting gitolite.  Any user can host gitolite on
+his userid by just running "gl-setup".
+
+When you upgrade, just overwrite all the files; it'll all just work.  In fact,
+other than the initial "gl-setup" run, the only time a gitolite hosting user
+has to actually do anything is to edit their own `~/.gitolite.rc` file if they
+want to enable or disable specific features.
diff --git a/doc/9-uninstall.mkd b/doc/9-uninstall.mkd
new file mode 100644
index 0000000..9cbe829
--- /dev/null
+++ b/doc/9-uninstall.mkd
@@ -0,0 +1,67 @@
+# uninstalling gitolite
+
+Sometimes you might find gitolite is overkill -- you have only one user
+(yourself) pushing maybe.  Or maybe gitolite is just not enough -- you want a
+web-based front end that users can use to manage their keys themselves, etc.,
+in which case you'd probably switch to [github][g1], [girocco][g2],
+[indefero][g3] or [gitorious][g4].  [Gerrit][g5] is quite nice too, if you
+want collaborative code review there's nothing like it.  Either way, you'd
+like to uninstall gitolite.
+
+[g1]: http://github.com
+[g2]: http://repo.or.cz/w/girocco.git
+[g3]: http://www.indefero.net/
+[g4]: http://gitorious.com/
+[g5]: http://code.google.com/p/gerrit/
+
+Uninstalling gitolite is fairly easy, although it is manual.  (We'll assume
+`$REPO_BASE` in the rc file was left at its default of `~/repositories`; if
+not, adjust accordingly):
+
+**server side tasks**
+
+  * edit `~/.ssh/authorized_keys` and delete the `# gitolite start` and `#
+    gitolite end` markers and all the lines between them.  This will prevent
+    any of your users from attempting a push while you are doing this.
+
+    If you are the only user, and/or *need* one or more of those keys to
+    continue to access this account (like if one of them is your laptop or
+    your home desktop etc.) then instead of deleting the line you can just
+    delete everything upto but not including the words "ssh-rsa" or "ssh-dss".
+
+  * Now remove (or move aside or rename to something else if you're paranoid)
+    the following files and directories.
+
+        ~/.gitolite
+        ~/.gitolite.rc
+        ~/repositories/gitolite-admin.git
+
+  * You can remove all of `~/repositories` if you have not really started
+    using gitolite properly yet; that's your choice.
+
+    If you *do* need to preserve the other repos and continue to use them,
+    remove all the `update` hooks that git installs on each repository.  The
+    easiest way is:
+
+        find ~/repositories -wholename "*.git/hooks/update" | xargs rm -f
+
+    but you can do it manually if you want to be careful.
+
+**client side tasks**
+
+  * Any remote users that still have access must update their clone's remote
+    URLs (edit `.git/config` in the repo) to prefix `repositories/` before the
+    actual path used, in order for the remote to still work.  This is because
+    you'll now be accessing it through plain ssh, which means you have to give
+    it the full path.
+
+  * Finally, you as the gitolite admin will probably have a host stanza for
+    "gitolite" in your *client*'s `~/.ssh/config`.  Find and delete lines that
+    look like this:
+
+        host gitolite
+            user git
+            hostname your.server
+            port 22
+            identityfile ~/.ssh/your-gitolite-admin-username
+
diff --git a/doc/TODO b/doc/TODO
deleted file mode 100644
index 9c6faef..0000000
--- a/doc/TODO
+++ /dev/null
@@ -1,3 +0,0 @@
-  * make a proper test suite
-
-  * change the "rc" file to use "gitconfig" instead...
diff --git a/doc/admin-defined-commands.mkd b/doc/admin-defined-commands.mkd
index a1d1b89..969f420 100644
--- a/doc/admin-defined-commands.mkd
+++ b/doc/admin-defined-commands.mkd
@@ -11,16 +11,18 @@ There may be other such **WARNING** sections below.  **Read all of them**.
 
 In this document:
 
-  * background
-  * setting it up
-  * anatomy of a command
-  * example uses and sample commands in contrib
-      * fork
-      * rmrepo
-      * (bonus) restricted admin
+  * <a href="#A1">background</a>
+  * <a href="#A2">setting it up</a>
+  * <a href="#A3">anatomy of a command</a>
+  * <a href="#A4">example uses and sample commands in contrib</a>
+      * <a href="#A5">fork</a>
+      * <a href="#A6">rmrepo</a>
+      * <a href="#A7">(bonus) restricted admin</a>
 
 ----
 
+<a name="A1"></a>
+
 ### background
 
 Gitolite was named to be short for "gitosis-lite".  Someone now wants to turn
@@ -59,6 +61,8 @@ What we want now is more than that, as you'll see in the examples below.  And
 I'm sure if you think of more uses you'll send them to me as "contrib"
 entries, right?
 
+<a name="A2"></a>
+
 ### setting it up
 
 This can only be setup by someone who has shell access to the server.  Edit
@@ -77,6 +81,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="A3"></a>
+
 ### anatomy of a command
 
 You can basically do whatever you want in such a command -- go wild!  It's
@@ -130,8 +136,12 @@ convenient.  See any of the other samples for how to use it.
 If you don't like this, roll your own.  If you don't like bash, do the eqvt in
 your language of choice.
 
+<a name="A4"></a>
+
 ### example uses and sample commands in contrib
 
+<a name="A5"></a>
+
 #### fork
 
 A user would use the fork command like this:
@@ -165,6 +175,8 @@ So now we have an actual command to just create a repo and do nothing else:
 `ssh git@server git-init \'reponame\'`.  [Yes; those single quotes are
 required.  Deal with it.]
 
+<a name="A6"></a>
+
 #### rmrepo
 
 This is one thing that you really could not do before this setup was created.
@@ -175,6 +187,8 @@ Use it like this:
 The script checks to make sure that the repo being deleted was *created* by
 the user invoking it.
 
+<a name="A7"></a>
+
 #### (bonus) restricted admin
 
 It's rather important to me (and presumably others in the "corporate" world)
diff --git a/doc/big-config.mkd b/doc/big-config.mkd
index 5965aca..5531167 100644
--- a/doc/big-config.mkd
+++ b/doc/big-config.mkd
@@ -2,11 +2,13 @@
 
 In this document:
 
-  * when/why do we need it?
-  * how do we use it?
-  * summary of settings in RC file
-  * what are the downsides?
-  * (extra coolness) usergroups and LDAP/similar tools
+  * <a href="#A1">when/why do we need it?</a>
+  * <a href="#A2">how do we use it?</a>
+  * <a href="#A3">summary of settings in RC file</a>
+  * <a href="#A4">what are the downsides?</a>
+  * <a href="#A5">(extra coolness) usergroups and LDAP/similar tools</a>
+
+<a name="A1"></a>
 
 ### when/why do we need it?
 
@@ -93,6 +95,8 @@ Phew!
 You can imagine what that does when you have 10,000 users and 10,000 repos.
 Let's just say it's not pretty :)
 
+<a name="A2"></a>
+
 ### how do we use it?
 
 Now, if you had all those 10,000 users and repos explicitly listed (no
@@ -138,6 +142,8 @@ configuration, the compiled file looks like this:
 That's a lot smaller, and allows orders of magintude more repos and groups to
 be supported.
 
+<a name="A3"></a>
+
 ### summary of settings in RC file
 
 The default RC file contains the following lines:
@@ -156,6 +162,8 @@ you push the gitolite-admin repo with changes.
 
 [gw]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gitweb
 
+<a name="A4"></a>
+
 ### what are the downsides?
 
 There is one minor issue.
@@ -168,6 +176,8 @@ subset of the allowed @fragname, which would work normally, do not work now).
 (If you didn't understand all that, you're probably not using delegation, so
 feel free to ignore it!)
 
+<a name="A5"></a>
+
 ### (extra coolness) usergroups and LDAP/similar tools
 
 [Please NOTE: this is all about *user* groups, not *repo* groups]
diff --git a/doc/progit-article.mkd b/doc/progit-article.mkd
index 916faf6..8d7fa4f 100644
--- a/doc/progit-article.mkd
+++ b/doc/progit-article.mkd
@@ -2,7 +2,7 @@
 
 Git has started to become very popular in corporate environments, which tend to have some additional requirements in terms of access control.  Gitolite was created to help with those requirements.
 
-Gitolite allows you to specify permissions not just by repository (like Gitosis does), but also by branch or tag names within each repository.  That is, you can specify that certain people (or groups of people) can only push certain "refs" (branches or tags) but not others.
+Gitolite allows you to specify permissions not just by repository, but also by branch or tag names within each repository.  That is, you can specify that certain people (or groups of people) can only push certain "refs" (branches or tags) but not others.
 
 ### Installing ###
 
@@ -25,7 +25,7 @@ Next, you clone Gitolite from the project's main site and run the "easy install"
 	$ cd gitolite/src
 	$ ./gl-easy-install -q gitolite gitserver sitaram
 
-And you're done!  Gitolite has now been installed on the server, and you now have a brand new repository called `gitolite-admin` in the home directory of your workstation.  You administer your gitolite setup by making changes to this repository and pushing (just like Gitosis).
+And you're done!  Gitolite has now been installed on the server, and you now have a brand new repository called `gitolite-admin` in the home directory of your workstation.  You administer your gitolite setup by making changes to this repository and pushing.
 
 [By the way, *upgrading* gitolite is also done the same way.  Also, if you're interested, run the script without any arguments to get a usage message.]
 
@@ -57,7 +57,7 @@ So once the install is done, you switch to the `gitolite-admin` repository (plac
 
 Notice that "sitaram" (the last argument in the `gl-easy-install` command you gave earlier) has read-write permissions on the `gitolite-admin` repository as well as a public key file of the same name.
 
-The config file syntax for Gitolite is *quite* different from Gitosis.  Again, this is liberally documented in `conf/example.conf`, so we'll only mention some highlights here.
+The config file syntax for gitolite is liberally documented in `conf/example.conf`, so we'll only mention some highlights here.
 
 You can group users or repos for convenience.  The group names are just like macros; when defining them, it doesn't even matter whether they are projects or users; that distinction is only made when you *use* the "macro".
 
@@ -90,7 +90,7 @@ That rule will just get added to the ruleset for the `gitolite` repository.
 
 At this point you might be wondering how the access control rules are actually applied, so let's go over that briefly.
 
-There are two levels of access control in gitolite.  The first is at the repository level; if you have read (or write) access to *any* ref in the repository, then you have read (or write) access to the repository.  This is the only access control that Gitosis had.
+There are two levels of access control in gitolite.  The first is at the repository level; if you have read (or write) access to *any* ref in the repository, then you have read (or write) access to the repository.
 
 The second level, applicable only to "write" access, is by branch or tag within a repository.  The username, the access being attempted (`W` or `+`), and the refname being updated are known.  The access rules are checked in order of appearance in the config file, looking for a match for this combination (but remember that the refname is regex-matched, not merely string-matched).  If a match is found, the push succeeds.  A fallthrough results in access being denied.