document $GL_ALL_INCLUDES_SPECIAL (and clarify/refactor the docs a bit)

doc/2-admin.mkd

@@ -180,6 +180,8 @@ to take a bunch of existing repos and add them to gitolite:
     `conf/gitolite.conf` in your gitolite-admin repo clone.  Then add, commit,
     push.
 
+<a name="gwd"></a>
+
 <a name="_specifying_gitweb_and_daemon_access"></a>
 
 #### specifying gitweb and daemon access
@@ -188,10 +190,15 @@ This is a feature that I personally do not use (corporate environments don't
 like unauthenticated access of any kind to any repo!), but someone wanted it,
 so here goes.
 
-To make a repo or repo group accessible via "git daemon", just give read
+Gitolite defines two "special" usernames: `daemon` and `gitweb`.
-permission to the special user "daemon".
+
+To make a repo or repo group accessible via "git daemon", just give read
+permission to the special user "daemon".  Similarly, give read permission to
+`gitweb` to allow the gitweb CGI to show the repo.
+
+This gives you a quick way to offer multiple repos up for gitweb/daemon
+access.
 
-There's a special user called "gitweb" also, which works the same way.
 However, setting a description for the project also enables gitweb permissions
 so you may as well use that method and kill two birds with one stone, like so:
 
@@ -201,8 +208,8 @@ You can also specify an owner for gitweb to show, if you like:
 
     gitolite "Sitaram Chamarty" = "fast, secure, access control for git in a corporate environment"
 
-Note that gitolite does **not** install or configure gitweb/daemon -- that is
+Note that gitolite does **not** install or configure gitweb/git-daemon -- that
-a one-time setup you must do separately.  All this does is:
+is a one-time setup you must do separately.  All gitolite does is:
 
   * for daemon, create the file `git-daemon-export-ok` in the repository
   * for gitweb, add the repo (plus owner name, if given) to the list of
@@ -215,6 +222,13 @@ 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.
 
+Please **note** that giving permissions to these special users via `@all`
+(that is, using either `repo @all` or `R = @all`), will not work unless you
+set the rc-file variable `$GL_ALL_INCLUDES_SPECIAL` to `1`.  Also, **NOTE**
+that giving them read access to `repo @all` means the `gitolite-admin` repo is
+also accessible.  **It is upto you to decide if that is OK in your
+environment**.
+
 <a name="_custom_git_config"></a>
 
 #### custom git config

doc/3-faq-tips-etc.mkd

@@ -569,22 +569,11 @@ complete, you can do it all from within the gitolite config file!
 
 ##### easier to specify gitweb "description" and gitweb/daemon access
 
-To enable access to a repo via gitweb *and* create a "description" for it to
+Please see [gwd] for details on how to do this if you've never done this
-show up on the webpage, just add a line like this, anywhere in the config
+before.  This section is only about how gitolite makes it easy to specify
-file:
+different combinations of access for different sets of repos.
 
-    reponame = "one line of description"
+[gwd]: http://github.com/sitaramc/gitolite/blob/pu/doc/2-admin.mkd#gwd
-
-You can also specify an "owner":
-
-    reponame "owner name" = "one line of description"
-
-To enable access to one or more repos via git daemon, just give "read"
-permissions to the special username `daemon`.
-
-There is also a special user called `gitweb` to specify gitweb access; useful
-if you don't care about specifying individual descriptions for each repo and
-just want to quickly enable gitweb access to one or more repos.
 
 Remember gitolite lets you specify the access control specs in bits and
 pieces, so you can keep all the daemon/gitweb access in one place, even if