Commits

Anonymous committed 100c845

Fixed all the documents so that they adhere to the 80 characters per line standard.

Comments (0)

Files changed (8)

source/contributing.txt

 
 .. image:: images/pypi_screenshot.jpg
 
-Tools like :ref:`Pip <pip_info>` or `zc.buildout <http://pypi.python.org/pypi/zc.buildout>`_ are using PyPI as the default location to find :term:`distributions <distribution>` to install. When ``pip install Foo`` is called, it will browse PyPI to find the latest available version of the ``Foo`` project using `The Simple Index Protocol`_. If it finds it, it will download it and install it automatically.
+Tools like :ref:`Pip <pip_info>` or `zc.buildout
+<http://pypi.python.org/pypi/zc.buildout>`_ are using PyPI as the default
+location to find :term:`distributions <distribution>` to install. When ``pip
+install Foo`` is called, it will browse PyPI to find the latest available
+version of the ``Foo`` project using `The Simple Index Protocol`_. If it finds
+it, it will download it and install it automatically.
 
 This automatic installation ala :ref:`pip_info` will work only if the distribution is using the Distutils-based structure and contains a ``setup.py`` file.
 
 Registering projects
 --------------------
 
-Registering a project at PyPI is done by using :term:`Distutils`' ``register`` command. This command performs a simple HTTP post using basic authentication
+Registering a project at PyPI is done by using :term:`Distutils`' ``register``
+command. This command performs a simple HTTP post using basic authentication
 with the login name and password stored in the ``.pypirc`` file
 located in your home directory. This login has to be registered at PyPI, so
-you should go there and create an account before running ``register`` for the first time.
+you should go there and create an account before running ``register`` for the
+first time.
 
 Another option is to call ``register`` once on any Distutils-based project.
 It will register the new account for you and all you'll have to do is to reply
 
 A good practice is to use reST, and make sure your ``long_description``
 field doesn't contain any reStructuredText syntax error. See
-:ref:`rest_example` for a quick introduction on how to write a reST compatible field.
+:ref:`rest_example` for a quick introduction on how to write a reST compatible
+field.
 
 To perform a check, install ``docutils`` by using Pip
 (``pip install docutils``) and run::
 has started to develop strategies to avoid it:
 
 - ``zc.buildout`` comes with a cache that will keep a copy
-  of downloaded archives on the local system. This avoids getting packages at PyPI when they were
-  already downloaded once.
+  of downloaded archives on the local system. This avoids getting packages at
+  PyPI when they were already downloaded once.
 
 - the `collective.eggproxy <http://pypi.python.org/pypi/collective.eggproxy>`_
   project provides a cache server that acts like
 
 In the last year, PEP 381 was added to describe a mirroring protocol and
 set up an official "ring" of PyPI mirrors. This system should be ready
-by the end of the year 2010, and will provide a DNS entry under ``mirrors.pypi.org``
-listing all mirrors IPs. This will allow tools like :ref:`pip_info` to
-list all mirrors and pick the closest one, or fall back in case a server is
-down.
+by the end of the year 2010, and will provide a DNS entry under
+``mirrors.pypi.org`` listing all mirrors IPs. This will allow tools like
+:ref:`pip_info` to list all mirrors and pick the closest one, or fall back in
+case a server is down.
 
 .. index::
    single: package index; pypi
 Private and secondary PyPI servers
 ==================================
 
-.. note:: XXX explain here that other servers can have a pypi feature (like plone.org, or private)
+.. note:: XXX explain here that other servers can have a pypi feature (like
+   plone.org, or private)
 .. note:: XXX explain that pip can point to any pypi-like server
 .. note:: XXX conclude on the multiple-index merge idea

source/creation.txt

 Entry points
 ------------
 
-.. note:: XXX Ditch the example here and use the `parrot example <http://bitbucket.org/carljm/sample-distutils2-project/>`_, developed by Carl Meyer, to illustrate how this works.
+.. note:: XXX Ditch the example here and use the `parrot example
+<http://bitbucket.org/carljm/sample-distutils2-project/>`_, developed by Carl
+Meyer, to illustrate how this works.
 
 Entry points are a Setuptools/Distribute feature that’s really handy in one
 specific case: register something under a specific key in package A that

