New installation instructions & credits (backport from trunk)

--HG--
branch : setuptools-0.6
extra : convert_revision : svn%3A6015fed2-1504-0410-9fe1-9d1591cc4771/sandbox/branches/setuptools-0.6%4053176

2 files changed, 170 insertions, 21 deletions

diff --git a/README.txt b/README.txt
new file mode 100755
index 00000000..d9b11301
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,149 @@
+===============================
+Installing and Using Setuptools
+===============================
+
+.. contents:: **Table of Contents**
+
+
+-------------------------
+Installation Instructions
+-------------------------
+
+Windows
+=======
+
+Install setuptools using the provided ``.exe`` installer.  If you've previously
+installed older versions of setuptools, please delete all ``setuptools*.egg``
+files from your system FIRST.
+
+If you are upgrading a previous version of setuptools that was installed using
+an ``.exe`` installer, please be sure to also *uninstall that older version*
+via your system's "Add/Remove Programs" feature, BEFORE installing the newer
+version.
+
+Once installation is complete, you will find an ``easy_install.exe`` program in
+your Python ``Scripts`` subdirectory.  Be sure to add this directory to your
+``PATH`` environment variable, if you haven't already done so.
+
+
+RPM-Based Systems
+=================
+
+Install setuptools using the provided source RPM.  The included ``.spec`` file
+assumes you are installing using the default ``python`` executable, and is not
+specific to a particular Python version.  The ``easy_install`` executable will
+be installed to a system ``bin`` directory such as ``/usr/bin``.
+
+If you wish to install to a location other than the default Python
+installation's default ``site-packages`` directory (and ``$prefix/bin`` for
+scripts), please use the ``.egg``-based installation approach described in the
+following section.
+
+
+Cygwin, Mac OS X, Linux, Other
+==============================
+
+1. Download the appropriate egg for your version of Python (e.g.
+   ``setuptools-0.6c4-py2.4.egg``).  Do NOT rename it.
+
+2. Run it as if it were a shell script, e.g. ``sh setuptools-0.6c4-py2.4.egg``.
+   Setuptools will install itself using the matching version of Python (e.g.
+   ``python2.4``), and will place the ``easy_install`` executable in the
+   default location for installing Python scripts (as determined by the
+   standard distutils configuration files, or by the Python installation).
+
+If you want to install setuptools to somewhere other than ``site-packages`` or
+your default distutils installation locations for libraries and scripts, you
+may include EasyInstall command-line options such as ``--prefix``,
+``--install-dir``, and so on, following the ``.egg`` filename on the same
+command line.  For example::
+
+    sh setuptools-0.6c4-py2.4.egg --prefix=~
+
+You can use ``--help`` to get a full options list, but we recommend consulting
+the `EasyInstall manual`_ for detailed instructions, especially `the section
+on custom installation locations`_.
+
+.. _The EasyInstall user's guide and reference manual: http://peak.telecommunity.com/DevCenter/EasyInstall
+.. _the section on custom installation locations: http://peak.telecommunity.com/DevCenter/EasyInstall#custom-installation-locations
+
+
+Cygwin Note
+-----------
+
+If you are trying to install setuptools for the *Windows* version of Python (as
+opposed to the Cygwin version that lives in ``/usr/bin``), you must make sure
+that an appropriate executable (``python2.3``, ``python2.4``, or ``python2.5``)
+is on your **Cygwin** ``PATH`` when invoking the egg.  For example, doing the
+following at a Cygwin bash prompt will install setuptools for the *Windows*
+Python found at ``C:\\Python24``::
+
+    ln -s /cygdrive/c/Python24/python.exe python2.4
+    PATH=.:$PATH sh setuptools-0.6c4-py2.4.egg
+    rm python2.4
+
+
+Downloads
+=========
+
+All setuptools downloads can be found at `the project's home page in the Python
+Cheese Shop`_.  Scroll to the very bottom of the page to find the links.
+
+.. _the project's home page in the Python Cheese Shop: http://cheeseshop.python.org/pypi/setuptools
+
+--------------------------------
+Using Setuptools and EasyInstall
+--------------------------------
+
+Here are some of the available manuals, tutorials, and other resources for
+learning about Setuptools, Python Eggs, and EasyInstall:
+
+* `The EasyInstall user's guide and reference manual`_
+* `The setuptools Developer's Guide`_
+* `The pkg_resources API reference`_
+* `Package Compatibility Notes`_ (user-maintained)
+* `The Internal Structure of Python Eggs`_
+
+Questions, comments, and bug reports should be directed to the `distutils-sig
+mailing list`_.  If you have written (or know of) any tutorials, documentation,
+plug-ins, or other resources for setuptools users, please let us know about
+them there, so this reference list can be updated.
+
+.. _Package Compatibility Notes: http://peak.telecommunity.com/DevCenter/PackageNotes
+.. _The Internal Structure of Python Eggs: http://peak.telecommunity.com/DevCenter/EggFormats
+.. _The setuptools Developer's Guide: http://peak.telecommunity.com/DevCenter/setuptools
+.. _The pkg_resources API reference: http://peak.telecommunity.com/DevCenter/PkgResources
+.. _The EasyInstall user's guide and reference manual: http://peak.telecommunity.com/DevCenter/EasyInstall
+.. _distutils-sig mailing list: http://mail.python.org/pipermail/distutils-sig/
+
+
+-------
+Credits
+-------
+
+* The original design for the ``.egg`` format and the ``pkg_resources`` API was
+  co-created by Phillip Eby and Bob Ippolito.  Bob also implemented the first
+  version of ``pkg_resources``, and supplied the OS X operating system version
+  compatibility algorithm.
+
+* Ian Bicking implemented many early "creature comfort" features of
+  easy_install, including support for downloading via Sourceforge and
+  Subversion repositories.  Ian's comments on the Web-SIG about WSGI
+  application deployment also inspired the concept of "entry points" in eggs,
+  and he has given talks at PyCon and elsewhere to inform and educate the
+  community about eggs and setuptools.
+
+* Jim Fulton contributed time and effort to build automated tests of various
+  aspects of ``easy_install``, and supplied the doctests for the command-line
+  ``.exe`` wrappers on Windows.
+
+* Phillip J. Eby is the principal author and maintainer of setuptools, and
+  first proposed the idea of an importable binary distribution format for
+  Python application plug-ins.
+
+* Significant parts of the implementation of setuptools were funded by the Open
+  Source Applications Foundation, to provide a plug-in infrastructure for the
+  Chandler PIM application.  In addition, many OSAF staffers (such as Mike
+  "Code Bear" Taylor) contributed their time and stress as guinea pigs for the
+  use of eggs and setuptools, even before eggs were "cool".  (Thanks, guys!)
+
diff --git a/setup.py b/setup.py
index c7168682..68203829 100755
--- a/setup.py
+++ b/setup.py
@@ -1,25 +1,14 @@
 #!/usr/bin/env python
 """Distutils setup file, used to install or test 'setuptools'"""
 
