diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst
index d575b8b..efdc51a 100644
--- a/Doc/distutils/setupscript.rst
+++ b/Doc/distutils/setupscript.rst
@@ -19,18 +19,18 @@
 distributions.  The Distutils' own setup script, shown here, is used to install
 the package into Python 1.5.2.) ::
 
-   #!/usr/bin/env python
+    #!/usr/bin/env python
 
-   from distutils.core import setup
+    from distutils.core import setup
 
-   setup(name='Distutils',
-         version='1.0',
-         description='Python Distribution Utilities',
-         author='Greg Ward',
-         author_email='gward@python.net',
-         url='http://www.python.org/sigs/distutils-sig/',
-         packages=['distutils', 'distutils.command'],
-        )
+    setup(name='Distutils',
+          version='1.0',
+          description='Python Distribution Utilities',
+          author='Greg Ward',
+          author_email='gward@python.net',
+          url='http://www.python.org/sigs/distutils-sig/',
+          packages=['distutils', 'distutils.command'],
+         )
 
 There are only two differences between this and the trivial one-file
 distribution presented in section :ref:`distutils-simple-example`: more metadata, and the
@@ -53,8 +53,8 @@
 :func:`os.listdir` to specify files, you should be careful to write portable
 code instead of hardcoding path separators::
 
-   glob.glob(os.path.join('mydir', 'subdir', '*.html'))
-   os.listdir(os.path.join('mydir', 'subdir'))
+    glob.glob(os.path.join('mydir', 'subdir', '*.html'))
+    os.listdir(os.path.join('mydir', 'subdir'))
 
 
 .. _listing-packages:
@@ -81,7 +81,7 @@
 package at all) are in :file:`lib`, modules in the :mod:`foo` package are in
 :file:`lib/foo`, and so forth.  Then you would put ::
 
-   package_dir = {'': 'lib'}
+    package_dir = {'': 'lib'}
 
 in your setup script.  The keys to this dictionary are package names, and an
 empty package name stands for the root package.  The values are directory names
@@ -92,7 +92,7 @@
 :file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc.  This would be
 written in the setup script as ::
 
-   package_dir = {'foo': 'lib'}
+    package_dir = {'foo': 'lib'}
 
 A ``package: dir`` entry in the :option:`package_dir` dictionary implicitly
 applies to all packages below *package*, so the :mod:`foo.bar` case is
@@ -114,7 +114,7 @@
 "root package" (i.e., no package at all).  This simplest case was shown in
 section :ref:`distutils-simple-example`; here is a slightly more involved example::
 
-   py_modules = ['mod1', 'pkg.mod2']
+    py_modules = ['mod1', 'pkg.mod2']
 
 This describes two modules, one of them in the "root" package, the other in the
 :mod:`pkg` package.  Again, the default package/directory layout implies that
@@ -144,17 +144,17 @@
 implemented by :file:`foo.c`.  If no additional instructions to the
 compiler/linker are needed, describing this extension is quite simple::
 
-   Extension('foo', ['foo.c'])
+    Extension('foo', ['foo.c'])
 
 The :class:`Extension` class can be imported from :mod:`distutils.core` along
 with :func:`setup`.  Thus, the setup script for a module distribution that
 contains only this one extension and nothing else might be::
 
-   from distutils.core import setup, Extension
-   setup(name='foo',
-         version='1.0',
-         ext_modules=[Extension('foo', ['foo.c'])],
-         )
+    from distutils.core import setup, Extension
+    setup(name='foo',
+          version='1.0',
+          ext_modules=[Extension('foo', ['foo.c'])],
+          )
 
 The :class:`Extension` class (actually, the underlying extension-building
 machinery implemented by the :command:`build_ext` command) supports a great deal
@@ -168,11 +168,11 @@
 The first argument to the :class:`Extension` constructor is always the name of
 the extension, including any package names.  For example, ::
 
-   Extension('foo', ['src/foo1.c', 'src/foo2.c'])
+    Extension('foo', ['src/foo1.c', 'src/foo2.c'])
 
 describes an extension that lives in the root package, while ::
 
-   Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
+    Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
 
 describes the same extension in the :mod:`pkg` package.  The source files and
 resulting object code are identical in both cases; the only difference is where
@@ -183,11 +183,11 @@
 same base package), use the :option:`ext_package` keyword argument to
 :func:`setup`.  For example, ::
 