source/glossary.txt

 .. glossary::
 
    CPAN
-       CPAN is the Comprehensive Perl Archive Network, a large collection of :term:`Perl` software and documentation. You can begin exploring from either http://www.cpan.org/, http://www.perl.com/CPAN/ or any of the mirrors listed at http://www.cpan.org/SITES.html. [CPAN]_
+       CPAN is the Comprehensive Perl Archive Network, a large collection of
+       :term:`Perl` software and documentation. You can begin exploring from
+       either http://www.cpan.org/, http://www.perl.com/CPAN/ or any of the
+       mirrors listed at http://www.cpan.org/SITES.html. [CPAN]_
 
    Developer
        The person developing the package.
        distribution).
 
    IRC
-       Internet Relay Chat (IRC) is a form of real-time Internet text messaging (chat) or synchronous conferencing. It is mainly designed for group communication in discussion forums, called channels, but also allows one-to-one communication via private message as well as chat and data transfers via Direct Client-to-Client. [WikipediaIRC]_
+       Internet Relay Chat (IRC) is a form of real-time Internet text messaging
+       (chat) or synchronous conferencing. It is mainly designed for group
+       communication in discussion forums, called channels, but also allows
+       one-to-one communication via private message as well as chat and data
+       transfers via Direct Client-to-Client. [WikipediaIRC]_
 
    module
        A python source code file (ex. ``mymodule.py``), most often
        (e.g. Debian).
 
    Perl
-       Perl is a high-level programming language with an eclectic heritage written by Larry Wall and a cast of thousands. It derives from the ubiquitous C programming language and to a lesser extent from sed, awk, the Unix shell, and at least a dozen other tools and languages. Perl's process, file, and text manipulation facilities make it particularly well-suited for tasks involving quick prototyping, system utilities, software tools, system management tasks, database access, graphical programming, networking, and world wide web programming. These strengths make it especially popular with system administrators and CGI script authors, but mathematicians, geneticists, journalists, and even managers also use Perl. [PERL]_
+       Perl is a high-level programming language with an eclectic heritage
+       written by Larry Wall and a cast of thousands. It derives from the
+       ubiquitous C programming language and to a lesser extent from sed, awk,
+       the Unix shell, and at least a dozen other tools and languages. Perl's
+       process, file, and text manipulation facilities make it particularly
+       well-suited for tasks involving quick prototyping, system utilities,
+       software tools, system management tasks, database access, graphical
+       programming, networking, and world wide web programming. These strengths
+       make it especially popular with system administrators and CGI script
+       authors, but mathematicians, geneticists, journalists, and even managers
+       also use Perl. [PERL]_
 
    reStructuredText
        A plain text format used in many Python projects for documentation. The
        encourage and enhance the portability of Python programs by abstracting
        away platform-specifics into platform-neutral APIs. [StandardLibrary]_
 
-       .. seealso:: `Python Standard Library Documentation <http://docs.python.org/library/>`_
+       .. seealso:: `Python Standard Library Documentation
+          <http://docs.python.org/library/>`_
 
    tarball
        An archive format for collected a group of files together as one. The
 
 .. [CPAN] `What is CPAN? <http://www.cpan.org/misc/cpan-faq.html#What_is_CPAN>`_
 .. [PERL] `What is Perl? <http://www.cpan.org/misc/cpan-faq.html#What_is_Perl>`_
-.. [StandardLibrary] `Python Standard Library Documentation <http://docs.python.org/library/>`_
-.. [WikipediaIRC] `Internet Relay Chat (Wikipedia) <http://en.wikipedia.org/wiki/Internet_Relay_Chat>`_
+.. [StandardLibrary] `Python Standard Library Documentation
+   <http://docs.python.org/library/>`_
+.. [WikipediaIRC] `Internet Relay Chat (Wikipedia)
+   <http://en.wikipedia.org/wiki/Internet_Relay_Chat>`_

source/installation.txt

 Installing the Package Tools
 ============================
 
