- Conditional documentation in installation section ("how to install a

  Python interpreter").

3 files changed, 107 insertions, 9 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index dae7cfb75..7be237db1 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -8,6 +8,12 @@ Features
   attribute should refer to an interface or a class (ala the ``for``
   attribute of the ``view`` ZCML directive).
 
+Documentation
+-------------
+
+- Conditional documentation in installation section ("how to install a
+  Python interpreter").
+
 1.0a1 (2009-06-22)
 ==================
 
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index d2065d75e..4dc130d5c 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -17,14 +17,16 @@ run under Python 3.X.
    on within your Python system in order to run the ``easy_install``
    command.
 
-.. note:: As of version 0.8.0, installation of :mod:`repoze.bfg` does
-   not require the compilation of any C code, so you do not need to
-   have development tools installed on the target machine.
+.. note:: Installation of :mod:`repoze.bfg` does not require the
+   compilation of any C code, so as long as you have a Python
+   interpreter that meets the above requirements, you do not need to
+   have development tools installed on the target machine to run
+   :mod:`repoze.bfg`.
 
 BFG is known to run properly on all popular (and even some
 less-popular) Unix-like systems such as Linux, MacOS X, and FreeBSD.
 
-``repoze.bfg`` runs on Windows systems.  However, none of its main
+:mod:`repoze.bfg` runs on Windows systems.  However, none of its main
 developers use the Windows platform.  Therefor, most of the
 platform-specific documentation (excepting this chapter) assumes
 you're using a UNIX system. If you're using a Windows system, you'll
@@ -41,6 +43,82 @@ Jython or IronPython.
    <http://lists.repoze.org/listinfo/repoze-dev>`_ if you'd like to
    contribute.
 
+If You Don't Yet Have A Python Interpreter (UNIX)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your system doesn't have a Python interpreter, and you're on UNIX,
+you can either install Python using your operating system's package
+manager *or* you can install Python from source fairly easily on any
+UNIX system that has development tools.
+
+Package Manager Method
+++++++++++++++++++++++
+
+You can use your system's "package manager" to install Python. Every
+system's package manager is slightly different, but the "flavor" of
+them is usually the same.
+
+For example, on an Ubuntu Linux system, to use the system package
+manager to install a Python 2.5 interpreter, use the following
+command:
+
+.. code-block:: bash
+
+  $ sudo apt-get install python2.5-dev
+
+Once these steps are performed, the Python interpreter will usually be
+invokable via ``python2.5`` from a shell prompt.
+
+Source Compile Method
++++++++++++++++++++++
+
+It's useful to use a Python that *isn't* the "system" Python to
+develop your software (the authors of BFG never use the system Python
+to run BFG; always a self-compiled one).  Often the "system" Python is
+compiled with options that aren't optimal for web development, or they
+have
+
+To compile software on your UNIX system, typically you need
+development tools.  Often these can be installed via the package
+manager.  For example, this works to do so on an Ubuntu Linux system:
+
+.. code-block:: bash
+
+  $ sudo apt-get install build-essential
+
+On Mac OS X, installing XCode has much the same effect.
+
+Once you've got development tools installed on your system, On the
+same system, to install a Python 2.5 interpreter from *source*, use
+the following commands:
+
+.. code-block:: bash
+
+  [chrism@vitaminf ~]$ cd ~
+  [chrism@vitaminf ~]$ mkdir tmp
+  [chrism@vitaminf ~]$ mkdir opt
+  [chrism@vitaminf ~]$ cd tmp
+  [chrism@vitaminf tmp]$ cd tmp
+  [chrism@vitaminf tmp]$ wget http://python.org/ftp/python/2.5.4/Python-2.5.4.tgz
+  [chrism@vitaminf tmp]$ tar xvzf Python-2.5.4.tgz
+  [chrism@vitaminf tmp]$ cd Python-2.5.4
+  [chrism@vitaminf Python-2.5.4]$ ./configure --prefix=$HOME/opt/Python-2.5.4
+  [chrism@vitaminf Python-2.5.4]$ make; make install
+
+Once these steps are performed, the Python interpreter will be
+invokable via ``$HOME/opt/Python-2.5.4/bin/python`` from a shell
+prompt.
+
+If You Don't Yet Have A Python Interpreter (Windows)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your Windows system doesn't have a Python interpreter, you'll need
+to install it by downloading a Python 2.4, 2.5 or 2.6-series
+interpreter executable from `<python.org
+http://python.org/download/>`_ (the files labeled "Windows
+Installer").  Once you've downloaded it, double click on the
+executable and accept the defaults during the installation process.
+
 Installing :mod:`repoze.bfg` on a UNIX System
 ---------------------------------------------
 
@@ -53,7 +131,7 @@ are not compatible with your system Python).
 To set up a virtualenv to install :mod:`repoze.bfg` within, first
 ensure that setuptools is installed.  Invoke ``import setuptools``
 within the Python interpreter you'd like to run :mod:`repoze.bfg`
-under.
+with.
 
 .. code-block:: bash
 
@@ -81,12 +159,17 @@ using the Python interpreter you want to install setuptools into.
 
 .. code-block:: bash
 
-  $ python ez_setup.py
+  $ sudo python ez_setup.py
 
 Once this command is invoked, setuptools should be installed on your
 system.  If the command fails due to permission errors, you may need
 to be the administrative user on your system to successfully invoke
-the script.
+the script.  To remediate this, you may need to do:
+
+.. code-block:: bash
+
+  $ sudo python ez_setup.py
+
 
 Installing the ``virtualenv`` Package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -102,7 +185,11 @@ into your setuptools-enabled Python interpreter, use the
 
 This command should succeed, and tell you that the virtualenv package
 is now installed.  If it fails due to permission errors, you may need
-to install it as your system's administrative user.
+to install it as your system's administrative user.  For example:
+
+.. code-block:: bash
+
+  $ sudo easy_install virtualenv
 
 Creating the Virtual Python Environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -127,6 +214,10 @@ following:
    depending on the packages you've already got installed into your
    Python's "main" site-packages dir.
 
+.. warning:: If you're on UNIX, *do not* use ``sudo`` to run the
+   ``virtualenv`` script.  It's perfectly acceptable (and desirable)
+   to create a virtualenv as a normal user.
+
 You should perform any following commands that mention a "bin"
 directory from within the ``bfgenv`` virtualenv dir.
 
diff --git a/docs/tutorials/bfgwiki2/installation.rst b/docs/tutorials/bfgwiki2/installation.rst
index 12d6bbe47..73687fff2 100644
--- a/docs/tutorials/bfgwiki2/installation.rst
+++ b/docs/tutorials/bfgwiki2/installation.rst
@@ -17,7 +17,8 @@ Windows.
 Preparation, UNIX
 -----------------
 
-#. Obtain, install, or find `Python 2.5
+#. If you don't already have a Python 2.5 interpreter installed on
+   your system, obtain, install, or find `Python 2.5
    <http://python.org/download/releases/2.5.4/>`_ for your system.
 
 #. Install latest `setuptools` into the Python you