[zpkg] SVN: zpkgtools/trunk/doc/ improve docs based on proofread
Fred L. Drake, Jr.
fdrake at gmail.com
Tue Sep 13 22:36:41 EDT 2005
Log message for revision 38460:
improve docs based on proofread
Changed:
U zpkgtools/trunk/doc/quickstart.txt
U zpkgtools/trunk/doc/zpkg.txt
-=-
Modified: zpkgtools/trunk/doc/quickstart.txt
===================================================================
--- zpkgtools/trunk/doc/quickstart.txt 2005-09-13 22:38:19 UTC (rev 38459)
+++ zpkgtools/trunk/doc/quickstart.txt 2005-09-14 02:36:38 UTC (rev 38460)
@@ -11,15 +11,14 @@
Unix systems.
The packaging tool builds a distribution pacakge based on *resources*.
-The tool builds a distribution based on a single resource named on the
-command line; this is called the *primary resource*. Individual
-resources can be Python packages or *collections*, which are
-(essentially) a bunch of files that should be included. Resources
-have *metadata* which describe what they contain and how they should
-be installed. One part of the metadata is a list of dependencies; a
-resource can depend on other resources. The packaging tool can be
-told to collect the dependencies of the primary resource into the
-distribution using a command-line option.
+The tool builds a distribution based on a single resource; this is
+called the *primary resource*. Individual resources can be Python
+packages or *collections*, which are (essentially) a bunch of files
+that should be included. Resources have *metadata* which describe
+what they contain and how they should be installed. One part of the
+metadata is a list of dependencies; a resource can depend on other
+resources. The packaging tool can be told to collect the dependencies
+of the primary resource into the distribution.
Preparation
@@ -42,10 +41,9 @@
You will need to define a *resource map* to tell |zpkg|_ where package
components can be found. Resource maps can be loaded from local files
or from remote locations specified by URL. The |zpkg|_ configuration
-file can contain a resource map as well, avoidin the need for a
+file can contain a resource map as well, avoiding the need for a
separate file. If you are primarily working with the Zope 3 packages,
-you should be able to use some prepared resource maps rather than
-defining your own.
+you can use a prepared map rather than defining your own.
The resource maps can be specified from the |zpkg|_ command line or in
a configuration file. It's generally easiest to work with a
@@ -61,9 +59,9 @@
'C:\\Documents and Settings\\username'
If you're working with the Zope 3 source code (for Zope 3.2 or newer),
-a sample configuration with an embedded resource map is in the
-checked-out sources as *releases/Zope.cfg*. Take a look at that for a
-moderately typical configuration.
+a sample configuration and resource map are in the checked-out sources
+as *releases/Zope.cfg* and *releases/Zope.map*. Take a look at that
+for a moderately typical configuration.
Read more about resource maps in |zpkg|_, and about how resource
locations are specified in `Resource Locations <resources.html>`_.
@@ -162,7 +160,7 @@
itself. For that, at least a small bit of additional metadata is
required.
-The additional metadata required is called "publication metadata" and
+The additional metadata required is called *publication metadata* and
is stored in the file *PUBLICATION.cfg* in the top directory of the
resource being described. For Python packages, this is the directory
that contains the *__init__.py* file. The *PUBLICATION.cfg* file has
Modified: zpkgtools/trunk/doc/zpkg.txt
===================================================================
--- zpkgtools/trunk/doc/zpkg.txt 2005-09-13 22:38:19 UTC (rev 38459)
+++ zpkgtools/trunk/doc/zpkg.txt 2005-09-14 02:36:38 UTC (rev 38460)
@@ -184,6 +184,11 @@
the package. Every line should specify one package. This is equivalent of
specifying **-x** or **--exclude** for every excluded package.
+If a package is excluded, dependency information is not loaded for
+that package either. Dependencies for that package are only loaded if
+some other package also depends on them, unless they have also been
+excluded explicitly.
+
For example, we can exclude ``zope.interface`` and ``zope.component``
using::
@@ -207,8 +212,8 @@
Resources are identified by names without any whitespace; if the
resource is a Python package, the resource name is the full package
-name ("ZConfig" or "zope.app.tree" for example). Resource names must
-be unique.
+name (``ZConfig`` or ``zope.app.tree`` for example). Resource names
+must be unique.
A file representing a resource map is a simple two-column table with
the fields separated by whitespace. Blank lines and comments (lines
@@ -237,22 +242,25 @@
Release tags which follow this convention all have the form:
- *name*-*encoded-version*
+ *name*-*encoded_version*
where *name* is the name of the package being released and
-*encoded-version* is the result of a simple transformation of the
+*encoded_version* is the result of a simple transformation of the
version number. **zpkg** doesn't ever care about the name used in the
tag, only about the version information. It is significant that the
version information follows the last hyphen in the tag name; it *must*
-be the last part of the tag. The encoded version is the version
-number with all periods replaced by underscore characters; it may
-prove that the replacement isn't necessary when working with
-Subversion, though it is required for CVS. The version number must
-conform to a pattern of two to four numbers separated by periods,
-optionally followed by one or more letters, which in turn may be
-optionally followed by another number. Reasonable examples include
-``1.0``, ``0.1``, ``1.1.42``, ``2.3.4.5``, ``1.0a``, ``1.0a1``, and
-``5.4.3beta2``.
+be the last part of the tag. The encoding for theh version number is
+very simple: any underscores in the tag name are converted to dots to
+get the actual version number. Existing dots in the encoded version
+number are not changed. This allows using a version number like
+``ZConfig-2.3.1`` in Subversion, where dots are allowed in tags names
+(since there's no special interpretation of names), while
+``ZConfig-2_3_1`` would be required in CVS, since dots are not allowed
+in version names. The version number must conform to a pattern of two
+to four numbers separated by periods, optionally followed by one or
+more letters, which in turn may be optionally followed by another
+number. Reasonable examples include ``1.0``, ``0.1``, ``1.1.42``,
+``2.3.4.5``, ``1.0a``, ``1.0a1``, and ``5.4.3beta2``.
For example, for the package ``mypkg``, the following tags correspond
to the following version numbers:
@@ -261,9 +269,9 @@
Tag Version
================== ============
mypkg-1_0 1.0
-mypkg-0_1 0.1
+mypkg-0.1 0.1
mypkg-1_1_42 1.1.42
-mypkg-2_3_4_5 2.3.4.5
+mypackage-2_3.4_5 2.3.4.5
mypkg-1_0a 1.0a
mypkg-1_0a1 1.0a1
mypkg-5_4_3_0beta2 5.4.3.0beta2
More information about the zpkg
mailing list