-In the :ref:`current state of packaging <state_of_packaging_info>` in Python, one needs a set of tools to easily manipulate the packaging ecosystem. There are two tools in particular that are extremely handy in the current ecosystem. There is a third tool, :doc:`virtualenv`, that will be discussed later in this documentation that will assist in isolating a packaging ecosystem from the global one. The combination of these tools will help to find, install and uninstall packages.
+In the :ref:`current state of packaging <state_of_packaging_info>` in Python,
+one needs a set of tools to easily manipulate the packaging ecosystem. There are
+two tools in particular that are extremely handy in the current ecosystem. There
+is a third tool, :doc:`virtualenv`, that will be discussed later in this
+documentation that will assist in isolating a packaging ecosystem from the
+global one. The combination of these tools will help to find, install and
+uninstall packages.
 
 .. _distribute_info:
 
 
 .. _Distribute: http://packages.python.org/distribute
 
-Distribute_ is a collection of enhancements to the Python standard library module: :mod:`distutils` (for Python 2.3.5 and up on most platforms; 64-bit platforms require a minimum of Python 2.4) that allows you to more easily build and distribute Python packages, especially ones that have dependencies on other packages.
+Distribute_ is a collection of enhancements to the Python standard library
+module: :mod:`distutils` (for Python 2.3.5 and up on most platforms; 64-bit
+platforms require a minimum of Python 2.4) that allows you to more easily build
+and distribute Python packages, especially ones that have dependencies on other
+packages.
 
-Distribute was created because the `Setuptools package <http://pypi.python.org/pypi/setuptools/>`_ is no longer maintained. Third-party packages will likely require :mod:`setuptools`, which is provided by the Distribute_ package. Therefore, anytime time a packages depends on the `Setuptools package <http://pypi.python.org/pypi/setuptools/>`_, Distribute_ will step in to say it already provides the :mod:`setuptools` module.
+Distribute was created because the `Setuptools package
+<http://pypi.python.org/pypi/setuptools/>`_ is no longer maintained. Third-party
+packages will likely require :mod:`setuptools`, which is provided by the
+Distribute_ package. Therefore, anytime time a packages depends on the
+`Setuptools package <http://pypi.python.org/pypi/setuptools/>`_, Distribute_
+will step in to say it already provides the :mod:`setuptools` module.
 
 .. seealso:: `Distribute documentation <http://packages.python.org/distribute>`_.
 
 Installation Instructions
 -------------------------
 
-Distribute_ can be installed using the `distribute_setup.py <http://python-distribute.org/distribute_setup.py>`_ script.  It can also be installed using easy_install, pip, the source tarball, or the egg distribution. `distribute_setup.py <http://python-distribute.org/distribute_setup.py>`_ is the simplest and preferred way to install Distribute on all systems.
+Distribute_ can be installed using the `distribute_setup.py
+<http://python-distribute.org/distribute_setup.py>`_ script.  It can also be
+installed using easy_install, pip, the source tarball, or the egg distribution.
+`distribute_setup.py <http://python-distribute.org/distribute_setup.py>`_ is the
+simplest and preferred way to install Distribute on all systems.
 
-Download `distribute_setup.py <http://python-distribute.org/distribute_setup.py>`_ and execute it, using the Python interpreter of your choice.
+Download `distribute_setup.py
+<http://python-distribute.org/distribute_setup.py>`_ and execute it, using the
+Python interpreter of your choice.
 
 From the \*nix shell you can do::
 
     $ wget http://python-distribute.org/distribute_setup.py
     $ python distribute_setup.py
 
-.. note:: For those on Mac OS X, you can use ``curl -O <url>`` instead of ``wget``.
+.. note:: For those on Mac OS X, you can use ``curl -O <url>`` instead of
+   ``wget``.
 
-.. seealso:: The development version of Distribute can be found at: http://bitbucket.org/tarek/distribute/
+.. seealso:: The development version of Distribute can be found at:
+   http://bitbucket.org/tarek/distribute/
 
 .. _pip_info:
 
 same techniques for finding packages, so packages that were made
 easy_installable should be pip-installable as well.
 
-.. seealso:: `Pip Documentation <http://pip.openplans.org/index.html>`_ and `Pip PyPI description <http://pypi.python.org/pypi/pip>`_
+.. seealso:: `Pip Documentation <http://pip.openplans.org/index.html>`_ and `Pip
+   PyPI description <http://pypi.python.org/pypi/pip>`_
 
 .. note:: ??? `Pip requirements <http://pip.openplans.org/#requirements-files>`_
 
 Installing Pip
 --------------
 