-   setup(...,
-         ext_package='pkg',
-         ext_modules=[Extension('foo', ['foo.c']),
-                      Extension('subpkg.bar', ['bar.c'])],
-        )
+    setup(...,
+          ext_package='pkg',
+          ext_modules=[Extension('foo', ['foo.c']),
+                       Extension('subpkg.bar', ['bar.c'])],
+         )
 
 will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to
 :mod:`pkg.subpkg.bar`.
@@ -212,15 +212,15 @@
 This warning notwithstanding, options to SWIG can be currently passed like
 this::
 
-   setup(...,
-         ext_modules=[Extension('_foo', ['foo.i'],
-                                swig_opts=['-modern', '-I../include'])],
-         py_modules=['foo'],
-        )
+    setup(...,
+          ext_modules=[Extension('_foo', ['foo.i'],
+                                 swig_opts=['-modern', '-I../include'])],
+          py_modules=['foo'],
+         )
 
 Or on the commandline like this::
 
-   > python setup.py build_ext --swig-opts="-modern -I../include"
+    > python setup.py build_ext --swig-opts="-modern -I../include"
 
 On some platforms, you can include non-source files that are processed by the
 compiler and included in your extension.  Currently, this just means Windows
@@ -239,18 +239,18 @@
 For example, if your extension requires header files in the :file:`include`
 directory under your distribution root, use the ``include_dirs`` option::
 
-   Extension('foo', ['foo.c'], include_dirs=['include'])
+    Extension('foo', ['foo.c'], include_dirs=['include'])
 
 You can specify absolute directories there; if you know that your extension will
 only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get
 away with ::
 
-   Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
+    Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
 
 You should avoid this sort of non-portable usage if you plan to distribute your
 code: it's probably better to write C code like  ::
 
-   #include <X11/Xlib.h>
+    #include <X11/Xlib.h>
 
 If you need to include header files from some other Python extension, you can
 take advantage of the fact that header files are installed in a consistent way
@@ -262,17 +262,17 @@
 included in the search path when building Python extensions, the best approach
 is to write C code like  ::
 
-   #include <Numerical/arrayobject.h>
+    #include <Numerical/arrayobject.h>
 
 If you must put the :file:`Numerical` include directory right into your header
 search path, though, you can find that directory using the Distutils
 :mod:`distutils.sysconfig` module::
 
-   from distutils.sysconfig import get_python_inc
-   incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
-   setup(...,
-         Extension(..., include_dirs=[incdir]),
-         )
+    from distutils.sysconfig import get_python_inc
+    incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
+    setup(...,
+          Extension(..., include_dirs=[incdir]),
+          )
 
 Even though this is quite portable---it will work on any Python installation,
 regardless of platform---it's probably easier to just write your C code in the
@@ -288,17 +288,17 @@
 
 For example::
 
-   Extension(...,
-             define_macros=[('NDEBUG', '1'),
-                            ('HAVE_STRFTIME', None)],
-             undef_macros=['HAVE_FOO', 'HAVE_BAR'])
+    Extension(...,
+              define_macros=[('NDEBUG', '1'),
+                             ('HAVE_STRFTIME', None)],
+              undef_macros=['HAVE_FOO', 'HAVE_BAR'])
 
 is the equivalent of having this at the top of every C source file::
 
-   #define NDEBUG 1
-   #define HAVE_STRFTIME
-   #undef HAVE_FOO
-   #undef HAVE_BAR
+    #define NDEBUG 1
+    #define HAVE_STRFTIME
+    #undef HAVE_FOO
+    #undef HAVE_BAR
 
 
 Library options
@@ -313,15 +313,15 @@
 For example, if you need to link against libraries known to be in the standard
 library search path on target systems ::
 
-   Extension(...,
-             libraries=['gdbm', 'readline'])
+    Extension(...,
+              libraries=['gdbm', 'readline'])
 
 If you need to link with libraries in a non-standard location, you'll have to
 include the location in ``library_dirs``::
 
-   Extension(...,
-             library_dirs=['/usr/X11R6/lib'],
-             libraries=['X11', 'Xt'])
+    Extension(...,
+              library_dirs=['/usr/X11R6/lib'],
+              libraries=['X11', 'Xt'])
 
 (Again, this sort of non-portable construct should be avoided if you intend to
 distribute your code.)
@@ -379,8 +379,8 @@
 parentheses.  Each qualifier may consist of a comparison operator and a version
 number.  The accepted comparison operators are::
 
