General overhaul of the "Creating a Source Distribution" section --

better explanation of manifest files, in particular.

1 files changed, 80 insertions, 51 deletions

diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex
index abf749d..4ac9c32 100644
--- a/Doc/dist/dist.tex
+++ b/Doc/dist/dist.tex
@@ -691,12 +691,10 @@ python setup.py sdist
 \end{verbatim}
 (assuming you haven't specified any \command{sdist} options in the setup
 script or config file), \command{sdist} creates the archive of the
-default format for the current platform.  The default formats are:
-\begin{tableii}{ll}{textrm}%
-  {Platform}{Default archive format for source distributions}
-  \lineii{Unix}{gzipped tar file (\file{.tar.gz})}
-  \lineii{Windows}{zip file}  
-\end{tableii}
+default format for the current platform.  The default format is gzip'ed
+tar file (\file{.tar.gz}) on Unix, and ZIP file on Windows. \XXX{no Mac
+  OS support here}
+
 You can specify as many formats as you like using the
 \longprogramopt{formats} option, for example:
 \begin{verbatim}
@@ -705,29 +703,31 @@ 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),(2)}
-  \lineiii{gztar}{gzip'ed tar file (\file{.tar.gz})}{(3),(4)}
+  \lineiii{zip}{zip file (\file{.zip})}{(1),(3)}
+  \lineiii{gztar}{gzip'ed tar file (\file{.tar.gz})}{(2),(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})}{}
+  \lineiii{tar}{tar file (\file{.tar})}{(4)}
 \end{tableiii}
 
 \noindent Notes:
 \begin{description}
 \item[(1)] default on Windows
-\item[(2)] under both Unix and Windows, requires either external
+\item[(2)] default on Unix
+\item[(3)] 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}
 
 
-\subsection{The manifest and manifest template}
+
+\subsection{Specifying the files to distribute}
 \label{manifest}
 
-Without any additional information, the \command{sdist} command puts a
-minimal set of files into the source distribution:
+If you don't supply an explicit list of files (or instructions on how to
+generate one), the \command{sdist} command puts a minimal default set
+into the source distribution:
 \begin{itemize}
 \item all Python source files implied by the \option{py\_modules} and
   \option{packages} options
@@ -738,15 +738,22 @@ minimal set of files into the source distribution:
   (currently, the Distutils don't do anything with test scripts except
   include them in source distributions, but in the future there will be
   a standard for testing Python module distributions)
-\item \file{README.txt} (or \file{README}) and \file{setup.py}
+\item \file{README.txt} (or \file{README}), \file{setup.py} (or whatever 
+  you called your setup script), and \file{setup.cfg}
 \end{itemize}
 Sometimes this is enough, but usually you will want to specify
 additional files to distribute.  The typical way to do this is to write
 a \emph{manifest template}, called \file{MANIFEST.in} by default.  The
-\command{sdist} command processes this template and generates a manifest
-file, \file{MANIFEST}.  (If you prefer, you can skip the manifest
-template and generate the manifest yourself: it just lists one file per
-line.)
+manifest template is just a list of instructions for how to generate
+your manifest file, \file{MANIFEST}, which is the exact list of files to
+include in your source distribution.  The \command{sdist} command
+processes this template and generates a manifest based on its
+instructions and what it finds in the filesystem.
+
+If you prefer to roll your own manifest file, the format is simple: one
+filename 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.
 
 The manifest template has one command per line, where each command
 specifies a set of files to include or exclude from the source
@@ -760,16 +767,30 @@ prune examples/sample?/build
 The meanings should be fairly clear: include all files in the
 distribution root matching \code{*.txt}, all files anywhere under the
 \file{examples} directory matching \code{*.txt} or \code{*.py}, and