-def get_description():
-    # Get our long description from the documentation
-    f = file('setuptools.txt')
-    lines = []
-    for line in f:
-        if not line.strip():
-            break     # skip to first blank line
-    for line in f:
-        if line.startswith('.. contents::'):
-            break     # read to table of contents
-        lines.append(line)
-    f.close()
-    return ''.join(lines)
-
 from distutils.util import convert_path
-d = {}; execfile(convert_path('setuptools/command/__init__.py'), d)
-SETUP_COMMANDS = d['__all__']
 
+d = {}
+execfile(convert_path('setuptools/command/__init__.py'), d)
+
+SETUP_COMMANDS = d['__all__']
 VERSION = "0.6c4"
+
 from setuptools import setup, find_packages
 import sys
 scripts = []
@@ -30,9 +19,9 @@ setup(
     description="Download, build, install, upgrade, and uninstall Python "
         "packages -- easily!",
     author="Phillip J. Eby",
-    author_email="peak@eby-sarna.com",
+    author_email="distutils-sig@python.org",
     license="PSF or ZPL",
-    long_description = get_description(),
+    long_description = open('README.txt').read(),
     keywords = "CPAN PyPI distutils eggs package management",
     url = "http://peak.telecommunity.com/DevCenter/setuptools",
     test_suite = 'setuptools.tests',
@@ -77,9 +66,6 @@ setup(
             "dependency_links.txt = setuptools.command.egg_info:overwrite_arg",
         ],
 
-
-
-
         "console_scripts": [
              "easy_install = setuptools.command.easy_install:main",
              "easy_install-%s = setuptools.command.easy_install:main"
@@ -93,6 +79,7 @@ setup(
             ['eggsecutable = setuptools.command.easy_install:bootstrap'],
         },
 
+
     classifiers = [f.strip() for f in """
     Development Status :: 3 - Alpha
     Intended Audience :: Developers
@@ -121,3 +108,16 @@ setup(
 
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+