(minor) doc updates

README.mkd

@@ -143,7 +143,7 @@ detail somewhere in gitolite's [doc/][docs] subdirectory.
 
 Most installation problems are caused by not knowing ssh.  Take a look at this
 [transcript][] to see how simple it actually is, if your server's ssh daemon
-is behaving itself.
+is behaving itself.  Someone also wrote a tutorial, see [here][tut].
 
 If I suspect your problem is an ssh issue, I will probably ignore it.  Please
 learn how [gitolite uses ssh][doc9gas] and then methodically go through the
@@ -194,4 +194,4 @@ Gitolite is released under GPL v2.  See COPYING for details.
 [doc9gas]: http://github.com/sitaramc/gitolite/blob/pu/doc/gitolite-and-ssh.mkd
 [doc6sts]: http://github.com/sitaramc/gitolite/blob/pu/doc/ssh-troubleshooting.mkd
 [who]: http://github.com/sitaramc/gitolite/blob/pu/doc/who-uses-it.mkd
-
+[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial

conf/example.conf

@@ -155,7 +155,7 @@ repo    git
 
 # ***IMPORTANT NOTES ABOUT "DENY" RULES***:
 
-# - deny rules do NOT affect read access.  They only apply to `W` and `+`.
+# - deny rules do NOT affect read access.  They only apply to write access.
 #
 # - when using deny rules, the order of your rules starts to matter, where
 #   earlier it did not.  The first matching rule applies, where "matching" is

doc/3-faq-tips-etc.mkd

@@ -101,7 +101,6 @@ There *is* a way to use the `@all` syntax for repos also, as described in
   * don't use `NAME/` or such restrictions on the special `@all` repo.  Due to
     the potential for defeating a crucial optimisation and slowing down *all*
     access, we do not support this.
-  * don't try giving `@all` users some permission for `@all` repos
 
 <a name="_umask_setting"></a>
 

doc/big-config.mkd

@@ -11,6 +11,7 @@ In this document:
   * <a href="#_storing_usergroup_information_outside_gitolite_like_in_LDAP_">storing usergroup information outside gitolite (like in LDAP)</a>
       * <a href="#_why">why</a>
       * <a href="#_how">how</a>
+  * <a href="#_implementation_notes">implementation notes</a>
 
 <a name="_when_why_do_we_need_it_"></a>
 
@@ -292,3 +293,45 @@ Then set the `$GL_GET_MEMBERSHIPS_PGM` variable in the rc file to the full
 path to this program, set `$GL_BIG_CONFIG` to 1, and that will be that.
 
 [gwd]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gwd
+
+<a name="_implementation_notes"></a>
+
+### implementation notes
+
+To understand how big-config works, we'll first look at how it works without
+this setting.  Think back to the example at the top, and assume 'alice' is
+accessing the 'lynx' repo.  The various rights are governed by the following
+hash elements:
+
+    # for the first level checks
+    $repos{'lynx'}{'R'}{'alice'} = 1
+    $repos{'lynx'}{'W'}{'alice'} = 1
+
+    # for the second level checks
+    $repos{'lynx'}{'alice'}{'refs/heads/master'} = 'RW';
+    $repos{'lynx'}{'alice'}{'refs/heads/next'} = 'RW+';
+
+Those elements are explicitly specified in the compiled hash, as you can see
+(you don't need to know perl too much to read a hash; just make some educated
+guesses if needed!)
+
+Now look at the compiled hash produced when `GL_BIG_CONFIG` is set.  In place
+of both 'firefox' and 'lynx' you have '@wbr', and similarly '@devs' for both
+'alice' and 'bob'.  In addition, there is a group hash at the bottom that
+lists each group and its members.
+
+When 'alice' tries to access the 'lynx' repo, gitolite collects all the group
+names that these names belong to, so '@devs' is added to the list of 'user'
+names that 'alice' inherits permissions from, and '@wbr' is added to the list
+of 'repo' names that 'lynx' inherits from.  This means that the final access
+inherits all permissions pertaining to the following combinations:
+
+    alice, lynx
+    alice, @wbr
+    @devs, lynx
+    @devs, @wbr
+
+(Actually there are 3 more... try and guess what they may be!)
+
+Anyway, all ACL rules for these combinations are clubbed together to make the
+composite set of rules that 'alice' accessing 'lynx' is subject to.

doc/ssh-troubleshooting.mkd

@@ -39,6 +39,8 @@ Other resources:
   * people who think this is too hard should take a look at this
     [transcript][] to **see how simple it *actually* is**.
 
+  * someone also wrote a tutorial, see [here][tut].
+
   * I **strongly** recommend reading [doc/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;
@@ -421,9 +423,9 @@ or
 
     gl-tool shell-add ~/foo.pub
 
-The first method is to be used if you used the **user-install** mode, while
+The first method is applicable if you installed using the **from-client**
-the second method is for the **system-install followed by user-setup** mode
+method, while the second method is for any of the other three (see
-(see doc/1-INSTALL.mkd, section on "install methods", for more on this)
+doc/1-INSTALL.mkd, section on "install methods", for more on this)
 
 **IMPORTANT UPGRADE NOTE**: previous implementations of this feature were
 crap.  There was no easy/elegant way to ensure that someone who had repo admin
@@ -474,3 +476,4 @@ bigger problems than gitolite install not working!)]
 [repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd
 [transcript]: http://github.com/sitaramc/gitolite/blob/pu/doc/install-transcript.mkd
 [openssh56]: http://www.openssh.org/txt/release-5.6
+[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial

doc/wildcard-repositories.mkd

@@ -264,6 +264,15 @@ commands, thanks to Teemu.
 In order to see what repositories were created from a wildcard, use the
 "expand" command, described briefly in [doc/report-output.mkd][repout].
 
+### deleting a wild repo
+
+See [repo deletion][rmr] for more on this.  Note that this requires you to
+install/setup "adc"s (admin defined commands).  See
+[doc/admin-defined-commands.mkd][adc] for how to do that.
+
+[adc]: http://github.com/sitaramc/gitolite/blob/pu/doc/admin-defined-commands.mkd
+[rmr]: http://github.com/sitaramc/gitolite/blob/pu/contrib/adc/repo-deletion.README
+
 <a name="_how_it_actually_works"></a>
 
 ### how it actually works