-The `Pip`_ installer can be installed using the source tarball or using ``easy_install``.  The source tarball is the recommended method of installation.
+The `Pip`_ installer can be installed using the source tarball or using
+``easy_install``.  The source tarball is the recommended method of installation.
 
 The latest version of the source tarball can be obtained from PyPI::
 
 
 .. Can the above be simplified?
 
-.. note:: ``pip`` is complementary with :doc:`virtualenv`, and it is encouraged that you use :doc:`virtualenv` to isolate your installation.
+.. note:: ``pip`` is complementary with :doc:`virtualenv`, and it is encouraged
+   that you use :doc:`virtualenv` to isolate your installation.
 
 Installing a package
 --------------------
 Upgrading
 ---------
 
-If you want to upgrade a package to its most recent available version, use the ``-U`` or ``--upgrade`` flag::
+If you want to upgrade a package to its most recent available version, use the
+``-U`` or ``--upgrade`` flag::
 
     $ pip install -U Markdown
 
 the Markdown package.
 
 .. Note::
-   Pip inside a :doc:`Virtual Environment <virtualenv>` will only uninstall packages installed within that virtual environment. For instance, if you try to ``pip uninstall wsgiref`` it will refuse, because the reference is within the global Python's standard library.
+   Pip inside a :doc:`Virtual Environment <virtualenv>` will only uninstall
+   packages installed within that virtual environment. For instance, if you try
+   to ``pip uninstall wsgiref`` it will refuse, because the reference is within
+   the global Python's standard library.
 
 .. _Pip: http://pip.openplans.org/
 .. _Markdown: http://pypi.python.org/pypi/Markdown

source/introduction.txt

 Discovering a Python Package
 ----------------------------
 
-Using :term:`packages <package>` in the current working directory only works for small projects in most cases. Using the working directory as a package location usually becomes a problem when distributing packages for larger systems. Therefore, :mod:`distutils` was created to **install** packages into the :envvar:`PYTHONPATH` with little difficulty. The :envvar:`PYTHONPATH`, also ``sys.path`` in code, is a list of locations to look for Python packages.  Example::
+Using :term:`packages <package>` in the current working directory only works for
+small projects in most cases. Using the working directory as a package location
+usually becomes a problem when distributing packages for larger systems.
+Therefore, :mod:`distutils` was created to **install** packages into the
+:envvar:`PYTHONPATH` with little difficulty. The :envvar:`PYTHONPATH`, also
+``sys.path`` in code, is a list of locations to look for Python packages. 
+Example::
 
    >>> import sys
    >>> sys.path
    >>> mypackage.__file__
    'mypackage/__init__.py'
 
-The first value, the null or empty string, in ``sys.path`` is the current working directory, which is what allows the packages in the current working directory to be found.
+The first value, the null or empty string, in ``sys.path`` is the current
+working directory, which is what allows the packages in the current working
+directory to be found.
 
-.. note:: Your :envvar:`PYTHONPATH` values will likely be different from those displayed.
+.. note:: Your :envvar:`PYTHONPATH` values will likely be different from those
+   displayed.
 
 Explicitly Including a Package Location
 ---------------------------------------
 
-The convention way of manually installing packages is to put them in the :file:`{...}/site-packages/` directory. But one may want to install Python modules into some arbitrary directory. For example, your site may have a convention of keeping all software related to the web server application under :file:`/www`. Add-on Python modules might then belong in :file:`/www/python{x.y}/`, and in order to import them, this directory must be added to ``sys.path``. There are several different ways to add the directory.
+The convention way of manually installing packages is to put them in the
+:file:`{...}/site-packages/` directory. But one may want to install Python
+modules into some arbitrary directory. For example, your site may have a
+convention of keeping all software related to the web server application under
+:file:`/www`. Add-on Python modules might then belong in
+:file:`/www/python{x.y}/`, and in order to import them, this directory must be
+added to ``sys.path``. There are several different ways to add the directory.
 
