Documentation updates.

- Add info about the  development workflow and Launchpad, major edits
to various docs.
- As I went, updated various files to remove hard tabs, update source
listings to bash highlighting, etc.

docs/source/development/development.txt

@@ -1,446 +1,549 b''
 .. _development:
 
 ==============================
 IPython development guidelines
 ==============================
 
 
 Overview
 ========
 
-IPython is the next generation of IPython.  It is named such for two reasons:
-
-- Eventually, IPython will become IPython version 1.0.
-- This new code base needs to be able to co-exist with the existing IPython until
-  it is a full replacement for it.  Thus we needed a different name.  We couldn't
-  use ``ipython`` (lowercase) as some files systems are case insensitive.
-
-There are two, no three, main goals of the IPython effort:
+Currently, IPython's development tree contains all of the code that used to be
+part of IPython since the project's inception in 2001, plus all of the effort
+that was known for a while (roughly 2004-2008) as `IPython1'.  The IPyhton1
+development was meant to be an effort to:
 
 1. Clean up the existing codebase and write lots of tests.
-2. Separate the core functionality of IPython from the terminal to enable IPython
-   to be used from within a variety of GUI applications.
+
+2. Separate the core functionality of IPython from the terminal to enable
+   IPython to be used from within a variety of GUI applications.
+   
 3. Implement a system for interactive parallel computing.
 
 While the third goal may seem a bit unrelated to the main focus of IPython, it
 turns out that the technologies required for this goal are nearly identical
 with those required for goal two. This is the main reason the interactive
 parallel computing capabilities are being put into IPython proper. Currently
 the third of these goals is furthest along.
 
 This document describes IPython from the perspective of developers.  
 
 
 Project organization
 ====================
 
 Subpackages
 -----------
 
 IPython is organized into semi self-contained subpackages.  Each of the
 subpackages will have its own:
 
 - **Dependencies**.  One of the most important things to keep in mind in
   partitioning code amongst subpackages, is that they should be used to cleanly
   encapsulate dependencies.
   
 - **Tests**.  Each subpackage shoud have its own ``tests`` subdirectory that
   contains all of the tests for that package.  For information about writing
   tests for IPython, see the `Testing System`_ section of this document.
   
 - **Configuration**.  Each subpackage should have its own ``config``
   subdirectory that contains the configuration information for the components
   of the subpackage.  For information about how the IPython configuration
   system works, see the `Configuration System`_ section of this document.
   
 - **Scripts**.  Each subpackage should have its own ``scripts`` subdirectory
   that contains all of the command line scripts associated with the subpackage.
 
+  
 Installation and dependencies
 -----------------------------
    
 IPython will not use `setuptools`_ for installation. Instead, we will use
 standard ``setup.py`` scripts that use `distutils`_. While there are a number a
 extremely nice features that `setuptools`_ has (like namespace packages), the
 current implementation of `setuptools`_ has performance problems, particularly
 on shared file systems. In particular, when Python packages are installed on
 NSF file systems, import times become much too long (up towards 10 seconds).
 
 Because IPython is being used extensively in the context of high performance
 computing, where performance is critical but shared file systems are common, we
 feel these performance hits are not acceptable. Thus, until the performance
 problems associated with `setuptools`_ are addressed, we will stick with plain
 `distutils`_. We are hopeful that these problems will be addressed and that we
 will eventually begin using `setuptools`_. Because of this, we are trying to
 organize IPython in a way that will make the eventual transition to
 `setuptools`_ as painless as possible.
 
 Because we will be using `distutils`_, there will be no method for
 automatically installing dependencies.  Instead, we are following the approach
 of `Matplotlib`_ which can be summarized as follows:
 
 - Distinguish between required and optional dependencies.  However, the required
   dependencies for IPython should be only the Python standard library.
   
 - Upon installation check to see which optional dependencies are present and
   tell the user which parts of IPython need which optional dependencies.
 
 It is absolutely critical that each subpackage of IPython has a clearly
 specified set of dependencies and that dependencies are not carelessly
 inherited from other IPython subpackages. Furthermore, tests that have certain
 dependencies should not fail if those dependencies are not present. Instead
 they should be skipped and print a message.
 
 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
 .. _distutils: http://docs.python.org/lib/module-distutils.html
 .. _Matplotlib: http://matplotlib.sourceforge.net/
 
 Specific subpackages
 --------------------
 
 ``core``
     This is the core functionality of IPython that is independent of the
     terminal, network and GUIs.  Most of the code that is in the current
     IPython trunk will be refactored, cleaned up and moved here.
 
 ``kernel``
     The enables the IPython core to be expose to a the network.  This is
     also where all of the parallel computing capabilities are to be found.
     
 ``config``
     The configuration package used by IPython.
 
 ``frontends``
     The various frontends for IPython.  A frontend is the end-user application
     that exposes the capabilities of IPython to the user.  The most basic
     frontend will simply be a terminal based application that looks just like
     today 's IPython.  Other frontends will likely be more powerful and based
     on GUI toolkits.
 
 ``notebook``
     An application that allows users to work with IPython notebooks.
 
 ``tools``
     This is where general utilities go.
 
 
 Version control
 ===============
 
-In the past, IPython development has been done using `Subversion`__.  Recently,
-we made the transition to using `Bazaar`__ and `Launchpad`__.  This makes it
-much easier for people to contribute code to IPython.  Here is a sketch of how
-to use Bazaar for IPython development.  First, you should install Bazaar.
-After you have done that, make sure that it is working by getting the latest
-main branch of IPython::
+All IPython development today is done using the `Bazaar`__ system for
+distributed version control and the `Launchpad`__ site for code hosting and bug
+tracking.  This makes it very easy for anyone to contribute code to IPython.
 
-    $ bzr branch lp:ipython
+.. __: http://bazaar-vcs.org
+.. __: http://launchpad.net/ipython
 
-Now you can create a new branch for you to do your work in::
+If you are interested in contributing to IPython, you should familiarize a bit
+with how to use bazaar, but this document gives you a concise set of steps to
+get started.  If you are going to become heavily involved with creating code
+for IPython you'll eventually want to have a Launchpad account (free) so you
+can publish your own code on the site for review and merging, but small
+contributions can be simply sent via email to the IPython list as patches.
 
-    $ bzr branch ipython ipython-mybranch
+Start by creating what Bazaar calls a `shared repository`_:
 
-The typical work cycle in this branch will be to make changes in
-``ipython-mybranch`` and then commit those changes using the commit command::
+.. sourcecode:: bash
 
-    $ ...do work in ipython-mybranch...
-    $ bzr ci -m "the commit message goes here"
+    # You can choose any name you want instead of "ipython-repo"
+    bzr init-repo ipython-repo
 
-Please note that since we now don't use an old-style linear ChangeLog (that
-tends to cause problems with distributed version control systems), you should
-ensure that your log messages are reasonably detailed.  Use a docstring-like
-approach in the commit messages (including the second line being left
-*blank*)::
+.. _shared repository: http://bazaar-vcs.org/SharedRepositoryTutorial
 
-  Single line summary of  changes being committed.
+This creates an empty repository where a lot of related branches can be kept,
+and they all reuse common storage.  This way, many operations are very fast and
+take up less space.  Now, go to the newly created repository and make a local
+branch of the public trunk:
 
-  - more details when warranted ...
-  - including crediting outside contributors if they sent the
-    code/bug/idea!
+.. sourcecode:: bash
 
-If we couple this with a policy of making single commits for each reasonably
-atomic change, the bzr log should give an excellent view of the project, and
-the `--short` log option becomes a nice summary.
+    cd ipython-repo
+    # This makes a local copy of the public trunk called "trunk-lp"
+    bzr branch lp:ipython trunk-lp
+
+The ``trunk-lp`` branch is meant to always be a pristine copy of the public
+trunk.  From here, make a personal development copy of the public trunk, where
+you'll make your changes:
+
+.. sourcecode:: bash
 
-While working with this branch, it is a good idea to merge in changes that have
-been made upstream in the parent branch.  This can be done by doing::
+    bzr branch trunk-lp trunk-dev
 
-    $ bzr pull
+Now, your working area looks like this::
     
-If this command shows that the branches have diverged, then you should do a
-merge instead::
+    maqroll[ipython-repo]> ls -a
+    ./  ../  .bzr/  trunk-dev/  trunk-lp/
+
+The ``.bzr`` directory is the Bazaar storage area, and you now have both the
+reference copy of the public trunk and one working copy for your own
+development.  You can later make further branches as needed (a common workflow
+is to make branches to contain specific feature implementations until they are
+ready to be merged).
+    
+The typical work cycle will be to make changes in ``trunk-dev`` and then commit
+those changes as often as needed:
 
-    $ bzr merge lp:ipython
+.. sourcecode:: bash
 
-If you want others to be able to see your branch, you can create an account
-with launchpad and push the branch to your own workspace::
+    cd trunk-dev
+    # ... implement cool new feature...
+    bzr commit -m "Commit message goes here."
 
-    $ bzr push bzr+ssh://<me>@bazaar.launchpad.net/~<me>/+junk/ipython-mybranch
+Please note that since we now don't use an old-style linear ChangeLog (that
+tends to cause problems with distributed version control systems), you should
+ensure that your log messages are reasonably detailed.  For non-trivial
+changes, use a docstring-like approach in the commit messages (including the
+second line being left *blank*).  Type ``bzr commit`` *without* the ``-m``
+switch, and Bazaar will open an editor where you can type a more detailed
+message::
 
-Finally, once the work in your branch is done, you can merge your changes back
-into the `ipython` branch by using merge::
+    Single line summary of changes being committed.
 
-    $ cd ipython
-    $ merge ../ipython-mybranch
-    [resolve any conflicts]
-    $ bzr ci -m "Fixing that bug"
-    $ bzr push
+    - more details when warranted ...
+    - including crediting outside contributors if they sent the
+      code/bug/idea!
 
-But this will require you to have write permissions to the `ipython` branch.
-It you don't you can tell one of the IPython devs about your branch and they
-can do the merge for you.
+If we couple this with a policy of making single commits for each reasonably
+atomic change, the bzr log should give an excellent view of the project, and
+the ``--short`` log option becomes a nice summary.
 
-More information about Bazaar workflows can be found `here`__.
+As you work on the branch, it's a good idea to frequently keep your copy of the
+trunk updated with respect to Launchpad.  This is done via:
 
-.. __: http://subversion.tigris.org/
-.. __: http://bazaar-vcs.org/
-.. __: http://www.launchpad.net/ipython
-.. __: http://doc.bazaar-vcs.org/bzr.dev/en/user-guide/index.html
+.. sourcecode:: bash
 
-Documentation
-=============
+    cd trunk-lp
+    bzr pull
 
-Standalone documentation
-------------------------
+Bazaar can then merge any changes that were done to the public trunk into your
+local branch via:
 
-All standalone documentation should be written in plain text (``.txt``) files
-using `reStructuredText`_ for markup and formatting. All such documentation
-should be placed in the top level directory ``docs`` of the IPython source
-tree. Or, when appropriate, a suitably named subdirectory should be used. The
-documentation in this location will serve as the main source for IPython
-documentation and all existing documentation should be converted to this
-format.
+.. sourcecode:: bash
 
-In the future, the text files in the ``docs`` directory will be used to
-generate all forms of documentation for IPython. This include documentation on
-the IPython website as well as *pdf* documentation.
+    cd trunk-dev
+    bzr merge ../trunk-lp
+    bzr commit -m"Merged upstream changes"
 
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+This workflow ensures that a local copy stays in sync with the public trunk,
+while allowing for local development to be pushed back for public review.
 
-Docstring format
-----------------
+Once your changes are ready for review, you can push them to Launchpad where
+the IPython team can review them and give you feedback.  The first time, use:
 
-Good docstrings are very important. All new code will use `Epydoc`_ for
-generating API docs, so we will follow the `Epydoc`_ conventions. More
-specifically, we will use `reStructuredText`_ for markup and formatting, since
-it is understood by a wide variety of tools. This means that if in the future
-we have any reason to change from `Epydoc`_ to something else, we'll have fewer
-transition pains.
+.. sourcecode:: bash
 
-Details about using `reStructuredText`_ for docstrings can be found `here
-<http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
+    bzr push --remember bzr+ssh://<you>@bazaar.launchpad.net/~<you>/ipython/trunk-dev
 
