Add a note about how this fix relates to include_package_data. Although still...

Add a note about how this fix relates to include_package_data. Although still somewhat buried, this should clarify the issue raised in #218, and points out that include_package_data should really only be used if all the relevant files are in a supported version control system.

--HG--
branch : distribute
extra : rebase_source : e29284c59469ba9543b57afa64a0f52ee07eebf3

docs/setuptools.txt

@@ -756,17 +756,18 @@ e.g.::
         include_package_data = True
     )
 
-This tells setuptools to install any data files it finds in your packages.  The
-data files must be under CVS or Subversion control, or else they must be
+This tells setuptools to install any data files it finds in your packages.
+The data files must be under CVS or Subversion control, or else they must be
 specified via the distutils' ``MANIFEST.in`` file.  (They can also be tracked
 by another revision control system, using an appropriate plugin.  See the
 section below on `Adding Support for Other Revision Control Systems`_ for
 information on how to write such plugins.)
 
-If you want finer-grained control over what files are included (for example, if
-you have documentation files in your package directories and want to exclude
-them from installation), then you can also use the ``package_data`` keyword,
-e.g.::
+If the data files are not under version control, or are not in a supported
+version control system, or if you want finer-grained control over what files
+are included (for example, if you have documentation files in your package
+directories and want to exclude them from installation), then you can also use
+the ``package_data`` keyword, e.g.::
 
     from setuptools import setup, find_packages
     setup(
@@ -822,7 +823,10 @@ converts slashes to appropriate platform-specific separators at build time.
 (Note: although the ``package_data`` argument was previously only available in
 ``setuptools``, it was also added to the Python ``distutils`` package as of
 Python 2.4; there is `some documentation for the feature`__ available on the
-python.org website.)
+python.org website.  If using the setuptools-specific ``include_package_data``
+argument, files specified by ``package_data`` will *not* be automatically
+added to the manifest unless they are tracked by a supported version control
+system, or are listed in the MANIFEST.in file.)
 
 __ http://docs.python.org/dist/node11.html