-.. note:: TODO Better define where the :file:`{...}/site-packages/` directory is located.
+.. note:: TODO Better define where the :file:`{...}/site-packages/` directory is
+   located.
 
 The most convenient way is to add a path configuration file to a directory
 that's already in Python's path, which could be the :file:`.../site-packages/`
 directory. Path configuration files have an extension of :file:`.pth`, and each
-line must contain a single path that will be appended to ``sys.path``. (Because the new paths are appended to ``sys.path``, modules in the added directories will not override standard modules.  This means you can't use this mechanism for installing fixed versions of standard modules.)
+line must contain a single path that will be appended to ``sys.path``. (Because
+the new paths are appended to ``sys.path``, modules in the added directories
+will not override standard modules.  This means you can't use this mechanism for
+installing fixed versions of standard modules.)
 
 Paths can be absolute or relative, in which case they're relative to the
 directory containing the :file:`.pth` file.  See the documentation of
 the :mod:`site` module for more information.
 
-In addition there are two environment variables that can modify ``sys.path``. :envvar:`PYTHONHOME` sets an alternate value for the prefix of the Python installation. For example, if :envvar:`PYTHONHOME` is set to :file:`/www/python/lib/python2.6/`, the search path will be set to ``['', '/www/python/lib/python2.6/', ...]``.
+In addition there are two environment variables that can modify ``sys.path``.
+:envvar:`PYTHONHOME` sets an alternate value for the prefix of the Python
+installation. For example, if :envvar:`PYTHONHOME` is set to
+:file:`/www/python/lib/python2.6/`, the search path will be set to ``['',
+'/www/python/lib/python2.6/', ...]``.
 
 The :envvar:`PYTHONPATH` variable can be set to a list of paths that will be
 added to the beginning of ``sys.path``.  For example, if :envvar:`PYTHONPATH` is
 set to ``/www/python:/opt/py``, the search path will begin with
 ``['', '/www/python', '/opt/py', ...]``.
 
-.. note:: Directories must exist in order to be added to ``sys.path``. The :mod:`site` module removes paths that don't exist.
+.. note:: Directories must exist in order to be added to ``sys.path``. The
+   :mod:`site` module removes paths that don't exist.
 
 Finally, ``sys.path`` is just a regular Python list, so any Python application
 can modify it by adding or removing entries.
 
-.. note:: The `zc.buildout <http://pypi.python.org/pypi/zc.buildout/>`_ package modifies the sys.path in order to include all packages relative to a buildout.  The ``zc.buildout`` package is often used to build large projects that have external build requirements.
+.. note:: The `zc.buildout <http://pypi.python.org/pypi/zc.buildout/>`_ package
+   modifies the sys.path in order to include all packages relative to a
+   buildout.  The ``zc.buildout`` package is often used to build large projects
+   that have external build requirements.
 
 Python file layout
 ------------------
 contains paths to the directories where the extra packages are
 installed.
 
-.. note:: For details on the ``.pth`` file, please refer to `modifying Python's search path <http://docs.python.org/install/index.html#inst-search-path>`_. In short, when a new package is installed using :mod:`distutils` or `one of its extenders <installation>`_, the contents of the package are dropped into the ``site-packages`` directory and then the name of the new package directory is added to a ``.pth`` file. This allows Python upon the next startup to see the new package.
+.. note:: For details on the ``.pth`` file, please refer to `modifying Python's
+   search path <http://docs.python.org/install/index.html#inst-search-path>`_.
+   In short, when a new package is installed using :mod:`distutils` or `one of
+   its extenders <installation>`_, the contents of the package are dropped into
+   the ``site-packages`` directory and then the name of the new package
+   directory is added to a ``.pth`` file. This allows Python upon the next
+   startup to see the new package.
 
 Benefits of packaging
 =====================
 
-While it's possible to unpack :term:`tarballs <tarball>` and manually put them into your Python installation directories (see `Explicitly Including a Package Location`_), using a package management system gives you some significant benefits. Here are some of the obvious ones:
+While it's possible to unpack :term:`tarballs <tarball>` and manually put them
+into your Python installation directories (see `Explicitly Including a Package
+Location`_), using a package management system gives you some significant
+benefits. Here are some of the obvious ones:
 
 - Dependency management
-      Often, the package you want to install requires that others be there. A package management system can automatically resolve dependencies and make your installation pain free and quick. This is one of the basic facilities offered by :mod:`distutils`. However, other extensions to :mod:`distutils` do a better job of installing dependencies. (see :ref:`distribute_info`)
+      Often, the package you want to install requires that others be there. A
+      package management system can automatically resolve dependencies and make
+      your installation pain free and quick. This is one of the basic facilities
+      offered by :mod:`distutils`. However, other extensions to :mod:`distutils`
+      do a better job of installing dependencies. (see :ref:`distribute_info`)
 
 - Accounting
-      Package managers can maintain lists of things installed and other metadata like the version installed etc. which makes is easy for the user to know what are the things his system has. (see :ref:`pip_info`)
+      Package managers can maintain lists of things installed and other metadata
+      like the version installed etc. which makes is easy for the user to know
+      what are the things his system has. (see :ref:`pip_info`)
 
 - Uninstall
       Package managers can give you push button ways of removing a package from your environment. (see :ref:`pip_info`)
 
 .. image:: images/state_of_packaging.jpg
 
-The :mod:`distutils` modules is part of the :term:`standard library` and will be until Python 3.3. The :mod:`distutils` module will be discontinued in Python 3.3.  The :mod:`distutils2` (note the number two) will be backwards compatible for Python 2.4 onward; and will be part of the :term:`standard library` in Python 3.3.
+The :mod:`distutils` modules is part of the :term:`standard library` and will be
+until Python 3.3. The :mod:`distutils` module will be discontinued in Python
+3.3.  The :mod:`distutils2` (note the number two) will be backwards compatible
+for Python 2.4 onward; and will be part of the :term:`standard library` in
+Python 3.3.
 
-The :mod:`distutils` module provides the basics for packaging Python. Unfortunately, the :mod:`distutils` module is riddled with problems, which is why a small group of python developers are working on :mod:`distutils2`. However, until :mod:`distutils2` is complete it is recommended that the :term:`Developer` either use pure :mod:`distutils` or the `Distribute package <distribute_info_>`_ for packaging Python software.
+The :mod:`distutils` module provides the basics for packaging Python.
+Unfortunately, the :mod:`distutils` module is riddled with problems, which is
+why a small group of python developers are working on :mod:`distutils2`.
+However, until :mod:`distutils2` is complete it is recommended that the
+:term:`Developer` either use pure :mod:`distutils` or the `Distribute package
+<distribute_info_>`_ for packaging Python software.
 
-.. see also:: For more information about the :mod:`distutils2` package, you can take a look at the :doc:`future` document.
+.. see also:: For more information about the :mod:`distutils2` package, you can
+   take a look at the :doc:`future` document.
 
-In the mean time, if a package requires the ``setuptools`` package, it is our recommendation that you install the `Distribute` package, which provides a more up to date version of ``setuptools`` than does the `original Setuptools package <http://pypi.python.org/pypi/setuptools/>`_.
+In the mean time, if a package requires the ``setuptools`` package, it is our
+recommendation that you install the `Distribute` package, which provides a more
+up to date version of ``setuptools`` than does the `original Setuptools package
+<http://pypi.python.org/pypi/setuptools/>`_.
 
-In the :doc:`future <future>` :mod:`distutils2` will replace :mod:`setuptools` and :mod:`distutils`, which will also remove the need for :ref:`Distribute <distribute_info>`. And as stated before :mod:`distutils` will be removed from the :term:`standard library`. For more information, please refer to the :doc:`future`.
+In the :doc:`future <future>` :mod:`distutils2` will replace :mod:`setuptools`
+and :mod:`distutils`, which will also remove the need for :ref:`Distribute
+<distribute_info>`. And as stated before :mod:`distutils` will be removed from
+the :term:`standard library`. For more information, please refer to the
+:doc:`future`.
 
-.. warning:: Please use the :ref:`Distribute package <distribute_info>` rather than the `Setuptools package <http://pypi.python.org/pypi/setuptools/>`_ because there are problems in this package that can and will not be fixed.
+.. warning:: Please use the :ref:`Distribute package <distribute_info>` rather
+   than the `Setuptools package <http://pypi.python.org/pypi/setuptools/>`_
+   because there are problems in this package that can and will not be fixed.
 
 Creating a Micro-Ecosystem with :mod:`virtualenv`
 =================================================
 
-Here we have a small digression to briefly discuss :doc:`Virtual Environments <virtualenv>`, which will be covered later in this guide. In most situations, the ``site-packages`` directory is part of the system Python installation and not writable by unprivileged users. Also, it's useful to have a solid reliable installation of the language which we can use. Experimental packages shouldn't be mixed with the stable ones if we want to keep this quality. In order to achieve this, most Python developers use the :doc:`virtualenv </virtualenv>` package which allows people to create a *virtual* installation of Python. This replicates the ``site-packages`` directory in an user writable area. The ``site-packages`` directory located in the :doc:`virtualenv` is in addition to the global one. While orthogonal to the whole package installation process, it's an extremely useful and natural way to work and so the whole thing will be mentioned again.  The installation and usage of ``virtualenv`` is covered in :doc:`virtualenv` document.
-
-
+Here we have a small digression to briefly discuss :doc:`Virtual Environments
+<virtualenv>`, which will be covered later in this guide. In most situations,
+the ``site-packages`` directory is part of the system Python installation and
+not writable by unprivileged users. Also, it's useful to have a solid reliable
+installation of the language which we can use. Experimental packages shouldn't
+be mixed with the stable ones if we want to keep this quality. In order to
+achieve this, most Python developers use the :doc:`virtualenv </virtualenv>`
+package which allows people to create a *virtual* installation of Python. This
+replicates the ``site-packages`` directory in an user writable area. The
+``site-packages`` directory located in the :doc:`virtualenv` is in addition to
+the global one. While orthogonal to the whole package installation process, it's
+an extremely useful and natural way to work and so the whole thing will be
+mentioned again.  The installation and usage of ``virtualenv`` is covered in
+:doc:`virtualenv` document.

source/license.txt

 License
 =======
 
-The Hitchhiker's Guide to Packaging is licensed under a Creative Commons Attribution-Noncommercial-Share Alike license: http://creativecommons.org/licenses/by-nc-sa/3.0
+The Hitchhiker's Guide to Packaging is licensed under a Creative Commons
+Attribution-Noncommercial-Share Alike license:
+http://creativecommons.org/licenses/by-nc-sa/3.0

source/quickstart.txt

 Grab Your Towel and Save the Universe
 =====================================
 
-The `Quick Start`_ is a good brief introduction, but does not cover a lot of obscure use-cases. For those wanting more, please read the :doc:`introduction` document to gain a better understanding of the :ref:`state_of_packaging_info`.
-
+The `Quick Start`_ is a good brief introduction, but does not cover a lot of
+obscure use-cases. For those wanting more, please read the :doc:`introduction`
+document to gain a better understanding of the :ref:`state_of_packaging_info`.
 Finding Packages
 ================
 
-.. note:: TODO I'm mentioning :ref:`pypi_info` everywhere. Should probably move this up in the documentation instead of explaining it over and over.
+.. note:: TODO I'm mentioning :ref:`pypi_info` everywhere. Should probably move
+   this up in the documentation instead of explaining it over and over.
 
-How does one find a package. Well, the simple answer is to check :ref:`pypi_info` first. The other options are:
+How does one find a package. Well, the simple answer is to check
+:ref:`pypi_info` first. The other options are:
 
 - To do a simple web search with google.com, yahoo, etc.
 - Ask around the python community using :term:`IRC` 
 Installing from other sources
 =============================
 
-When using the :ref:`pip_info` application, how does it know what to install when you run ``pip install Markdown``? By default, it checks the :ref:`pypi_info` for a package of that name. In this case, it found one; but what if you want to install a package that hasn't been uploaded to PyPI?
+When using the :ref:`pip_info` application, how does it know what to install
+when you run ``pip install Markdown``? By default, it checks the
+:ref:`pypi_info` for a package of that name. In this case, it found one; but
+what if you want to install a package that hasn't been uploaded to PyPI?
 
 You have several options:
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.