-.. _Epydoc: http://epydoc.sourceforge.net/
+where ``<you>`` is your Launchpad user name. This will make this branch
+publicly visible to all.  In subsequent uses you can simply run in the branch:
 
-Additional PEPs of interest regarding documentation of code:
+.. sourcecode:: bash
 
-- `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_
-- `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
-- `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
+    bzr push
+
+.. note::
+
+    Before you can push your code to Launchpad, you need to configure your SSH
+    keys.  You can do this by clicking on ``Change details`` for your profile
+    and then clicking on the ``SSH Keys`` tab.  This should take you to a URL
+    of the form ``https://launchpad.net/~<you>/+editsshkeys`` with instructions
+    on how to upload your keys.
+    
+Once the branch is publicly visible, using the launchpad interface it can be
+marked for merging with the link ``Propose for merging into another branch``,
+leaving the default choice of trunk as its target.  This way, Launchpad tracks
+what changes of this branch are new with respect to the trunk, others in the
+team can review it, and merge the changes into the trunk.
+
+The IPython team has a policy of reviewing all code (both from core members of
+the team and from external contributors) before merging it.  Code should be
+clearly documented (as explained further in this guide), clear and well tested.
+We will be happy to provide you with feedback for your code to be a great
+contribution to the project, and we've found that peer review of code is an
+excellent way to improve the quality of everyone's work.
 
 
 Coding conventions
 ==================
 
 General
 -------
 
 In general, we'll try to follow the standard Python style conventions as
 described here:
 
 - `Style Guide for Python Code  <http://www.python.org/peps/pep-0008.html>`_  
 
 
 Other comments:
 
 - In a large file, top level classes and functions should be 
   separated by 2-3 lines to make it easier to separate them visually.
 - Use 4 spaces for indentation.
 - Keep the ordering of methods the same in classes that have the same 
   methods.  This is particularly true for classes that implement 
   similar interfaces and for interfaces that are similar.
 
 Naming conventions
 ------------------
 
 In terms of naming conventions, we'll follow the guidelines from the `Style
 Guide for Python Code`_.
 
 For all new IPython code (and much existing code is being refactored), we'll use:
 
 - All ``lowercase`` module names.
 
 - ``CamelCase`` for class names.
 
 - ``lowercase_with_underscores`` for methods, functions, variables and
   attributes.
 
 This may be confusing as most of the existing IPython codebase uses a different
 convention (``lowerCamelCase`` for methods and attributes).  Slowly, we will
 move IPython over to the new convention, providing shadow names for backward
 compatibility in public interfaces.
 
 There are, however, some important exceptions to these rules.  In some cases,
 IPython code will interface with packages (Twisted, Wx, Qt) that use other
 conventions.  At some level this makes it impossible to adhere to our own
 standards at all times.  In particular, when subclassing classes that use other
 naming conventions, you must follow their naming conventions.  To deal with
 cases like this, we propose the following policy:
 
 - If you are subclassing a class that uses different conventions, use its
   naming conventions throughout your subclass.  Thus, if you are creating a
   Twisted Protocol class, used Twisted's
   ``namingSchemeForMethodsAndAttributes.``
 
 - All IPython's official interfaces should use our conventions.  In some cases
   this will mean that you need to provide shadow names (first implement
   ``fooBar`` and then ``foo_bar = fooBar``).  We want to avoid this at all
   costs, but it will probably be necessary at times.  But, please use this
   sparingly!
 
 Implementation-specific *private* methods will use
 ``_single_underscore_prefix``.  Names with a leading double underscore will
 *only* be used in special cases, as they makes subclassing difficult (such
 names are not easily seen by child classes).
 
 Occasionally some run-in lowercase names are used, but mostly for very short
 names or where we are implementing methods very similar to existing ones in a
 base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had
 established precedent).
 
 The old IPython codebase has a big mix of classes and modules prefixed with an
 explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned
 upon, as namespaces offer cleaner prefixing. The only case where this approach
 is justified is for classes which are expected to be imported into external
 namespaces and a very generic name (like Shell) is too likely to clash with
 something else. We'll need to revisit this issue as we clean up and refactor
 the code, but in general we should remove as many unnecessary ``IP``/``ip``
 prefixes as possible. However, if a prefix seems absolutely necessary the more
 specific ``IPY`` or ``ipy`` are preferred.
 
+
+Documentation
+=============
+
+Standalone documentation
+------------------------
+
+All standalone documentation should be written in plain text (``.txt``) files
+using `reStructuredText`_ for markup and formatting. All such documentation
+should be placed in the top level directory ``docs`` of the IPython source
+tree. Or, when appropriate, a suitably named subdirectory should be used. The
+documentation in this location will serve as the main source for IPython
+documentation and all existing documentation should be converted to this
+format.
+
+In the future, the text files in the ``docs`` directory will be used to
+generate all forms of documentation for IPython. This include documentation on
+the IPython website as well as *pdf* documentation.
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+
+A bit of shell code:
+
+.. sourcecode:: bash
+
+    cd /tmp
+    echo "My home directory is: $HOME"
+    ls
+
+A bit of Python code:
+
+.. sourcecode:: python
+
+    for i in range(10):
+        print i,
+    print "A big number:",2**34
+
+An interactive Python session:
+
+.. sourcecode:: python
+
+    >>> from IPython import genutils
+    >>> genutils.get_ipython_dir()
+    '/home/fperez/.ipython'
+
+
+An IPython session:
+
+.. sourcecode:: ipython
+
+  In [8]: import IPython
+
+  In [9]: print "This IPython is version:",IPython.__version__
+  This IPython is version: 0.9.1
+
+
+
+Docstring format
+----------------
+
+Good docstrings are very important. All new code will use `Epydoc`_ for
+generating API docs, so we will follow the `Epydoc`_ conventions. More
+specifically, we will use `reStructuredText`_ for markup and formatting, since
+it is understood by a wide variety of tools. This means that if in the future
+we have any reason to change from `Epydoc`_ to something else, we'll have fewer
+transition pains.
+
+Details about using `reStructuredText`_ for docstrings can be found `here
+<http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
+
+.. _Epydoc: http://epydoc.sourceforge.net/
+
+Additional PEPs of interest regarding documentation of code:
+
+- `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_
+- `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
+- `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
+
+
+
 .. _devel_testing:
 
 Testing system
 ==============
 
 It is extremely important that all code contributed to IPython has tests. Tests
 should be written as unittests, doctests or as entities that the `Nose`_
 testing package will find. Regardless of how the tests are written, we will use
 `Nose`_ for discovering and running the tests. `Nose`_ will be required to run
 the IPython test suite, but will not be required to simply use IPython.
 
 .. _Nose: http://code.google.com/p/python-nose/
 
 Tests of `Twisted`__ using code should be written by subclassing the
 ``TestCase`` class that comes with ``twisted.trial.unittest``. When this is
 done, `Nose`_ will be able to run the tests and the twisted reactor will be
 handled correctly.
 
 .. __: http://www.twistedmatrix.com
 
 Each subpackage in IPython should have its own ``tests`` directory that
 contains all of the tests for that subpackage. This allows each subpackage to
 be self-contained. If a subpackage has any dependencies beyond the Python
 standard library, the tests for that subpackage should be skipped if the
 dependencies are not found. This is very important so users don't get tests
 failing simply because they don't have dependencies.
 
 We also need to look into use Noses ability to tag tests to allow a more
 modular approach of running tests.
 
 .. _devel_config:
 
 Configuration system
 ====================
 
 IPython uses `.ini`_ files for configuration purposes. This represents a huge
 improvement over the configuration system used in IPython. IPython works with
 these files using the `ConfigObj`_ package, which IPython includes as
 ``ipython1/external/configobj.py``.
 
 Currently, we are using raw `ConfigObj`_ objects themselves. Each subpackage of
 IPython should contain a ``config`` subdirectory that contains all of the
 configuration information for the subpackage. To see how configuration
 information is defined (along with defaults) see at the examples in
 ``ipython1/kernel/config`` and ``ipython1/core/config``. Likewise, to see how
 the configuration information is used, see examples in
 ``ipython1/kernel/scripts/ipengine.py``.
 
 Eventually, we will add a new layer on top of the raw `ConfigObj`_ objects. We
 are calling this new layer, ``tconfig``, as it will use a `Traits`_-like
 validation model.  We won't actually use `Traits`_, but will implement
 something similar in pure Python.  But, even in this new system, we will still
 use `ConfigObj`_ and `.ini`_ files underneath the hood. Talk to Fernando if you
 are interested in working on this part of IPython. The current prototype of
 ``tconfig`` is located in the IPython sandbox.
 
 .. _.ini: http://docs.python.org/lib/module-ConfigParser.html
 .. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
 .. _Traits: http://code.enthought.com/traits/
 
 
 Installation and testing scenarios
 ==================================
 
 This section outlines the various scenarios that we need to test before we
 release an IPython version.  These scenarios represent different ways of
 installing IPython and its dependencies.
 
 Installation scenarios under Linux and OS X
 -------------------------------------------
 
     1.  Install from tarball using ``python setup.py install``.
         a.  With only readline+nose dependencies installed.
         b.  With all dependencies installed (readline, zope.interface, Twisted,
         foolscap, Sphinx, nose, pyOpenSSL).
 	    
     2.  Install using easy_install.
 
         a.  With only readline+nose dependencies installed.
             i.  Default dependencies: ``easy_install ipython-0.9.beta3-py2.5.egg``
             ii. Optional dependency sets: ``easy_install -f ipython-0.9.beta3-py2.5.egg IPython[kernel,doc,test,security]``
 
         b.  With all dependencies already installed.
 	
 
 Installation scenarios under Win32
 ----------------------------------
 
 	1.  Install everything from .exe installers
 	2.  easy_install?
 
 
 Tests to run for these scenarios
 --------------------------------
 
     1.  Run the full test suite.
     2.  Start a controller and engines and try a few things by hand.
         a.  Using ipcluster.
         b.  Using ipcontroller/ipengine by hand.
 
     3.  Run a few of the parallel examples.
     4.  Try the kernel with and without security with and without PyOpenSSL
         installed.
     5.  Beat on the IPython terminal a bunch.
     6.  Make sure that furl files are being put in proper locations.
 
 
 Release checklist
 =================
 
 Most of the release process is automated by the :file:`release` script in the
 :file:`tools` directory.  This is just a handy reminder for the release manager.
 
 #. Run the release script, which makes the tar.gz, eggs and Win32 .exe
    installer.  It posts them to the site and registers the release with PyPI.
 
 #. Updating the website with announcements and links to the updated changes.txt
    in html form.  Remember to put a short note both on the news page of the site
    and on launcphad.
 
 #. Drafting a short release announcement with i) highlights and ii) a link to
    the html changes.txt.
 
 #. Make sure that the released version of the docs is live on the site.
 
 #. Celebrate!

docs/source/install/index.txt

@@ -1,10 +1,10 b''
 .. _install_index:
 
-==================
+============
 Installation
-==================
+============
 
 .. toctree::
    :maxdepth: 2
 
    install.txt

docs/source/install/install.txt

@@ -1,191 +1,300 b''
 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.  
+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.  We have not tested
-IPython with the upcoming 2.6 or 3.0 versions.
+dependencies. IPython requires Python version 2.4 or greater.  We have not
+tested IPython with the upcoming 2.6 or 3.0 versions, though preliminary
+reports of 2.6 usage are encouraging.  3.0 porting will take longer, however.
 
 .. warning::
 
-	IPython will not work with Python 2.3 or below.
+    IPython will not work with Python 2.3 or below.
 
-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.
+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/.
 
-More general information about installing Python packages can be found in Python's documentation at http://www.python.org/doc/.
 
 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`.
