Elaborate some more on S22:

Describe:
- CompUnitRepo specification (e.g. "inst:name<work>:/installed_modules")
- Distribution class
- %*CUSTOM_LIB
- %*INC
and other various tweaks, fixes and elaborations

S22-package-format.pod

@@ -12,10 +12,10 @@ Synopsis 22: Distributions, Recommendations, Delivery and Installation
 
     Created: 15 March 2014
 
-    Last Modified: 15 March 2014
-    Version: 1
+    Last Modified: 16 June 2014
+    Version: 2
 
-=head1 Terminology
+=head1 TERMINOLOGY
 
 Because many of the concepts used in this document may be overloaded by
 other concepts in the mind of the reader, it seems like a good idea to define
@@ -106,7 +106,7 @@ The identity of a distribution, is the combination of name of the content
 storage, the name of the owner, name and version of a distribution, separated
 by colons.  For example:
 
- cpan:JRANDOM:JSON-Fast:1.23
+  cpan:JRANDOM:JSON-Fast:1.23
 
 There should really be only one unique distribution for a given identity in the
 world.
@@ -160,7 +160,7 @@ listen to a name (such as C<Rakudo *>).  A recommendation manager may provide
 bundles as part of its service.  And packagers may use this information as the
 source for bundling distributions in their specific packaging system.
 
-=head1 Distribution
+=head1 DISTRIBUTION
 
 A Perl 6 distribution consists of an archive of some form (presumably a
 .tar.gz, .tar.bz2 or .zip file) which is expected to at least contain a file
@@ -486,52 +486,156 @@ select the C<CompUnitRepo> in which the distribution should be installed, and
 the recommendation manager that should be used to convert requests for a
 compilation unit into an identity of a distribution to be downloaded.
 
-=head2 Classes
+=head1 CLASSES
 
-=head3 CompUnitRepo
+=head2 CompUnitRepo
 
-Base class (interface, really) for the object living in the @*INC array.  Used
-both for installing compunits, as well as finding a certain compunit by way
-of its from, longname, auth and ver information.
+Base class (interface, really) for the object living in the L</@*INC> array.
+Used both for installing compunits, as well as finding a certain compunit by
+way of its from, longname, auth and ver information.
 
-=head3 new
+=head3 Specifying a CompUnitRepo
 
- my $repo = CompUnitRepo.new( $location );
+The specification of a CompUnitRepo can happen at various places: in a
+configuration file, on the command-line when starting (with C<-I>), and in
+code when trying to create a CompUnitRepo object programmatically.
 
-Create a new CompUnitRepo object, either for inclusion in C<@*INC>, or to
-install a compilation unit..  The parameter indicates the location in
-which compunits are supposed to be located for this object.  This could be a
-local directory (as in the case of L<CompUnitRepo::Local::File> and
-L<CompUnitRepo::Local::Installation>).  Or it could be anything that indicates
-a remote repository, such as a connect string to a database, or a URL to a
-an authority (such as CPAN or Github).  Returns the instantiated object.
+Each specification consists of a CompUnitRepo class specification (either
+explicitely, implicitely, or the short-hand form using the L</short-id>
+identifier), optional named parameters and a location indicator (usually a
+path or a URL).
 
-=head3 install
+Some examples (where CURL is short for CompUnitRepo::Local):
+
+  /foo/bar                    simple CURL::File in /foo/bar
+  file:/foo/bar               (same)
+  inst:/installed             simple CURL::Installation in /installed
+  inst:name<work>:/installed  (same) but also set %*CUSTOM_LIB<work>
+  inst:name[work]:/installed  (same) but more CLI-friendly
+  inst:name{work}:/installed  (same) alternate CLI-friendly way
+  CompUnitRepo::Local::Installation:/installed  (same) but with full class name
+  CompUnitRepo::GitHub:masak/html-template      get it from GitHub
+
+Multiple specifications may be concatenated with C<,>.  If no class is
+specified on subsequent specifications, then the previous class specification
+will be assumed.  So:
+
+  /foo/bar,/foo/baz           both use CURL::File
+  inst:/installed,/also       both use CURL::Installation
+  /foo/bar,inst:/installed    first CURL::File, second CURL::Installation
+
+=head2 new
+
+  my $repo = CompUnitRepo.new( $specification );
+
+Create a new CompUnitRepo-like object with the given specification, either
+for inclusion in L</<@*INC>, or to install a distribution.  Returns the
+instantiated object.
+
+=head3 short-id
 
