Further PEP 426 cleanups

- better explain the new description format
- rationale for why Obsoletes-Dist header was removed
- rationale for why Description header was retained
- miscellaneous formatting and editorial fixes

pep-0426.txt

@@ -37,11 +37,12 @@ Metadata Files
 
 The syntax defined in this PEP is for use with Python distribution
 metadata files. The file format is a simple UTF-8 encoded Key: value
-format with case-insensitive keys and no maximum line length, followed by
-a blank line and an arbitrary payload.  It is parseable by the ``email``
-module with an appropriate ``email.policy.Policy()``.
+format with case-insensitive keys and no maximum line length, optionally
+followed by a blank line and a payload containing a description of the
+distribution.
 
-When ``metadata`` is a Unicode string,
+This format is parseable by the ``email`` module with an appropriate
+``email.policy.Policy()``. When ``metadata`` is a Unicode string,
 ```email.parser.Parser().parsestr(metadata)`` is a serviceable parser.
 
 There are two standard locations for these metadata files:
@@ -63,17 +64,18 @@ ASCII. Parser implementations should be aware that older versions of
 the Metadata specification do not specify an encoding.
 
 
-Fields
-======
+Metadata Header Fields
+=======================
 
 This section specifies the names and semantics of each of the
-supported metadata fields.
+supported fields in the metadata header.
 
 In a single Metadata 1.3 file, fields marked with "(optional)" may occur
 0 or 1 times.  Fields marked with "(multiple use)" may be specified
 0, 1 or more times.  Only "Metadata-Version", "Name", "Version", and
-"Summary" must appear exactly once.  The fields may appear in any order
-within the header section of the file.
+"Summary" must appear exactly once.
+
+The fields may appear in any order within the header section of the file.
 
 
 Metadata-Version
@@ -120,24 +122,21 @@ Example::
 Description (optional, deprecated)
 ----------------------------------
 
-A longer description of the distribution that can run to several
-paragraphs.  Software that deals with metadata should not assume
-any maximum size for this field.
-
-The contents of this field can be written using reStructuredText
-markup [1]_.  For programs that work with the metadata, supporting
-markup is optional; programs can also display the contents of the
-field as-is.  This means that authors should be conservative in
-the markup they use.
-
-Since a line separator immediately followed by another line separator
-indicates the end of the headers section, any line separators in the
-description must be suffixed by whitespace to indicate continuation.
-
 Starting with Metadata 1.3, the recommended place for the description is in
 the payload section of the document, after the last header.  The description
 does not need to be reformatted when it is included in the payload.
 
+See `Describing the Distribution`_ for more information on the expected
+contents of this field.
+
+Since a line separator immediately followed by another line separator
+indicates the end of the headers section, any line separators in a
+``Description`` header field must be suffixed by whitespace to
+indicate continuation.
+
+It is an error to provide both a ``Description`` header and a metadata
+payload.
+
 
 Keywords (optional)
 -------------------
@@ -510,6 +509,31 @@ error, as is an extension field with no corresponding ``Extension: Name``
 entry.
 
 
+Describing the Distribution
+===========================
+
+The distribution metadata should include a longer description of the
+distribution that may run to several paragraphs. Software that deals
+with metadata should not assume any maximum size for the description.
+
+The recommended location for the description is in the metadata payload,
+separated from the header fields by at least one completely blank line
+(that is, two successive line separators with no other characters
+between them, not even whitespace).
+
+Alternatively, the description may be provided in the `Description`__
+metadata header field. Providing both a ``Description`` field and a
+payload is an error.
+
+__ `Description (optional, deprecated)`_
+
+The distribution description can be written using reStructuredText
+markup [1]_.  For programs that work with the metadata, supporting
+markup is optional; programs may also display the contents of the
+field as plain text without any special formatting.  This means that
+authors should be conservative in the markup they use.
+
+
 Version Scheme
 ==============
 
@@ -543,8 +567,8 @@ Within a post release (``1.0.post1``)::
     devN, <no suffix>
 
 Note that ``devN`` and ``postN`` must always be preceded by a dot, even
-when used immediately following a numeric version (e.g. `1.0.dev456`,
-`1.0.post1`).
+when used immediately following a numeric version (e.g. ``1.0.dev456``,
+``1.0.post1``).
 
 Within a given suffix, ordering is by the value of the numeric component.
 
@@ -557,6 +581,8 @@ within the same numeric version.
 Example Version Order
 ---------------------
 
+::
+
     1.0.dev456
     1.0a1
     1.0a2.dev456
@@ -570,8 +596,7 @@ Example Version Order
     1.0
     1.0.post456.dev34
     1.0.post456
-    1.1.dev123
-    ...
+    1.1.dev1
 
 
 Version Specifiers
@@ -612,7 +637,7 @@ excludes all pre-releases of later versions::
 
     >= 1.0
 
-While these specifiers would include them:
+While these specifiers would include them::
 
     >= 1.0a1
     >= 1.0c1
@@ -620,10 +645,10 @@ While these specifiers would include them:
     >= 1.0, < 2.0.dev123
 
 Dependency resolution tools should use the above rules by default, but may
-also allow users to request the following alternative behaviour:
+also allow users to request the following alternative behaviours:
 
 * accept already installed pre-releases for all version specifiers
-* retrieve and install pre-releases for all version specifiers
+* retrieve and install available pre-releases for all version specifiers
 
 Post releases and purely numeric releases receive no special treatment -
 they are always included unless explicitly excluded.
@@ -645,8 +670,7 @@ Some Examples:
 - ``Requires-Dist: zope.interface (3.1.0)``: any version that starts with
   3.1.0, excluding pre-releases. Since that particular project doesn't
   use more than 3 digits, it also means "only the 3.1.0 release".
-- ``Requires-Python: 3``: Any Python 3 version, no matter wich one, excluding
-  pre-releases.
+- ``Requires-Python: 3``: Any Python 3 version, excluding pre-releases.
 - ``Requires-Python: >=2.6,<3``: Any version of Python 2.6 or 2.7, including
   post releases (if they were used for Python). It excludes pre releases of
   Python 3.
@@ -703,12 +727,12 @@ to use other sequences like tuples or lists on the right side.
 
 The fields that benefit from this marker are:
 
-- Requires-Python
-- Requires-External
-- Requires-Dist
-- Setup-Requires-Dist
-- Provides-Dist
-- Classifier
+- ``Requires-Python``
+- ``Requires-External``
+- ``Requires-Dist``
+- ``Setup-Requires-Dist``
+- ``Provides-Dist``
+- ``Classifier``
 
 
 Optional features
@@ -723,10 +747,10 @@ feature has been requested.
 Other distributions then require an optional feature by placing it
 inside square brackets after the distribution name when declaring the
 dependency. Multiple features can be requisted by separating them with a
-comma (,).
+comma within the brackets.
 
 The full set of dependency requirements is then the union of the
-sets created first evaluating the `Requires-Dist` (or
+sets created by first evaluating the `Requires-Dist` (or
 `Setup-Requires-Dist`) fields with `extra` set to `None` and then to
 the name of each requested feature.
 
@@ -758,12 +782,12 @@ The metadata specification may be updated with clarifications without
 requiring a new PEP or a change to the metadata version.
 
 Adding new features (other than through the extension mechanism), or
-changing the meaning of existing fields requires a new metadata version
+changing the meaning of existing fields, requires a new metadata version
 defined in a new PEP.
 
 
-Summary of Differences From PEP 345
-===================================
+Summary of Differences From \PEP 345
+====================================
 
 * Metadata-Version is now 1.3
 
@@ -772,6 +796,8 @@ Summary of Differences From PEP 345
 * Explicit permission for in-place clarifications without releasing a new
   version of the specification
 
+* General reformatting of the PEP to make it easier to read
+
 * Values are now expected to be UTF-8
 
 * Changed the version scheme (eliminating the dependency on PEP 386)
@@ -910,11 +936,15 @@ Updated obsolescence mechanism
 The marker to indicate when a project is obsolete and should be replaced
 has been moved to the obsolete project (the new ``Obsoleted-By`` field),
 replacing the previous marker on the replacement project (the removed
-``Obsoletes`` field).
+``Obsoletes-Dist`` field).
 
 This should allow distribution tools to more easily warn users of
 obsolete projects and their suggested replacements.
 
+The ``Obsoletes-Dist`` header is removed rather than deprecated as it
+is not widely supported, and so removing it does not present any significant
+barrier to tools and projects adopting the new metadata format.
+
 
 Simpler description format
 --------------------------
@@ -925,6 +955,10 @@ them to be formatted neatly as reStructuredText without needing to
 carefully avoid the introduction of a blank line that would terminate
 the header section.
 
+The ``Distribution`` header is deprecated rather than removed to support
+easier conversion of existing tools and projects to the new metadata
+format.
+
 
 References
 ==========