doc fixes:

- install is even clearer now (I hope!), esp to people with root
    access who seem to expect something else :)
  - used path vars (from ~/.gitolite.rc) more consistently, and
  - added refeerences to ~/.gitolite.rc for resolving them

doc/0-INSTALL.mkd

@@ -2,47 +2,54 @@
 
 ### pre-requisites
 
-One of the big needs I'm trying to fill here is people who do not have root
+If you managed to install git, you might already have what gitolite needs:
-access, permissions to create other userids, etc.  This could be a typical
-hosting provider type of thing, or -- in a corporate setting -- a very tightly
-controlled server.
-
-Gitolite requires these:
 
   * git itself, the more recent the better
   * perl, typically installed with git, since git sort of needs it; any
     version that includes `Data::Dumper`[1] will do.
   * one user account on the server, with password access [2]
 
+A major objective is to allow use by people without root access, permissions
+to create other userids, etc.  If you have root, congratulations and all that,
+but go add a user just for gitolite and do all this from that user.  Really.
+I see no earthly reason for this to run as root.
+
+And don't bug me about wanting to install it in `/opt` or whatever if you
+haven't the time to read the docs or change a path in a config file.
+
 ### quick install
 
-I assume all the files pertaining to this software are untarred and available
+  * cd to the directory where you unpacked the source
-in the current directory.
+  * run `src/install.pl` and follow the prompts
 
-A quick install, taking all the defaults, can be done with the `install.sh`
+**When you are told to edit some file, please read the comments in the file**.
-script in the `src` directory.
+And if you can make some time to read the documentation, please do.
+Especially if you have problems.
 
-Note:
+Notes:
 
   * At present the location of `~/.gitolite.rc` is fixed (maybe later I'll
-    change it to a "git config" variable).
+    change it to a "git config" variable but I don't see much need right now)
 
     If you edit it and change any paths, 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.  And of course, make sure you adjust the commands shown
     above to suit the new locations
 
-  * the config file is (by default) at `~/.gitolite/conf/gitolite.conf`.
+  * the config file is (by default) at `~/.gitolite/conf/gitolite.conf`,
-    Edit the file as you wish.  The comments in the file ought to be clear
+    though you can change its location in the "rc" file.  Edit the file as you
-    enough but let me know if not
+    wish.  The comments in the file ought to be clear enough but let me know
+    if not
 
   * if you want to bring in existing (bare, server) repos into gitolite, this
-    should work:
+    should work (refer to `~/.gitolite.rc` for *your* values of the pathnames
+    below):
       * backup the repo, then move it to `$BASE_REPO`
       * copy `$GL_ADMINDIR/src/update-hook.pl` to
         `[reponame].git/hooks/update` -- if you don't do this, per branch
         restrictions will not work
-      * then update the keys and the config file and "compile"
+      * then update the keys and the config file and "compile" (see "admin"
+        document)
 
 ### Footnotes:
 

doc/1-migrate.mkd

@@ -7,7 +7,8 @@ the same.  The differences are:
     You can choose to version that directory but it is not required that you
     do so
 
-Here's how we migrated my work repos:
+Here's how we migrated my work repos (note: substitute real paths, from your
+`~/.gitolite.rc`, for `$REPO_BASE` and `$GL_ADMINDIR` below):
 
 1.  login as the `git` user on the server, and get a bash shell prompt
 
@@ -18,7 +19,7 @@ Here's how we migrated my work repos:
 3.  For added safety, **delete** the post-update hook that gitosis-admin
     installed
 
-        rm ~/repositories/gitosis-admin.git/hooks/post-update
+        rm $REPO_BASE/gitosis-admin.git/hooks/post-update
 
     or at least rename it to `.sample` like all the other hooks hanging
     around, or edit it and comment out the line that calls `gitosis-run-hook
@@ -27,31 +28,29 @@ Here's how we migrated my work repos:
     If you do not do this, an accidental push to the gitosis-admin repo will
     mess up your `~/.ssh/authorized_keys` file
 
-4.  take a **backup** of the `~/repositories` directory
+4.  take a **backup** of the `$REPO_BASE` directory
 
 5.  untar gitolite to some temporary directory and follow the instructions to
-    **install** it.  Some of the steps (like `mkdir ~/repositories`) will
+    **install** it using `src/install.pl`
-    fail, but this is expected.  Once this is done, cd to the `$GL_ADMINDIR`
-    (by default `~/.gitolite`)
-
-        cd ~/.gitolite
 
 6.  **convert** your gitosis config file:
 
+        cd $GL_ADMINDIR
         src/conf-convert.pl < ~/.gitosis.conf > conf/gitolite.conf
 
     be sure to check the file to make sure it converted correctly
 
-7.  **copy** the update hook to each of the existing repos
+7.  **copy** the update hook to each of the existing repos (if you have repos
+    in subdirectories, this won't work as is; adapt it):
 
-        for i in ~/repositories/*.git
+        for i in $REPO_BASE/*.git
         do
             cp src/update-hook.pl $i/hooks/update
         done
 
 8.  **copy** the keys from gitosis's keydir
 
-        cp ~/repositories/gitosis-admin.git/gitosis-export/keydir/* keydir
+        cp $REPO_BASE/gitosis-admin.git/gitosis-export/keydir/* keydir
 
 9.  **Important: expand** any multi-key files you may have.  See the "faq,
     tips, etc" document in the doc directory for an explanation of what
@@ -61,6 +60,7 @@ Here's how we migrated my work repos:
     You can split the keys manually, or use the following code (just
     copy-paste it into your xterm):
 
+        cd $GL_ADMINDIR
         wc -l keydir/*.pub | grep -v total | grep -v -w 1 | while read a b
         do
             i=1

doc/2-admin.mkd

@@ -1,8 +1,7 @@
 # administering and running gitolite
 
-Note: some of the paths in this document use variable names.  Just refer to
+*Note*: some of the paths in this document use variable names.  Just refer to
-`~/.gitolite.rc` for the correct values, assuming you followed the
+`~/.gitolite.rc` for the correct values for *your* installation.
-instructions in the "INSTALL" document.
 
 ### administer
 
@@ -30,10 +29,8 @@ the first couple of times you use it, you may want to check these:
         not remove!).  The line should contain a "command=" pointing to a
         `$GL_ADMINDIR/src/gl-auth-command` file, then some sshd restrictions, the
         key, etc.
-      * `$GL_CONF_COMPILED` (default
+      * `$GL_CONF_COMPILED` should contain an expanded list of the access
-        `~/.gitolite/conf/gitolite.conf-compiled.pm`) should contain an
+        control rules.  It may look a little long, but it's fairly intuitive!
-        expanded list of the access control rules.  It may look a little long,
-        but it's fairly intuitive!
 
   * if the run threw up any "initialising empty repo" messages, check the
     individual repos (inside `$REPO_BASE`) if you wish.  Especially make sure