reverted distutils doc to its 3.1 state

8 files changed, 244 insertions, 203 deletions

diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst
index d65c59f..69ec0de 100644
--- a/Doc/distutils/apiref.rst
+++ b/Doc/distutils/apiref.rst
@@ -21,9 +21,7 @@ setup script). Indirectly provides the  :class:`distutils.dist.Distribution` and
 .. function:: setup(arguments)
 
    The basic do-everything function that does most everything you could ever ask
-   for from a Distutils method.
-
-   .. See XXXXX
+   for from a Distutils method. See XXXXX
 
    The setup function takes a large number of arguments. These are laid out in the
    following table.
@@ -149,11 +147,11 @@ setup script). Indirectly provides the  :class:`distutils.dist.Distribution` and
 In addition, the :mod:`distutils.core` module exposed a number of  classes that
 live elsewhere.
 
-* :class:`~distutils.extension.Extension` from :mod:`distutils.extension`
+* :class:`Extension` from :mod:`distutils.extension`
 
-* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd`
+* :class:`Command` from :mod:`distutils.cmd`
 
-* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist`
+* :class:`Distribution` from :mod:`distutils.dist`
 
 A short description of each of these follows, but see the relevant module for
 the full reference.
@@ -997,7 +995,7 @@ directories.
    errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
    true).
 
-.. XXX Some of this could be replaced with the shutil module?
+**\*\*** Some of this could be replaced with the shutil module? **\*\***
 
 
 :mod:`distutils.file_util` --- Single file operations
@@ -1313,7 +1311,8 @@ provides the following additional features:
   the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the
   command line sets *verbose* to false.
 
-.. XXX Should be replaced with :mod:`optparse`.
+**\*\*** Should be replaced with :mod:`optik` (which is also now known as
+:mod:`optparse` in Python 2.3 and later). **\*\***
 
 
 .. function:: fancy_getopt(options, negative_opt, object, args)
@@ -1681,8 +1680,8 @@ lines, and joining lines with backslashes.
 ===================================================================
 
 .. module:: distutils.cmd
-   :synopsis: This module provides the abstract base class Command. This class
-              is subclassed by the modules in the distutils.command subpackage.
+   :synopsis: This module provides the abstract base class Command. This class is subclassed
+              by the modules in the distutils.command  subpackage.
 
 
 This module supplies the abstract base class :class:`Command`.
@@ -1692,84 +1691,20 @@ This module supplies the abstract base class :class:`Command`.
 
    Abstract base class for defining command classes, the "worker bees" of the
    Distutils.  A useful analogy for command classes is to think of them as
-   subroutines with local variables called *options*.  The options are declared
-   in :meth:`initialize_options` and defined (given their final values) in
-   :meth:`finalize_options`, both of which must be defined by every command
-   class.  The distinction between the two is necessary because option values
-   might come from the outside world (command line, config file, ...), and any
-   options dependent on other options must be computed after these outside
-   influences have been processed --- hence :meth:`finalize_options`.  The body
-   of the subroutine, where it does all its work based on the values of its
-   options, is the :meth:`run` method, which must also be implemented by every
-   command class.
-
-   The class constructor takes a single argument *dist*, a :class:`Distribution`
+   subroutines with local variables called *options*.  The options are declared in
+   :meth:`initialize_options` and defined (given their final values) in
+   :meth:`finalize_options`, both of which must be defined by every command class.
+   The distinction between the two is necessary because option values might come
+   from the outside world (command line, config file, ...), and any options
+   dependent on other options must be computed after these outside influences have
+   been processed --- hence :meth:`finalize_options`.  The body of the subroutine,
+   where it does all its work based on the values of its options, is the
+   :meth:`run` method, which must also be implemented by every command class.
+
+   The class constructor takes a single argument *dist*, a  :class:`Distribution`
    instance.
 
 
