Small documentation updates and comments about Windows install.

docs/source/config/initial_config.txt

@@ -1,244 +1,249
 .. _initial config:
 
 =========================================
 Initial configuration of your environment
 =========================================
 
 This section will help you set various things in your environment for
 your IPython sessions to be as efficient as possible. All of IPython's
 configuration information, along with several example files, is stored
 in a directory named by default $HOME/.ipython. You can change this by
 defining the environment variable IPYTHONDIR, or at runtime with the
 command line option -ipythondir.
 
 If all goes well, the first time you run IPython it should automatically create
 a user copy of the config directory for you, based on its builtin defaults. You
 can look at the files it creates to learn more about configuring the
 system. The main file you will modify to configure IPython's behavior is called
 ipythonrc (with a .ini extension under Windows), included for reference
 :ref:`here <ipythonrc>`. This file is very commented and has many variables you
 can change to suit your taste, you can find more details :ref:`here
 <customization>`. Here we discuss the basic things you will want to make sure
 things are working properly from the beginning.
 
 
 .. _accessing_help:
 
 Access to the Python help system
 ================================
 
 This is true for Python in general (not just for IPython): you should have an
 environment variable called PYTHONDOCS pointing to the directory where your
 HTML Python documentation lives. In my system it's
 :file:`/usr/share/doc/python-doc/html`, check your local details or ask your
 systems administrator.
 
 This is the directory which holds the HTML version of the Python
 manuals. Unfortunately it seems that different Linux distributions
 package these files differently, so you may have to look around a bit.
 Below I show the contents of this directory on my system for reference::
 
     [html]> ls
     about.html  dist/  icons/      lib/           python2.5.devhelp.gz  whatsnew/
     acks.html   doc/   index.html  mac/           ref/
     api/        ext/   inst/       modindex.html  tut/
 
 You should really make sure this variable is correctly set so that
 Python's pydoc-based help system works. It is a powerful and convenient
 system with full access to the Python manuals and all modules accessible
 to you.
 
 Under Windows it seems that pydoc finds the documentation automatically,
 so no extra setup appears necessary.
 
 
 Editor
 ======
 
 The %edit command (and its alias %ed) will invoke the editor set in your
 environment as EDITOR. If this variable is not set, it will default to
 vi under Linux/Unix and to notepad under Windows. You may want to set
 this variable properly and to a lightweight editor which doesn't take
 too long to start (that is, something other than a new instance of
 Emacs). This way you can edit multi-line code quickly and with the power
 of a real editor right inside IPython.
 
 If you are a dedicated Emacs user, you should set up the Emacs server so
 that new requests are handled by the original process. This means that
 almost no time is spent in handling the request (assuming an Emacs
 process is already running). For this to work, you need to set your
 EDITOR environment variable to 'emacsclient'. The code below, supplied
 by Francois Pinard, can then be used in your .emacs file to enable the
 server::
 
     (defvar server-buffer-clients)
     (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm))
       (server-start)
       (defun fp-kill-server-with-buffer-routine ()
         (and server-buffer-clients (server-done)))
       (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))
 
 You can also set the value of this editor via the commmand-line option
 '-editor' or in your ipythonrc file. This is useful if you wish to use
 specifically for IPython an editor different from your typical default
 (and for Windows users who tend to use fewer environment variables).
 
 
 Color
 =====
 
 The default IPython configuration has most bells and whistles turned on
 (they're pretty safe). But there's one that may cause problems on some
 systems: the use of color on screen for displaying information. This is
 very useful, since IPython can show prompts and exception tracebacks
 with various colors, display syntax-highlighted source code, and in
 general make it easier to visually parse information.
 
 The following terminals seem to handle the color sequences fine:
 
     * Linux main text console, KDE Konsole, Gnome Terminal, E-term,
       rxvt, xterm.
     * CDE terminal (tested under Solaris). This one boldfaces light colors.
     * (X)Emacs buffers. See the emacs_ section for more details on
       using IPython with (X)Emacs.
     * A Windows (XP/2k) command prompt with pyreadline_.
     * A Windows (XP/2k) CygWin shell. Although some users have reported
       problems; it is not clear whether there is an issue for everyone
       or only under specific configurations. If you have full color
       support under cygwin, please post to the IPython mailing list so
       this issue can be resolved for all users.
 
 .. _pyreadline: https://code.launchpad.net/pyreadline
       
 These have shown problems:
 
     * Windows command prompt in WinXP/2k logged into a Linux machine via
       telnet or ssh.
     * Windows native command prompt in WinXP/2k, without Gary Bishop's
       extensions. Once Gary's readline library is installed, the normal
       WinXP/2k command prompt works perfectly.
 
 Currently the following color schemes are available:
 
     * NoColor: uses no color escapes at all (all escapes are empty '' ''
       strings). This 'scheme' is thus fully safe to use in any terminal.
     * Linux: works well in Linux console type environments: dark
       background with light fonts. It uses bright colors for
       information, so it is difficult to read if you have a light
       colored background.
     * LightBG: the basic colors are similar to those in the Linux scheme
       but darker. It is easy to read in terminals with light backgrounds.
 
 IPython uses colors for two main groups of things: prompts and
 tracebacks which are directly printed to the terminal, and the object
 introspection system which passes large sets of data through a pager.
 
 
 Input/Output prompts and exception tracebacks
 =============================================
 
 You can test whether the colored prompts and tracebacks work on your
 system interactively by typing '%colors Linux' at the prompt (use
 '%colors LightBG' if your terminal has a light background). If the input
 prompt shows garbage like::
 
     [0;32mIn [[1;32m1[0;32m]: [0;00m
 
 instead of (in color) something like::
 
     In [1]:
 
 this means that your terminal doesn't properly handle color escape
 sequences. You can go to a 'no color' mode by typing '%colors NoColor'.
 
 You can try using a different terminal emulator program (Emacs users,
 see below). To permanently set your color preferences, edit the file
 $HOME/.ipython/ipythonrc and set the colors option to the desired value.
 
 
 Object details (types, docstrings, source code, etc.)
 =====================================================
 
 IPython has a set of special functions for studying the objects you are working
 with, discussed in detail :ref:`here <dynamic_object_info>`. But this system
 relies on passing information which is longer than your screen through a data
 pager, such as the common Unix less and more programs. In order to be able to
 see this information in color, your pager needs to be properly configured. I
 strongly recommend using less instead of more, as it seems that more simply can
 not understand colored text correctly.
 
 In order to configure less as your default pager, do the following:
 
    1. Set the environment PAGER variable to less.
    2. Set the environment LESS variable to -r (plus any other options
       you always want to pass to less by default). This tells less to
       properly interpret control sequences, which is how color
       information is given to your terminal.
 
+For the bash shell, add to your ~/.bashrc file the lines::
+
+    export PAGER=less
+    export LESS=-r
+
 For the csh or tcsh shells, add to your ~/.cshrc file the lines::
 
     setenv PAGER less
     setenv LESS -r
 
 There is similar syntax for other Unix shells, look at your system
 documentation for details.
 
 If you are on a system which lacks proper data pagers (such as Windows),
 IPython will use a very limited builtin pager.
 
 .. _emacs:
 
 (X)Emacs configuration
 ======================
 
 Thanks to the work of Alexander Schmolck and Prabhu Ramachandran,
 currently (X)Emacs and IPython get along very well.
 
 Important note: You will need to use a recent enough version of
 python-mode.el, along with the file ipython.el. You can check that the
 version you have of python-mode.el is new enough by either looking at
 the revision number in the file itself, or asking for it in (X)Emacs via
 M-x py-version. Versions 4.68 and newer contain the necessary fixes for
 proper IPython support.
 
 The file ipython.el is included with the IPython distribution, in the
 documentation directory (where this manual resides in PDF and HTML
 formats).
 
 Once you put these files in your Emacs path, all you need in your .emacs
 file is::
 
     (require 'ipython)
 
 This should give you full support for executing code snippets via
 IPython, opening IPython as your Python shell via ``C-c !``, etc.
 
 You can customize the arguments passed to the IPython instance at startup by
 setting the ``py-python-command-args`` variable.  For example, to start always
 in ``pylab`` mode with hardcoded light-background colors, you can use::
 
     (setq py-python-command-args '("-pylab" "-colors" "LightBG"))
 
 If you happen to get garbage instead of colored prompts as described in
 the previous section, you may need to set also in your .emacs file::
 
     (setq ansi-color-for-comint-mode t)
 
 Notes:
 
     * There is one caveat you should be aware of: you must start the
       IPython shell before attempting to execute any code regions via
       ``C-c |``. Simply type C-c ! to start IPython before passing any code
       regions to the interpreter, and you shouldn't experience any
       problems.
       This is due to a bug in Python itself, which has been fixed for
       Python 2.3, but exists as of Python 2.2.2 (reported as SF bug [
       737947 ]).
     * The (X)Emacs support is maintained by Alexander Schmolck, so all
       comments/requests should be directed to him through the IPython
       mailing lists.
     * This code is still somewhat experimental so it's a bit rough
       around the edges (although in practice, it works quite well).
     * Be aware that if you customize py-python-command previously, this
       value will override what ipython.el does (because loading the
       customization variables comes later).

docs/source/install/install.txt

@@ -1,281 +1,293
 Overview
 ========
 
 This document describes the steps required to install IPython.  IPython is
 organized into a number of subpackages, each of which has its own dependencies.
 All of the subpackages come with IPython, so you don't need to download and
 install them separately.  However, to use a given subpackage, you will need to
 install all of its dependencies.
 
 
 Please let us know if you have problems installing IPython or any of its
-dependencies. IPython requires Python version 2.4 or greater.  Light testing
-has been done on version 2.6, and so far everything looks fine.  We have *not*
-yet started to port IPython to Python 3.0, where the language changes are much
-more significant.
+dependencies. Officially, IPython requires Python version 2.5 or 2.6.  We
+have *not* yet started to port IPython to Python 3.0.
 
 .. warning::
 
-	IPython will not work with Python 2.4 or below.
+    Officially, IPython supports Python versions 2.5 and 2.6.
+
+    IPython 0.10 has only been well tested with Python 2.5 and 2.6.  Parts of
+    it may work with Python 2.4, but we do not officially support Python 2.4
+    anymore.  If you need to use 2.4, you can still run IPython 0.9.
 
 Some of the installation approaches use the :mod:`setuptools` package and its
 :command:`easy_install` command line program.  In many scenarios, this provides
 the most simple method of installing IPython and its dependencies.  It is not
 required though.  More information about :mod:`setuptools` can be found on its
 website.
 
 More general information about installing Python packages can be found in
 Python's documentation at http://www.python.org/doc/.
 
 Quickstart
 ==========
 
 If you have :mod:`setuptools` installed and you are on OS X or Linux (not
 Windows), the following will download and install IPython *and* the main
 optional dependencies::
 
     $ easy_install ipython[kernel,security,test]
 
 This will get Twisted, zope.interface and Foolscap, which are needed for
 IPython's parallel computing features as well as the nose package, which will
 enable you to run IPython's test suite.  To run IPython's test suite, use the
 :command:`iptest` command::
 
     $ iptest
 
 Read on for more specific details and instructions for Windows.
 
 Installing IPython itself
 =========================
 
 Given a properly built Python, the basic interactive IPython shell will work
 with no external dependencies.  However, some Python distributions
 (particularly on Windows and OS X), don't come with a working :mod:`readline`
 module.  The IPython shell will work without :mod:`readline`, but will lack
 many features that users depend on, such as tab completion and command line
 editing.  See below for details of how to make sure you have a working
 :mod:`readline`.
 
 Installation using easy_install
 -------------------------------
 
 If you have :mod:`setuptools` installed, the easiest way of getting IPython is
 to simple use :command:`easy_install`::
 
 	$ easy_install ipython
 
 That's it.
 
 Installation from source
 ------------------------
 
 If you don't want to use :command:`easy_install`, or don't have it installed,
 just grab the latest stable build of IPython from `here
 <http://ipython.scipy.org/dist/>`_.  Then do the following::
 
 	$ tar -xzf ipython.tar.gz
 	$ cd ipython
 	$ python setup.py install
 
 If you are installing to a location (like ``/usr/local``) that requires higher
 permissions, you may need to run the last command with :command:`sudo`.
 
 Windows
 -------
 
 There are a few caveats for Windows users.  The main issue is that a basic
 ``python setup.py install`` approach won't create ``.bat`` file or Start Menu
-shortcuts, which most users want.  To get an installation with these, there are
-two choices:
+shortcuts, which most users want.  To get an installation with these, you can
+use any of the following alternatives:
 
 1. Install using :command:`easy_install`.
 
 2. Install using our binary ``.exe`` Windows installer, which can be found at
    `here <http://ipython.scipy.org/dist/>`_
 
 3. Install from source, but using :mod:`setuptools` (``python setupegg.py
    install``).
 
+IPython by default runs in a termninal window, but the normal terminal
+application supplied by Microsoft Windows is very primitive.  You may want to
+download the excellent and free Console_ application instead, which is a far
+superior tool.  You can even configure Console to give you by default an
+IPython tab, which is very convenient to create new IPython sessions directly
+from the working terminal.
+
+.. _Console:  http://sourceforge.net/projects/console
+
+   
 Installing the development version
 ----------------------------------
 
 It is also possible to install the development version of IPython from our
 `Bazaar <http://bazaar-vcs.org/>`_ source code repository.  To do this you will
 need to have Bazaar installed on your system.  Then just do::
 
 	$ bzr branch lp:ipython
 	$ cd ipython
 	$ python setup.py install
 
 Again, this last step on Windows won't create ``.bat`` files or Start Menu
 shortcuts, so you will have to use one of the other approaches listed above.
 
 Some users want to be able to follow the development branch as it changes.  If
 you have :mod:`setuptools` installed, this is easy. Simply replace the last
 step by::
 
 	$ python setupegg.py develop
 
 This creates links in the right places and installs the command line script to
 the appropriate places.  Then, if you want to update your IPython at any time,
 just do::
 
 	$ bzr pull
 
 Basic optional dependencies
 ===========================
 
 There are a number of basic optional dependencies that most users will want to
 get.  These are:
 
 * readline (for command line editing, tab completion, etc.)
 * nose (to run the IPython test suite)
 * pexpect (to use things like irunner)
 
 If you are comfortable installing these things yourself, have at it, otherwise
 read on for more details.
 
 readline
 --------
 
 In principle, all Python distributions should come with a working
 :mod:`readline` module.  But, reality is not quite that simple.  There are two
 common situations where you won't have a working :mod:`readline` module:
 
 * If you are using the built-in Python on Mac OS X.
 
 * If you are running Windows, which doesn't have a :mod:`readline` module.
 
 On OS X, the built-in Python doesn't not have :mod:`readline` because of
 license issues.  Starting with OS X 10.5 (Leopard), Apple's built-in Python has
 a BSD-licensed not-quite-compatible readline replacement. As of IPython 0.9,
 many of the issues related to the differences between readline and libedit have
 been resolved.  For many users, libedit may be sufficient.
 
 Most users on OS X will want to get the full :mod:`readline` module.  To get a
 working :mod:`readline` module, just do (with :mod:`setuptools` installed)::
 
 	$ easy_install readline
 
 .. note:
 
     Other Python distributions on OS X (such as fink, MacPorts and the 
     official python.org binaries) already have readline installed so 
     you don't have to do this step.
 
 If needed, the readline egg can be build and installed from source (see the
 wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard).
 
 On Windows, you will need the PyReadline module. PyReadline is a separate,
 Windows only implementation of readline that uses native Windows calls through
 :mod:`ctypes`. The easiest way of installing PyReadline is you use the binary
 installer available `here <http://ipython.scipy.org/dist/>`_. The :mod:`ctypes`
 module, which comes with Python 2.5 and greater, is required by PyReadline. It
 is available for Python 2.4 at http://python.net/crew/theller/ctypes.
 
 nose
 ----
 
 To run the IPython test suite you will need the :mod:`nose` package.  Nose
 provides a great way of sniffing out and running all of the IPython tests.  The
 simplest way of getting nose, is to use :command:`easy_install`::
 
 	$ easy_install nose
 
 Another way of getting this is to do::
 
     $ easy_install ipython[test]
 
 For more installation options, see the `nose website
 <http://somethingaboutorange.com/mrl/projects/nose/>`_.  Once you have nose
 installed, you can run IPython's test suite using the iptest command::
 
 	$ iptest
 
 
 pexpect
 -------
 
 The `pexpect <http://www.noah.org/wiki/Pexpect>`_ package is used in IPython's
 :command:`irunner` script.  On Unix platforms (including OS X), just do::
 
 	$ easy_install pexpect
 
 Windows users are out of luck as pexpect does not run there.
 
 Dependencies for IPython.kernel (parallel computing)
 ====================================================
 
 The IPython kernel provides a nice architecture for parallel computing.  The
 main focus of this architecture is on interactive parallel computing.  These
 features require a number of additional packages:
 
 * zope.interface (yep, we use interfaces)
 * Twisted (asynchronous networking framework)
 * Foolscap (a nice, secure network protocol)
 * pyOpenSSL (security for network connections)
 
 On a Unix style platform (including OS X), if you want to use :mod:`setuptools`, you can just do::
 
     $ easy_install ipython[kernel]    # the first three
     $ easy_install ipython[security]  # pyOpenSSL
 
 zope.interface and Twisted
 --------------------------
 
 Twisted [Twisted]_ and zope.interface [ZopeInterface]_ are used for networking
 related things. On Unix style platforms (including OS X), the simplest way of
 getting the these is to use :command:`easy_install`::
 
 	$ easy_install zope.interface
 	$ easy_install Twisted
 
 Of course, you can also download the source tarballs from the `Twisted website
 <twistedmatrix.org>`_ and the `zope.interface page at PyPI
 <http://pypi.python.org/pypi/zope.interface>`_ and do the usual ``python
 setup.py install`` if you prefer.
 
 Windows is a bit different.  For zope.interface and Twisted, simply get the latest binary ``.exe`` installer from the Twisted website.  This installer includes both zope.interface and Twisted and should just work.
 
 Foolscap
 --------
 
 Foolscap [Foolscap]_ uses Twisted to provide a very nice secure RPC protocol that we use to implement our parallel computing features.
 
 On all platforms a simple::
 
     $ easy_install foolscap
 
 should work.  You can also download the source tarballs from the `Foolscap
 website <http://foolscap.lothar.com/trac>`_ and do ``python setup.py install``
 if you prefer.
 
 pyOpenSSL
 ---------
 
 IPython requires an older version of pyOpenSSL [pyOpenSSL]_ (0.6 rather than
 the current 0.7).  There are a couple of options for getting this:
 
 1.  Most Linux distributions have packages for pyOpenSSL.
 2.  The built-in Python 2.5 on OS X 10.5 already has it installed.
 3.  There are source tarballs on the pyOpenSSL website.  On Unix-like
     platforms, these can be built using ``python seutp.py install``.
 4.  There is also a binary ``.exe`` Windows installer on the `pyOpenSSL website <http://pyopenssl.sourceforge.net/>`_.
 
 Dependencies for IPython.frontend (the IPython GUI)
 ===================================================
 
 wxPython
 --------
 
 Starting with IPython 0.9, IPython has a new IPython.frontend package that has
 a nice wxPython based IPython GUI.  As you would expect, this GUI requires
 wxPython.  Most Linux distributions have wxPython packages available and the
 built-in Python on OS X comes with wxPython preinstalled.  For Windows, a
 binary installer is available on the `wxPython website
 <http://www.wxpython.org/>`_.
 
 .. [Twisted] Twisted matrix.  http://twistedmatrix.org
 .. [ZopeInterface] http://pypi.python.org/pypi/zope.interface
 .. [Foolscap] Foolscap network protocol.  http://foolscap.lothar.com/trac
 .. [pyOpenSSL] pyOpenSSL.  http://pyopenssl.sourceforge.net