-   <    >    ==
-   <=   >=   !=
+    <    >    ==
+    <=   >=   !=
 
 These can be combined by using multiple qualifiers separated by commas (and
 optional whitespace).  In this case, all of the qualifiers must be matched; a
@@ -446,13 +446,13 @@
 The :option:`scripts` option simply is a list of files to be handled in this
 way.  From the PyXML setup script::
 
-   setup(...,
-         scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
-         )
+    setup(...,
+          scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
+          )
 
 .. versionchanged:: 2.7
-  All the scripts will also be added to the ``MANIFEST``
-  file if no template is provided. See :ref:`manifest`.
+    All the scripts will also be added to the ``MANIFEST``
+    file if no template is provided. See :ref:`manifest`.
 
 .. _distutils-installing-package-data:
 
@@ -478,29 +478,29 @@
 For example, if a package should contain a subdirectory with several data files,
 the files can be arranged like this in the source tree::
 
-   setup.py
-   src/
-       mypkg/
-           __init__.py
-           module.py
-           data/
-               tables.dat
-               spoons.dat
-               forks.dat
+    setup.py
+    src/
+        mypkg/
+            __init__.py
+            module.py
+            data/
+                tables.dat
+                spoons.dat
+                forks.dat
 
 The corresponding call to :func:`setup` might be::
 
-   setup(...,
-         packages=['mypkg'],
-         package_dir={'mypkg': 'src/mypkg'},
-         package_data={'mypkg': ['data/*.dat']},
-         )
+    setup(...,
+          packages=['mypkg'],
+          package_dir={'mypkg': 'src/mypkg'},
+          package_data={'mypkg': ['data/*.dat']},
+          )
 
 .. versionadded:: 2.4
 
 .. versionchanged:: 2.7
-  All the files that match ``package_data`` will be added to the ``MANIFEST``
-  file if no template is provided. See :ref:`manifest`.
+    All the files that match ``package_data`` will be added to the ``MANIFEST``
+    file if no template is provided. See :ref:`manifest`.
 
 
 .. _distutils-additional-files:
@@ -515,11 +515,11 @@
 :option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the
 following way::
 
-   setup(...,
-         data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
-                     ('config', ['cfg/data.cfg']),
-                     ('/etc/init.d', ['init-script'])]
-        )
+    setup(...,
+          data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
+                      ('config', ['cfg/data.cfg']),
+                      ('/etc/init.d', ['init-script'])]
+         )
 
 Note that you can specify the directory names where the data files will be
 installed, but you cannot rename the data files themselves.
@@ -540,8 +540,8 @@
 directory.
 
 .. versionchanged:: 2.7
-  All the files that match ``data_files`` will be added to the ``MANIFEST``
-  file if no template is provided. See :ref:`manifest`.
+    All the files that match ``data_files`` will be added to the ``MANIFEST``
+    file if no template is provided. See :ref:`manifest`.
 
 
 
@@ -576,7 +576,7 @@
 |                      | description of the        |                 |        |
 |                      | package                   |                 |        |
 +----------------------+---------------------------+-----------------+--------+
-| ``long_description`` | longer description of the | long string     |        |
+| ``long_description`` | longer description of the | long string     | \(5)   |
 |                      | package                   |                 |        |
 +----------------------+---------------------------+-----------------+--------+
 | ``download_url``     | location where the        | URL             | \(4)   |
@@ -590,28 +590,32 @@
 Notes:
 
 (1)
-   These fields are required.
+    These fields are required.
 
 (2)
-   It is recommended that versions take the form *major.minor[.patch[.sub]]*.
+    It is recommended that versions take the form *major.minor[.patch[.sub]]*.
 
 (3)
-   Either the author or the maintainer must be identified.
+    Either the author or the maintainer must be identified.
 
 (4)
-   These fields should not be used if your package is to be compatible with Python
-   versions prior to 2.2.3 or 2.3.  The list is available from the `PyPI website
-   <http://pypi.python.org/pypi>`_.
+    These fields should not be used if your package is to be compatible with Python
+    versions prior to 2.2.3 or 2.3.  The list is available from the `PyPI website
+    <http://pypi.python.org/pypi>`_.
+
+(5)
+    The ``long_description`` field is used by PyPI when you are registering a
+    package, to build its home page.
 
 'short string'
-   A single line of text, not more than 200 characters.
+    A single line of text, not more than 200 characters.
 
 'long string'
