Commits

Anonymous committed 963907f

This commit was manufactured by cvs2svn to create tag 'r232'.

Comments (0)

Files changed (23)

Doc/dist/dist.tex

-\documentclass{howto}
-\usepackage{distutils}
-
-% $Id$
-
-% TODO
-%   Document extension.read_setup_file
-%   Document build_clib command
-%
-
-\title{Distributing Python Modules}
-
-\author{Greg Ward}
-\authoraddress{Email: \email{distutils-sig@python.org}}
-
-\makeindex
-
-\begin{document}
-
-\maketitle
-\begin{abstract}
-  \noindent
-  This document describes the Python Distribution Utilities
-  (``Distutils'') from the module developer's point of view, describing
-  how to use the Distutils to make Python modules and extensions easily
-  available to a wider audience with very little overhead for
-  build/release/install mechanics.
-\end{abstract}
-
-% The ugly "%begin{latexonly}" pseudo-environment supresses the table
-% of contents for HTML generation.
-%
-%begin{latexonly}
-\tableofcontents
-%end{latexonly}
-
-
-\section{Introduction}
-\label{intro}
-
-This document covers using the Distutils to distribute your Python
-modules, concentrating on the role of developer/distributor: if
-you're looking for information on installing Python modules, you
-should refer to the \citetitle[../inst/inst.html]{Installing Python
-Modules} manual.
-
-
-\section{Concepts \& Terminology}
-\label{concepts}
-
-Using the Distutils is quite simple, both for module developers and for
-users/administrators installing third-party modules.  As a developer,
-your responsibilities (apart from writing solid, well-documented and
-well-tested code, of course!) are:
-\begin{itemize}
-\item write a setup script (\file{setup.py} by convention)
-\item (optional) write a setup configuration file
-\item create a source distribution
-\item (optional) create one or more built (binary) distributions
-\end{itemize}
-Each of these tasks is covered in this document.
-
-Not all module developers have access to a multitude of platforms, so
-it's not always feasible to expect them to create a multitude of built
-distributions.  It is hoped that a class of intermediaries, called
-\emph{packagers}, will arise to address this need.  Packagers will take
-source distributions released by module developers, build them on one or
-more platforms, and release the resulting built distributions.  Thus,
-users on the most popular platforms will be able to install most popular
-Python module distributions in the most natural way for their platform,
-without having to run a single setup script or compile a line of code.
-
-
-\subsection{A Simple Example}
-\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,
-though you should 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 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
-simple as this:
-
-\begin{verbatim}
-from distutils.core import setup
-setup(name="foo",
-      version="1.0",
-      py_modules=["foo"])
-\end{verbatim}
-
-Some observations:
-\begin{itemize}
-\item most information that you supply to the Distutils is supplied as
-  keyword arguments to the \function{setup()} function
-\item those keyword arguments fall into two categories: package
-  metadata (name, version number) and information about what's in the
-  package (a list of pure Python modules, in this case)
-\item modules are specified by module name, not filename (the same will
-  hold true for packages and extensions)
-\item it's recommended that you supply a little more metadata, 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
-setup script, \file{setup.py}, containing the above code, and run:
-
-\begin{verbatim}
-python setup.py sdist
-\end{verbatim}
-
-which will create an archive file (e.g., tarball on \UNIX, ZIP file on
-Windows) containing your setup script \file{setup.py}, and your module
-\file{foo.py}.  The archive file will be named \file{foo-1.0.tar.gz} (or
-\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,
-and---from the \file{foo-1.0} directory---run
-
-\begin{verbatim}
-python setup.py install
-\end{verbatim}
-
-which will ultimately copy \file{foo.py} to the appropriate directory
-for third-party modules in their Python installation.
-
-This simple example demonstrates some fundamental concepts of the
-Distutils. First, both developers and installers have the same basic
-user interface, i.e. the setup script.  The difference is which
-Distutils \emph{commands} they use: the \command{sdist} command is
-almost exclusively for module developers, while \command{install} is
-more often for installers (although most developers will want to install
-their own code occasionally).
-
-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
-Windows users, you can create an executable installer (the most
-appropriate type of built distribution for this platform) with the
-\command{bdist\_wininst} command.  For example:
-
-\begin{verbatim}
-python setup.py bdist_wininst
-\end{verbatim}
-
-will create an executable installer, \file{foo-1.0.win32.exe}, in the
-current directory.
-
-Other useful built distribution formats are RPM, implemented by the
-\command{bdist\_rpm} command, Solaris \program{pkgtool}
-(\command{bdist\_pkgtool}), and HP-UX \program{swinstall}
-(\command{bdist_sdux}).  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}
-
-(The \command{bdist\_rpm} command uses the \command{rpm} executable,
-therefore this 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}
-\label{python-terms}
-
-If you're reading this document, you probably have a good idea of what
-modules, extensions, and so forth are.  Nevertheless, just to be sure
-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.  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.''
-
-\item[extension module] a module written in the low-level language of
-  the Python implementation: C/\Cpp{} for Python, Java for Jython.
-  Typically contained in a single dynamically loadable pre-compiled
-  file, e.g. a shared object (\file{.so}) file for Python extensions on
-  \UNIX, a DLL (given the \file{.pyd} extension) for Python extensions
-  on Windows, or a Java class file for Jython extensions.  (Note that
-  currently, the Distutils only handles C/\Cpp{} extensions for Python.)
-
-\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 root of the hierarchy of packages.  (This isn't
-  really a package, since it doesn't have an \file{\_\_init\_\_.py}
-  file.  But we have to call it something.)  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.
-  Unlike regular packages, modules in the root package can be found in
-  many directories: in fact, every directory listed in \code{sys.path}
-  contributes modules to the root package.
-\end{description}
-
-
-\subsection{Distutils-specific terminology}
-\label{distutils-term}
-
-The following terms apply more specifically to the domain of
-distributing Python modules using the Distutils:
-\begin{description}
-\item[module distribution] a collection of Python modules distributed
-  together as a single downloadable resource and meant to be installed
-  \emph{en masse}.  Examples of some well-known module distributions are
-  Numeric Python, PyXML, PIL (the Python Imaging Library), or
-  mxBase.  (This would be called a \emph{package}, except that term
-  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.''
-
-\item[non-pure module distribution] a module distribution that contains
-  at least one extension module.  Sometimes referred to as a ``non-pure
-  distribution.''
-
-\item[distribution root] the top-level directory of your source tree (or 
-  source distribution); the directory where \file{setup.py} exists.  Generally 
-  \file{setup.py} will be run from this directory.
-\end{description}
-
-
-\section{Writing the Setup Script}
-\label{setup-script}
-
-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
-most information supplied to the Distutils by the module developer 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 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
-
-from distutils.core import setup
-
-setup(name="Distutils",
-      version="1.0",
-      description="Python Distribution Utilities",
-      author="Greg Ward",
-      author_email="gward@python.net",
-      url="http://www.python.org/sigs/distutils-sig/",
-      packages=['distutils', 'distutils.command'],
-     )
-\end{verbatim}
-
-There are only two differences between this and the trivial one-file
-distribution presented in section~\ref{simple-example}: more
-metadata, and the specification of pure Python modules by package,
-rather than by module.  This is important since the Distutils consist of
-a couple of dozen modules split into (so far) two packages; an explicit
-list of every module would be tedious to generate and difficult to
-maintain.  For more information on the additional meta-data, see
-section~\ref{meta-data}.
-
-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 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.  (MacOS programmers should keep in
-mind that the \emph{absence} of a leading slash indicates a relative
-path, the opposite of the MacOS convention with colons.)
-
-This, of course, only applies to pathnames given to Distutils
-functions.  If you, for example, use standard Python functions such as
-\function{glob.glob()} or \function{os.listdir()} to specify files, you
-should be careful to write portable code instead of hardcoding path
-separators:
-
-\begin{verbatim}
-    glob.glob(os.path.join('mydir', 'subdir', '*.html'))
-    os.listdir(os.path.join('mydir', 'subdir'))
-\end{verbatim}
-
-
-\subsection{Listing whole packages}
-\label{listing-packages}
-
-The \option{packages} option tells the Distutils to process (build,
-distribute, install, etc.) all pure Python modules found in each package
-mentioned in the \option{packages} list.  In order to do this, of
-course, there has to be a correspondence between package names and
-directories in the filesystem.  The default correspondence is the most
-obvious one, i.e. package \module{distutils} is found in the directory
-\file{distutils} relative to the distribution root.  Thus, when you say
-\code{packages = ['foo']} in your setup script, you are promising that
-the Distutils will find a file \file{foo/\_\_init\_\_.py} (which might
-be spelled differently on your system, but you get the idea) relative to
-the directory where your setup script lives.  If you break this
-promise, the Distutils will issue a warning but still process the broken
-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 in the
-``root package'' (i.e., not in any package at all) are 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.  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 
-\file{lib}, the \module{foo.bar} package in \file{lib/bar}, etc.  This
-would be written in the setup script as
-
-\begin{verbatim}
-package_dir = {'foo': 'lib'}
-\end{verbatim}
-
-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}
-\label{listing-modules}
-
-For a small module distribution, you might prefer to list all modules
-rather than listing packages---especially the case of a single module
-that goes in the ``root package'' (i.e., no package at all).  This
-simplest case was shown in section~\ref{simple-example}; here is a
-slightly more involved example:
-
-\begin{verbatim}
-py_modules = ['mod1', 'pkg.mod2']
-\end{verbatim}
-
-This describes two modules, one of them in the ``root'' package, the
-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 correspondence using
-the \option{package\_dir} option.
-
-
-\subsection{Describing extension modules}
-\label{describing-extensions}
-
-% XXX read over this section
-Just as writing Python extension modules is a bit more complicated than
-writing pure Python modules, describing them to the Distutils is a bit
-more complicated.  Unlike pure modules, it's not enough just to list
-modules or packages and expect the Distutils to go out and find the
-right files; you have to specify the extension name, source file(s), and
-any compile/link requirements (include directories, libraries to link
-with, etc.).
-
-All of this is done through another keyword argument to
-\function{setup()}, the \option{extensions} option.  \option{extensions}
-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
-additional instructions to the compiler/linker are needed, describing
-this extension is quite simple:
-
-\begin{verbatim}
-uExtension("foo", ["foo.c"])
-\end{verbatim}
-
-The \class{Extension} class can be imported from
-\module{distutils.core} along with \function{setup()}.  Thus, the setup
-script for a module distribution that contains only this one extension
-and nothing else might be:
-
-\begin{verbatim}
-from distutils.core import setup, Extension
-setup(name="foo", version="1.0",
-      ext_modules=[Extension("foo", ["foo.c"])])
-\end{verbatim}
-
-The \class{Extension} class (actually, the underlying extension-building
-machinery implemented by the \command{build\_ext} command) supports a
-great deal of flexibility in describing Python extensions, which is
-explained in the following sections.  
-
-
-\subsubsection{Extension names and packages}
-
-The first argument to the \class{Extension} constructor is always the
-name of the extension, including any package names.  For example,
-
-\begin{verbatim}
-Extension("foo", ["src/foo1.c", "src/foo2.c"])
-\end{verbatim}
-
-describes an extension that lives in the root package, while
-
-\begin{verbatim}
-Extension("pkg.foo", ["src/foo1.c", "src/foo2.c"])
-\end{verbatim}
-
-describes the same extension in the \module{pkg} package.  The source
-files and resulting object code are identical in both cases; the only
-difference is where in the filesystem (and therefore where in Python's
-namespace hierarchy) the resulting extension lives.
-
-If you have a number of extensions all in the same package (or all under
-the same base package), use the \option{ext\_package} keyword argument
-to \function{setup()}.  For example,
-
-\begin{verbatim}
-setup(...
-      ext_package="pkg",
-      ext_modules=[Extension("foo", ["foo.c"]),
-                   Extension("subpkg.bar", ["bar.c"])]
-     )
-\end{verbatim}
-
-will compile \file{foo.c} to the extension \module{pkg.foo}, and
-\file{bar.c} to \module{pkg.subpkg.bar}.
-
-
-\subsubsection{Extension source files}
-
-The second argument to the \class{Extension} constructor is a list of
-source files.  Since the Distutils currently only support C, \Cpp, and
-Objective-C extensions, these are normally C/\Cpp/Objective-C source
-files.  (Be sure to use appropriate extensions to distinguish \Cpp\
-source files: \file{.cc} and \file{.cpp} seem to be recognized by both
-\UNIX{} and Windows compilers.)
-
-However, you can also include SWIG interface (\file{.i}) files in the
-list; the \command{build\_ext} command knows how to deal with SWIG
-extensions: it will run SWIG on the interface file and compile the
-resulting C/\Cpp{} file into your extension.
-
-\XXX{SWIG support is rough around the edges and largely untested;
-  especially SWIG support for \Cpp{} extensions!  Explain in more detail
-  here when the interface firms up.}
-
-On some platforms, you can include non-source files that are processed
-by the compiler and included in your extension.  Currently, this just
-means Windows message text (\file{.mc}) files and resource definition
-(\file{.rc}) files for Visual \Cpp. These will be compiled to binary resource
-(\file{.res}) files and linked into the executable.
-
-
-\subsubsection{Preprocessor options}
-
-Three optional arguments to \class{Extension} will help if you need to
-specify include directories to search or preprocessor macros to
-define/undefine: \code{include\_dirs}, \code{define\_macros}, and
-\code{undef\_macros}.
-
-For example, if your extension requires header files in the
-\file{include} directory under your distribution root, use the
-\code{include\_dirs} option:
-
-\begin{verbatim}
-Extension("foo", ["foo.c"], include_dirs=["include"])
-\end{verbatim}
-
-You can specify absolute directories there; if you know that your
-extension will only be built on \UNIX{} systems with X11R6 installed to
-\file{/usr}, you can get away with
-
-\begin{verbatim}
-Extension("foo", ["foo.c"], include_dirs=["/usr/include/X11"])
-\end{verbatim}
-
-You should avoid this sort of non-portable usage if you plan to
-distribute your code: it's probably better to write C code like
-\begin{verbatim}
-#include <X11/Xlib.h>
-\end{verbatim}
-
-If you need to include header files from some other Python extension,
-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}.
-(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
-included in the search path when building Python extensions, the best
-approach is to write C code like
-\begin{verbatim}
-#include <Numerical/arrayobject.h>
-\end{verbatim}
-If you must put the \file{Numerical} include directory right into your
-header search path, though, you can find that directory using the
-Distutils \module{sysconfig} module:
-
-\begin{verbatim}
-from distutils.sysconfig import get_python_inc
-incdir = os.path.join(get_python_inc(plat_specific=1), "Numerical")
-setup(...,
-      Extension(..., include_dirs=[incdir]))
-\end{verbatim}
-
-Even though this is quite portable---it will work on any Python
-installation, regardless of platform---it's probably easier to just
-write your C code in the sensible way.
-
-You can define and undefine pre-processor macros with the
-\code{define\_macros} and \code{undef\_macros} options.
-\code{define\_macros} takes a list of \code{(name, value)} tuples, where
-\code{name} is the name of the macro to define (a string) and
-\code{value} is its value: either a string or \code{None}.  (Defining a
-macro \code{FOO} to \code{None} is the equivalent of a bare
-\code{\#define FOO} in your C source: with most compilers, this sets
-\code{FOO} to the string \code{1}.)  \code{undef\_macros} is just
-a list of macros to undefine.
-
-For example:
-
-\begin{verbatim}
-Extension(...,
-          define_macros=[('NDEBUG', '1')],
-                         ('HAVE_STRFTIME', None),
-          undef_macros=['HAVE_FOO', 'HAVE_BAR'])
-\end{verbatim}
-
-is the equivalent of having this at the top of every C source file:
-
-\begin{verbatim}
-#define NDEBUG 1
-#define HAVE_STRFTIME
-#undef HAVE_FOO
-#undef HAVE_BAR
-\end{verbatim}
-
-
-\subsubsection{Library options}
-
-You can also specify the libraries to link against when building your
-extension, and the directories to search for those libraries.  The
-\code{libraries} option is a list of libraries to link against,
-\code{library\_dirs} is a list of directories to search for libraries at 
-link-time, and \code{runtime\_library\_dirs} is a list of directories to 
-search for shared (dynamically loaded) libraries at run-time.
-
-For example, if you need to link against libraries known to be in the
-standard library search path on target systems
-
-\begin{verbatim}
-Extension(...,
-          libraries=["gdbm", "readline"])
-\end{verbatim}
-
-If you need to link with libraries in a non-standard location, you'll
-have to include the location in \code{library\_dirs}:
-
-\begin{verbatim}
-Extension(...,
-          library_dirs=["/usr/X11R6/lib"],
-          libraries=["X11", "Xt"])
-\end{verbatim}
-
-(Again, this sort of non-portable construct should be avoided if you
-intend to distribute your code.)
-
-\XXX{Should mention clib libraries here or somewhere else!}
-
-\subsubsection{Other options}
-
-There are still some other options which can be used to handle special
-cases.
-
-The \option{extra\_objects} option is a list of object files to be passed
-to the linker. These files must not have extensions, as the default
-extension for the compiler is used.
-
-\option{extra\_compile\_args} and \option{extra\_link\_args} can be used
-to specify additional command line options for the respective compiler and
-linker command lines.
-
-\option{export\_symbols} is only useful on Windows.  It can contain a list
-of symbols (functions or variables) to be exported. This option
-is not needed when building compiled extensions: Distutils 
-will automatically add \code{initmodule}
-to the list of exported symbols.
-
-\subsection{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.
-
-Scripts are files containing Python source code, intended to be
-started from the command line.  Scripts don't require Distutils to do
-anything very complicated.  The only clever feature is that if the
-first line of the script starts with \code{\#!} and contains the word
-``python'', the Distutils will adjust the first line to refer to the
-current interpreter location.
-
-The \option{scripts} option simply is a list of files to be handled
-in this way.  From the PyXML setup script:
-
-\begin{verbatim}
-setup (... 
-       scripts = ['scripts/xmlproc_parse', 'scripts/xmlproc_val']
-      )
-\end{verbatim}
-
-
-\subsection{Installing Additional Files}
-
-The \option{data\_files} option can be used to specify additional
-files needed by the module distribution: configuration files, message
-catalogs, data files, anything which doesn't fit in the previous
-categories.
-
-\option{data\_files} specifies a sequence of (\var{directory},
-\var{files}) pairs in the following way:
-
-\begin{verbatim}
-setup(...
-      data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
-                  ('config', ['cfg/data.cfg']),
-                  ('/etc/init.d', ['init-script'])]
-     )
-\end{verbatim}
-
-Note that you can specify the directory names where the data files
-will be installed, but you cannot rename the data files themselves.
-
-Each (\var{directory}, \var{files}) pair in the sequence specifies the
-installation directory and the files to install there.  If
-\var{directory} is a relative path, it is interpreted relative to the
-installation prefix (Python's \code{sys.prefix} for pure-Python
-packages, \code{sys.exec_prefix} for packages that contain extension
-modules).  Each file name in \var{files} is interpreted relative to
-the \file{setup.py} script at the top of the package source
-distribution.  No directory information from \var{files} is used to
-determine the final location of the installed file; only the name of
-the file is used.
-
-You can specify the \option{data\_files} options as a simple sequence
-of files without specifying a target directory, but this is not recommended,
-and the \command{install} command will print a warning in this case.
-To install data files directly in the target directory, an empty
-string should be given as the directory.
-
-\subsection{Additional meta-data}
-\label{meta-data}
-
-The setup script may include additional meta-data beyond the name and
-version. This information includes:
-
-\begin{tableiv}{l|l|l|c}{code}%
-  {Meta-Data}{Description}{Value}{Notes}
-  \lineiv{name}{name of the package}
-         {short string}{(1)}
-  \lineiv{version}{version of this release}
-         {short string}{(1)(2)}
-  \lineiv{author}{package author's name}
-         {short string}{(3)}
-  \lineiv{author_email}{email address of the package author}
-         {email address}{(3)}
-  \lineiv{maintainer}{package maintainer's name}
-         {short string}{(3)}
-  \lineiv{maintainer_email}{email address of the package maintainer}
-         {email address}{(3)}
-  \lineiv{url}{home page for the package}
-         {URL}{(1)}
-  \lineiv{description}{short, summary description of the package}
-         {short string}{}
-  \lineiv{long_description}{longer description of the package}
-         {long string}{}
-  \lineiv{download_url}{location where the package may be downloaded}
-         {URL}{(4)}
-  \lineiv{classifiers}{a list of Trove classifiers}
-         {list of strings}{(4)}
-\end{tableiv}
-
-\noindent Notes:
-\begin{description}
-\item[(1)] These fields are required.
-\item[(2)] It is recommended that versions take the form
-  \emph{major.minor\optional{.patch\optional{.sub}}}.
-\item[(3)] Either the author or the maintainer must be identified.
-\item[(4)] These fields should not be used if your package is to be
-  compatible with Python versions prior to 2.2.3 or 2.3.  The list is
-  available from the \ulink{PyPI website}{http://www.python.org/pypi}.
-
-\item["short string"] A single line of text, not more than 200 characters.
-\item["long string"] Multiple lines of plain text in ReStructuredText
-  format (see \url{http://docutils.sf.net/}).
-\item["list of strings"] See below.
-\end{description}
-
-None of the string values may be Unicode.
-
-Encoding the version information is an art in itself. Python packages
-generally adhere to the version format
-\emph{major.minor\optional{.patch}\optional{sub}}. The major number is
-0 for
-initial, experimental releases of software. It is incremented for
-releases that represent major milestones in a package. The minor
-number is incremented when important new features are added to the
-package. The patch number increments when bug-fix releases are
-made. Additional trailing version information is sometimes used to
-indicate sub-releases.  These are "a1,a2,...,aN" (for alpha releases,
-where functionality and API may change), "b1,b2,...,bN" (for beta
-releases, which only fix bugs) and "pr1,pr2,...,prN" (for final
-pre-release release testing). Some examples:
-
-\begin{description}
-\item[0.1.0] the first, experimental release of a package
-\item[1.0.1a2] the second alpha release of the first patch version of 1.0
-\end{description}
-
-\option{classifiers} are specified in a python list:
-
-\begin{verbatim}
-setup(...
-      classifiers = [
-          'Development Status :: 4 - Beta',
-          'Environment :: Console',
-          'Environment :: Web Environment',
-          'Intended Audience :: End Users/Desktop',
-          'Intended Audience :: Developers',
-          'Intended Audience :: System Administrators',
-          'License :: OSI Approved :: Python Software Foundation License',
-          'Operating System :: MacOS :: MacOS X',
-          'Operating System :: Microsoft :: Windows',
-          'Operating System :: POSIX',
-          'Programming Language :: Python',
-          'Topic :: Communications :: Email',
-          'Topic :: Office/Business',
-          'Topic :: Software Development :: Bug Tracking',
-          ],
-      )
-\end{verbatim}
-
-If you wish to include classifiers in your \file{setup.py} file and also
-wish to remain backwards-compatible with Python releases prior to 2.2.3,
-then you can include the following code fragment in your \file{setup.py}
-before the \code{setup()} call.
-
-\begin{verbatim}
-# patch distutils if it can't cope with the "classifiers" or
-# "download_url" keywords
-if sys.version < '2.2.3':
-    from distutils.dist import DistributionMetadata
-    DistributionMetadata.classifiers = None
-    DistributionMetadata.download_url = None
-\end{verbatim}
-
-
-\subsection{Debugging the setup script}
-\label{meta-data}
-
-Sometimes things go wrong, and the setup script doesn't do what the
-developer wants.
-
-Distutils catches any exceptions when running the setup script, and
-print a simple error message before the script is terminated.  The
-motivation for this behaviour is to not confuse administrators who
-don't know much about Python and are trying to install a package.  If
-they get a big long traceback from deep inside the guts of Distutils,
-they may think the package or the Python installation is broken
-because they don't read all the way down to the bottom and see that
-it's a permission problem.
-
-On the other hand, this doesn't help the developer to find the cause
-of the failure. For this purpose, the DISTUTILS_DEBUG environment
-variable can be set to anything except an empty string, and distutils
-will now print detailed information what it is doing, and prints the
-full traceback in case an exception occurrs.
-
-\section{Writing the Setup Configuration File}
-\label{setup-config}
-
-Often, it's not possible to write down everything needed to build a
-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.)
-
-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, which
-run from a \character{\#} character until the end of the 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}
-
-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.
-
-
-\begin{seealso}
-  \seetitle[../inst/config-syntax.html]{Installing Python
-            Modules}{More information on the configuration files is
-            available in the manual for system administrators.}
-\end{seealso}
-
-
-\section{Creating a Source Distribution}
-\label{source-dist}
-
-As shown in section~\ref{simple-example}, you use the
-\command{sdist} command to create a source distribution.  In the
-simplest case,
-
-\begin{verbatim}
-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 format is a gzip'ed
-tar file (\file{.tar.gz}) on \UNIX, and ZIP file on Windows.
-\XXX{no MacOS support here}
-
-You can specify as many formats as you like using the
-\longprogramopt{formats} option, for example:
-
-\begin{verbatim}
-python setup.py sdist --formats=gztar,zip
-\end{verbatim}
-
-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),(3)}
-  \lineiii{gztar}{gzip'ed tar file (\file{.tar.gz})}{(2),(4)}
-  \lineiii{bztar}{bzip2'ed tar file (\file{.tar.bz2})}{(4)}
-  \lineiii{ztar}{compressed tar file (\file{.tar.Z})}{(4)}
-  \lineiii{tar}{tar file (\file{.tar})}{(4)}
-\end{tableiii}
-
-\noindent Notes:
-\begin{description}
-\item[(1)] default on Windows
-\item[(2)] default on \UNIX
-\item[(3)] requires either external \program{zip} utility or
-  \module{zipfile} module (part of the standard Python library since
-  Python~1.6)
-\item[(4)] requires external utilities: \program{tar} and possibly one
-  of \program{gzip}, \program{bzip2}, or \program{compress}
-\end{description}
-
-
-
-\subsection{Specifying the files to distribute}
-\label{manifest}
-
-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
-\item all C source files mentioned in the \option{ext\_modules} or
-  \option{libraries} options (\XXX{getting C library sources currently
-    broken -- no get\_source\_files() method in build\_clib.py!})
-\item anything that looks like a test script: \file{test/test*.py}
-  (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}), \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
-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
-distribution.  For an example, again we turn to the Distutils' own
-manifest template:
-
-\begin{verbatim}
-include *.txt
-recursive-include examples *.txt *.py
-prune examples/sample?/build
-\end{verbatim}
-
-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}.  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).
-
-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
-Distutils source distribution:
-\begin{enumerate}
-\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---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 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.
-That way, the manifest template is portable across operating systems.
-
-
-\subsection{Manifest-related options}
-\label{manifest-options}
-
-The normal course of operations for the \command{sdist} command is as
-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
-\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, use
-the \longprogramopt{no-defaults} and \longprogramopt{no-prune} to
-disable the standard ``include'' and ``exclude'' sets.
-
-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:
-
-\begin{verbatim}
-python setup.py sdist --force-manifest
-\end{verbatim}
-
-Or, you might just want to (re)generate the manifest, but not create a
-source distribution:
-
-\begin{verbatim}
-python setup.py sdist --manifest-only
-\end{verbatim}
-
-\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}
-\label{built-dist}
-
-A ``built distribution'' is what you're probably used to thinking of
-either as a ``binary package'' or an ``installer'' (depending on your
-background).  It's not necessarily binary, though, because it might
-contain only Python source code and/or byte-code; and we don't call it a
-package, because that word is already spoken for in Python.  (And
-``installer'' is a term specific to the Windows world.  \XXX{do Mac
-  people use it?})
-
-A built distribution is how you make life as easy as possible for
-installers of your module distribution: for users of RPM-based Linux
-systems, it's a binary RPM; for Windows users, it's an executable
-installer; for Debian-based Linux users, it's a Debian package; and so
-forth.  Obviously, no one person will be able to create built
-distributions for every platform under the sun, so the Distutils are
-designed to enable module developers to concentrate on their
-specialty---writing code and creating source distributions---while an
-intermediary species called \emph{packagers} springs up to turn source
-distributions into built distributions for as many platforms as there
-are packagers.
-
-Of course, the module developer could be his own packager; or the
-packager could be a volunteer ``out there'' somewhere who has access to
-a platform which the original developer does not; or it could be
-software periodically grabbing new source distributions and turning them
-into built distributions for as many platforms as the software has
-access to.  Regardless of who they are, a packager uses the
-setup script and the \command{bdist} command family to generate built
-distributions.
-
-As a simple example, if I run the following command in the Distutils
-source tree:
-
-\begin{verbatim}
-python setup.py bdist
-\end{verbatim}
-
-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.  The default format for built distributions is a ``dumb'' tar
-file on \UNIX, and a simple executable installer on Windows.  (That tar
-file is considered ``dumb'' because it has to be unpacked in a specific
-location to work.)
-
-Thus, the above command on a \UNIX{} system creates
-\file{Distutils-1.0.\filevar{plat}.tar.gz}; unpacking this tarball
-from the right place installs the Distutils just as though you had
-downloaded the source distribution and run \code{python setup.py
-  install}.  (The ``right place'' is either the root of the filesystem or 
-Python's \filevar{prefix} directory, depending on the options given to
-the \command{bdist\_dumb} command; the default is to make dumb
-distributions relative to \filevar{prefix}.)  
-
-Obviously, for pure Python distributions, this isn't any simpler than
-just running \code{python setup.py install}---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.  And creating ``smart'' built distributions,
-such as an RPM package or an executable installer for Windows, is far
-more convenient for users even if your distribution doesn't include
-any extensions.
-
-The \command{bdist} command has a \longprogramopt{formats} option,
-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-1.0.\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{gztar}{gzipped tar file (\file{.tar.gz})}{(1),(3)}
-  \lineiii{ztar}{compressed tar file (\file{.tar.Z})}{(3)}
-  \lineiii{tar}{tar file (\file{.tar})}{(3)}
-  \lineiii{zip}{zip file (\file{.zip})}{(4)}
-  \lineiii{rpm}{RPM}{(5)}
-  \lineiii{pkgtool}{Solaris \program{pkgtool}}{}
-  \lineiii{sdux}{HP-UX \program{swinstall}}{}
-  \lineiii{rpm}{RPM}{(5)}
-%  \lineiii{srpm}{source RPM}{(5) \XXX{to do!}}
-  \lineiii{wininst}{self-extracting ZIP file for Windows}{(2),(4)}
-\end{tableiii}
-
-\noindent Notes:
-\begin{description}
-\item[(1)] default on \UNIX
-\item[(2)] default on Windows \XXX{to-do!}
-\item[(3)] requires external utilities: \program{tar} and possibly one
-  of \program{gzip}, \program{bzip2}, or \program{compress}
-\item[(4)] requires either external \program{zip} utility or
-  \module{zipfile} module (part of the standard Python library since
-  Python~1.6)
-\item[(5)] requires external \program{rpm} utility, version 3.0.4 or
-  better (use \code{rpm --version} to find out which version you have)
-\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.  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
-\code{zip}), and \command{bdist\_rpm} generates both binary and source
-RPMs.  The \command{bdist} sub-commands, and the formats generated by
-each, are:
-\begin{tableii}{l|l}{command}%
-  {Command}{Formats}
-  \lineii{bdist\_dumb}{tar, ztar, gztar, zip}
-  \lineii{bdist\_rpm}{rpm, srpm}
-  \lineii{bdist\_wininst}{wininst}
-\end{tableii}
-
-The following sections give details on the individual \command{bdist\_*}
-commands.
-
-
-\subsection{Creating dumb built distributions}
-\label{creating-dumb}
-
-\XXX{Need to document absolute vs. prefix-relative packages here, but
-  first I have to implement it!}
-
-
-\subsection{Creating RPM packages}
-\label{creating-rpms}
-
-The RPM format is used by many popular Linux distributions, including
-Red Hat, SuSE, and Mandrake.  If one of these (or any of the other
-RPM-based Linux distributions) is your usual environment, creating RPM
-packages for other users of that same distribution is trivial.
-Depending on the complexity of your module distribution and differences
-between Linux distributions, you may also be able to create RPMs that
-work on different RPM-based distributions.
-
-The usual way to create an RPM of your module distribution is to run the 
-\command{bdist\_rpm} command:
-
-\begin{verbatim}
-python setup.py bdist_rpm
-\end{verbatim}
-
-or the \command{bdist} command with the \longprogramopt{format} option:
-
-\begin{verbatim}
-python setup.py bdist --formats=rpm
-\end{verbatim}
-
-The former allows you to specify RPM-specific options; the latter allows 
-you to easily specify multiple formats in one run.  If you need to do
-both, you can explicitly specify multiple \command{bdist\_*} commands
-and their options:
-
-\begin{verbatim}
-python setup.py bdist_rpm --packager="John Doe <jdoe@python.net>" \
-                bdist_wininst --target_version="2.0"
-\end{verbatim}
-
-Creating RPM packages is driven by a \file{.spec} file, much as using
-the Distutils is driven by the setup script.  To make your life easier,
-the \command{bdist\_rpm} command normally creates a \file{.spec} file
-based on the information you supply in the setup script, on the command
-line, and in any Distutils configuration files.  Various options and
-sections in the \file{.spec} file are derived from options in the setup
-script as follows:
-\begin{tableii}{l|l}{textrm}%
-  {RPM \file{.spec} file option or section}{Distutils setup script option}
-  \lineii{Name}{\option{name}}
-  \lineii{Summary (in preamble)}{\option{description}}
-  \lineii{Version}{\option{version}}
-  \lineii{Vendor}{\option{author} and \option{author\_email}, or \\&
-                  \option{maintainer} and \option{maintainer\_email}}
-  \lineii{Copyright}{\option{licence}}
-  \lineii{Url}{\option{url}}
-  \lineii{\%description (section)}{\option{long\_description}}
-\end{tableii}
-
-Additionally, there 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:
-\begin{tableiii}{l|l|l}{textrm}%
-  {RPM \file{.spec} file option or section}%
-  {\command{bdist\_rpm} option}%
-  {default value}
-  \lineiii{Release}{\option{release}}{``1''}
-  \lineiii{Group}{\option{group}}{``Development/Libraries''}
-  \lineiii{Vendor}{\option{vendor}}{(see above)}
-  \lineiii{Packager}{\option{packager}}{(none)}
-  \lineiii{Provides}{\option{provides}}{(none)}
-  \lineiii{Requires}{\option{requires}}{(none)}
-  \lineiii{Conflicts}{\option{conflicts}}{(none)}
-  \lineiii{Obsoletes}{\option{obsoletes}}{(none)}
-  \lineiii{Distribution}{\option{distribution\_name}}{(none)}
-  \lineiii{BuildRequires}{\option{build\_requires}}{(none)}
-  \lineiii{Icon}{\option{icon}}{(none)}
-\end{tableiii}
-Obviously, supplying even a few of these options on the command-line
-would be tedious and error-prone, so it's usually best to put them in
-the setup configuration file, \file{setup.cfg}---see
-section~\ref{setup-config}.  If you distribute or package many Python
-module distributions, you might want to put options that apply to all of
-them in your personal Distutils configuration file
-(\file{\textasciitilde/.pydistutils.cfg}).
-
-There are three steps to building a binary RPM package, all of which are 
-handled automatically by the Distutils:
-\begin{enumerate}
-\item create a \file{.spec} file, which describes the package (analogous 
-  to the Distutils setup script; in fact, much of the information in the 
-  setup script winds up in the \file{.spec} file)
-\item create the source RPM
-\item create the ``binary'' RPM (which may or may not contain binary
-  code, depending on whether your module distribution contains Python
-  extensions)
-\end{enumerate}
-Normally, RPM bundles the last two steps together; when you use the
-Distutils, all three steps are typically bundled together.
-
-If you wish, you can separate these three steps.  You can use the
-\longprogramopt{spec-only} option to make \command{bdist\_rpm} just
-create the \file{.spec} file and exit; in this case, the \file{.spec}
-file will be written to the ``distribution directory''---normally
-\file{dist/}, but customizable with the \longprogramopt{dist-dir}
-option.  (Normally, the \file{.spec} file winds up deep in the ``build
-tree,'' in a temporary directory created by \command{bdist\_rpm}.)
-
-\XXX{this isn't implemented yet---is it needed?!}
-You can also specify a custom \file{.spec} file with the
-\longprogramopt{spec-file} option; used in conjunction with
-\longprogramopt{spec-only}, this gives you an opportunity to customize
-the \file{.spec} file manually:
-
-\begin{verbatim}
-> python setup.py bdist_rpm --spec-only
-# ...edit dist/FooBar-1.0.spec
-> python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec
-\end{verbatim}
-
-(Although a better way to do this is probably to override the standard
-\command{bdist\_rpm} command with one that writes whatever else you want
-to the \file{.spec} file.)
-
-
-\subsection{Creating Windows Installers}
-\label{creating-wininst}
-
-Executable installers are the natural format for binary distributions
-on Windows.  They display a nice graphical user interface, display
-some information about the module distribution to be installed taken
-from the metadata in the setup script, let the user select a few
-options, and start or cancel the installation.
-
-Since the metadata is taken from the setup script, creating Windows
-installers is usually as easy as running:
-
-\begin{verbatim}
-python setup.py bdist_wininst
-\end{verbatim}
-
-or the \command{bdist} command with the \longprogramopt{formats} option:
-
-\begin{verbatim}
-python setup.py bdist --formats=wininst
-\end{verbatim}
-
-If you have a pure module distribution (only containing pure Python
-modules and packages), the resulting installer will be version
-independent and have a name like \file{foo-1.0.win32.exe}.  These
-installers can even be created on \UNIX{} or MacOS platforms.
-
-If you have a non-pure distribution, the extensions can only be
-created on a Windows platform, and will be Python version dependent.
-The installer filename will reflect this and now has the form
-\file{foo-1.0.win32-py2.0.exe}.  You have to create a separate installer
-for every Python version you want to support.
-
-The installer will try to compile pure modules into bytecode after
-installation on the target system in normal and optimizing mode.  If
-you don't want this to happen for some reason, you can run the
-\command{bdist_wininst} command with the
-\longprogramopt{no-target-compile} and/or the
-\longprogramopt{no-target-optimize} option.
-
-By default the installer will display the cool ``Python Powered'' logo
-when it is run, but you can also supply your own bitmap which must be
-a Windows \file{.bmp} file with the \longprogramopt{bitmap} option.
-
-The installer will also display a large title on the desktop
-background window when it is run, which is constructed from the name
-of your distribution and the version number.  This can be changed to
-another text by using the \longprogramopt{title} option.
-
-The installer file will be written to the ``distribution directory''
---- normally \file{dist/}, but customizable with the
-\longprogramopt{dist-dir} option.
-
-\subsubsection{The Postinstallation script}
-\label{postinstallation-script}
-
-Starting with Python 2.3, a postinstallation script can be specified
-which the \longprogramopt{install-script} option.  The basename of the
-script must be specified, and the script filename must also be listed
-in the scripts argument to the setup function.
-
-This script will be run at installation time on the target system
-after all the files have been copied, with argv[1] set to '-install',
-and again at uninstallation time before the files are removed with argv[1]
-set to '-remove'.
-
-The installation script runs embedded in the windows installer, every
-output (sys.stdout, sys.stderr) is redirected into a buffer and will
-be displayed in the GUI after the script has finished.
-
-Some functions especially useful in this context are available in the
-installation script.
-
-\begin{verbatim}
-dir_created(pathname)
-file_created(pathname)
-\end{verbatim}
-
-These functions should be called when a directory or file is created
-by the postinstall script at installation time.  It will register the
-pathname with the uninstaller, so that it will be removed when the
-distribution is uninstalled.  To be safe, directories are only removed
-if they are empty.
-
-\begin{verbatim}
-get_special_folder_path(csidl_string)
-\end{verbatim}
-
-This function can be used to retrieve special folder locations on
-Windows like the Start Menu or the Desktop.  It returns the full path
-to the folder.  'csidl_string' must be one of the following strings:
-
-\begin{verbatim}
-"CSIDL_APPDATA"
-
-"CSIDL_COMMON_STARTMENU"
-"CSIDL_STARTMENU"
-
-"CSIDL_COMMON_DESKTOPDIRECTORY"
-"CSIDL_DESKTOPDIRECTORY"
-
-"CSIDL_COMMON_STARTUP"
-"CSIDL_STARTUP"
-
-"CSIDL_COMMON_PROGRAMS"
-"CSIDL_PROGRAMS"
-
-"CSIDL_FONTS"
-\end{verbatim}
-
-If the folder cannot be retrieved, OSError is raised.
-
-Which folders are available depends on the exact Windows version, and probably
-also the configuration. For details refer to Microsoft's documentation of the
-\code{SHGetSpecialFolderPath} function.
-
-\begin{verbatim}
-create_shortcut(target, description, filename[, arguments[,
-                workdir[, iconpath[, iconindex]]]])
-\end{verbatim}
-
-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{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.
-\var{iconpath} is the file containing the icon for the shortcut,
-and \var{iconindex} is the index of the icon in the file
-\var{iconpath}.  Again, for details consult the Microsoft
-documentation for the \code{IShellLink} interface.
-
-\section{Registering with the Package Index}
-\label{package-index}
-
-The Python Package Index (PyPI) holds meta-data describing distributions
-packaged with distutils. The distutils command \command{register} is
-used to submit your distribution's meta-data to the index. It is invoked
-as follows:
-
-\begin{verbatim}
-python setup.py register
-\end{verbatim}
-
-Distutils will respond with the following prompt:
-
-\begin{verbatim}
-running register
-We need to know who you are, so please choose either:
- 1. use your existing login,
- 2. register as a new user,
- 3. have the server generate a new password for you (and email it to you), or
- 4. quit
-Your selection [default 1]:
-\end{verbatim}
-
-\noindent Note: if your username and password are saved locally, you will
-not see this menu.
-
-If you have not registered with PyPI, then you will need to do so now. You
-should choose option 2, and enter your details as required. Soon after
-submitting your details, you will receive an email which will be used to
-confirm your registration.
-
-Once you are registered, you may choose option 1 from the menu. You will
-be prompted for your PyPI username and password, and \command{register}
-will then submit your meta-data to the index.
-
-You may submit any number of versions of your distribution to the index. If
-you alter the meta-data for a particular version, you may submit it again
-and the index will be updated.
-
-PyPI holds a record for each (name, version) combination submitted. The
-first user to submit information for a given name is designated the Owner
-of that name. They may submit changes through the \command{register}
-command or through the web interface. They may also designate other users
-as Owners or Maintainers. Maintainers may edit the package information, but
-not designate other Owners or Maintainers.
-
-By default PyPI will list all versions of a given package. To hide certain
-versions, the Hidden property should be set to yes. This must be edited
-through the web interface.
-
-
-
-\section{Examples}
-\label{examples}
-  
-\subsection{Pure Python distribution (by module)}
-\label{pure-mod}
-
-If you're just distributing a couple of modules, especially if they
-don't live in a particular package, you can specify them individually
-using the \option{py\_modules} option in the setup script.
-
-In the simplest case, you'll have two files to worry about: a setup
-script and the single module you're distributing, \file{foo.py} in this
-example:
-\begin{verbatim}
-<root>/
-        setup.py
-        foo.py
-\end{verbatim}
-(In all diagrams in this section, \verb|<root>| will refer to the
-distribution root directory.)  A minimal setup script to describe this
-situation would be:
-\begin{verbatim}
-from distutils.core import setup
-setup(name = "foo", version = "1.0",
-      py_modules = ["foo"])
-\end{verbatim}
-Note that the name of the distribution is specified independently with
-the \option{name} option, and there's no rule that says it has to be the
-same as the name of the sole module in the distribution (although that's
-probably a good convention to follow).  However, the distribution name
-is used to generate filenames, so you should stick to letters, digits,
-underscores, and hyphens.
-
-Since \option{py\_modules} is a list, you can of course specify multiple 
-modules, eg. if you're distributing modules \module{foo} and
-\module{bar}, your setup might look like this:
-\begin{verbatim}
-<root>/
-        setup.py
-        foo.py
-        bar.py
-\end{verbatim}
-and the setup script might be
-\begin{verbatim}
-from distutils.core import setup
-setup(name = "foobar", version = "1.0",
-      py_modules = ["foo", "bar"])
-\end{verbatim}
-
-You can put module source files into another directory, but if you have
-enough modules to do that, it's probably easier to specify modules by
-package rather than listing them individually.
-
-
-\subsection{Pure Python distribution (by package)}
-\label{pure-pkg}
-
-If you have more than a couple of modules to distribute, especially if
-they are in multiple packages, it's probably easier to specify whole
-packages rather than individual modules.  This works even if your
-modules are not in a package; you can just tell the Distutils to process
-modules from the root package, and that works the same as any other
-package (except that you don't have to have an \file{\_\_init\_\_.py}
-file).
-
-The setup script from the last example could also be written as
-\begin{verbatim}
-from distutils.core import setup
-setup(name = "foobar", version = "1.0",
-      packages = [""])
-\end{verbatim}
-(The empty string stands for the root package.)
-
-If those two files are moved into a subdirectory, but remain in the root
-package, e.g.:
-\begin{verbatim}
-<root>/
-        setup.py
-        src/      foo.py
-                  bar.py
-\end{verbatim}
-then you would still specify the root package, but you have to tell the
-Distutils where source files in the root package live:
-\begin{verbatim}
-from distutils.core import setup
-setup(name = "foobar", version = "1.0",
-      package_dir = {"": "src"},
-      packages = [""])
-\end{verbatim}
-
-More typically, though, you will want to distribute multiple modules in
-the same package (or in sub-packages).  For example, if the \module{foo} 
-and \module{bar} modules belong in package \module{foobar}, one way to
-layout your source tree is
-\begin{verbatim}
-<root>/
-        setup.py
-        foobar/
-                 __init__.py
-                 foo.py
-                 bar.py
-\end{verbatim}
-This is in fact the default layout expected by the Distutils, and the
-one that requires the least work to describe in your setup script:
-\begin{verbatim}
-from distutils.core import setup
-setup(name = "foobar", version = "1.0",
-      packages = ["foobar"])
-\end{verbatim}
-
-If you want to put modules in directories not named for their package,
-then you need to use the \option{package\_dir} option again.  For
-example, if the \file{src} directory holds modules in the
-\module{foobar} package:
-\begin{verbatim}
-<root>/
-        setup.py
-        src/
-                 __init__.py
-                 foo.py
-                 bar.py
-\end{verbatim}
-an appropriate setup script would be
-\begin{verbatim}
-from distutils.core import setup
-setup(name = "foobar", version = "1.0",
-      package_dir = {"foobar" : "src"},
-      packages = ["foobar"])
-\end{verbatim}
-
-Or, you might put modules from your main package right in the
-distribution root:
-\begin{verbatim}
-<root>/
-        setup.py
-        __init__.py
-        foo.py
-        bar.py
-\end{verbatim}
-in which case your setup script would be
-\begin{verbatim}
-from distutils.core import setup
-setup(name = "foobar", version = "1.0",
-      package_dir = {"foobar" : ""},
-      packages = ["foobar"])
-\end{verbatim}
-(The empty string also stands for the current directory.)
-
-If you have sub-packages, they must be explicitly listed in
-\option{packages}, but any entries in \option{package\_dir}
-automatically extend to sub-packages.  (In other words, the Distutils
-does \emph{not} scan your source tree, trying to figure out which
-directories correspond to Python packages by looking for
-\file{\_\_init\_\_.py} files.)  Thus, if the default layout grows a
-sub-package:
-\begin{verbatim}
-<root>/
-        setup.py
-        foobar/
-                 __init__.py
-                 foo.py
-                 bar.py
-                 subfoo/
-                           __init__.py
-                           blah.py
-\end{verbatim}
-then the corresponding setup script would be
-\begin{verbatim}
-from distutils.core import setup
-setup(name = "foobar", version = "1.0",
-      packages = ["foobar", "foobar.subfoo"])
-\end{verbatim}
-(Again, the empty string in \option{package\_dir} stands for the current
-directory.)
-
-
-\subsection{Single extension module}
-\label{single-ext}
-
-Extension modules are specified using the \option{ext\_modules} option.
-\option{package\_dir} has no effect on where extension source files are
-found; it only affects the source for pure Python modules.  The simplest 
-case, a single extension module in a single C source file, is:
-\begin{verbatim}
-<root>/
-        setup.py
-        foo.c
-\end{verbatim}
-If the \module{foo} extension belongs in the root package, the setup
-script for this could be
-\begin{verbatim}
-from distutils.core import setup
-setup(name = "foobar", version = "1.0",
-      ext_modules = [Extension("foo", ["foo.c"])])
-\end{verbatim}
-
-If the extension actually belongs in a package, say \module{foopkg},
-then 
-
-With exactly the same source tree layout, this extension can be put in
-the \module{foopkg} package simply by changing the name of the
-extension:
-\begin{verbatim}
-from distutils.core import setup
-setup(name = "foobar", version = "1.0",
-      ext_modules = [Extension("foopkg.foo", ["foo.c"])])
-\end{verbatim}
-
-
-%\subsection{Multiple extension modules}
-%\label{multiple-ext}
-
-
-%\subsection{Putting it all together}
-
-
-%\section{Extending the Distutils}
-%\label{extending}
-
-
-%\subsection{Extending existing commands}
-%\label{extend-existing}
-
-
-%\subsection{Writing new commands}
-%\label{new-commands}
-
-%\XXX{Would an uninstall command be a good example here?}
-
-
-
-\section{Reference}
-\label{reference}
-
-
-%\subsection{Building modules: the \protect\command{build} command family}
-%\label{build-cmds}
-
-%\subsubsection{\protect\command{build}}
-%\label{build-cmd}
-
-%\subsubsection{\protect\command{build\_py}}
-%\label{build-py-cmd}
-
-%\subsubsection{\protect\command{build\_ext}}
-%\label{build-ext-cmd}
-
-%\subsubsection{\protect\command{build\_clib}}
-%\label{build-clib-cmd}
-
-
-\subsection{Installing modules: the \protect\command{install} command family}
-\label{install-cmd}
-
-The install command ensures that the build commands have been run and then
-runs the subcommands \command{install\_lib},
-\command{install\_data} and
-\command{install\_scripts}.
-
-%\subsubsection{\protect\command{install\_lib}}
-%\label{install-lib-cmd}
-
-\subsubsection{\protect\command{install\_data}}
-\label{install-data-cmd}
-This command installs all data files provided with the distribution.
-
-\subsubsection{\protect\command{install\_scripts}}
-\label{install-scripts-cmd}
-This command installs all (Python) scripts in the distribution.
-
-
-%\subsection{Cleaning up: the \protect\command{clean} command}
-%\label{clean-cmd}
-
-
-\subsection{Creating a source distribution: the
-            \protect\command{sdist} command}
-\label{sdist-cmd}
-
-
-\XXX{fragment moved down from above: needs context!}
-
-The manifest template commands are:
-\begin{tableii}{ll}{command}{Command}{Description}
-  \lineii{include \var{pat1} \var{pat2} ... }
-    {include all files matching any of the listed patterns}
-  \lineii{exclude \var{pat1} \var{pat2} ... }
-    {exclude all files matching any of the listed patterns}
-  \lineii{recursive-include \var{dir} \var{pat1} \var{pat2} ... }
-    {include all files under \var{dir} matching any of the listed patterns}
-  \lineii{recursive-exclude \var{dir} \var{pat1} \var{pat2} ...}
-    {exclude all files under \var{dir} matching any of the listed patterns}
-  \lineii{global-include \var{pat1} \var{pat2} ...}
-    {include all files anywhere in the source tree matching\\&
-     any of the listed patterns}
-  \lineii{global-exclude \var{pat1} \var{pat2} ...}
-    {exclude all files anywhere in the source tree matching\\&
-     any of the listed patterns}
-  \lineii{prune \var{dir}}{exclude all files under \var{dir}}
-  \lineii{graft \var{dir}}{include all files under \var{dir}}
-\end{tableii}
-The patterns here are \UNIX-style ``glob'' patterns: \code{*} matches any
-sequence of regular filename characters, \code{?} matches any single
-regular filename character, and \code{[\var{range}]} matches any of the
-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 MacOS anything except colon.
-
-\XXX{Windows and MacOS support not there yet}
-
-
-%\subsection{Creating a built distribution: the
-%  \protect\command{bdist} command family}
-%\label{bdist-cmds}
-
-
-%\subsubsection{\protect\command{bdist}}
-
-%\subsubsection{\protect\command{bdist\_dumb}}
-
-%\subsubsection{\protect\command{bdist\_rpm}}
-
-%\subsubsection{\protect\command{bdist\_wininst}}
-
-
-\input{sysconfig}
-
-
-\end{document}

Doc/dist/sysconfig.tex

-\section{\module{distutils.sysconfig} ---
-         System configuration information}
-
-\declaremodule{standard}{distutils.sysconfig}
-\modulesynopsis{Low-level access to configuration information of the
-                Python interpreter.}
-\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-\moduleauthor{Greg Ward}{gward@python.net}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-The \module{distutils.sysconfig} module provides access to Python's
-low-level configuration information.  The specific configuration
-variables available depend heavily on the platform and configuration.
-The specific variables depend on the build process for the specific
-version of Python being run; the variables are those found in the
-\file{Makefile} and configuration header that are installed with
-Python on \UNIX{} systems.  The configuration header is called
-\file{pyconfig.h} for Python versions starting with 2.2, and
-\file{config.h} for earlier versions of Python.
-
-Some additional functions are provided which perform some useful
-manipulations for other parts of the \module{distutils} package.
-
-
-\begin{datadesc}{PREFIX}
-  The result of \code{os.path.normpath(sys.prefix)}.
-\end{datadesc}
-
-\begin{datadesc}{EXEC_PREFIX}
-  The result of \code{os.path.normpath(sys.exec_prefix)}.
-\end{datadesc}
-
-\begin{funcdesc}{get_config_var}{name}
-  Return the value of a single variable.  This is equivalent to
-  \code{get_config_vars().get(\var{name})}.
-\end{funcdesc}
-
-\begin{funcdesc}{get_config_vars}{\moreargs}
-  Return a set of variable definitions.  If there are no arguments,
-  this returns a dictionary mapping names of configuration variables
-  to values.  If arguments are provided, they should be strings, and
-  the return value will be a sequence giving the associated values.
-  If a given name does not have a corresponding value, \code{None}
-  will be included for that variable.
-\end{funcdesc}
-
-\begin{funcdesc}{get_config_h_filename}{}
-  Return the full path name of the configuration header.  For \UNIX,
-  this will be the header generated by the \program{configure} script;
-  for other platforms the header will have been supplied directly by
-  the Python source distribution.  The file is a platform-specific
-  text file.
-\end{funcdesc}
-
-\begin{funcdesc}{get_makefile_filename}{}
-  Return the full path name of the \file{Makefile} used to build
-  Python.  For \UNIX, this will be a file generated by the
-  \program{configure} script; the meaning for other platforms will
-  vary.  The file is a platform-specific text file, if it exists.
-  This function is only useful on \POSIX{} platforms.
-\end{funcdesc}
-
-\begin{funcdesc}{get_python_inc}{\optional{plat_specific\optional{, prefix}}}
-  Return the directory for either the general or platform-dependent C
-  include files.  If \var{plat_specific} is true, the
-  platform-dependent include directory is returned; if false or
-  omitted, the platform-independent directory is returned.  If
-  \var{prefix} is given, it is used as either the prefix instead of
-  \constant{PREFIX}, or as the exec-prefix instead of
-  \constant{EXEC_PREFIX} if \var{plat_specific} is true.
-\end{funcdesc}
-
-\begin{funcdesc}{get_python_lib}{\optional{plat_specific\optional{,
-                                 standard_lib\optional{, prefix}}}}
-  Return the directory for either the general or platform-dependent
-  library installation.  If \var{plat_specific} is true, the
-  platform-dependent include directory is returned; if false or
-  omitted, the platform-independent directory is returned.  If
-  \var{prefix} is given, it is used as either the prefix instead of
-  \constant{PREFIX}, or as the exec-prefix instead of
-  \constant{EXEC_PREFIX} if \var{plat_specific} is true.  If
-  \var{standard_lib} is true, the directory for the standard library
-  is returned rather than the directory for the installation of
-  third-party extensions.
-\end{funcdesc}
-
-
-The following function is only intended for use within the
-\module{distutils} package.
-
-\begin{funcdesc}{customize_compiler}{compiler}
-  Do any platform-specific customization of a
-  \class{distutils.ccompiler.CCompiler} instance.
-
-  This function is only needed on \UNIX{} at this time, but should be
-  called consistently to support forward-compatibility.  It inserts
-  the information that varies across \UNIX{} flavors and is stored in
-  Python's \file{Makefile}.  This information includes the selected
-  compiler, compiler and linker options, and the extension used by the
-  linker for shared objects.
-\end{funcdesc}
-
-
-This function is even more special-purpose, and should only be used
-from Python's own build procedures.
-
-\begin{funcdesc}{set_python_build}{}
-  Inform the \module{distutils.sysconfig} module that it is being used
-  as part of the build process for Python.  This changes a lot of
-  relative locations for files, allowing them to be located in the
-  build area rather than in an installed Python.
-\end{funcdesc}

Doc/doc/doc.tex

-\documentclass{howto}
-\usepackage{ltxmarkup}
-
-\title{Documenting Python}
-
-\makeindex
-
-\input{boilerplate}
-
-% Now override the stuff that includes author information;
-% Guido did *not* write this one!
-
-\author{Fred L. Drake, Jr.}
-\authoraddress{
-        PythonLabs \\
-        Email: \email{fdrake@acm.org}
-}
-
-
-\begin{document}
-
-\maketitle
-
-\begin{abstract}
-\noindent
-The Python language has a substantial body of
-documentation, much of it contributed by various authors.  The markup
-used for the Python documentation is based on \LaTeX{} and requires a
-significant set of macros written specifically for documenting Python.
-This document describes the macros introduced to support Python
-documentation and how they should be used to support a wide range of
-output formats.
-
-This document describes the document classes and special markup used
-in the Python documentation.  Authors may use this guide, in
-conjunction with the template files provided with the
-distribution, to create or maintain whole documents or sections.
-\end{abstract}
-
-\tableofcontents
-
-
-\section{Introduction \label{intro}}
-
-  Python's documentation has long been considered to be good for a
-  free programming language.  There are a number of reasons for this,
-  the most important being the early commitment of Python's creator,
-  Guido van Rossum, to providing documentation on the language and its
-  libraries, and the continuing involvement of the user community in
-  providing assistance for creating and maintaining documentation.
-
-  The involvement of the community takes many forms, from authoring to
-  bug reports to just plain complaining when the documentation could
-  be more complete or easier to use.  All of these forms of input from
-  the community have proved useful during the time I've been involved
-  in maintaining the documentation.
-
-  This document is aimed at authors and potential authors of
-  documentation for Python.  More specifically, it is for people
-  contributing to the standard documentation and developing additional
-  documents using the same tools as the standard documents.  This
-  guide will be less useful for authors using the Python documentation
-  tools for topics other than Python, and less useful still for
-  authors not using the tools at all.
-
-  The material in this guide is intended to assist authors using the
-  Python documentation tools.  It includes information on the source
-  distribution of the standard documentation, a discussion of the
-  document types, reference material on the markup defined in the
-  document classes, a list of the external tools needed for processing
-  documents, and reference material on the tools provided with the
-  documentation resources.  At the end, there is also a section
-  discussing future directions for the Python documentation and where
-  to turn for more information.
-
-\section{Directory Structure \label{directories}}
-
-  The source distribution for the standard Python documentation
-  contains a large number of directories.  While third-party documents
-  do not need to be placed into this structure or need to be placed
-  within a similar structure, it can be helpful to know where to look
-  for examples and tools when developing new documents using the
-  Python documentation tools.  This section describes this directory
-  structure.
-
-  The documentation sources are usually placed within the Python
-  source distribution as the top-level directory \file{Doc/}, but
-  are not dependent on the Python source distribution in any way.
-
-  The \file{Doc/} directory contains a few files and several
-  subdirectories.  The files are mostly self-explanatory, including a
-  \file{README} and a \file{Makefile}.  The directories fall into
-  three categories:
-
-  \begin{definitions}
-    \term{Document Sources}
-        The \LaTeX{} sources for each document are placed in a
-        separate directory.  These directories are given short
-        names which vaguely indicate the document in each:
-
-        \begin{tableii}{p{.75in}|p{3in}}{filenq}{Directory}{Document Title}
-          \lineii{api/}
-            {\citetitle[../api/api.html]{The Python/C API}}
-          \lineii{dist/}
-            {\citetitle[../dist/dist.html]{Distributing Python Modules}}
-          \lineii{doc/}
-            {\citetitle[../doc/doc.html]{Documenting Python}}
-          \lineii{ext/}
-            {\citetitle[../ext/ext.html]{Extending and Embedding the Python Interpreter}}
-          \lineii{inst/}
-            {\citetitle[../inst/inst.html]{Installing Python Modules}}
-          \lineii{lib/}
-            {\citetitle[../lib/lib.html]{Python Library Reference}}
-          \lineii{mac/}
-            {\citetitle[../mac/mac.html]{Macintosh Module Reference}}
-          \lineii{ref/}
-            {\citetitle[../ref/ref.html]{Python Reference Manual}}