minor docfixes

typos, minor clarifications, removing outdated stuff that got missed,
adding some emphasis here and there, re-phrasing some places, etc.

contrib/adc/README.mkd

@@ -25,7 +25,7 @@ this ADC are [here][dbsha]; details on RWC/RWD/RWCD etc are [here][rwcd].
 sample of how to write an ADC in perl.
 
 **git-annex-shell**: allows git-annex to store and retrieve annexed file content in
-repositories. To use, install in $GL_ADC_PATH/ua/git-annex-shell
+repositories. To use, install in `$GL_ADC_PATH/ua/git-annex-shell`
 
 **gl-reflog**: show a fake "reflog" from the server, and allow recovery from
 deleted branches and bad force pushes; details in source.
@@ -45,12 +45,6 @@ itself.  This ADC displays site-local help, if the site admin enabled it.
 
 [rddoc]: http://sitaramc.github.com/gitolite/contrib/adc/repo-deletion.html
 
-**restrict-admin**: sample program to show how you can allow the admin to run
-pre-specified shell commands (without actually having full shell access).
-Details [here][ra].
-
-[ra]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#_bonus_restricted_admin
-
 **sudo**: allow admin to run ADCs on behalf of a user.  Useful in support
 situations I guess.  Details in source.
 

doc/2-admin.mkd

@@ -413,19 +413,21 @@ permission to the special user "daemon".  Similarly, give read permission to
 This gives you a quick way to offer multiple repos up for gitweb and/or daemon
 access.
 
-However, setting a description for the project also enables gitweb permissions
-so you can do it that way if you want.  Of course in this case you have to
-deal with each repo separately.  Add lines like this to gitolite.conf:
+However, **setting a description** for the project also enables gitweb
+permissions so you can do it that way if you want.  Of course in this case you
+have to deal with each repo separately.  Add lines like this to gitolite.conf:
 
     foo = "some description"
     bar = "some other description"
     baz = "yet another description"
 
-You can also specify an owner for gitweb to show, if you like; for example I
-might use:
+You can also **specify an owner** for gitweb to show, if you like; for example
+I might use:
 
     gitolite "Sitaram Chamarty" = "fast, secure, fine-grained, access control for git"
 
+These lines are standalone, so you can add them anywhere in the conf file.
+
 Note that gitolite does **not** install or configure gitweb/git-daemon -- that
 is a one-time setup you must do separately.  All gitolite does is:
 

doc/3-faq-tips-etc.mkd

@@ -430,8 +430,8 @@ 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!
 
-If you just want gitweb to show some repositories, see [gwd] for how to
-specify which repos to show.  Other advanced uses are described here.
+If you just want gitweb to show some repositories, see [here][gwd] for how to
+specify which repos to show.
 
 [gwd]: http://sitaramc.github.com/gitolite/doc/2-admin.html#gwd
 

doc/gitolite.conf-by-example.mkd

@@ -63,12 +63,11 @@ end of the string respectively.
     ^foo$   matches exact string 'foo'.
 
 To be precise, the last one is "any string starting and ending with *the same*
-'foo'".  (Without the italicised phrase, it could mean "foofoo" would also
-match, but it doesn't).
+'foo'".  "foofoo" does not match.
 
-`[0-9]` is an example of a character class; this one matches any single digit.
-`[a-z]` matches any lower case alpha.  For example, `[0-9a-f]` is the range of
-hex characters.  You can guess what `[a-zA-Z0-9_]` does, then.
+`[0-9]` is an example of a character class; it matches any single digit.
+`[a-z]` matches any lower case alpha, and `[0-9a-f]` is the range of hex
+characters.  You should now guess what `[a-zA-Z0-9_]` does.
 
 `.` (the period) is special -- it matches any character.  If you want to match
 an actual period, you need to say `\.`.
@@ -107,31 +106,36 @@ branch or tag on it.
 Wally can only read the repo.  Alice and Ashok can push but not rewind; only
 Sitaram and Dilbert can do that.
 
-            R master    =   wally       # MEANINGLESS!  WONT DO WHAT YOU THINK IT DOES!!
+            R master    =   wally       # MEANINGLESS!  WILL NOT DO WHAT YOU THINK IT DOES!!
 
-This won't work.  You can only restrict "read" access at the repo level not
-the branch level.  This is a git issue, not a gitolite issue.  Go bother them,
-or switch to gerrit.
+This won't work.  You can only restrict "read" access at the repo level, not
+at the branch level.  This is a git issue, not a gitolite issue.  Go bother
+them, or switch to gerrit.
 
     repo    foo
             RW      master$             =   dilbert alice
             # this is equivalent to:
             RW      refs/heads/master$  =   dilbert alice
 
 The reason for treating "master$" as "refs/heads/master$" is that  matching
