Commits

Éric Araujo  committed 4392a96

Change description → description-file.

Reusing the PEP 345 name for a field with different semantics would
cause confusion, so it’s best to change it for a clear name. Thanks
to Ronald Oussoren for the suggestion.

  • Participants
  • Parent commits 1acfde0

Comments (0)

Files changed (2)

File new-config-file.rst

   maintainer = Éric Araujo
   maintainer-email = merwok@netwok.org
   summary = A sample project demonstrating distutils2 packaging
-  description = README
+  description-file = README
   keywords = distutils2, packaging, sample project
 
   classifiers =
 is a path relative to the directory containing the :file:`setup.cfg` (``..``
 disallowed). Examples::
 
-  description = README
+  description-file = README
 
 ::
 
-  description = lib/python/unicorn/README.rst
+  description-file = lib/python/unicorn/README.rst
 
 The value can be a list of files, to be concatenated in order and used as
 description. Now that Distutils2 and PyPI allow uploading documentation and
 adding arbitrary links in a project page, the need for overly long
-``description`` values is reduced, but some users would still want to
-concatenate e.g. :file:`README` and :file:`NEWS`. Thus, this field should
-allow a newline-separated list of files (it allows paths with spaces and
-complies with already-defined way of giving multi-value fields).
+descriptions is reduced, but some users would still want to concatenate e.g.
+:file:`README` and :file:`NEWS`. Thus, this field should allow a
+newline-separated list of files (it allows paths with spaces and complies with
+the already defined way of giving multi-value fields).
+
+The name is not ``description`` since it would have conflicting semantics with
+PEP 345, but not ``description-files`` so as not to encourage multi-file
+values.
 
 Files listed in that field are automatically added to distributions.
 
 Argument in :file:`setup.py` Field in :file:`setup.cfg`
 ============================ ========================================
 description                  summary
-long_description             description (changed meaning)
+long_description             description-file (changed meaning)
 url                          home-page
 N/A                          project-url
 every other metadata field   unchanged
 with separate author name and email fields, the user-written :file:`setup.cfg`
 could have some additional niceties. The Distutils maintainer voted this down
 for the sake of clarity: Field names in :file:`setup.cfg` are directly
-translated from :PEP:`345` without any complication. In a case like
-description__, there are real advantages in changing it in :file:`setup.cfg`,
-but this is not the case for author and author-email.
-
-.. __: `Get description from a file`_
+translated from :PEP:`345` without any complication. There is no real
+advantage in changing the format here.
 
 
 Get metadata from hooks
 maintainer = Éric Araujo
 maintainer-email = merwok@netwok.org
 summary = A sample project demonstrating distutils2 packaging
-description = README
+description-file = README
 keywords = distutils2, packaging, sample project
 
 classifiers =