+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`::
+If you have :mod:`setuptools` installed, the easiest way of getting IPython is
+to use :command:`easy_install`:
+
+.. sourcecode:: bash
+
+    easy_install IPython
+
+Unless you've written a custom distutils script as explained here_, that will
+try to install either in a default system-wide location, which may require
+administrator access.  If that is the case, you can either run the command with
+root privileges:
+
+.. sourcecode:: bash
+
+    sudo easy_install IPython
+
+or you can specify an alternate location, for example:
 
-	$ easy_install IPython
+.. sourcecode:: bash
+
+    easy_install --prefix=~/usr/local IPython
+
+where this assumes that ``~/usr/local`` is a valid prefix for you to install
+packages to in your user account.
+
+.. _here: http://docs.python.org/install/index.html#inst-config-files
 
-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::
+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 (using the
+appropriate version number):
 
-	$ tar -xzf ipython.tar.gz
-	$ cd ipython
-	$ python setup.py install
+.. sourcecode:: bash
 
-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`.
+    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:
 
 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``).
 
 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::
+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::
+
+    .. sourcecode:: bash
 
-	$ bzr branch lp:ipython
-	$ cd ipython
-	$ python setup.py install
+    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::
+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:
+
+.. sourcecode:: bash
 
-	$ python setupegg.py develop
+    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::
+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
+.. sourcecode:: bash
+
+    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.
+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):
 