-branches is the most common use so we made it convenient to use.  Anything
-*not* starting with `refs/` (or `NAME/`, but that is out of scope of this
-document), is implicitly prefixed with `refs/heads/`).
+branches is the most common use so the syntax is optimised to make that
+simpler to write and easier to read.  Anything *not* starting with `refs/`
+(<font color="gray">or `NAME/`, but that is out of scope for this
+document</font>), is implicitly prefixed with `refs/heads/`.
 
 The `master$` is called a "refex" (a regex that matches a ref).
 
 Dilbert and Alice can push to the "master" branch.  Unless some other rule
 allows it, they cannot push to, say, "master1", "masterfull" etc., due to the
 `$` at the end of the refex.
 
-This rule does not match "headmaster"; refexes are treated as if they have a
-`^` at the start.  (This means `^refs/heads/master` in this case, not
-`^master`, in case you forgot!)
+Refexes are *prefix matched*; i.e., treated as if they have a `^` at the
+start.  (This means `^refs/heads/master` in this case, not `^master`, in case
+you forgot!)
+
+This rule therefore does not match "headmaster", or even
+"refs/heads/refs/heads/master" (<font color="gray">yes, it is possible to
+confuse yourself by pushing a branch like that in git</font>).
 
             RW+     pu                  =   dilbert
             # again, remember this is equivalent to:
@@ -181,8 +185,8 @@ earlier.
 
   * for non-version tags, only the 3rd rule matches, so anyone on staff can
     push them
-  * for version tags by bruce, the first rule matches so he can push them
-  * for version tags by staffers *other than bruce*, the second rule matches
+  * for version tags by ashok, the first rule matches so he can push them
+  * for version tags by staffers *other than ashok*, the second rule matches
     before the third one, and it has a `-` as the permission, so the push
     fails
 

doc/gitolite.conf.mkd

@@ -306,9 +306,9 @@ We'll look at the delete/rewind case in detail first:
   * if, however, *any* of the rules for a repo contains a `D` (example: `RWD`,
     `RW+D`, etc) then `RW+` by itself will permit only a rewind, not a delete
 
-The same thing applies to create/push, where if you have a permissions like
-`RWC` or `RW+C` anywhere, a simple `RW` or `RW+` can no longer *create* a new
-ref.
+The same thing applies to create/push, where if you have permissions like
+`RWC` or `RW+C` anywhere in that repo, a simple `RW` or `RW+` can no longer
+*create* a new ref.
 
 You can combine the `C` and `D` also.  Thus, the set of permissions you now
 know about are, in regex syntax: `R|RW+?C?D?`.  See a later section for the
@@ -596,17 +596,5 @@ later to override the generic settings.
 #### repo owner/description line for gitweb
 
 You can include owner/description information in the conf file, and gitolite
-will put it in places where gitweb will pick it up.  For example, suppose this
-software (gitolite) itself was being hosted on a gitolite server and intended
-to be shown on gitweb, I'd use a line like this:
-
-    gitolite "Sitaram Chamarty" = "fast, secure, access control for git"
-
-The general syntax is very simple, just use one of:
-
-    reponame = "some description string in double quotes"
-    reponame "owner name" = "some description string in double quotes"
-
-Note: setting a description also gives gitweb access; you do not have to give
-gitweb access explicitly (as described or linked above) if you're specifying a
-description.
+will put it in places where gitweb will pick it up.  See [here][gwd] for more
+on this.

doc/gitolite.rc.mkd

@@ -294,18 +294,6 @@ on feedback from my users to find or fix issues.
     does *not* include the special users "gitweb" and "daemon".  If you want
     @all to include these two users, set this variable.
 
-  * mirroring setup
-
-    These two variables enable mirroring support; see
-    [doc/mirroring.mkd][mirr] for details.  The two variables are
-    `$GL_SLAVE_MODE`, (boolean, default undef), and `$ENV{GL_SLAVES}`,
-    (environment variable, string, default undef)
-
-    Note on the second variable above: you must use single quotes to give it
-    its value, not double quotes, (like `$ENV{GL_SLAVES} = 'gitolite@server2
-    gitolite@server3';`).  Also note that this is an environment variable, not
-    a regular perl variable, so mind the syntax if you're not a perl guy :-)
-
   * `$GL_WILDREPOS_PERM_CATS`, string, default "READERS WRITERS"
 
     Originally, we only allowed "R" and "RW" in the setperms command.  Now we

