Minor tweaks to catch up with the current code in a few spots.

Wrote the "Distutils Configuration Files" section.

1 files changed, 147 insertions, 16 deletions

diff --git a/Doc/inst/inst.tex b/Doc/inst/inst.tex
index 6578496..fab4d2a 100644
--- a/Doc/inst/inst.tex
+++ b/Doc/inst/inst.tex
@@ -271,14 +271,14 @@ or
                temp.<plat>/
 \end{verbatim}
 where \code{<plat>} expands to a brief description of the current
-OS/hardware platform.  The first form, with just a \file{lib} directory,
-is used for ``pure module distributions''---that is, module
-distributions that include only pure Python modules.  If a module
-distribution contains any extensions (modules written in C/C++, or Java
-for JPython), then the second form, with two \code{<plat>} directories,
-is used.  In that case, the \file{temp.\filevar{plat}} directory holds
-temporary files generated by the compile/link process that don't
-actually get installed.  In either case, the \file{lib} (or
+OS/hardware platform and Python version.  The first form, with just a
+\file{lib} directory, is used for ``pure module distributions''---that
+is, module distributions that include only pure Python modules.  If a
+module distribution contains any extensions (modules written in C/C++),
+then the second form, with two \code{<plat>} directories, is used.  In
+that case, the \file{temp.\filevar{plat}} directory holds temporary
+files generated by the compile/link process that don't actually get
+installed.  In either case, the \file{lib} (or
 \file{lib.\filevar{plat}}) directory contains all Python modules (pure
 Python and extensions) that will be installed.
 
@@ -300,7 +300,7 @@ If you don't choose an installation directory---i.e., if you just run
 \code{setup.py install}---then the \command{install} command installs to
 the standard location for third-party Python modules.  This location
 varies by platform and by how you built/installed Python itself.  On
-Unix and Mac OS, it also depends on whether the module distribution
+Unix and Mac~OS, it also depends on whether the module distribution
 being installed is pure Python or contains extensions (``non-pure''):
 \begin{tableiv}{l|l|l|c}{textrm}%
   {Platform}{Standard installation location}{Default value}{Notes}
@@ -317,12 +317,12 @@ being installed is pure Python or contains extensions (``non-pure''):
           {\filenq{C:\textbackslash{}Python}}
           {(2)}
   \lineiv{Mac~OS (pure)}
-          {\filenq{\filevar{prefix}:Lib}}
-          {\filenq{Python:Lib}  \XXX{???}}
+          {\filenq{\filevar{prefix}:Lib:site-packages}}
+          {\filenq{Python:Lib:site-packages}}
           {}
   \lineiv{Mac~OS (non-pure)}
-          {\filevar{prefix}:Mac:PlugIns}
-          {\filenq{Python:Mac:PlugIns}\XXX{???}}
+          {\filenq{\filevar{prefix}:Lib:site-packages}}
+          {\filenq{Python:Lib:site-packages}}
           {}
 \end{tableiv}
 
@@ -361,9 +361,11 @@ Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
 '/usr'
 \end{verbatim}
 
-If you don't want to install to the standard location, or if you don't
-have permission to write there, then you need to read about alternate
-installations in the next section.
+If you don't want to install modules to the standard location, or if you
+don't have permission to write there, then you need to read about
+alternate installations in section~\ref{alt-install}.  If you want to
+customize your installation directories more heavily, see
+section~\ref{custom-install} on custom installations.
 
 
 % This rather nasty macro is used to generate the tables that describe
@@ -711,6 +713,135 @@ section~\ref{config-files} for details.
 \section{Distutils Configuration Files}
 \label{config-files}
 
+As mentioned above, you can use Distutils configuration files to record
+personal or site preferences for any Distutils options.  That is, any
+option to any command can be stored in one of two or three (depending on
+your platform) configuration files, which will be consulted before the
+command-line is parsed.  This means that configuration files will
+override default values, and the command-line will in turn override
+configuration files.  Furthermore, if multiple configuration files
+apply, values from ``earlier'' files are overridden by ``later'' files.
+
+
+\subsection{Location and names of config files}
+\label{sec:config-filenames}
+
+The names and locations of the configuration files vary slightly across
+platforms.  On Unix, the three configuration files (in the order they
+are processed) are:
+\begin{tableiii}{l|l|c}{textrm}
+  {Type of file}{Location and filename}{Notes}
+  \lineiii{system}{\filenq{\filevar{prefix}/lib/python\filevar{ver}/distutils/pydistutils.cfg}}{(1)}
+  \lineiii{personal}{\filenq{\$HOME/.pydistutils.cfg}}{(2)}
+  \lineiii{local}{\filenq{setup.cfg}}{(3)}
+\end{tableiii}
+
+On Windows, the configuration files are:
+\begin{tableiii}{l|l|c}{textrm}
+  {Type of file}{Location and filename}{Notes}
+  \lineiii{system}{\filenq{\filevar{prefix}\textbackslash{}Lib\textbackslash{}distutils\textbackslash{}pydistutils.cfg}}{(4)}
+  \lineiii{personal}{\filenq{\%HOME\textbackslash{}pydistutils.cfg}}{(5)}
+  \lineiii{local}{\filenq{setup.cfg}}{(3)}
+\end{tableiii}
+
+And on Mac~OS, they are:
+\begin{tableiii}{l|l|c}{textrm}
+  {Type of file}{Location and filename}{Notes}
+  \lineiii{system}{\filenq{\filevar{prefix}:Lib:distutils:pydistutils.cfg}}{(6)}
+  \lineiii{personal}{N/A}{}
+  \lineiii{local}{\filenq{setup.cfg}}{(3)}
+\end{tableiii}
+
+\noindent Notes:
+\begin{description}
+\item[(1)] Strictly speaking, the system-wide configuration file lives
+  in the directory where the Distutils are installed; under Python 1.6
+  and later on Unix, this is as shown. For Python 1.5.2, the Distutils
+  will normally be installed to
+  \file{\filevar{prefix}/lib/site-packages/python1.5/distutils},
+  so the system configuration file should be put there under Python
+  1.5.2.
+\item[(2)] On Unix, if the \envvar{HOME} environment variable is not
+  defined, the user's home directory will be determined with the
+  \function{getpwuid()} function from the standard \module{pwd} module.
+\item[(3)] I.e., in the current directory (usually the location of the
+  setup script).
+\item[(4)] (See also note (1).)  Under Python 1.6 and later, Python's
+  default ``installation prefix'' is \file{C:\textbackslash{}Python}, so
+  the system configuration file is normally
+  \file{C:\textbackslash{}Python\textbackslash{}Lib\textbackslash{}distutils\textbackslash{}pydistutils.cfg}.
+  Under Python 1.5.2, the default prefix was
+  \file{C:\textbackslash{}Program~Files\textbackslash{}Python}, and the
+  Distutils were not part of the standard library---so the system
+  configuration file would be
+  \file{C:\textbackslash{}Program~Files\textbackslash{}Python\textbackslash{}distutils\textbackslash{}pydistutils.cfg}
+  in a standard Python 1.5.2 installation under Windows.
+\item[(5)] On Windows, if the \envvar{HOME} environment variable is not
+  defined, no personal configuration file will be found or used.  (In
+  other words, the Distutils make no attempt to guess your home
+  directory on Windows.)
+\item[(6)] (See also notes (1) and (4).)  The default installation
+  prefix is just \file{Python:}, so under Python 1.6 and later this is
+  normally\file{Python:Lib:distutils:pydistutils.cfg}.  (The Distutils
+  don't work very well with Python 1.5.2 under Mac~OS.  \XXX{true?})
+\end{description}
+
+
+\subsection{Syntax of config files}
+\label{sec:config-syntax}
+
+The Distutils configuration files all have the same syntax.  The config
+files are grouped into sections; there is one section for each Distutils
+command, plus a \code{global} section for global options that affect
+every command.  Each section consists of one option per line, specified
+like \code{option=value}.
+
+For example, the following is a complete config file that just forces
+all commands to run quietly by default:
+\begin{verbatim}
+[global]
+verbose=0
+\end{verbatim}
+
+If this is installed as the system config file, it will affect all
+processing of any Python module distribution by any user on the current
+system.  If it is installed as your personal config file (on systems
+that support them), it will affect only module distributions processed
+by you.  And if it is used as the \file{setup.cfg} for a particular
+module distribution, it affects only that distribution.
+
+You could override the default ``build base'' directory and make the
+\command{build*} commands always forcibly rebuild all files with the
+following:
+\begin{verbatim}
+[build]
+build-base=blib
+force=1
+\end{verbatim}
+which corresponds to the command-line arguments
+\begin{verbatim}
+python setup.py build --build-base=blib --force
+\end{verbatim}
+except that including the \command{build} command on the command-line
+means that command will be run.  Including a particular command in
+config files has no such implication; it only means that if the command
+is run, the options in the config file will apply.  (Or if other
+commands that derive values from it are run, they will use the values in
+the config file.)
+
+You can find out the complete list of options for any command using the
+\longprogramopt{help} option, e.g.:
+\begin{verbatim}
+python setup.py build --help
+\end{verbatim}
+and you can find out the complete list of global options by using
+\longprogramopt{help} without a command:
+\begin{verbatim}
+python setup.py --help
+\end{verbatim}
+See also the ``Reference'' section of the ``Distributing Python
+Modules'' manual.
+
 
 \section{Pre-Distutils Conventions}
 \label{pre-distutils}