--- Python-Docs-2.4/./dist/dist.tex	2004-08-25 23:01:32.000000000 +0900
+++ Python-Docs-2.5/./dist/dist.tex	2006-08-13 09:20:49.000000000 +0900
@@ -1,7 +1,7 @@
 \documentclass{manual}
 \usepackage{distutils}
 
-% $Id: dist.tex.patch,v 1.1 2006/11/09 12:18:51 moriwaka Exp $
+% $Id: dist.tex.patch,v 1.1 2006/11/09 12:18:51 moriwaka Exp $
 
 % TODO
 %   Document extension.read_setup_file
@@ -25,6 +25,9 @@
 \begin{document}
 
 \maketitle
+
+\input{copyright}
+
 \begin{abstract}
   \noindent
   This document describes the Python Distribution Utilities
@@ -34,7 +37,7 @@
   build/release/install mechanics.
 \end{abstract}
 
-% The ugly "%begin{latexonly}" pseudo-environment supresses the table
+% The ugly "%begin{latexonly}" pseudo-environment suppresses the table
 % of contents for HTML generation.
 %
 %begin{latexonly}
@@ -298,7 +301,7 @@
 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 programmers should keep in
+this document are slash-separated.  (Mac OS 9 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.)
 
@@ -403,7 +406,7 @@
 with, etc.).
 
 All of this is done through another keyword argument to
-\function{setup()}, the \option{extensions} option.  \option{extensions}
+\function{setup()}, the \option{ext_modules} option.  \option{ext_modules}
 is just a list of \class{Extension} instances, each of which describes a
 single extension module.  Suppose your distribution includes a single
 extension, called \module{foo} and implemented by \file{foo.c}.  If no
@@ -527,7 +530,7 @@
 you can take advantage of the fact that header files are installed in a
 consistent way by the Distutils \command{install\_header} command.  For
 example, the Numerical Python header files are installed (on a standard
-Unix installation) to \file{/usr/local/include/python1.5/Numerical}.
+\UNIX{} installation) to \file{/usr/local/include/python1.5/Numerical}.
 (The exact location will differ according to your platform and Python
 installation.)  Since the Python include
 directory---\file{/usr/local/include/python1.5} in this case---is always
@@ -631,7 +634,83 @@
 will automatically add \code{initmodule}
 to the list of exported symbols.
 