-   Multiple lines of plain text in reStructuredText format (see
-   http://docutils.sf.net/).
+    Multiple lines of plain text in reStructuredText format (see
+    http://docutils.sf.net/).
 
 'list of strings'
-   See below.
+    See below.
 
 None of the string values may be Unicode.
 
@@ -627,44 +631,44 @@
 (for final pre-release release testing). Some examples:
 
 0.1.0
-   the first, experimental release of a package
+    the first, experimental release of a package
 
 1.0.1a2
-   the second alpha release of the first patch version of 1.0
+    the second alpha release of the first patch version of 1.0
 
 :option:`classifiers` are specified in a python list::
 
-   setup(...,
-         classifiers=[
-             'Development Status :: 4 - Beta',
-             'Environment :: Console',
-             'Environment :: Web Environment',
-             'Intended Audience :: End Users/Desktop',
-             'Intended Audience :: Developers',
-             'Intended Audience :: System Administrators',
-             'License :: OSI Approved :: Python Software Foundation License',
-             'Operating System :: MacOS :: MacOS X',
-             'Operating System :: Microsoft :: Windows',
-             'Operating System :: POSIX',
-             'Programming Language :: Python',
-             'Topic :: Communications :: Email',
-             'Topic :: Office/Business',
-             'Topic :: Software Development :: Bug Tracking',
-             ],
-         )
+    setup(...,
+          classifiers=[
+              'Development Status :: 4 - Beta',
+              'Environment :: Console',
+              'Environment :: Web Environment',
+              'Intended Audience :: End Users/Desktop',
+              'Intended Audience :: Developers',
+              'Intended Audience :: System Administrators',
+              'License :: OSI Approved :: Python Software Foundation License',
+              'Operating System :: MacOS :: MacOS X',
+              'Operating System :: Microsoft :: Windows',
+              'Operating System :: POSIX',
+              'Programming Language :: Python',
+              'Topic :: Communications :: Email',
+              'Topic :: Office/Business',
+              'Topic :: Software Development :: Bug Tracking',
+              ],
+          )
 
 If you wish to include classifiers in your :file:`setup.py` file and also wish
 to remain backwards-compatible with Python releases prior to 2.2.3, then you can
 include the following code fragment in your :file:`setup.py` before the
 :func:`setup` call. ::
 
-   # patch distutils if it can't cope with the "classifiers" or
-   # "download_url" keywords
-   from sys import version
-   if version < '2.2.3':
-       from distutils.dist import DistributionMetadata
-       DistributionMetadata.classifiers = None
-       DistributionMetadata.download_url = None
+    # patch distutils if it can't cope with the "classifiers" or
+    # "download_url" keywords
+    from sys import version
+    if version < '2.2.3':
+        from distutils.dist import DistributionMetadata
+        DistributionMetadata.classifiers = None
+        DistributionMetadata.download_url = None
 
 
 Debugging the setup script
@@ -686,5 +690,3 @@
 to anything except an empty string, and distutils will now print detailed
 information what it is doing, and prints the full traceback in case an exception
 occurs.
-
-
diff --git a/Doc/distutils/uploading.rst b/Doc/distutils/uploading.rst
index 71b3ca1..84388c2 100644
--- a/Doc/distutils/uploading.rst
+++ b/Doc/distutils/uploading.rst
@@ -43,3 +43,32 @@
 *section* the name of the section in :file:`$HOME/.pypirc`, and
 :option:`--show-response` (which displays the full response text from the PyPI
 server for help in debugging upload problems).
+
+PyPI package display
+====================
+
+The ``long_description`` field plays a special role at PyPI. It is used by
+the server to display a home page for the registered package.
+
+If you use the `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
+syntax for this field, PyPI will parse it and display an HTML output for
+the package home page.
+
+The ``long_description`` field can be attached to a text file located
+in the package::
+
+    from distutils.core import setup
+
+    setup(name='Distutils',
+          long_description=open('README.txt'))
+
+In that case, `README.txt` is a regular reStructuredText text file located
+in the root of the package besides `setup.py`.
+
+To prevent registering broken reStructuredText content, you can use the
+:program:`rst2html` program that is provided by the `docutils` package
+and check the ``long_description`` from the command line::
+
+    $ python setup.py --long-description | rst2html.py > output.html
+
+`docutils` will display a warning if there's something wrong with your syntax.