-Creating a new Distutils command
-================================
-
-This section outlines the steps to create a new Distutils command.
-
-A new command lives in a module in the :mod:`distutils.command` package. There
-is a sample template in that directory called :file:`command_template`.  Copy
-this file to a new module with the same name as the new command you're
-implementing.  This module should implement a class with the same name as the
-module (and the command).  So, for instance, to create the command
-``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
-:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit
-it so that it's implementing the class :class:`peel_banana`, a subclass of
-:class:`distutils.cmd.Command`.
-
-Subclasses of :class:`Command` must define the following methods.
-
-.. method:: Command.initialize_options()
-
-   Set default values for all the options that this command supports.  Note that
-   these defaults may be overridden by other commands, by the setup script, by
-   config files, or by the command-line.  Thus, this is not the place to code
-   dependencies between options; generally, :meth:`initialize_options`
-   implementations are just a bunch of ``self.foo = None`` assignments.
-
-
-.. method:: Command.finalize_options()
-
-   Set final values for all the options that this command supports. This is
-   always called as late as possible, ie.  after any option assignments from the
-   command-line or from other commands have been done.  Thus, this is the place
-   to to code option dependencies: if *foo* depends on *bar*, then it is safe to
-   set *foo* from *bar* as long as *foo* still has the same value it was
-   assigned in :meth:`initialize_options`.
-
-
-.. method:: Command.run()
-
-   A command's raison d'etre: carry out the action it exists to perform,
-   controlled by the options initialized in :meth:`initialize_options`,
-   customized by other commands, the setup script, the command-line, and config
-   files, and finalized in :meth:`finalize_options`.  All terminal output and
-   filesystem interaction should be done by :meth:`run`.
-
-
-.. attribute:: Command.sub_commands
-
-   *sub_commands* formalizes the notion of a "family" of commands,
-   e.g. ``install`` as the parent with sub-commands ``install_lib``,
-   ``install_headers``, etc.  The parent of a family of commands defines
-   *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name,
-   predicate)``, with *command_name* a string and *predicate* a function, a
-   string or ``None``.  *predicate* is a method of the parent command that
-   determines whether the corresponding command is applicable in the current
-   situation.  (E.g. we ``install_headers`` is only applicable if we have any C
-   header files to install.)  If *predicate* is ``None``, that command is always
-   applicable.
-
-   *sub_commands* is usually defined at the *end* of a class, because
-   predicates can be methods of the class, so they must already have been
-   defined.  The canonical example is the :command:`install` command.
-
-
 :mod:`distutils.command` --- Individual Distutils commands
 ==========================================================
 
@@ -2008,3 +1943,76 @@ The ``register`` command registers the package with the Python Package  Index.
 This is described in more detail in :pep:`301`.
 
 .. % todo
+
+:mod:`distutils.command.check` --- Check the meta-data of a package
+===================================================================
+
+.. module:: distutils.command.check
+   :synopsis: Check the metadata of a package
+
+
+The ``check`` command performs some tests on the meta-data of a package.
+For example, it verifies that all required meta-data are provided as
+the arguments passed to the :func:`setup` function.
+
+.. % todo
+
+
+Creating a new Distutils command
+================================
+
+This section outlines the steps to create a new Distutils command.
+
+A new command lives in a module in the :mod:`distutils.command` package. There
+is a sample template in that directory called  :file:`command_template`. Copy
+this file to a new module with the same name as the new command you're
+implementing. This module should implement a class with the same name as the
+module (and the command). So, for instance, to create the command
+``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
+:file:`command_template`  to :file:`distutils/command/peel_banana.py`, then edit
+it so that it's implementing the class :class:`peel_banana`, a subclass of
+:class:`distutils.cmd.Command`.
+
+Subclasses of :class:`Command` must define the following methods.
+
+
+.. method:: Command.initialize_options()
+
+   Set default values for all the options that this command supports.  Note that
+   these defaults may be overridden by other commands, by the setup script, by
+   config files, or by the command-line.  Thus, this is not the place to code
+   dependencies between options; generally, :meth:`initialize_options`
+   implementations are just a bunch of ``self.foo = None`` assignments.
+
+
+.. method:: Command.finalize_options()
+
+   Set final values for all the options that this command supports. This is
+   always called as late as possible, ie.  after any option assignments from the
+   command-line or from other commands have been done.  Thus, this is the place
+   to to code option dependencies: if *foo* depends on *bar*, then it is safe to
+   set *foo* from *bar* as long as *foo* still has the same value it was
+   assigned in :meth:`initialize_options`.
+
+
+.. method:: Command.run()
+
+   A command's raison d'etre: carry out the action it exists to perform, controlled
+   by the options initialized in :meth:`initialize_options`, customized by other
+   commands, the setup script, the command-line, and config files, and finalized in
+   :meth:`finalize_options`.  All terminal output and filesystem interaction should
+   be done by :meth:`run`.
+
+*sub_commands* formalizes the notion of a "family" of commands, eg. ``install``
+as the parent with sub-commands ``install_lib``, ``install_headers``, etc.  The
+parent of a family of commands defines *sub_commands* as a class attribute; it's
+a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string
+and *predicate* a function, a string or None. *predicate* is a method of
+the parent command that determines whether the corresponding command is
+applicable in the current situation.  (Eg. we ``install_headers`` is only
+applicable if we have any C header files to install.)  If *predicate* is None,
+that command is always applicable.
+
+*sub_commands* is usually defined at the \*end\* of a class, because predicates
+can be methods of the class, so they must already have been defined.  The
+canonical example is the :command:`install` command.
diff --git a/Doc/distutils/builtdist.rst b/Doc/distutils/builtdist.rst
index 8ce94d3..ee06fb4 100644
--- a/Doc/distutils/builtdist.rst
+++ b/Doc/distutils/builtdist.rst
@@ -146,8 +146,8 @@ commands.
 Creating dumb built distributions
 =================================
 
-.. XXX Need to document absolute vs. prefix-relative packages here, but first
-       I have to implement it!
+**\*\*** Need to document absolute vs. prefix-relative packages here, but first
+I have to implement it! **\*\***
 
 
 .. _creating-rpms:
@@ -241,8 +241,7 @@ tedious and error-prone, so it's usually best to put them in the setup
 configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`.  If
 you distribute or package many Python module distributions, you might want to
 put options that apply to all of them in your personal Distutils configuration
-file (:file:`~/.pydistutils.cfg`).  If you want to temporarily disable
-this file, you can pass the --no-user-cfg option to setup.py.
+file (:file:`~/.pydistutils.cfg`).
 
 There are three steps to building a binary RPM package, all of which are
 handled automatically by the Distutils:
diff --git a/Doc/distutils/commandref.rst b/Doc/distutils/commandref.rst
index 7282961..fbe40de 100644
--- a/Doc/distutils/commandref.rst
+++ b/Doc/distutils/commandref.rst
@@ -48,6 +48,50 @@ This command installs all (Python) scripts in the distribution.
 .. % \label{clean-cmd}
 
 
+.. _sdist-cmd:
+
+Creating a source distribution: the :command:`sdist` command
+============================================================
+
+**\*\*** fragment moved down from above: needs context! **\*\***
+
+The manifest template commands are:
+
++-------------------------------------------+-----------------------------------------------+
+| Command                                   | Description                                   |
++===========================================+===============================================+
+| :command:`include pat1 pat2 ...`          | include all files matching any of the listed  |
+|                                           | patterns                                      |
++-------------------------------------------+-----------------------------------------------+
+| :command:`exclude pat1 pat2 ...`          | exclude all files matching any of the listed  |
+|                                           | patterns                                      |
++-------------------------------------------+-----------------------------------------------+
+| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of |
+| ...`                                      | the listed patterns                           |
++-------------------------------------------+-----------------------------------------------+
+| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of |
+| ...`                                      | the listed patterns                           |
++-------------------------------------------+-----------------------------------------------+
+| :command:`global-include pat1 pat2 ...`   | include all files anywhere in the source tree |
+|                                           | matching --- & any of the listed patterns     |
++-------------------------------------------+-----------------------------------------------+
+| :command:`global-exclude pat1 pat2 ...`   | exclude all files anywhere in the source tree |
+|                                           | matching --- & any of the listed patterns     |
++-------------------------------------------+-----------------------------------------------+
+| :command:`prune dir`                      | exclude all files under *dir*                 |
++-------------------------------------------+-----------------------------------------------+
+| :command:`graft dir`                      | include all files under *dir*                 |
++-------------------------------------------+-----------------------------------------------+
+
+The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of
+regular filename characters, ``?`` matches any single regular filename
+character, and ``[range]`` matches any of the characters in *range* (e.g.,
+``a-z``, ``a-zA-Z``, ``a-f0-9_.``).  The definition of "regular filename
+character" is platform-specific: on Unix it is anything except slash; on Windows
+anything except backslash or colon.
+
+**\*\*** Windows support not there yet **\*\***
+
 .. % \section{Creating a built distribution: the
 .. % \protect\command{bdist} command family}
 .. % \label{bdist-cmds}
diff --git a/Doc/distutils/examples.rst b/Doc/distutils/examples.rst
index b495928..648063b 100644
--- a/Doc/distutils/examples.rst
+++ b/Doc/distutils/examples.rst
@@ -233,6 +233,58 @@ With exactly the same source tree layout, this extension can be put in the
          ext_modules=[Extension('foopkg.foo', ['foo.c'])],
          )
 
+Checking a package
+==================
+
+The ``check`` command allows you to verify if your package meta-data
+meet the minimum requirements to build a distribution.
+
+To run it, just call it using your :file:`setup.py` script. If something is
+missing, ``check`` will display a warning.
+
+Let's take an example with a simple script::
+
+    from distutils.core import setup
+
+    setup(name='foobar')
+
+Running the ``check`` command will display some warnings::
+
+    $ python setup.py check
+    running check
+    warning: check: missing required meta-data: version, url
+    warning: check: missing meta-data: either (author and author_email) or
+             (maintainer and maintainer_email) must be supplied
+
+
+If you use the reStructuredText syntax in the `long_description` field and
+`docutils <http://docutils.sourceforge.net/>`_ is installed you can check if
+the syntax is fine with the ``check`` command, using the `restructuredtext`
+option.
+
+For example, if the :file:`setup.py` script is changed like this::
+
+    from distutils.core import setup
+
+    desc = """\
+    My description
+    =============
+
+    This is the description of the ``foobar`` package.
+    """
+
+    setup(name='foobar', version='1', author='tarek',
+        author_email='tarek@ziade.org',
+        url='http://example.com', long_description=desc)
+
+Where the long description is broken, ``check`` will be able to detect it
+by using the `docutils` parser::
+
+    $ pythontrunk setup.py check --restructuredtext
+    running check
+    warning: check: Title underline too short. (line 2)
+    warning: check: Could not finish the parsing.
+
 .. % \section{Multiple extension modules}
 .. % \label{multiple-ext}
 
diff --git a/Doc/distutils/extending.rst b/Doc/distutils/extending.rst
index 5a70d03..972ff02 100644
--- a/Doc/distutils/extending.rst
+++ b/Doc/distutils/extending.rst
@@ -15,8 +15,8 @@ want to modify existing commands; many simply add a few file extensions that
 should be copied into packages in addition to :file:`.py` files as a
 convenience.
 
-Most distutils command implementations are subclasses of the
-:class:`distutils.cmd.Command` class.  New commands may directly inherit from
+Most distutils command implementations are subclasses of the :class:`Command`
+class from :mod:`distutils.cmd`.  New commands may directly inherit from
 :class:`Command`, while replacements often derive from :class:`Command`
 indirectly, directly subclassing the command they are replacing.  Commands are
 required to derive from :class:`Command`.
diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst
index 9208e36..5ec94c7 100644
--- a/Doc/distutils/setupscript.rst
+++ b/Doc/distutils/setupscript.rst
@@ -207,7 +207,7 @@ However, you can also include SWIG interface (:file:`.i`) files in the list; the
 SWIG on the interface file and compile the resulting C/C++ file into your
 extension.
 
-.. XXX SWIG support is rough around the edges and largely untested!
+**\*\*** SWIG support is rough around the edges and largely untested! **\*\***
 
 This warning notwithstanding, options to SWIG can be currently passed like
 this::
@@ -326,7 +326,7 @@ include the location in ``library_dirs``::
 (Again, this sort of non-portable construct should be avoided if you intend to
 distribute your code.)
 
-.. XXX Should mention clib libraries here or somewhere else!
+**\*\*** Should mention clib libraries here or somewhere else! **\*\***
 
 
 Other options
diff --git a/Doc/distutils/sourcedist.rst b/Doc/distutils/sourcedist.rst
index 2cfdf69..96e891b 100644
--- a/Doc/distutils/sourcedist.rst
+++ b/Doc/distutils/sourcedist.rst
@@ -26,16 +26,16 @@ to create a gzipped tarball and a zip file.  The available formats are:
 +===========+=========================+=========+
 | ``zip``   | zip file (:file:`.zip`) | (1),(3) |
 +-----------+-------------------------+---------+
-| ``gztar`` | gzip'ed tar file        | \(2)    |
+| ``gztar`` | gzip'ed tar file        | (2),(4) |
 |           | (:file:`.tar.gz`)       |         |
 +-----------+-------------------------+---------+
-| ``bztar`` | bzip2'ed tar file       |         |
+| ``bztar`` | bzip2'ed tar file       | \(4)    |
 |           | (:file:`.tar.bz2`)      |         |
 +-----------+-------------------------+---------+
 | ``ztar``  | compressed tar file     | \(4)    |
 |           | (:file:`.tar.Z`)        |         |
 +-----------+-------------------------+---------+
-| ``tar``   | tar file (:file:`.tar`) |         |
+| ``tar``   | tar file (:file:`.tar`) | \(4)    |
 +-----------+-------------------------+---------+
 
 Notes:
@@ -51,16 +51,8 @@ Notes:
    of the standard Python library since Python 1.6)
 
 (4)
-   requires the :program:`compress` program. Notice that this format is now
-   pending for deprecation and will be removed in the future versions of Python.
-
-When using any ``tar`` format (``gztar``, ``bztar``, ``ztar`` or
-``tar``) under Unix, you can specify the ``owner`` and ``group`` names
-that will be set for each member of the archive.
-
-For example, if you want all files of the archive to be owned by root::
-
-    python setup.py sdist --owner=root --group=root
+   requires external utilities: :program:`tar` and possibly one of :program:`gzip`,
+   :program:`bzip2`, or :program:`compress`
 
 
 .. _manifest:
@@ -76,10 +68,10 @@ source distribution:
   :option:`packages` options
 
 * all C source files mentioned in the :option:`ext_modules` or
-  :option:`libraries` options
+  :option:`libraries` options (
 
-  .. XXX Getting C library sources is currently broken -- no
-     :meth:`get_source_files` method in :file:`build_clib.py`!
+  **\*\*** getting C library sources currently broken---no
+  :meth:`get_source_files` method in :file:`build_clib.py`! **\*\***)
 
 * scripts identified by the :option:`scripts` option
   See :ref:`distutils-installing-scripts`.
@@ -111,60 +103,9 @@ per line, regular files (or symlinks to them) only.  If you do supply your own
 :file:`MANIFEST`, you must specify everything: the default set of files
 described above does not apply in this case.
 
-See :ref:`manifest_template` section for a syntax reference.
-
-.. _manifest-options:
-
-Manifest-related options
-========================
-
-The normal course of operations for the :command:`sdist` command is as follows:
-
-* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in`
-  and create the manifest
-
-* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
-  with just the default file set
-
-* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more
-  recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading
-  :file:`MANIFEST.in`
-
-* use the list of files now in :file:`MANIFEST` (either just generated or read
-  in) to create the source distribution archive(s)
-
-There are a couple of options that modify this behaviour.  First, use the
-:option:`--no-defaults` and :option:`--no-prune` to disable the standard
-"include" and "exclude" sets.
-
-Second, you might just want to (re)generate the manifest, but not create a
-source distribution::
-
-   python setup.py sdist --manifest-only
-
-:option:`-o` is a sortcut for :option:`--manifest-only`.
-
-.. _manifest_template:
-
-The MANIFEST.in template
-========================
-
-A :file:`MANIFEST.in` file can be added in a project to define the list of
-files to include in the distribution built by the :command:`sdist` command.
-
-When :command:`sdist` is run, it will look for the :file:`MANIFEST.in` file
-and interpret it to generate the :file:`MANIFEST` file that contains the
-list of files that will be included in the package.
-
-This mechanism can be used when the default list of files is not enough.
-(See :ref:`manifest`).
-
-Principle
----------
-
 The manifest template has one command per line, where each command specifies a
 set of files to include or exclude from the source distribution.  For an
-example, let's look at the Distutils' own manifest template::
+example, again we turn to the Distutils' own manifest template::
 
    include *.txt
    recursive-include examples *.txt *.py
@@ -176,7 +117,9 @@ matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching
 :file:`examples/sample?/build`.  All of this is done *after* the standard
 include set, so you can exclude files from the standard set with explicit
 instructions in the manifest template.  (Or, you can use the
-:option:`--no-defaults` option to disable the standard set entirely.)
+:option:`--no-defaults` option to disable the standard set entirely.)  There are
+several other commands available in the manifest template mini-language; see
+section :ref:`sdist-cmd`.
 
 The order of commands in the manifest template matters: initially, we have the
 list of default files as described above, and each command in the template adds
@@ -230,41 +173,36 @@ should always be slash-separated; the Distutils will take care of converting
 them to the standard representation on your platform. That way, the manifest
 template is portable across operating systems.
 
-Commands
---------
-
-The manifest template commands are:
-
-+-------------------------------------------+-----------------------------------------------+
-| Command                                   | Description                                   |
-+===========================================+===============================================+
-| :command:`include pat1 pat2 ...`          | include all files matching any of the listed  |
-|                                           | patterns                                      |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`exclude pat1 pat2 ...`          | exclude all files matching any of the listed  |
-|                                           | patterns                                      |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of |
-| ...`                                      | the listed patterns                           |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of |
-| ...`                                      | the listed patterns                           |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`global-include pat1 pat2 ...`   | include all files anywhere in the source tree |
-|                                           | matching --- & any of the listed patterns     |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`global-exclude pat1 pat2 ...`   | exclude all files anywhere in the source tree |
-|                                           | matching --- & any of the listed patterns     |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`prune dir`                      | exclude all files under *dir*                 |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`graft dir`                      | include all files under *dir*                 |
-+-------------------------------------------+-----------------------------------------------+
-
-The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of
-regular filename characters, ``?`` matches any single regular filename
-character, and ``[range]`` matches any of the characters in *range* (e.g.,
-``a-z``, ``a-zA-Z``, ``a-f0-9_.``).  The definition of "regular filename
-character" is platform-specific: on Unix it is anything except slash; on Windows
-anything except backslash or colon.
+
+.. _manifest-options:
+
+Manifest-related options
+========================
+
+The normal course of operations for the :command:`sdist` command is as follows:
+
+* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in`
+  and create the manifest
+
+* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
+  with just the default file set
+
+* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more
+  recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading
+  :file:`MANIFEST.in`
+
+* use the list of files now in :file:`MANIFEST` (either just generated or read
+  in) to create the source distribution archive(s)
+
+There are a couple of options that modify this behaviour.  First, use the
+:option:`--no-defaults` and :option:`--no-prune` to disable the standard
+"include" and "exclude" sets.
+
+Second, you might just want to (re)generate the manifest, but not create a source
+distribution::
+
+   python setup.py sdist --manifest-only
+
+:option:`-o` is a shortcut for :option:`--manifest-only`.
+
 
diff --git a/Doc/distutils/uploading.rst b/Doc/distutils/uploading.rst
index 7b790b1..e947245 100644
--- a/Doc/distutils/uploading.rst
+++ b/Doc/distutils/uploading.rst
@@ -60,13 +60,13 @@ in the package::
     setup(name='Distutils',
           long_description=open('README.txt'))
 
-In that case, :file:`README.txt` is a regular reStructuredText text file located
-in the root of the package besides :file:`setup.py`.
+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 :mod:`docutils` package
+: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
 
-:mod:`docutils` will display a warning if there's something wrong with your syntax.
+`docutils` will display a warning if there's something wrong with your syntax.