-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)::
+.. sourcecode:: bash
 
-	$ easy_install readline
+    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).
+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.
+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`::
+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`:
+
+.. sourcecode:: bash
 
-	$ easy_install nose
+    easy_install nose
 
-Another way of getting this is to do::
+Another way of getting this is to do:
 
-    $ easy_install IPython[test]
+.. sourcecode:: bash
 
-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::
+    easy_install IPython[test]
 
-	$ iptest
+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:
+
+.. sourcecode:: bash
+
+    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::
+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:
+
+.. sourcecode:: bash
 
-	$ easy_install pexpect
+    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:
+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::
+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
+.. sourcecode:: bash
+
+    easy_install IPython[kernel]    # the first three
+    easy_install IPython[security]  # pyOpenSSL
 
 zope.interface and Twisted
 --------------------------
 
-On Unix style platforms (including OS X), the simplest way of getting the these is to use :command:`easy_install`::
+On Unix style platforms (including OS X), the simplest way of getting the these
+is to use :command:`easy_install`:
+
+.. sourcecode:: bash
 
-	$ easy_install zope.interface
-	$ easy_install Twisted
+    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.
+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.
+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 uses Twisted to provide a very nice secure RPC protocol that we use to implement our parallel computing features.
+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:
 
-On all platforms a simple::
+.. sourcecode:: bash
 