+\section{Relationships between Distributions and Packages}
+
+A distribution may relate to packages in three specific ways:
+
+\begin{enumerate}
+  \item It can require packages or modules.
+
+  \item It can provide packages or modules.
+
+  \item It can obsolete packages or modules.
+\end{enumerate}
+
+These relationships can be specified using keyword arguments to the
+\function{distutils.core.setup()} function.
+
+Dependencies on other Python modules and packages can be specified by
+supplying the \var{requires} keyword argument to \function{setup()}.
+The value must be a list of strings.  Each string specifies a package
+that is required, and optionally what versions are sufficient.
+
+To specify that any version of a module or package is required, the
+string should consist entirely of the module or package name.
+Examples include \code{'mymodule'} and \code{'xml.parsers.expat'}.
+
+If specific versions are required, a sequence of qualifiers can be
+supplied in parentheses.  Each qualifier may consist of a comparison
+operator and a version number.  The accepted comparison operators are:
+
+\begin{verbatim}
+<    >    ==
+<=   >=   !=
+\end{verbatim}
+
+These can be combined by using multiple qualifiers separated by commas
+(and optional whitespace).  In this case, all of the qualifiers must
+be matched; a logical AND is used to combine the evaluations.
+
+Let's look at a bunch of examples:
+
+\begin{tableii}{l|l}{code}{Requires Expression}{Explanation}
+  \lineii{==1.0}               {Only version \code{1.0} is compatible}
+  \lineii{>1.0, !=1.5.1, <2.0} {Any version after \code{1.0} and before
+                                \code{2.0} is compatible, except
+                                \code{1.5.1}}
+\end{tableii}
+
+Now that we can specify dependencies, we also need to be able to
+specify what we provide that other distributions can require.  This is
+done using the \var{provides} keyword argument to \function{setup()}.
+The value for this keyword is a list of strings, each of which names a
+Python module or package, and optionally identifies the version.  If
+the version is not specified, it is assumed to match that of the
+distribution.
+
+Some examples:
+
+\begin{tableii}{l|l}{code}{Provides Expression}{Explanation}
+  \lineii{mypkg}      {Provide \code{mypkg}, using the distribution version}
+  \lineii{mypkg (1.1} {Provide \code{mypkg} version 1.1, regardless of the
+                       distribution version}
+\end{tableii}
+
+A package can declare that it obsoletes other packages using the
+\var{obsoletes} keyword argument.  The value for this is similar to
+that of the \var{requires} keyword: a list of strings giving module or
+package specifiers.  Each specifier consists of a module or package
+name optionally followed by one or more version qualifiers.  Version
+qualifiers are given in parentheses after the module or package name.
+
+The versions identified by the qualifiers are those that are obsoleted
+by the distribution being described.  If no qualifiers are given, all
+versions of the named module or package are understood to be
+obsoleted.
+
+
 \section{Installing Scripts}
+
 So far we have been dealing with pure and non-pure Python modules,
 which are usually not run by themselves but imported by scripts.
 
@@ -770,7 +849,7 @@
          {long string}{}
   \lineiv{download_url}{location where the package may be downloaded}
          {URL}{(4)}
-  \lineiv{classifiers}{a list of Trove classifiers}
+  \lineiv{classifiers}{a list of classifiers}
          {list of strings}{(4)}
 \end{tableiv}
 
@@ -842,7 +921,8 @@
 \begin{verbatim}
 # patch distutils if it can't cope with the "classifiers" or
 # "download_url" keywords
-if sys.version < '2.2.3':
+from sys import version
+if version < '2.2.3':
     from distutils.dist import DistributionMetadata
     DistributionMetadata.classifiers = None
     DistributionMetadata.download_url = None
@@ -965,7 +1045,7 @@
 \end{verbatim}
 
 This will affect all builds of this module distribution, whether or not
-you explcitly specify \command{build\_ext}.  If you include
+you explicitly 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
@@ -1021,7 +1101,6 @@
 script or config file), \command{sdist} creates the archive of the
 default format for the current platform.  The default format is a 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:
@@ -1388,7 +1467,7 @@
   \lineii{\%description (section)}{\option{long\_description}}
 \end{tableii}
 
-Additionally, there many options in \file{.spec} files that don't have
+Additionally, there are many options in \file{.spec} files that don't have
 corresponding options in the setup script.  Most of these are handled
 through options to the \command{bdist\_rpm} command as follows:
 
@@ -1579,7 +1658,7 @@
                                   iconpath\optional{, iconindex}}}}}
   This function creates a shortcut.
   \var{target} is the path to the program to be started by the shortcut.
-  \var{description} is the description of the sortcut.
+  \var{description} is the description of the shortcut.
   \var{filename} is the title of the shortcut that the user will see.
   \var{arguments} specifies the command line arguments, if any.
   \var{workdir} is the working directory for the program.
@@ -1640,7 +1719,58 @@
 versions, the Hidden property should be set to yes. This must be edited
 through the web interface.
 
