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

@@ -8,18 +8,16 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
@@ -56,6 +54,7 subpackages will have its own:
 - **Scripts**.  Each subpackage should have its own ``scripts`` subdirectory
   that contains all of the command line scripts associated with the subpackage.
 
+  
 Installation and dependencies
 -----------------------------
    
@@ -127,116 +126,140 Specific subpackages
 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
@@ -318,6 +341,86 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

docs/source/install/index.txt

@@ -1,8 +1,8
 .. _install_index:
 
-==================
+============
 Installation
-==================
+============
 
 .. toctree::
    :maxdepth: 2

docs/source/install/install.txt

@@ -1,45 +1,90
 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
 -------
@@ -55,22 +100,31 There are a few caveats for Windows users. The main issue is that a basic ``pyt
 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
 ===========================
@@ -92,11 +146,18 In principle, all Python distributions should come with a working :mod:`readline
 
 * 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:
 
@@ -104,83 +165,126 Most users on OS X will want to get the full :mod:`readline` module. To get a w
     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)
 ===================================================
@@ -188,4 +292,9 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

@@ -91,10 +91,10 Main features of the interactive shell
   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
@@ -150,17 +150,16 Main features of the interactive shell
   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.
@@ -176,10 +175,11 Main features of the interactive shell
 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:
 
@@ -204,16 +204,16 The main features of this system are:
 
 * 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
 -----------------------------------
@@ -225,8 +225,7 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.)
 

docs/source/parallel/index.txt

@@ -11,4 +11,4 Using IPython for parallel computing
    parallel_multiengine.txt
    parallel_task.txt
    parallel_mpi.txt
-
+   visionhpc.txt