Fleshed out the section on the setup config file, setup.cfg.

Added a few clarifying footnotes and cross-references.
Various minor tweaks.

1 files changed, 139 insertions, 26 deletions

diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex
index 3f1001d..abf749d 100644
--- a/Doc/dist/dist.tex
+++ b/Doc/dist/dist.tex
@@ -78,7 +78,13 @@ 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 with it.  If
+Python, there are no arbitrary limits to what you can do with
+it.\footnote{But be careful about putting arbitrarily expensive
+  operations in your setup script; unlike, say, Autoconf-style configure
+  scripts, the setup script may be run multiple times in the course of
+  building and installing your module distribution.  If you need to
+  insert potentially expensive processing steps into the Distutils
+  chain, see section~\ref{extending} on extending the Distutils.}  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:
@@ -100,6 +106,7 @@ Some observations:
   hold true for packages and extensions)
 \item it's recommended that you supply a little more meta-data, in
   particular your name, email address and a URL for the project
+  (see section~\ref{setup-script} for an example)
 \end{itemize}
 
 To create a source distribution for this module, you would create a
@@ -153,7 +160,7 @@ 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}.)
 
-Currently (Distutils 0.9.1), the are only other useful built
+Currently (Distutils 0.9.2), 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}:
@@ -552,24 +559,125 @@ intend to distribute your code.)
 \label{setup-config}
 
 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
-might include an optional extension module that provides an interface to
-a particular C library.  If that library is installed on the user's
-system, then you can build your optional extension---but you need to
-know where to find the header and library file.  If it's not installed,
-you need to know this so you can omit your optional extension.
-
-The preferred way to do this, of course, would be for you to tell the
-Distutils which optional features (C libraries, system calls, external
-utilities, etc.) you're looking for, and it would inspect the user's
-system and try to find them.  This functionality may appear in a future
-version of the Distutils, but it isn't there now.  So, for the time
-being, we rely on the user building and installing your software to
-provide the necessary information.  The vehicle for doing so is the
-setup configuration file, \file{setup.cfg}.
-
-\XXX{need more here!}
+distribution \emph{a priori}: you may need to get some information from
+the user, or from the user's system, in order to proceed.  As long as
+that information is fairly simple---a list of directories to search for
+C header files or libraries, for example---then providing a
+configuration file, \file{setup.cfg}, for users to edit is a cheap and
+easy way to solicit it.  Configuration files also let you provide
+default values for any command option, which the installer can then
+override either on the command-line or by editing the config file.
+
+(If you have more advanced needs, such as determining which extensions
+to build based on what capabilities are present on the target system,
+then you need the Distutils ``auto-configuration'' facility.  This
+started to appear in Distutils 0.9 but, as of this writing, isn't mature 
+or stable enough yet for real-world use.)
+
+\XXX{should reference description of distutils config files in
+  ``Installing'' manual here}
+
+The setup configuration file is a useful middle-ground between the setup
+script---which, ideally, would be opaque to installers\footnote{This
+  ideal probably won't be achieved until auto-configuration is fully
+  supported by the Distutils.}---and the command-line to the setup
+script, which is outside of your control and entirely up to the
+installer.  In fact, \file{setup.cfg} (and any other Distutils
+configuration files present on the target system) are processed after
+the contents of the setup script, but before the command-line.  This has 
+several useful consequences:
+\begin{itemize}
+\item installers can override some of what you put in \file{setup.py} by
+  editing \file{setup.cfg}
+\item you can provide non-standard defaults for options that are not
+  easily set in \file{setup.py}
+\item installers can override anything in \file{setup.cfg} using the
+  command-line options to \file{setup.py}
+\end{itemize}
+
+The basic syntax of the configuration file is simple:
+\begin{verbatim}
+[command]
+option=value
+...
+\end{verbatim}
+where \var{command} is one of the Distutils commands (e.g.
+\command{build\_py}, \command{install}), and \var{option} is one of the
+options that command supports.  Any number of options can be supplied
+for each command, and any number of command sections can be included in
+the file.  Blank lines are ignored, as are comments (from a \verb+#+
+character to end-of-line).  Long option values can be split across
+multiple lines simply by indenting the continuation lines.
+
+You can find out the list of options supported by a particular command
+with the universal \longprogramopt{help} option, e.g.
+\begin{verbatim}
+> python setup.py --help build_ext
+[...]
+Options for 'build_ext' command:
+  --build-lib (-b)     directory for compiled extension modules
+  --build-temp (-t)    directory for temporary files (build by-products)
+  --inplace (-i)       ignore build-lib and put compiled extensions into the
+                       source directory alongside your pure Python modules
+  --include-dirs (-I)  list of directories to search for header files
+  --define (-D)        C preprocessor macros to define
+  --undef (-U)         C preprocessor macros to undefine
+[...]
+\end{verbatim}
+Or consult section \ref{reference} of this document (the command
+reference).
+
+Note that an option spelled \longprogramopt{foo-bar} on the command-line 
+is spelled \option{foo\_bar} in configuration files.
+
+For example, say you want your extensions to be built
+``in-place''---that is, you have an extension \module{pkg.ext}, and you
+want the compiled extension file (\file{ext.so} on Unix, say) to be put
+in the same source directory as your pure Python modules
+\module{pkg.mod1} and \module{pkg.mod2}.  You can always use the
+\longprogramopt{inplace} option on the command-line to ensure this:
+\begin{verbatim}
+python setup.py build_ext --inplace
+\end{verbatim}
+But this requires that you always specify the \command{build\_ext}
+command explicitly, and remember to provide \longprogramopt{inplace}.
+An easier way is to ``set and forget'' this option, by encoding it in
+\file{setup.cfg}, the configuration file for this distribution:
+\begin{verbatim}
+[build_ext]
+inplace=1
+\end{verbatim}
+This will affect all builds of this module distribution, whether or not
+you explcitly specify \command{build\_ext}.  If you include
+\file{setup.cfg} in your source distribution, it will also affect
+end-user builds---which is probably a bad idea for this option, since
+always building extensions in-place would break installation of the
+module distribution.  In certain peculiar cases, though, modules are
+built right in their installation directory, so this is conceivably a
+useful ability.  (Distributing extensions that expect to be built in
+their installation directory is almost always a bad idea, though.)
+
+Another example: certain commands take a lot of options that don't
+change from run-to-run; for example, \command{bdist\_rpm} needs to know
+everything required to generate a ``spec'' file for creating an RPM
+distribution.  Some of this information comes from the setup script, and
+some is automatically generated by the Distutils (such as the list of
+files installed).  But some of it has to be supplied as options to
+\command{bdist\_rpm}, which would be very tedious to do on the
+command-line for every run.  Hence, here is a snippet from the
+Distutils' own \file{setup.cfg}:
+\begin{verbatim}
+[bdist_rpm]
+release = 1
+packager = Greg Ward <gward@python.net>
+doc_files = CHANGES.txt
+            README.txt
+            USAGE.txt
+            doc/
+            examples/
+\end{verbatim}
+Note that the \option{doc\_files} option is simply a
+whitespace-separated string split across multiple lines for readability.
 
 
 \section{Creating a Source Distribution}
