More suggestions from Sean R.:

* Rewrite introductory paragraph
   * Make some fields optional and others multiple-user
   * Add header name to examples

pep-0241.txt

@@ -9,8 +9,9 @@ Post-History:
 
 Introduction
 
-    This PEP specifies the names and semantics of the fields used to store
-    metadata about Python software packages.  
+   This PEP describes a mechanism for adding metadata to Python
+   packages.  It includes specifics of the field names, and their
+   semantics and usage.
 
 
 Including Metadata in Packages
@@ -22,10 +23,10 @@ Including Metadata in Packages
     distribution (where the README, INSTALL, and other files usually
     go).
 
-    Developers may not provide their own "PKG-INFO" file.  The "sdist"
-    command will, if it detects an existing "PKG-INFO" file, terminate
+    Developers may not provide their own PKG-INFO file.  The "sdist"
+    command will, if it detects an existing PKG-INFO file, terminate
     with an appropriate error message.  This should prevent confusion
-    caused by the "PKG-INFO" and "setup.py" files being out of sync.
+    caused by the PKG-INFO and setup.py files being out of sync.
 
     The PKG-INFO file format is a single set of RFC-822 headers
     parseable by the rfc822.py module.  The field names listed in the
@@ -38,19 +39,25 @@ Fields
 
     This section specifies the names and semantics of each of the
     supported metadata fields.
+ 
+    Fields marked with "(Multiple use)" may be specified multiple
+    times in a single PKG-INFO file.  Other fields may only occur
+    once in a PKG-INFO file.  Fields marked with "(optional)" are
+    not required to appear in a valid PKG-INFO file, all other
+    fields must be present.
 
     Metadata-Version
 
       Version of the file format; currently "1.0" is the only
-      legal value here.
+      legal value here.  
 
-      Example: '1.0'
+      Example: 'Metadata-Version: 1.0'
 
     Name
 
       The name of the package.  
 
-      Example: 'BeagleVote'
+      Example: 'Name: BeagleVote'
       
     Version
 
@@ -59,9 +66,9 @@ Fields
       (StrictVersion or LooseVersion) in the distutils.version
       module.
 
-      Example: '1.0a2'
+      Example: 'Version: 1.0a2'
       
-    Platforms
+    Platform (multiple use)
 
       A (XXX whitespace?  comma?)-separated list of platform
       specifications.  Platform specifications are limited to the
@@ -75,7 +82,7 @@ Fields
 
       A one-line summary of what the package does.
 
-      Example: "A module for collecting votes from beagles."
+      Example: "Summary: A module for collecting votes from beagles."
       
     Description (optional)
 
@@ -85,22 +92,23 @@ Fields
       people won't include their instruction manual as the
       long-description.)
 
-      Example: 'This module collects votes from beagles in order to
-      determine their electoral wishes.  Do NOT try to use this module
-      with basset hounds; it makes them grumpy.'
+      Example: "Description: This module collects votes from beagles\n
+                             in order to determine their electoral wishes.\n
+                             Do NOT try to use this module with basset hounds; 
+                             it makes them grumpy."
       
-    Keywords
+    Keywords (optional)
 
       A list of additional keywords to be used to assist searching
       for this package in a larger catalog.
 
-      Example: 'dog puppy voting election'
+      Example: 'Keywords: dog puppy voting election'
       
     Home-page (optional)
 
       A string containing the URL for the package's home page.
 
-      Example: 'http://www.example.com/~cschultz/bvote/'
+      Example: 'Home-page: http://www.example.com/~cschultz/bvote/'
       
     Author (optional)
 
@@ -108,7 +116,9 @@ Fields
       information can also be added, separating each line with
       newlines.
 
-      Example: 'C. Schultz\nUniversal Features Syndicate\nLos Angeles, CA'
+      Example: 'Author: C. Schultz
+                        Universal Features Syndicate
+                        Los Angeles, CA'
       
     Author-email
 
@@ -123,7 +133,7 @@ Fields
       person.  Author-related metadata fields are not covered by this
       PEP.  
 
-      Example: '"C. Schultz" <cschultz@example.com>'
+      Example: 'Author-email: "C. Schultz" <cschultz@example.com>'
       
     License
       
@@ -159,10 +169,11 @@ Fields
       Mozilla PL, "public domain", Python, Qt PL, Zope PL, 
       nosource, shareware
 
-
       Note that being redistributable does not mean a package
       qualifies as free software, 'nosource' and 'shareware' being
       examples.
+
+      Example: 'License: MIT/X11'
       
 
 Copyright