A grab-bag of wording tweakage.

1 files changed, 54 insertions, 29 deletions

diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex
index 7b5ffdd..04b1c8a 100644
--- a/Doc/dist/dist.tex
+++ b/Doc/dist/dist.tex
@@ -100,7 +100,7 @@ Windows) containing your setup script, \file{setup.py}, and your module,
 \file{.zip}), and will unpack into a directory \file{Foo-1.0}.
 
 If an end-user wishes to install your \module{foo} module, all she has
-to do is download \file{Foo-1.0.tar.gz}) (or \file{.zip}), unpack it,
+to do is download \file{Foo-1.0.tar.gz} (or \file{.zip}), unpack it,
 and---from the \file{Foo-1.0} directory---run
 \begin{verbatim}
 python setup.py install
@@ -122,21 +122,29 @@ 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
 Windows users, you can create an executable installer (the most
 appropriate type of built distribution for this platform) with the
-\command{bdist\_wise} command.  (Wise is the installation tool used to
-create Windows installers for Python itself, so we have adopted it for
-use by any Python module distribution.  You'll need to have version XXX
-of Wise installed on your system for the \command{bdist\_wise} to work;
-it's available from \url{http://foo/bar/baz}.  For example:
+\command{bdist\_wininst} command.  For example:
 \begin{verbatim}
-python setup.py bdist_wise
+python setup.py bdist_wininst
 \end{verbatim}
 will create an executable installer, \file{Foo-1\_0.exe}, in the current
 directory.
 
-\XXX{not implemented yet}
-Other \command{bdist\_*} commands exist for RPM-based Linux systems
-(\command{bdist\_rpm}), Debian-based Linux systems
-(\command{bdist\_deb}), ...
+(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
+the installer.  Wise-based installers are more appropriate for large,
+industrial-strength applications that need the full capabilities of a
+``real'' installer.  \command{bdist\_wininst} creates a self-extracting
+zip file with a minimal user interface, which is enough for small- to
+medium-sized module collections.  You'll need to have version XXX of
+Wise installed on your system for the \command{bdist\_wise} 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.
 
 
 \subsection{General Python terminology}
@@ -163,6 +171,12 @@ following glossary of common Python terms:
 \item[package] a module that contains other modules; typically contained
   in a directory in the filesystem and distinguished from other
   directories by the presence of a file \file{\_\_init\_\_.py}.
+\item[root package] the ``package'' that modules not in a package live
+  in.  The vast majority of the standard library is in the root package,
+  as are many small, standalone third-party modules that don't belong to
+  a larger module collection.  (The root package isn't really a package,
+  since it doesn't have an \file{\_\_init\_\_.py} file.  But we have to
+  call it something.)
 \end{description}
 
 
@@ -177,8 +191,8 @@ distributing Python modules using the Distutils:
   \emph{en masse}.  Examples of some well-known module distributions are
   Numeric Python, PyXML, PIL (the Python Imaging Library), or
   mxDateTime.  (This would be called a \emph{package}, except that term
-  is already spoken for in the Python context: a single module
-  distribution may contain zero, one, or many Python packages.)
+  is already taken in the Python context: a single module distribution
+  may contain zero, one, or many Python packages.)
 \item[pure module distribution] a module distribution that contains only
   pure Python modules and packages.  Sometimes referred to as a ``pure
   distribution.''
@@ -198,16 +212,17 @@ The setup script is the centre of all activity in building,
 distributing, and installing modules using the Distutils.  The main
 purpose of the setup script is to describe your module distribution to
 the Distutils, so that the various commands that operate on your modules
-do the right thing.  As we saw in section~\ref{simple-example}
-above, the setup script consists mainly of a call to \function{setup()},
-and all information supplied to the Distutils is suppled as keyword
+do the right thing.  As we saw in section~\ref{simple-example} above,
+the setup script consists mainly of a call to \function{setup()}, and
+all information supplied to the Distutils is 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 1.6, they also have an
 independent existence so that Python 1.5 users can use them to install
-other module distributions.)
+other module distributions.  The Distutils' own setup script is used to
+install the package into Python 1.5.)
 
 \begin{verbatim}
 #!/usr/bin/env python
@@ -235,13 +250,13 @@ maintain.
 Note that any pathnames (files or directories) supplied in the setup
 script should be written using the Unix convention, i.e.
 slash-separated.  The Distutils will take care of converting this
-platform-neutral representation to whatever is appropriate on your
+platform-neutral representation into whatever is appropriate on your
 current platform before actually using the pathname.  This makes your
 setup script portable across operating systems, which of course is one
 of the major goals of the Distutils.  In this spirit, all pathnames in
-this document are slash-separated (Mac OS users should keep in mind that
-the \emph{absence} of a leading slash indicates a relative directory,
-the opposite of the Mac OS convention with colons).
+this document are slash-separated (Mac OS programmers should keep in
+mind that the \emph{absence} of a leading slash indicates a relative
+path, the opposite of the Mac OS convention with colons).
 
 
 \subsection{Package directories}
@@ -283,12 +298,16 @@ would be written in the setup script as
 \begin{verbatim}
 package_dir = {'foo': 'lib'}
 \end{verbatim}
-Note that a \code{\var{package}: \var{dir}} entry in the
-\option{package\_dir} option implicitly applies to all packages below
-\var{package}, so the \module{foo.bar} case is automatically handled
-here.  In this example, having \code{packages = ['foo', 'foo.bar']}
-tells the Distutils to look for \file{lib/\_\_init\_\_.py} and
-\file{lib/bar/\_\_init\_\_.py}.
+A \code{\var{package}: \var{dir}} entry in the \option{package\_dir}
+dictionary implicitly applies to all packages below \var{package}, so
+the \module{foo.bar} case is automatically handled here.  In this
+example, having \code{packages = ['foo', 'foo.bar']} tells the Distutils
+to look for \file{lib/\_\_init\_\_.py} and
+\file{lib/bar/\_\_init\_\_.py}.  (Keep in mind that although
+\option{package\_dir} applies recursively, you must explicitly list all
+packages in \option{packages}: the Distutils will \emph{not} recursively
+scan your source tree looking for any directory with an
+\file{\_\_init\_\_.py} file.)
 
 
 \subsection{Listing individual modules}
@@ -307,8 +326,14 @@ other in the \module{pkg} package.  Again, the default package/directory
 layout implies that these two modules can be found in \file{mod1.py} and
 \file{pkg/mod2.py}, and that \file{pkg/\_\_init\_\_.py} exists as well.
 And again, you can override the package/directory layout using the
-\option{package\_dir} option.  \XXX{not sure if this is actually
-  true---must check!}
+\option{package\_dir} option.
+
+
+\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}