@@ -597,16 +705,21 @@ python setup.py sdist --formats=gztar,zip
 to create a gzipped tarball and a zip file.  The available formats 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{ztar}{compressed tar file (\file{.tar.Z})}{}
+  \lineiii{zip}{zip file (\file{.zip})}{(1),(2)}
+  \lineiii{gztar}{gzip'ed tar file (\file{.tar.gz})}{(3),(4)}
+  \lineiii{bztar}{bzip2'ed tar file (\file{.tar.gz})}{(4)}
+  \lineiii{ztar}{compressed tar file (\file{.tar.Z})}{(4)}
   \lineiii{tar}{tar file (\file{.tar})}{}
 \end{tableiii}
 
 \noindent Notes:
 \begin{description}
 \item[(1)] default on Windows
-\item[(2)] default on Unix
+\item[(2)] under both Unix and Windows, requires either external
+  Info-ZIP utility \emph{or} the \module{zipfile} module
+\item[(3)] default on Unix
+\item[(4)] requires external utilities: \program{tar} and possibly one
+  of \program{gzip}, \program{bzip2}, or \program{compress}
 \end{description}
 
 
@@ -659,7 +772,7 @@ list of files.  This list is written to the manifest for future
 reference, and then used to build the source distribution archive(s).
 
 Following the Distutils' own manifest template, let's trace how the
-\command{sdist} command will build the list of files to include in the
+\command{sdist} command builds the list of files to include in the
 Distutils source distribution:
 \begin{enumerate}
 \item include all Python source files in the \file{distutils} and
@@ -869,7 +982,7 @@ each, are:
 
 
 \section{Reference}
-\label{ref}
+\label{reference}
 
 
 \subsection{Building modules: the \protect\command{build} command family}