-exclude all directories matching \code{examples/sample?/build}.  There
-are several other commands available in the manifest template
-mini-language; see section~\ref{sdist-cmd}.
+exclude all directories matching \code{examples/sample?/build}.  All of
+this is done \emph{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 \longprogramopt{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 to or removes from that list of files.  Once we have
+fully processed the manifest template, we remove files that should not
+be included in the source distribution:
+\begin{itemize}
+\item all files in the Distutils ``build'' tree (default \file{build/})
+\item all files in directories named \file{RCS} or \file{CVS}
+\end{itemize}
+Now we have our complete list of files, which is written to the manifest
+for future reference, and then used to build the source distribution
+archive(s).
 
-The order of commands in the manifest template very much matters:
-initially, we have the list of default files as described above, and
-each command in the template adds to or removes from that list of files.
-When we have fully processed the manifest template, we have our complete
-list of files.  This list is written to the manifest for future
-reference, and then used to build the source distribution archive(s).
+You can disable the default set of included files with the
+\longprogramopt{no-defaults} option, and you can disable the standard
+exclude set with \longprogramopt{no-prune}.
 
 Following the Distutils' own manifest template, let's trace how the
 \command{sdist} command builds the list of files to include in the
@@ -778,23 +799,24 @@ Distutils source distribution:
 \item include all Python source files in the \file{distutils} and
   \file{distutils/command} subdirectories (because packages
   corresponding to those two directories were mentioned in the
-  \option{packages} option in the setup script)
-\item include \file{test/test*.py} (always included)
-\item include \file{README.txt} and \file{setup.py} (always included)
+  \option{packages} option in the setup script---see
+  section~\ref{setup-script})
+\item include \file{README.txt}, \file{setup.py}, and \file{setup.cfg}
+  (standard files)
+\item include \file{test/test*.py} (standard files)
 \item include \file{*.txt} in the distribution root (this will find
   \file{README.txt} a second time, but such redundancies are weeded out
   later)
-\item in the sub-tree under \file{examples}, include anything matching
-  \file{*.txt}
-\item in the sub-tree under \file{examples}, include anything matching
-  \file{*.py}
-\item remove all files in the sub-trees starting at directories matching
-  \file{examples/sample?/build}---this may exclude files included by the
-  previous two steps, so it's important that the \code{prune} command in
-  the manifest template comes after the two \code{recursive-include}
-  commands
+\item include anything matching \file{*.txt} or \file{*.py} in the
+  sub-tree under \file{examples},
+\item exclude all files in the sub-trees starting at directories
+  matching \file{examples/sample?/build}---this may exclude files
+  included by the previous two steps, so it's important that the
+  \code{prune} command in the manifest template comes after the
+  \code{recursive-include} command
+\item exclude the entire \file{build} tree, and any \file{RCS} or
+  \file{CVS} directories
 \end{enumerate}
-
 Just like in the setup script, file and directory names in the manifest
 template should always be slash-separated; the Distutils will take care
 of converting them to the standard representation on your platform.
@@ -809,15 +831,26 @@ follows:
 \begin{itemize}
 \item if the manifest file, \file{MANIFEST} doesn't exist, read
   \file{MANIFEST.in} and create the manifest
+\item if neither \file{MANIFEST} nor \file{MANIFEST.in} exist, create a
+  manifest with just the default file set\footnote{In versions of the
+    Distutils up to and including 0.9.2 (Python 2.0b1), this feature was
+    broken; use the \programopt{-f} (\longprogramopt{force-manifest})
+    option to work around the bug.}
 \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}
-There are a couple of options that modify this behaviour.
-
-First, you might want to force the manifest to be regenerated---for
+There are a couple of options that modify this behaviour.  First, use
+the \longprogramopt{no-defaults} and \longprogramopt{no-prune} to
+disable the standard ``include'' and ``exclude'' sets.\footnote{Note
+  that if you have no manifest template, no manifest, and use the
+  \longprogramopt{no-defaults}, you will get an empty manifest.  Another
+  bug in Distutils 0.9.2 and earlier causes an uncaught exception in
+  this case.  The workaround is: Don't Do That.}
+
+Second, you might want to force the manifest to be regenerated---for
 example, if you have added or removed files or directories that match an
 existing pattern in the manifest template, you should regenerate the
 manifest:
@@ -830,13 +863,9 @@ source distribution:
 \begin{verbatim}
 python setup.py sdist --manifest-only
 \end{verbatim}
-(\longprogramopt{manifest-only} implies \longprogramopt{force-manifest}.)
-
-If you don't want to use the default file set, you can supply the
-\longprogramopt{no-defaults} option.  If you use
-\longprogramopt{no-defaults} and don't supply a manifest template (or
-it's empty, or nothing matches the patterns in it), then your source
-distribution will be empty.
+\longprogramopt{manifest-only} implies \longprogramopt{force-manifest}.
+\programopt{-o} is a shortcut for \longprogramopt{manifest-only}, and
+\programopt{-f} for \longprogramopt{force-manifest}.
 
 
 \section{Creating Built Distributions}