+\section{The .pypirc file}
+\label{pypirc}
+
+The format of the \file{.pypirc} file is formated as follows:
+
+\begin{verbatim}
+[server-login]
+repository: <repository-url>
+username: <username>
+password: <password>
+\end{verbatim}
+
+\var{repository} can be ommitted and defaults to
+\code{http://www.python.org/pypi}.
+
+\chapter{Uploading Packages to the Package Index}
+\label{package-upload}
 
+\versionadded{2.5}
+
+The Python Package Index (PyPI) not only stores the package info, but also 
+the package data if the author of the package wishes to. The distutils
+command \command{upload} pushes the distribution files to PyPI.
+
+The command is invoked immediately after building one or more distribution
+files.  For example, the command
+
+\begin{verbatim}
+python setup.py sdist bdist_wininst upload
+\end{verbatim}
+
+will cause the source distribution and the Windows installer to be
+uploaded to PyPI.  Note that these will be uploaded even if they are
+built using an earlier invocation of \file{setup.py}, but that only
+distributions named on the command line for the invocation including
+the \command{upload} command are uploaded.
+
+The \command{upload} command uses the username, password, and repository
+URL from the \file{\$HOME/.pypirc} file (see section~\ref{pypirc} for
+more on this file).
+
+You can use the \longprogramopt{sign} option to tell \command{upload} to
+sign each uploaded file using GPG (GNU Privacy Guard).  The 
+\program{gpg} program must be available for execution on the system
+\envvar{PATH}.  You can also specify which key to use for signing
+using the \longprogramopt{identity=\var{name}} option.
+
+Other \command{upload} options include 
+\longprogramopt{repository=\var{url}} (which lets you override the
+repository setting from \file{\$HOME/.pypirc}), and
+\longprogramopt{show-response} (which displays the full response text
+from the PyPI server for help in debugging upload problems).
 
 \chapter{Examples}
 \label{examples}
@@ -1862,6 +1992,7 @@
 script for this could be
 \begin{verbatim}
 from distutils.core import setup
+from distutils.extension import Extension
 setup(name='foobar',
       version='1.0',
       ext_modules=[Extension('foo', ['foo.c'])],
@@ -1876,6 +2007,7 @@
 extension:
 \begin{verbatim}
 from distutils.core import setup
+from distutils.extension import Extension
 setup(name='foobar',
       version='1.0',
       ext_modules=[Extension('foopkg.foo', ['foo.c'])],
@@ -1980,6 +2112,14 @@
 implemented by the class \class{distcmds.bdist_openpkg.bdist_openpkg}
 or \class{buildcmds.bdist_openpkg.bdist_openpkg}.
 
+\section{Adding new distribution types}
+
+Commands that create distributions (files in the \file{dist/}
+directory) need to add \code{(\var{command}, \var{filename})} pairs to
+\code{self.distribution.dist_files} so that \command{upload} can
+upload it to PyPI.  The \var{filename} in the pair contains no path
+information, only the name of the file itself.  In dry-run mode, pairs
+should still be added to represent what would have been created.
 
 \chapter{Command Reference}
 \label{reference}
@@ -2059,9 +2199,9 @@
 characters in \var{range} (e.g., \code{a-z}, \code{a-zA-Z},
 \code{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; on Mac OS anything except colon.
+anything except backslash or colon; on Mac OS 9 anything except colon.
 
-\XXX{Windows and Mac OS support not there yet}
+\XXX{Windows support not there yet}
 
 
 %\section{Creating a built distribution: the
@@ -2113,7 +2253,7 @@
 \lineiii{scripts}{A list of standalone script files to be built and installed}{a list of strings}
 \lineiii{ext_modules}{A list of Python extensions to be built}{A list of 
 instances of \class{distutils.core.Extension}}
-\lineiii{classifiers}{A list of Trove categories for the package}{XXX link to better definition}
+\lineiii{classifiers}{A list of categories for the package}{The list of available categorizations is at \url{http://cheeseshop.python.org/pypi?:action=list_classifiers}.}
 \lineiii{distclass}{the \class{Distribution} class to use}{A subclass of \class{distutils.core.Distribution}}
 % What on earth is the use case for script_name?
 \lineiii{script_name}{The name of the setup.py script - defaults to \code{sys.argv[0]}}{a string}
@@ -2135,9 +2275,9 @@
 the contents of the config files or command-line.
 
 \var{script_name} is a file that will be run with \function{execfile()}
-\var{sys.argv[0]} will be replaced with \var{script} for the duration of the
+\code{sys.argv[0]} will be replaced with \var{script} for the duration of the
 call.  \var{script_args} is a list of strings; if supplied,
-\var{sys.argv[1:]} will be replaced by \var{script_args} for the duration 
+\code{sys.argv[1:]} will be replaced by \var{script_args} for the duration 
 of the call.
 
 \var{stop_after} tells \function{setup()} when to stop processing; possible 
@@ -2172,14 +2312,14 @@
 \begin{classdesc*}{Extension}
 
 The Extension class describes a single C or \Cpp extension module in a
-setup script. It accepts the following keyword arguments in it's
+setup script. It accepts the following keyword arguments in its
 constructor
 
 \begin{tableiii}{c|l|l}{argument name}{argument name}{value}{type}
 \lineiii{name}{the full name of the extension, including any packages
 --- ie. \emph{not} a filename or pathname, but Python dotted name}{string}
 \lineiii{sources}{list of source filenames, relative to the distribution
-root (where the setup script lives), in Unix form (slash-separated) for
+root (where the setup script lives), in \UNIX{} form (slash-separated) for
 portability. Source files may be C, \Cpp, SWIG (.i), platform-specific
 resource files, or whatever else is recognized by the \command{build_ext}
 command as source for a Python extension.}{string}
@@ -2232,7 +2372,7 @@
 \end{classdesc*}
 
 \begin{classdesc*}{Command}
-A \class{Command} class (or rather, an instance of one of it's subclasses)
+A \class{Command} class (or rather, an instance of one of its subclasses)
 implement a single distutils command.
 \end{classdesc*}
 
@@ -2258,22 +2398,24 @@
 \end{funcdesc}
     
 \begin{funcdesc}{gen_preprocess_options}{macros, include_dirs}
-Generate C pre-processor options (-D, -U, -I) as used by at least
+Generate C pre-processor options (\programopt{-D}, \programopt{-U},
+\programopt{-I}) as used by at least
 two types of compilers: the typical \UNIX{} compiler and Visual \Cpp.
-\var{macros} is the usual thing, a list of 1- or 2-tuples, where \var{(name,)}
-means undefine (-U) macro \var{name}, and \var{(name,value)} means define (-D)
-macro \var{name} to \var{value}.  \var{include_dirs} is just a list of directory
-names to be added to the header file search path (-I).  Returns a list
-of command-line options suitable for either \UNIX{} compilers or Visual
-\Cpp.
+\var{macros} is the usual thing, a list of 1- or 2-tuples, where
+\code{(\var{name},)} means undefine (\programopt{-U}) macro \var{name},
+and \code{(\var{name}, \var{value})} means define (\programopt{-D})
+macro \var{name} to \var{value}.  \var{include_dirs} is just a list of
+directory names to be added to the header file search path (\programopt{-I}).
+Returns a list of command-line options suitable for either \UNIX{} compilers
+or Visual \Cpp.
 \end{funcdesc}
 
 \begin{funcdesc}{get_default_compiler}{osname, platform}
 Determine the default compiler to use for the given platform.
     
-\var{osname} should be one of the standard Python OS names (i.e. the
-ones returned by \var{os.name}) and \var{platform} the common value
-returned by \var{sys.platform} for the platform in question.
+\var{osname} should be one of the standard Python OS names (i.e.\ the
+ones returned by \code{os.name}) and \var{platform} the common value
+returned by \code{sys.platform} for the platform in question.
     
 The default values are \code{os.name} and \code{sys.platform} in case the
 parameters are not given.
@@ -2319,7 +2461,7 @@
 (don't actually execute the steps) and \var{force} (rebuild
 everything, regardless of dependencies). All of these flags default to
 \code{0} (off). Note that you probably don't want to instantiate
-\class{CCompiler} or one of it's subclasses directly - use the
+\class{CCompiler} or one of its subclasses directly - use the
 \function{distutils.CCompiler.new_compiler()} factory function
 instead.
 
@@ -2505,7 +2647,8 @@
 \file{build/foo/bar.o}.
 
 \var{macros}, if given, must be a list of macro definitions.  A macro
-definition is either a \var{(name, value)} 2-tuple or a \var{(name,)} 1-tuple.
+definition is either a \code{(\var{name}, \var{value})} 2-tuple or a
+\code{(\var{name},)} 1-tuple.
 The former defines a macro; if the value is \code{None}, the macro is
 defined without an explicit value.  The 1-tuple case undefines a
 macro.  Later definitions/redefinitions/undefinitions take
@@ -2518,10 +2661,10 @@
 \var{debug} is a boolean; if true, the compiler will be instructed to
 output debug symbols in (or alongside) the object file(s).
 
-\var{extra_preargs} and \var{extra_postargs} are implementation- dependent.
+\var{extra_preargs} and \var{extra_postargs} are implementation-dependent.
 On platforms that have the notion of a command-line (e.g. \UNIX,
 DOS/Windows), they are most likely lists of strings: extra
-command-line arguments to prepand/append to the compiler command
+command-line arguments to prepend/append to the compiler command
 line.  On other platforms, consult the implementation class
 documentation.  In any event, they are intended as an escape hatch
 for those occasions when the abstract compiler framework doesn't
@@ -2732,9 +2875,20 @@
 \modulesynopsis{Microsoft Compiler}
 
 This module provides \class{MSVCCompiler}, an implementation of the abstract 
-\class{CCompiler} class for Microsoft Visual Studio. It should also work using
-the freely available compiler provided as part of the .Net SDK download. XXX
-download link.
+\class{CCompiler} class for Microsoft Visual Studio. Typically, extension
+modules need to be compiled with the same compiler that was used to compile
+Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For
+Python 2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64
+and Itanium binaries are created using the Platform SDK.
+
+\class{MSVCCompiler} will normally choose the right compiler, linker etc.
+on its own. To override this choice, the environment variables
+\var{DISTUTILS\_USE\_SDK} and \var{MSSdk} must be both set. \var{MSSdk}
+indicates that the current environment has been setup by the SDK's
+\code{SetEnv.Cmd} script, or that the environment variables had been
+registered when the SDK was installed; \var{DISTUTILS\_USE\_SDK} indicates
+that the distutils user has made an explicit choice to override the
+compiler selection by \class{MSVCCompiler}.
 
 \section{\module{distutils.bcppcompiler} --- Borland Compiler}
 \declaremodule{standard}{distutils.bcppcompiler}
@@ -2759,7 +2913,8 @@
 \modulesynopsis{Metrowerks CodeWarrior support}
 
 Contains \class{MWerksCompiler}, an implementation of the abstract 
-\class{CCompiler} class for MetroWerks CodeWarrior on the Macintosh. Needs work to support CW on Windows.
+\class{CCompiler} class for MetroWerks CodeWarrior on the pre-Mac OS X Macintosh.
+Needs work to support CW on Windows or Mac OS X.
 
 
 %\subsection{Utility modules}
@@ -2791,8 +2946,8 @@
 \end{funcdesc}
 
 \begin{funcdesc}{make_tarball}{base_name, base_dir\optional{, compress=\code{'gzip'}, verbose=\code{0}, dry_run=\code{0}}}'Create an (optional compressed) archive as a tar file from all files in and under \var{base_dir}. \var{compress} must be \code{'gzip'} (the default), 
-\code{'compress'}, \code{'bzip2'}, or \code{None}.  Both \code{'tar'}
-and the compression utility named by \var{'compress'} must be on the 
+\code{'compress'}, \code{'bzip2'}, or \code{None}.  Both \program{tar}
+and the compression utility named by \var{compress} must be on the 
 default program search path, so this is probably \UNIX-specific.  The 
 output tar file will be named \file{\var{base_dir}.tar}, possibly plus
 the appropriate compression extension (\file{.gz}, \file{.bz2} or
@@ -2881,7 +3036,7 @@
 Copy an entire directory tree \var{src} to a new location \var{dst}.  Both
 \var{src} and \var{dst} must be directory names.  If \var{src} is not a
 directory, raise \exception{DistutilsFileError}.  If \var{dst} does 
-not exist, it is created with \var{mkpath()}.  The end result of the 
+not exist, it is created with \function{mkpath()}.  The end result of the 
 copy is that every file in \var{src} is copied to \var{dst}, and 
 directories under \var{src} are recursively copied to \var{dst}.  
 Return the list of files that were copied or might have been copied,
@@ -2901,7 +3056,7 @@
 
 \begin{funcdesc}{remove_tree}{directory\optional{verbose=\code{0}, dry_run=\code{0}}}
 Recursively remove \var{directory} and all files and directories underneath
-it. Any errors are ignored (apart from being reported to \code{stdout} if 
+it. Any errors are ignored (apart from being reported to \code{sys.stdout} if
 \var{verbose} is true).
 \end{funcdesc}
 
@@ -2929,7 +3084,7 @@
 to \code{'hard'} or \code{'sym'}; if it is \code{None} (the default),
 files are copied. Don't set \var{link} on systems that don't support
 it: \function{copy_file()} doesn't check if hard or symbolic linking is
-available.  It uses \var{_copy_file_contents()} to copy file contents.
+available.  It uses \function{_copy_file_contents()} to copy file contents.
 
 Return a tuple \samp{(dest_name, copied)}: \var{dest_name} is the actual 
 name of the output file, and \var{copied} is true if the file was copied 
@@ -2946,7 +3101,7 @@
 Move file \var{src} to \var{dst}. If \var{dst} is a directory, the file will
 be moved into it with the same name; otherwise, \var{src} is just renamed
 to \var{dst}.  Returns the new full name of the file.
-\warning{Handles cross-device moves on Unix using \function{copy_file()}.  
+\warning{Handles cross-device moves on \UNIX{} using \function{copy_file()}.  
 What about other systems???}
 \end{funcdesc}
 
@@ -2989,7 +3144,7 @@
 Return 'pathname' as a name that will work on the native filesystem,
 i.e. split it on '/' and put it back together again using the current
 directory separator.  Needed because filenames in the setup script are
-always supplied in Unix style, and have to be converted to the local
+always supplied in \UNIX{} style, and have to be converted to the local
 convention before we can actually use them in the filesystem.  Raises
 \exception{ValueError} on non-\UNIX-ish systems if \var{pathname} either 
 starts or ends with a slash.
@@ -2999,7 +3154,7 @@
 Return \var{pathname} with \var{new_root} prepended.  If \var{pathname} is
 relative, this is equivalent to \samp{os.path.join(new_root,pathname)}
 Otherwise, it requires making \var{pathname} relative and then joining the
-two, which is tricky on DOS/Windows and Mac OS.
+two, which is tricky on DOS/Windows.
 \end{funcdesc}
 
 \begin{funcdesc}{check_environ}{}
@@ -3038,7 +3193,7 @@
 \end{funcdesc}
 
 \begin{funcdesc}{split_quoted}{s}
-Split a string up according to Unix shell-like rules for quotes and
+Split a string up according to \UNIX{} shell-like rules for quotes and
 backslashes.  In short: words are delimited by spaces, as long as those
 spaces are not escaped by a backslash, or inside a quoted string.
 Single and double quotes are equivalent, and the quote characters can
@@ -3197,7 +3352,7 @@
 The option_table is a list of 3-tuples: \samp{(long_option,
 short_option, help_string)}
 
-If an option takes an argument, it's \var{long_option} should have \code{'='}
+If an option takes an argument, its \var{long_option} should have \code{'='}
 appended; \var{short_option} should just be a single character, no \code{':'}
 in any case. \var{short_option} should be \code{None} if a \var{long_option} 
 doesn't have a corresponding \var{short_option}. All option tuples must have
@@ -3294,11 +3449,11 @@
 something that provides \method{readline()} and \method{close()} 
 methods).  It is recommended that you supply at least \var{filename}, 
 so that \class{TextFile} can include it in warning messages.  If 
-\var{file} is not supplied, TextFile creates its own using the 
-\var{open()} builtin.
+\var{file} is not supplied, \class{TextFile} creates its own using the 
+\function{open()} built-in function.
 
 The options are all boolean, and affect the values returned by
-\var{readline()}
+\method{readline()}
 
 \begin{tableiii}{c|l|l}{option name}{option name}{description}{default}
 \lineiii{strip_comments}{
