wildrepos doc badly needed update due to new features:

- 79f0a5f ("(big one!) more than one wildcard may match a repo...")
    makes some of the dire warnings about this irrelevant
  - d1d2c3e and ad64f99 ("git config settings in wild repos: part 1" and
    "...part 2") makes this caveat also useless

While we were about it, we added a quick intro and tried to make some
other details a little clearer.

doc/wildcard-repositories.mkd

@@ -8,19 +8,13 @@ created it, allowing him/her to hand out R and RW permissions to other users
 to collaborate, all these are possible.  And any of these could have a bug in
 it.  I haven't found any yet, but that doesn't mean there aren't any.
 
-Also, there are some limitations.  For example, you cannot specify gitconfig
-values for a wildcard repo; it only works for actual repos.
-
-There may be other such missing features.  Sometimes it's just not possible to
-make it work.  Or it may be cumbersome enough that unless there are *no*
-workarounds I may not have the time to code it right away.
-
 ----
 
 In this document:
 
+  * <a href="#_quick_introduction">quick introduction</a>
   * <a href="#_rc_file_setting_required">rc file setting required</a>
-  * <a href="#_wildcard_repos">wildcard repos</a>
+  * <a href="#_examples_of_wildcard_repos">examples of wildcard repos</a>
       * <a href="#_wildcard_repos_with_creator_name_in_them">wildcard repos with creator name in them</a>
       * <a href="#_wildcard_repos_without_creator_name_in_them">wildcard repos without creator name in them</a>
   * <a href="#_side_note_line_anchored_regexes">side-note: line-anchored regexes</a>
@@ -28,7 +22,6 @@ In this document:
   * <a href="#_handing_out_rights_to_wildcard_matched_repos">handing out rights to wildcard-matched repos</a>
   * <a href="#_setting_a_gitweb_description_for_a_wildcard_matched_repo">setting a gitweb description for a wildcard-matched repo</a>
   * <a href="#_reporting">reporting</a>
-  * <a href="#_other_issues_and_discussion">other issues and discussion</a>
   * <a href="#_how_it_actually_works">how it actually works</a>
 
 ----
@@ -37,6 +30,16 @@ This document is mostly "by example".
 
 ----
 
+<a name="_quick_introduction"></a>
+
+### quick introduction
+
+The wildrepos feature allows you to specify access control rules using regular
+expression patterns, so you can have many actual repos being served by a
+single set of rules in the config file.  The regex pattern can also include
+the word `CREATOR` in it, allowing you to parametrise the name of the user
+creating the repo.  The examples below will make this clearer.
+
 <a name="_rc_file_setting_required"></a>
 
 ### rc file setting required
@@ -45,13 +48,24 @@ This feature requires that you set `$GL_WILDREPOS` to "1" in `~/.gitolite.rc`
 on the server.  Please search for that variable and see comments around it in
 `conf/example.gitolite.rc` for more information on this.
 
-<a name="_wildcard_repos"></a>
+<a name="_examples_of_wildcard_repos"></a>
 
-### wildcard repos
+### examples of wildcard repos
+
+As the introduction said, you can include the word `CREATOR` in the regex
+pattern, though it is not mandatory.  We'll look at examples of both types of
+usage.
 
 Which of these alternatives you choose depends on your needs, and the social
-aspects of your environment.  The first one is a little more rigid, making it
-harder to make mistakes, and the second is more flexible and trusting.
+aspects of your environment.  Including the creator name in the pattern keeps
+users rigidly separated from each others repos, and is good for a largely
+autonomous collection of users with a high probability of repo name clashes.
+
+Omitting the creator name from the pattern puts the repos in a common
+namespace, and is suitable for environments where it is not very important to
+keep track of who actually created the repo (except for granting access), but
+needs more communication / co-operation among the users to avoid repo name
+clashes.
 
 <a name="_wildcard_repos_with_creator_name_in_them"></a>
 
@@ -196,28 +210,6 @@ 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].
 
-<a name="_other_issues_and_discussion"></a>
-
-### other issues and discussion
-
-  * *what if the repo name being pushed matches more than one pattern*?
-
-    I think it would be very hard to reason about access if we were to do
-    something like combine all the access rights in all the matching patterns.
-    No matter how you do it, and how carefully you document it, there'll be
-    someone who is surprised by the result.
-
-    And in security, that's a ***Bad Thing***.
-
-    So we don't combine permissions.  At runtime, we die if we find more than
-    one match.  Let 'em go holler at the admin for creating multiple matching
-    repo patterns :-)
-
-    This can make some repos inaccessible if the patterns changed *after* they
-    were created.  The administrator should be careful not to do this.  Most
-    of the time, it won't be difficult; the fixed prefix will usually be
-    different anyway so there won't be overlaps.
-
 <a name="_how_it_actually_works"></a>
 
 ### how it actually works
@@ -249,8 +241,8 @@ who actually *created* the repo (this name is recorded in a special file in
 the repo directory when the repo is first created, so it is available).
 
 Now find a repo pattern that matches the actual reponame being pushed -- this
-tells you which set of rules to apply.  Only one pattern is allowed to match;
-matching more than one is an error.
+tells you which set of rules to apply.  There can be multiple matches; if so,
+they will all be applied in the sequence they appear in the config file.
 
 If the invoking user has been given "RW" permissions using `setperms`, all
 occurrences of the word WRITERS are replaced by the invoking username.