Introduction of "supersedes" and "superseded_by"

And some other minor clarifications.

S11-modules.pod

@@ -13,8 +13,8 @@ Synopsis 11: Units, Modules and Distributions
 
     Created: 27 Oct 2004
 
-    Last Modified: 13 Mar 2014
-    Version: 41
+    Last Modified: 15 Mar 2014
+    Version: 42
 
 =head1 Overview
 
@@ -819,18 +819,69 @@ available to be C<use>d.  For example:
     "Dog" : "lib/Dog.pm6"
   }
 
+=head3 depends
+
+Optional.  A list of run-time dependencies, specified as C<use> strings.  An
+example of this would be:
+
+  "depends" : [
+    "Canine:auth<cpan:*>:ver(1..*)"
+  ]
+
+An installer has the option to automatically install any dependencies, if the
+use has so indicated.
+
 =head3 emulates
 
-Optional.  A hash of modules with C<use> string values, that will be
-aliased to the given module.  An example of this would be:
+Optional.  A hash in which the key is the compunit (provided by the
+distribution) to be aliased, and the value is the use string that should match
+to get that compilation unit.  An example of this would be:
 
   "emulates" : {
     "Dog" : "Wolf:auth<cpan:JRANDOM>:ver<1.0>"
   }
 
-Which would mean that after loading this distribution, there is a pre-defined
-alias for C<Dog> called C<Wolf>, which will become available if a C<use>
-statement is executed that matches the C<use> string given.
+If then later, a program would say:
+
+  use Wolf:auth<cpan:JRANDOM>:ver<1.0>;
+
+it would in fact load the C<Dog> compunit, but make it appear as a C<Wolf>
+compunit, but only if there was no "real" C<Wolf> compunit installed that would
+match the C<use> specification.  In other words: if the real thing is available,
+then it will be used.  If it is not, it will fall back to the indicated
+compilation unit.
+
+=head3 supersedes
+
+Optional.  Has the same meaning as "emulates" for the L<CompUnitRepo>.
+But has additional meaning for external packagers: it indicates a potential
+superseding of the indicated compilation unit from the packagers point of
+view.  See L<superseded_by>.
+
+=head3 superseded_by
+
+Optional.  Has the reverse meaning of "emulates" for the L<CompUnitRepo>.
+It is a hash in which the key is compunit provided by the distribution, and
+the value is the C<use> string of the compunit it should be aliased to if
+that compunit is available.  So in this case:
+
+  "superseded_by" : {
+    "Dog" : "SuperDog:ver(v1.0 .. *)"
+  }
+
+it would mean that if a program attempts to load the C<Dog> compunit of this
+distribution, it should instead use any C<SuperDog> compunit that is installed
+that has a version of 1.0 or higher.  In other words: please don't use my
+compunit, unless you really have to.
+
+This tag has additional meaning for packagers: if a packager detects a valid
+C<supersedes> and C<superseded_by> pair in its collection of distributions to
+be packaged, the packager may decide to only supply the distribution providing
+the C<superseded_by> compilation unit.
+
+Please note that C<superseded_by> has no meaning as a C<depends>, so an
+installer should probably not automatically install any C<superseded_by>
+compunits.
 
 =head3 excludes
 
@@ -843,15 +894,6 @@ An example of this would be:
 
 Trying to load a module that matches the C<use> string, will cause a failure.
 
-=head3 depends
-
-Optional.  A list of run-time dependencies, specified as C<use> strings.  An
-example of this would be:
-
-  "depends" : [
-    "Canine:auth<cpan:*>:ver(1..*)"
-  ]
-
 =head3 build-depends
 
 Optional.  A list of build-time dependencies, specified as C<use> strings.  An