doc/report-output.mkd

@@ -33,21 +33,21 @@ Here is a sample output of the info command.  There are 3 columns of
 permissions (create, read, and write) in the output, although the first column
 is often blank.
 
-        $ ssh git@server info
-        hello sitaram, the gitolite version here is v1.5.5-24-g2b066fc
-        the gitolite config gives you the following access:
-             R   W 	SecureBrowse
-             R   W 	anu-wsd
-             R   W 	entrans
-            @R   W 	git-notes
-            @R   W 	gitolite
-             R   W 	gitolite-admin
-             R   W 	indic_web_input
-         @C  R   W 	private/sitaram/[\w.-]+
-             R   W 	proxy
-         @C @R   W 	public/sitaram/[\w.-]+
-            @R_ @W_	testing
-             R   W 	vkc
+    $ ssh git@server info
+    hello sitaram, this is gitolite v2.1-29-g5a125fa running on git 1.7.4.4
+    the gitolite config gives you the following access:
+         R     	SecureBrowse
+         R   W 	anu-wsd
+         R   W 	entrans
+        @R   W 	git-notes
+        @R   W 	gitolite
+         R   W 	gitolite-admin
+         R   W 	indic_web_input
+     @C  R   W 	private/sitaram/[\w.-]+
+         R   W 	proxy
+     @C @R   W 	public/sitaram/[\w.-]+
+        @R_ @W_	testing
+         R   W 	vkc
 
 <a name="_interpreting_the_output"></a>
 
@@ -80,17 +80,17 @@ to one of the `@all` uses), but no explicit access.
 
 Here are a couple of samples with optional patterns:
 
-        $ ssh git@server info git
-        hello sitaram, the gitolite version here is v1.5.5-24-g2b066fc
-        the gitolite config gives you the following access:
-            @R   W 	git-notes
-            @R   W 	gitolite
-             R   W 	gitolite-admin
-
-        $ ssh git@server info admin
-        hello sitaram, the gitolite version here is v1.5.5-24-g2b066fc
-        the gitolite config gives you the following access:
-             R   W 	gitolite-admin
+    $ ssh git@server info git
+    hello sitaram, this is gitolite v2.1-29-g5a125fa running on git 1.7.4.4
+    the gitolite config gives you the following access:
+        @R   W 	git-notes
+        @R   W 	gitolite
+         R   W 	gitolite-admin
+
+    $ ssh git@server info admin
+    hello sitaram, this is gitolite v2.1-29-g5a125fa running on git 1.7.4.4
+    the gitolite config gives you the following access:
+         R   W 	gitolite-admin
 
 In "big-config" mode (i.e., when `GL_BIG_CONFIG` is set) the pattern is
 **mandatory**.  You can try and cheat the system by passing in a "." but

doc/ssh-troubleshooting.mkd

@@ -207,7 +207,7 @@ single key to allow both gitolite access *and* shell access.
 This is done by copying the pubkey (to which you want to give shell access) to
 the server and running
 
-    gl-tool shell-add ~/foo.pub
+    gl-tool add-shell-user ~/foo.pub
 
 **IMPORTANT UPGRADE NOTE**: previous implementations of this feature were
 crap.  There was no easy/elegant way to ensure that someone who had repo admin

doc/wildcard-repositories.mkd

@@ -87,6 +87,11 @@ Here's an example snippet:
         RW  =   WRITERS @TAs
         R   =   READERS @prof
 
+Note the "C" permission.  This is a standalone "C", which gives the named
+users the right to *create a repo*.  <font color="gray">This is not to be
+confused with the "RWC" or its variants described elsewhere, which are about
+*branches*, not *repos*.</font>
+
 For now, ignore the special usernames READERS and WRITERS, and just create a
 new repo, as user "u4" (a student):
 
@@ -204,9 +209,11 @@ use 'getperms' to check:
 
 The following points are important:
 
-  * note the syntax of the commands; it's not a "git" command, and there's no
-    `:` like in a repo URL.  The first space-separated word is READERS or
-    WRITERS, and the rest are simple usernames.
+  * note the syntax of the command; it's not a "git" command, and there's no
+    `:` like in a repo URL.
+  * for the actual text being sent in via STDIN, the first space-separated
+    word is the role (in this example, READERS or WRITERS), and the rest
+    are simple usernames.
 
 <a name="_admin_adding_other_roles_than_READERS_and_WRITERS"></a>