-    $ easy_install foolscap
+    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.
+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 (0.6 rather than the current 0.7).  There are a couple of options for getting this:
+IPython requires an older version of 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``.
 
-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/>`_.
+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/>`_. 
  No newline at end of file
+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/>`_.
  No newline at end of file

docs/source/overview.txt

@@ -1,233 +1,232 b''
 .. _overview:
 
 ============
 Introduction
 ============
 
 Overview
 ========
 
 One of Python's most useful features is its interactive interpreter.
 This system allows very fast testing of ideas without the overhead of
 creating test files as is typical in most programming languages.
 However, the interpreter supplied with the standard Python distribution
 is somewhat limited for extended interactive use.
 
 The goal of IPython is to create a comprehensive environment for
 interactive and exploratory computing.  To support this goal, IPython
 has two main components:
 
 * An enhanced interactive Python shell.
 * An architecture for interactive parallel computing.
 
 All of IPython is open source (released under the revised BSD license).
 
 Enhanced interactive Python shell
 =================================
 
 IPython's interactive shell (:command:`ipython`), has the following goals,
 amongst others:
 
 1. Provide an interactive shell superior to Python's default. IPython
    has many features for object introspection, system shell access,
    and its own special command system for adding functionality when
    working interactively. It tries to be a very efficient environment
    both for Python code development and for exploration of problems
    using Python objects (in situations like data analysis).
   
 2. Serve as an embeddable, ready to use interpreter for your own
    programs. IPython can be started with a single call from inside
    another program, providing access to the current namespace. This
    can be very useful both for debugging purposes and for situations
    where a blend of batch-processing and interactive exploration are
    needed.  New in the 0.9 version of IPython is a reusable wxPython
    based IPython widget.
   
 3. Offer a flexible framework which can be used as the base
    environment for other systems with Python as the underlying
    language. Specifically scientific environments like Mathematica,
    IDL and Matlab inspired its design, but similar ideas can be
    useful in many fields.
   
 4. Allow interactive testing of threaded graphical toolkits. IPython
    has support for interactive, non-blocking control of GTK, Qt and
    WX applications via special threading flags. The normal Python
    shell can only do this for Tkinter applications.
 
 Main features of the interactive shell
 --------------------------------------
 
 * Dynamic object introspection. One can access docstrings, function
   definition prototypes, source code, source files and other details
   of any object accessible to the interpreter with a single
   keystroke (:samp:`?`, and using :samp:`??` provides additional detail).
   
 * Searching through modules and namespaces with :samp:`*` wildcards, both
   when using the :samp:`?` system and via the :samp:`%psearch` command.
 
 * Completion in the local namespace, by typing :kbd:`TAB` at the prompt.
   This works for keywords, modules, methods, variables and files in the
   current directory. This is supported via the readline library, and
   full access to configuring readline's behavior is provided. 
   Custom completers can be implemented easily for different purposes
   (system commands, magic arguments etc.)
 
 * Numbered input/output prompts with command history (persistent
   across sessions and tied to each profile), full searching in this
   history and caching of all input and output.
 
 * User-extensible 'magic' commands. A set of commands prefixed with
   :samp:`%` is available for controlling IPython itself and provides
   directory control, namespace information and many aliases to
   common system shell commands.
 
 * Alias facility for defining your own system aliases.
 
 * Complete system shell access. Lines starting with :samp:`!` are passed
   directly to the system shell, and using :samp:`!!` or :samp:`var = !cmd` 
   captures shell output into python variables for further use.
 
 * Background execution of Python commands in a separate thread.
   IPython has an internal job manager called jobs, and a
   convenience backgrounding magic function called :samp:`%bg`.
 
-* The ability to expand python variables when calling the system
-  shell. In a shell command, any python variable prefixed with :samp:`$` is
-  expanded. A double :samp:`$$` allows passing a literal :samp:`$` to the shell (for
-  access to shell and environment variables like :envvar:`PATH`).
+* The ability to expand python variables when calling the system shell. In a
+  shell command, any python variable prefixed with :samp:`$` is expanded. A
+  double :samp:`$$` allows passing a literal :samp:`$` to the shell (for access
+  to shell and environment variables like :envvar:`PATH`).
 
 * Filesystem navigation, via a magic :samp:`%cd` command, along with a
   persistent bookmark system (using :samp:`%bookmark`) for fast access to
   frequently visited directories.
 
 * A lightweight persistence framework via the :samp:`%store` command, which
   allows you to save arbitrary Python variables. These get restored
   automatically when your session restarts.
 
 * Automatic indentation (optional) of code as you type (through the
   readline library).
 
 * Macro system for quickly re-executing multiple lines of previous
   input with a single name. Macros can be stored persistently via
   :samp:`%store` and edited via :samp:`%edit`.
 
 * Session logging (you can then later use these logs as code in your
   programs). Logs can optionally timestamp all input, and also store
   session output (marked as comments, so the log remains valid
   Python source code).
 
 * Session restoring: logs can be replayed to restore a previous
   session to the state where you left it.
 
 * Verbose and colored exception traceback printouts. Easier to parse
   visually, and in verbose mode they produce a lot of useful
   debugging information (basically a terminal version of the cgitb
   module).
 
 * Auto-parentheses: callable objects can be executed without
   parentheses: :samp:`sin 3` is automatically converted to :samp:`sin(3)`.
 
 * Auto-quoting: using :samp:`,`, or :samp:`;` as the first character forces
   auto-quoting of the rest of the line: :samp:`,my_function a b` becomes
   automatically :samp:`my_function("a","b")`, while :samp:`;my_function a b`
   becomes :samp:`my_function("a b")`.
 
 * Extensible input syntax. You can define filters that pre-process
   user input to simplify input in special situations. This allows
   for example pasting multi-line code fragments which start with
   :samp:`>>>` or :samp:`...` such as those from other python sessions or the
   standard Python documentation.
 
 * Flexible configuration system. It uses a configuration file which
   allows permanent setting of all command-line options, module
   loading, code and file execution. The system allows recursive file
   inclusion, so you can have a base file with defaults and layers
   which load other customizations for particular projects.
 
 * Embeddable. You can call IPython as a python shell inside your own
   python programs. This can be used both for debugging code or for
   providing interactive abilities to your programs with knowledge
   about the local namespaces (very useful in debugging and data
   analysis situations).
 
-* Easy debugger access. You can set IPython to call up an enhanced
-  version of the Python debugger (pdb) every time there is an
-  uncaught exception. This drops you inside the code which triggered
-  the exception with all the data live and it is possible to
-  navigate the stack to rapidly isolate the source of a bug. The
-  :samp:`%run` magic command (with the :samp:`-d` option) can run any script under
-  pdb's control, automatically setting initial breakpoints for you.
-  This version of pdb has IPython-specific improvements, including
-  tab-completion and traceback coloring support. For even easier
-  debugger access, try :samp:`%debug` after seeing an exception. winpdb is 
-  also supported, see ipy_winpdb extension.
+* Easy debugger access. You can set IPython to call up an enhanced version of
+  the Python debugger (pdb) every time there is an uncaught exception. This
+  drops you inside the code which triggered the exception with all the data
+  live and it is possible to navigate the stack to rapidly isolate the source
+  of a bug. The :samp:`%run` magic command (with the :samp:`-d` option) can run
+  any script under pdb's control, automatically setting initial breakpoints for
+  you.  This version of pdb has IPython-specific improvements, including
+  tab-completion and traceback coloring support. For even easier debugger
+  access, try :samp:`%debug` after seeing an exception. winpdb is also
+  supported, see ipy_winpdb extension.
 
 * Profiler support. You can run single statements (similar to
   :samp:`profile.run()`) or complete programs under the profiler's control.
   While this is possible with standard cProfile or profile modules,
   IPython wraps this functionality with magic commands (see :samp:`%prun`
   and :samp:`%run -p`) convenient for rapid interactive work.
 
 * Doctest support. The special :samp:`%doctest_mode` command toggles a mode
   that allows you to paste existing doctests (with leading :samp:`>>>`
   prompts and whitespace) and uses doctest-compatible prompts and
   output, so you can use IPython sessions as doctest code.
 
 Interactive parallel computing
 ==============================
 
-Increasingly, parallel computer hardware, such as multicore CPUs, clusters and supercomputers, is becoming ubiquitous. Over the last 3 years, we have developed an
-architecture within IPython that allows such hardware to be used quickly and easily
-from Python. Moreover, this architecture is designed to support interactive and
-collaborative parallel computing.
+Increasingly, parallel computer hardware, such as multicore CPUs, clusters and
+supercomputers, is becoming ubiquitous. Over the last 3 years, we have
+developed an architecture within IPython that allows such hardware to be used
+quickly and easily from Python. Moreover, this architecture is designed to
+support interactive and collaborative parallel computing.
 
 The main features of this system are:
 
 * Quickly parallelize Python code from an interactive Python/IPython session.
 
 * A flexible and dynamic process model that be deployed on anything from 
   multicore workstations to supercomputers.
 
 * An architecture that supports many different styles of parallelism, from
   message passing to task farming.  And all of these styles can be handled
   interactively.
 
 * Both blocking and fully asynchronous interfaces.
 
 * High level APIs that enable many things to be parallelized in a few lines
   of code.
 
 * Write parallel code that will run unchanged on everything from multicore
   workstations to supercomputers.
 
 * Full integration with Message Passing libraries (MPI).
 
 * Capabilities based security model with full encryption of network connections.
 
-* Share live parallel jobs with other users securely.  We call this collaborative
-  parallel computing.
+* Share live parallel jobs with other users securely.  We call this
+  collaborative parallel computing.
 
 * Dynamically load balanced task farming system.
 
 * Robust error handling.  Python exceptions raised in parallel execution are
   gathered and presented to the top-level code.
 
-For more information, see our :ref:`overview <parallel_index>` of using IPython for
-parallel computing.
+For more information, see our :ref:`overview <parallel_index>` of using IPython
+for parallel computing.
 
 Portability and Python requirements
 -----------------------------------
 
 As of the 0.9 release, IPython requires Python 2.4 or greater.  We have
 not begun to test IPython on Python 2.6 or 3.0, but we expect it will
 work with some minor changes.
 
 IPython is known to work on the following operating systems:
 
 	* Linux
-	* AIX
-	* Most other Unix-like OSs (Solaris, BSD, etc.)
+	* Most other Unix-like OSs (AIX, Solaris, BSD, etc.)
 	* Mac OS X
 	* Windows (CygWin, XP, Vista, etc.)
 
 See :ref:`here <install_index>` for instructions on how to install IPython.
  No newline at end of file

docs/source/parallel/index.txt

@@ -1,14 +1,14 b''
 .. _parallel_index:
 
 ====================================
 Using IPython for parallel computing
 ====================================
 
 .. toctree::
    :maxdepth: 2
 
    parallel_intro.txt
    parallel_multiengine.txt
    parallel_task.txt
    parallel_mpi.txt
-
+   visionhpc.txt