[Zope-CVS] CVS: Packages/zpkgtools/doc - collections.txt:1.8

[Fred L. Drake, Jr.]

Update of /cvs-repository/Packages/zpkgtools/doc
In directory cvs.zope.org:/tmp/cvs-serv22404

Modified Files:
	collections.txt 
Log Message:
update the description of the shape of a collection distribution to
reflect current thinking on the matter


=== Packages/zpkgtools/doc/collections.txt 1.7 => 1.8 ===
--- Packages/zpkgtools/doc/collections.txt:1.7	Thu Apr 29 10:24:58 2004
+++ Packages/zpkgtools/doc/collections.txt	Fri Apr 30 16:00:32 2004
@@ -13,33 +13,39 @@
 
 Collection distributions are laid out as a directory tree with a
 specific form.  If the primary resource being packaged is
-``Collection``, and the version number assigned is ``1.0``, we get a
+``Collection``, and the release tag is ``collection-1_0``, we get a
 tree that looks like this (assuming it has the ``zope`` package as a
 dependency)::
 
   Collection-1.0/
       MANIFEST
+      README.txt
       setup.cfg
       setup.py
-      Collection/
-          DEPENDENCIES.cfg
-          MANIFEST
-          PUBLICATION.cfg
-          README.txt
-          setup.cfg
-          setup.py
-      zope/
-          MANIFEST
-          PUBLICATION.cfg
-          setup.cfg
-          setup.py
-          zope/
-              __init__.py
+      Packages/
+          Collection-collection-1_0/
+              MANIFEST
               README.txt
-              version.txt
+              setup.cfg
+              setup.py
+          zope-collection-1_0/
+              MANIFEST
+              setup.cfg
+              setup.py
+              zope/
+                  __init__.py
+                  README.txt
+                  version.txt
+      Support/
+          setuptools/
+              __init__.py
+              ...
+          zpkgtools/
+              __init__.py
+              ...
 
-The support packages aren't listed for brevity, and because they
-really aren't the meaningful part of the payload.
+The support packages aren't shown in their entirety, both for brevity
+and because they really aren't the meaningful part of the payload.
 
 
 Explanation
@@ -53,8 +59,12 @@
 material being distributed.  The distutils support files there
 (`setup.py`, `setup.cfg`, `MANIFEST`) are all generated by |zpkg|_.
 
-Within the top-level directory, a directory is created which contains
-the files of the collection itself (`Collection/` in this example).
+Within the top-level directory, a `Packages/` directory is created
+which contains the packages that define the collection; one of the
+packages it contains includes the files of the collection itself
+(`Collection-collection-1_0/` in this example).  Each component is
+equivalent to a non-collection package of just the one component.
+
 Collections are defined by a set of metadata files similar to
 packages.  These include:
 
@@ -64,7 +74,7 @@
   for a distribution.
 
 `PACKAGE.cfg`
-  An optional file whihc describes how the collection distribution
+  An optional file which describes how the collection distribution
   should be assembled.
 
 `DEPENDENCIES.cfg`
@@ -77,12 +87,14 @@
 
 For each dependency that can be fulfilled (a location is specified in
 the `resource maps`_ loaded by |zpkg|_), an additional directory is
-added to the top-level directory.  The new directory will have the
-same name as the resource being included.  For collections, this
-directory will have the collection content and any distutils support
-files needed.  For packages, the contents of the directory are exactly
-the same as they would be for a separate package distribution build
-with |zpkg|_.
+added to the `Packages/` directory.  The new directory will have the
+same name as the resource being included, with the release tag for
+component appended following a hyphen; this will normally be the same
+as the release tag for the collection as a whole.  For collections,
+this directory will have the collection content and any distutils
+support files needed.  For packages, the contents of the directory are
+exactly the same as they would be for a separate package distribution
+build with |zpkg|_.
 
 
 Issues
@@ -105,9 +117,10 @@
   This isn't enough of a problem to worry about at this point; we just
   need to keep this in mind when naming components.
 
-- We're not currently loading any sort of "package information" for
-  collections, but this is a software issue, not a design problem.
-  The information file will be called `SETUP.cfg`.
+- We're currently only supporting a limited amount of "package
+  information" for collections, but this is largely a software issue,
+  not a design problem.  The information file will be called
+  `SETUP.cfg`.
 
 
 .. include:: links.rst