doc fixes...

- README: add a "what" section first, plus a few minor fixes
  - doc/5:
      - remove reference to obsolete ml branch URL; point it to the right
        place with the right section name
      - change text to reflect the fact that p-t-a is now the default!

README.mkd

@@ -15,13 +15,28 @@ specifying who can and cannot *rewind* a given branch.
 
 In this document:
 
+  * what
   * why
-  * what's extra
+  * extra features
   * security
   * contact and license
 
 ----
 
+### 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.
+
+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.
+
 ### why
 
 I have been using gitosis for a while, and have learnt a lot from it.  But in
@@ -33,15 +48,15 @@ a typical $DAYJOB setting, there are some issues:
     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 "what's new?") had to be written anyway
+  * the most requested feature (see below) had to be written anyway
 
 All of this pointed to a rewrite.  In perl, naturally :-)
 
-### what's extra
+### extra features
 
-**Per-branch permissions**.  You will not believe how often I am asked this at
+The most important feature I needed was **per-branch permissions**.  This is
-$DAYJOB.  This is almost the single reason I started *thinking* about rolling
+pretty much mandatory in a corporate environment, and is almost the single
-my own gitosis in the first place.
+reason I started *thinking* about rolling my own gitosis in the first place.
 
 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
@@ -53,8 +68,8 @@ Here're **some more features**.  All of them are documented in detail
 somewhere in the `doc/` subdirectory.
 
   * simpler, yet far more powerful, config file syntax, including specifying
-    gitweb/daemon access.  You'll need this power if you manage lots of users
+    gitweb/daemon access.  You'll need this power if you manage lots of
-    + repos + combinations of access
+    users+repos+combinations of access
   * 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
@@ -62,7 +77,7 @@ somewhere in the `doc/` subdirectory.
     a synonym for "annotate" :-)]
   * "personal namespace" prefix for each dev
   * migration guide and simple converter for gitosis conf file
-  * "exclude" (or "deny" rights in the config file) -- this is the "rebel"
+  * "exclude" (or "deny") rights in the config file -- this is the "rebel"
     branch in the repository, and always will be ;-)
 
 ### security

doc/5-delegation.mkd

@@ -5,14 +5,14 @@
 ### lots of repos, lots of users
 
 Gitolite tries to make it easy to manage access to lots of users and repos,
-exploiting commonalities wherever possible.  (The example under "simpler, more
+exploiting commonalities wherever possible.  (The example in the section
-powerful syntax" [here][ml] should give you an idea).  As you can see, it lets
+"simpler syntax" in [this page][ml] should give you an idea).  As you can see,
-you specify bits and pieces of the access control separately -- i.e., *all*
+it lets you specify bits and pieces of the access control separately -- i.e.,
-the access specs for a certain repo need not be together; they can be
+*all* the access specs for a certain repo need not be together; they can be
 scattered, which makes it easier to manage the sort of slice and dice needed
 in that example.
 
-[ml]: http://github.com/sitaramc/gitolite/blob/ml/update.mkd
+[ml]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd
 
 But eventually the config file will become too big.  If you let only one
 person have control, he could become a bottleneck.  If you give it to multiple
@@ -81,23 +81,24 @@ Splitting up the file does help, but there's also that little security issue
 -- anyone can make any change to any "fragment", unless you (once again) go
 back to Unix permissions to keep them separate.
 
-Fixing that requires using "push-to-admin".
+Fixing that requires using "push-to-admin", which is the default (and only)
+method to make config changes in gitosis.
 
-The page on [push-to-admin][ptd] explains clearly how to set it up.  Unlike
+For a long time, I refused to make "push to admin" the default because it's a
-gitosis, I refuse to make it the default because it's a support nightmare.
+support nightmare.  Don't get me wrong -- it's a great feature, and I use it
-Don't get me wrong -- it's a great feature, and I use it myself, but the
+myself, but the learning curve was too steep to make it *required*.
-learning curve is too steep to make it *required*.
 
-[ptd]: http://github.com/sitaramc/gitolite/blob/pu/doc/4-push-to-admin.mkd
+But eventually I figured out a way to front-load the darn ssh problem that
+everyone on #git seemed to run up against, created a nice "easy install"
+script, and made "push to admin" the default.
 
-So, having setup push-to-admin, you add these lines to the main config file,
+So now, you just add these lines to the main config file, assuming Alice is in
-assuming Alice is in charge of all web browser development projects, Bob takes
+charge of all web browser development projects, Bob takes care of web servers,
-care of web servers, and Mallory, as [tradition][abe] dictates, is in charge
+and Mallory, as [tradition][abe] dictates, is in charge of malware ;-)
-of malware ;-)
 
 [abe]: http://en.wikipedia.org/wiki/Alice_and_Bob#List_of_characters
 
-    # you probably added these two lines while setting up push-to-admin
+    # these 2 lines were probably present already
     repo gitolite-admin
         RW+                     = sitaram
     # now add these 3 lines
@@ -111,10 +112,10 @@ of malware ;-)
     @webserver_repos            = apache nginx
     @malware_repos              = conficker storm
 
-**As you can see, for each repo group you want to delegate authority over,
+As you can see, **for each repo group** you want to delegate authority over,
-there's a *branch* in the `gitolite-admin` repo with the same name.  If you
+there's a **branch with the same name** in the `gitolite-admin` repo.  If you
 have write access to that branch, you are allowed to define rules for repos in
-that repo group.**
+that repo group.
 
 In other words, we use gitolite's per-branch permissions to "enforce" the
 separation between the delegated configs!