- my $installed = $repo.install(...);
+  say CompUnitRepo::Local::File.short-id;   # "file"
+
+Returns a short C<\w+> identifier string (a C<tag> if you will) to identify
+the use of this repo, e.g. in strings provided with the C<-I> command line
+parameter.  It should be unique for all of the CompUnitRepo subclasses loaded.
+The following C<short-id>'s are pre-defined:
+
+  file   CompUnitRepo::Local::File
+  inst   CompUnitRepo::Local::Installation
+
+=head2 install
+
+  my $installed = $repo.install( $something );
 
 Install a compilation unit in the appropriate way for this object.  May cause
 a fatal exception if this repository does not support installing.  The first
-parameter contains the actual source-code of the compilation unit to be
+parameter contains some specification of the compilation unit to be
 installed.  The named parameters indicate the other meta-information to be
-associated with the compunit.  Returns whether compilation unit was installed.
+associated with the compunit.  Returns True if the compilation unit was
+installed, or a C<Failure> if it didn't.
 
 Of course, any implementation of L<CompUnitRepo>'s C<install> interface, may
 decide to accept additional meta-information and store this and make available
 for later introspection.
 
 =head3 candidates
 
- my @candidates = $repo.candidates( $longname, $auth?, $ver?, $from? );
+  my @candidates = $repo.candidates( $longname, $auth?, $ver?, $from? );
 
 Return L<CompUnit> candidates given the matching credentials.
 
+=head2 CompUnitRepo::Local::File
+
+The simplest, default case for locating compilation units on a file system.
+The module name specified should directly map to a file, similar to how
+Perl 5 this does.  Mainly intended to be used in development situations
+to allow developers to have modules to be available without them having to be
+installed.
+
+=head3 install
+
+Will fail unconditionally: installing compilation units is done by putting
+files in the right location.
+
+=head2 CompUnitRepo::Local::Installation
+
+The default case for installed compilation units.  Similar to the way Perl 5
+installs modules, but with meta-information per object, rather than globally
+in a C<packlist>.  This should be used by installers such as C<panda>.
+
+=head3 install
+
+  my $installed = $repo.install( $distribution );
+
+Install the given L</Distribution> object in this repo.
+
+=head2 Distribution
+
+The class for installing distributions using
+L</CompUnitRepo::Local::Installation>.  Basically provides the API to access
+the C<META6.json> file of a distribution.
+
+=head3 new
+
+  my $dist = Distribution( 'HTML-Template-1.20.tar.gz' );
+
+  my $dist = Distribution( '.unpacked/HTML-Template-1.20' );
+
+Create object from distribution file, or from an already unpacked distribution.
+
 =head2 CompUnit
 
-The object that describes a compilation unit.
+The object that describes a compilation unit.  Contains as much meta-data
+as possible, e.g. from the C<Distribution> object it came from.
 
 =head3 load
 
- my $loaded = @candidates[0].load;
+  my $loaded = @candidates[0].load(...);
+
+Returns True if loading of the C<CompUnit> was successful, or a C<Failure>
+if something went wrong.
+
+=head1 SYSTEM VARIABLES
+
+Several dynamic variables are available.
+
+=head2 %*CUSTOM_LIB
+
+This hash provides key/value pairs of C<CompUnitRepo> specifications, to be
+used by packagers and/or installers.
+
+=head2 @*INC
+
+This array contains the C<CompUnitRepo> objects that will be queried in turn
+whenever an attempt should be made to load a compilation unit (be that at
+compile time with C<use>, or at runtime with C<require>.
+
+The first C<CompUnitRepo> object to return one candidate, will then be loaded
+and no further C<CompUnitRepo> objects in C<@*INC> will be queried.  If the
+first C<CompUnitRepo> object to return C<any> candidates, returns more
+than one candidate, then B<all> other C<CompUnitRepo> objects in C<@*INC> will
+also be queried, to allow any error message to present a B<full> list of
+C<CompUnit> candidate objects.
 
 =for vim:set expandtab sw=4: