A bundle of wording improvements, corrections, clarifications, updates,

and so forth.

Doc/dist/dist.tex

@@ -21,16 +21,16 @@ In the past, Python module developers have not had much infrastructure
 support for distributing modules, nor have Python users had much support
 for installing and maintaining third-party modules.  With the
 introduction of the Python Distribution Utilities (Distutils for short)
-in Python 2.0, this situation should start to improve.
+in Python 1.6, this situation should start to improve.
 
 This document only covers using the Distutils to distribute your Python
-modules.  Using the Distutils does not tie you to Python 2.0, though:
-the Distutils work just fine with Python 1.5, and it is reasonable (and
-expected to become commonplace) to expect users of Python 1.5 to
+modules.  Using the Distutils does not tie you to Python 1.6, though:
+the Distutils work just fine with Python 1.5.2, and it is reasonable
+(and expected to become commonplace) to expect users of Python 1.5.2 to
 download and install the Distutils separately before they can install
-your modules.  Python 2.0 users, of course, won't have to add anything
-to their Python installation in order to use the Distutils to install
-third-party modules.
+your modules.  Python 1.6 (or later) users, of course, won't have to add
+anything to their Python installation in order to use the Distutils to
+install third-party modules.
 
 This document concentrates on the role of developer/distributor: if
 you're looking for information on installing Python modules, you
@@ -68,9 +68,10 @@ without having to run a single setup script or compile a line of code.
 \label{simple-example}
 
 The setup script is usually quite simple, although since it's written in
-Python, there are no arbitrary limits to what you can do.  If all you
-want to do is distribute a module called \module{foo}, contained in a
-file \file{foo.py}, then your setup script can be as little as this:
+Python, there are no arbitrary limits to what you can do with it.  If
+all you want to do is distribute a module called \module{foo}, contained
+in a file \file{foo.py}, then your setup script can be as little as
+this:
 \begin{verbatim}
 from distutils.core import setup
 setup (name = "foo",
@@ -118,7 +119,6 @@ almost exclusively for module developers, while \command{install} is
 more often for installers (although most developers will want to install
 their own code occasionally).
 
-\XXX{only partially implemented}%
 If you want to make things really easy for your users, you can create
 one or more built distributions for them.  For instance, if you are
 running on a Windows machine, and want to make things easy for other
@@ -128,9 +128,10 @@ appropriate type of built distribution for this platform) with the
 \begin{verbatim}
 python setup.py bdist_wininst
 \end{verbatim}
-will create an executable installer, \file{Foo-1\_0.exe}, in the current
-directory.
+will create an executable installer, \file{Foo-1.0.win32.exe}, in the
+current directory.
 
+\XXX{not implemented yet}
 (Another way to create executable installers for Windows is with the
 \command{bdist\_wise} command, which uses Wise---the commercial
 installer-generator used to create Python's own installer---to create
@@ -142,11 +143,21 @@ medium-sized module collections.  You'll need to have version XXX of
 Wise installed on your system for the \command{bdist\_wise} command to
 work; it's available from \url{http://foo/bar/baz}.)
 
-Other \command{bdist} commands exist for other platforms: for example,
-\command{bdist\_rpm} for RPM-based Linux systems, (\command{bdist\_deb})
-for Debian-based Linux systems, and so forth.  See
-section~\ref{bdist-cmds} for details on all the \command{bdist}
-commands.
+Currently (Distutils 0.9.1), the are only other useful built
+distribution format is RPM, implemented by the \command{bdist\_rpm}
+command.  For example, the following command will create an RPM file
+called \file{Foo-1.0.noarch.rpm}:
+\begin{verbatim}
+python setup.py bdist_rpm
+\end{verbatim}
+(This uses the \command{rpm} command, so has to be run on an RPM-based
+system such as Red Hat Linux, SuSE Linux, or Mandrake Linux.)
+
+You can find out what distribution formats are available at any time by
+running
+\begin{verbatim}
+python setup.py bdist --help-formats
+\end{verbatim}
 
 
 \subsection{General Python terminology}
@@ -158,9 +169,8 @@ that everyone is operating from a common starting point, we offer the
 following glossary of common Python terms:
 \begin{description}
 \item[module] the basic unit of code reusability in Python: a block of
-  code imported by some other code.  There are three types of modules
-  that concern us here: pure Python modules, extension modules, and
-  packages.
+  code imported by some other code.  Three types of modules concern us
+  here: pure Python modules, extension modules, and packages.
 \item[pure Python module] a module written in Python and contained in a
   single \file{.py} file (and possibly associated \file{.pyc} and/or
   \file{.pyo} files).  Sometimes referred to as a ``pure module.''
@@ -224,10 +234,10 @@ supplied as keyword arguments to \function{setup()}.
 
 Here's a slightly more involved example, which we'll follow for the next
 couple of sections: the Distutils' own setup script.  (Keep in mind that
-although the Distutils are included with Python 2.0, they also have an
-independent existence so that Python 1.5 users can use them to install
-other module distributions.  The Distutils' own setup script is used to
-install the package into Python 1.5.)
+although the Distutils are included with Python 1.6 and later, they also
+have an independent existence so that Python 1.5.2 users can use them to
+install other module distributions.  The Distutils' own setup script,
+shown here, is used to install the package into Python 1.5.2.)
 
 \begin{verbatim}
 #!/usr/bin/env python
@@ -236,7 +246,7 @@ from distutils.core import setup
 
 setup (name = "Distutils",
        version = "1.0",
-       description = "Python Module Distribution Utilities",
+       description = "Python Distribution Utilities",
        author = "Greg Ward",
        author_email = "gward@python.net",
        url = "http://www.python.org/sigs/distutils-sig/",
@@ -284,17 +294,17 @@ package anyways.)
 If you use a different convention to lay out your source directory,
 that's no problem: you just have to supply the \option{package\_dir}
 option to tell the Distutils about your convention.  For example, say
-you keep all Python source under \file{lib}, so that modules not in any
-package are right in \file{lib}, modules in the \module{foo} package
-are in \file{lib/foo}, and so forth.  Then you would put
+you keep all Python source under \file{lib}, so that modules in the
+``root package'' (i.e., not in any package at all) are right in
+\file{lib}, modules in the \module{foo} package are in \file{lib/foo},
+and so forth.  Then you would put
 \begin{verbatim}
 package_dir = {'': 'lib'}
 \end{verbatim}
 in your setup script.  (The keys to this dictionary are package names,
-and an empty package name stands for the ``root package,'' i.e. no
-package at all.  The values are directory names relative to your
-distribution root.)  In this case, when you say
-\code{packages = ['foo']}, you are promising that the file
+and an empty package name stands for the root package.  The values are
+directory names relative to your distribution root.)  In this case, when
+you say \code{packages = ['foo']}, you are promising that the file
 \file{lib/foo/\_\_init\_\_.py} exists.
 
 Another possible convention is to put the \module{foo} package right in 
@@ -337,15 +347,11 @@ And again, you can override the package/directory layout using the
 \subsection{Describing extension modules}
 \label{sec:describing-extensions}
 
-\XXX{be sure to describe the whole \code{build\_info} dict, including
-  \code{extra\_compile\_args} and \code{extra\_link\_args}}
 
 
 \section{Writing the Setup Configuration File}
 \label{setup-config}
 
-\XXX{not implemented yet!}
-
 Often, it's not possible to write down everything needed to build a
 distribution \emph{a priori}.  You need to get some information from the
 user, or from the user's system, in order to proceed.  For example, you
@@ -491,8 +497,9 @@ follows:
 \begin{itemize}
 \item if the manifest file, \file{MANIFEST} doesn't exist, read
   \file{MANIFEST.in} and create the manifest
-\item if \file{MANIFEST.in} is more recent than \file{MANIFEST},
-  recreate \file{MANIFEST} by reading \file{MANIFEST.in}
+\item 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}
 \item use the list of files now in \file{MANIFEST} (either just
   generated or read in) to create the source distribution archive(s)
 \end{itemize}
@@ -505,8 +512,6 @@ manifest:
 \begin{verbatim}
 python setup.py sdist --force-manifest
 \end{verbatim}
-\XXX{this is stupid, but is there a better way to do it without
-  reprocessing MANIFEST.in every single bloody time?}
 
 Or, you might just want to (re)generate the manifest, but not create a
 source distribution:
@@ -562,54 +567,57 @@ python setup.py bdist
 then the Distutils builds my module distribution (the Distutils itself
 in this case), does a ``fake'' installation (also in the \file{build}
 directory), and creates the default type of built distribution for my
-platform.  In Distutils 0.8, only two types of built distribution are
-supported: \code{gztar} (default on non-Linux Unix) and \code{zip}
-(default on Windows).  Thus, the above command on a Unix system creates
-\file{Distutils-0.8.built-posix.tar.gz}; unpacking this tarball from
-Python's \filevar{prefix} directory installs the Distutils just as
-though you had downloaded the source distribution and run \code{python
-  setup.py install}.  Obviously, for pure Python distributions, this
-isn't a huge win---but for non-pure distributions, which include
-extensions that would need to be compiled, it can mean the difference
-between someone being able to use your extensions or not.
+platform.  Currently, the default format for built distributions is a
+``dumb'' archive---tarball on Unix, ZIP file on Windows.  (These are
+called ``dumb'' built distributions, because they must be unpacked in a
+specific location to work.)
+
+Thus, the above command on a Unix system creates
+\file{Distutils-0.9.1.\filevar{plat}.tar.gz}; unpacking this tarball
+from the root of the filesystemq installs the Distutils just as though
+you had downloaded the source distribution and run \code{python setup.py
+  install}.  (Assuming that the target system has their Python
+installation laid out the same as you do---another reason these are
+called ``dumb'' distributions.)  Obviously, for pure Python
+distributions, this isn't a huge win---but for non-pure distributions,
+which include extensions that would need to be compiled, it can mean the
+difference between someone being able to use your extensions or not.
 
 \XXX{filenames are inaccurate here!}
 
 The \command{bdist} command has a \longprogramopt{format} option,
-similar to the \command{sdist} command, that you can use to select which
-formats to generate: for example,
+similar to the \command{sdist} command, which you can use to select the
+types of built distribution to generate: for example,
 \begin{verbatim}
 python setup.py bdist --format=zip
 \end{verbatim}
 would, when run on a Unix system, create
-\file{Distutils-0.8.built-posix.tar.gz}---again, this archive would be
-unpacked from Python's \filevar{prefix} directory to install the
-Distutils.
+\file{Distutils-0.8.\filevar{plat}.zip}---again, this archive would be
+unpacked from the root directory to install the Distutils.
 
 The available formats for built distributions are:
 \begin{tableiii}{l|l|c}{code}%
   {Format}{Description}{Notes}
-  \lineiii{zip}{zip file (\file{.zip})}{(1)}
-  \lineiii{gztar}{gzipped tar file (\file{.tar.gz})}{(2)}
+  \lineiii{zip}{zip file (\file{.zip})}{}
+  \lineiii{gztar}{gzipped tar file (\file{.tar.gz})}{(1)}
   \lineiii{ztar}{compressed tar file (\file{.tar.Z})}{}
   \lineiii{tar}{tar file (\file{.tar})}{}
-  \lineiii{rpm}{RPM}{(3)}
-  \lineiii{srpm}{source RPM}{}
-  \lineiii{wise}{Wise installer for Windows}{}
+  \lineiii{rpm}{RPM}{}
+  \lineiii{srpm}{source RPM}{\XXX{to do!}}
+  \lineiii{wininst}{self-extracting ZIP file for Windows}{(2)}
+  %\lineiii{wise}{Wise installer for Windows}{(3)}
 \end{tableiii}
 
 \noindent Notes:
 \begin{description}
-\item[(1)] default on Windows
-\item[(2)] default on Unix
-\item[(3)] not implemented yet; will be default on RPM-based Linux
-  systems
-\item[(5)] not implemented yet; will be default on Windows
+\item[(1)] default on Unix
+\item[(2)] default on Windows \XXX{to-do!}
+%\item[(3)] not implemented yet
 \end{description}
 
 You don't have to use the \command{bdist} command with the
 \longprogramopt{formats} option; you can also use the command that
-directly implements the format you're interested in.  Many of these
+directly implements the format you're interested in.  Some of these
 \command{bdist} ``sub-commands'' actually generate several similar
 formats; for instance, the \command{bdist\_dumb} command generates all
 the ``dumb'' archive formats (\code{tar}, \code{ztar}, \code{gztar}, and
@@ -620,7 +628,8 @@ each, are:
   {Command}{Formats}
   \lineii{bdist\_dumb}{tar, ztar, gztar, zip}
   \lineii{bdist\_rpm}{rpm, srpm}
-  \lineii{bdist\_wise}{wise}
+  \lineii{bdist\_wininst}{wininst}
+  %\lineii{bdist\_wise}{wise}
 \end{tableii}
 
 \section{Examples}