Resolves issues with newer versions of pip not having a --use-mirrors paramater for the install command

This module supports `virtualenv_site_packages` as an option to control whether or not to include system packages when installing pip packages into a virtual environment. 

The default is no, and when you say yes it explicitly it includes a flag to include site packages, otherwise it doesn't provide a flag. 

Some versions of virtualenv by default include site packages and other versions by default do not. 

This patch just makes both branches explicit, so `virtualenv_site_packages=no` really means no.

Python 2.4.3 returns:
TypeError: expected character buffer object

startswith is expecting only a string instead of a tuple like newer versions allow.

path explicit executable is passed to the task and to look for an explicit executable
by basename in a virtualenv if that is specified.

New module argument to specify the executable used for running 'pip'. This allows support for system installation of packages on systems with multiple installations of Python.

Changes examples from using Flask to some other package (Bottle was chosen) as per @mpdehaan's suggestion.

Adding the bin/ directory of the virtualenv (if you specify a virtualenv) as a path_prefix so that other programs that only exist in the virtualenv will be available to things being installed into said virtualenv.  Classic example: installing gevent requires cython binary to be available, but if cython is in the virtualenv only it won't be found without this.

  Migrated all examples: in DOCUMENTATION=''' string to standalone EXAMPLES=''' string
  Added deprecation warning to moduledev.rst and remove deprecated example from it
  Fixed up a few typos and uppercased some acronyms.
  add consistency to how EXAMPLES are formatted

This code:
```
    if name.endswith('.tar.gz') or name.endswith('.tar.bz2') or
name.endswith('.zip'):
        is_tar = True
```
was not checking whether name is defined since it is an
optional param.

**Summary**:

There was a bug in the previous commit; pip module would add --use-mirrors options to a source package when state is absent. The bug is resolved in this commit by checking ``not is_package`` in the if branch.

Furthermore, in order to support non-vcs source name like tarballs, we must not add -e option to the arg list. Given this circumstance, this commit have is_tar and is_vcs and the latter is checked to add -e option. Since mirrors do not make sense with vcs or tarball source, this commit will not add --use-mirrors (default to True) as always.

Summary:

Pip module would abort when name is a remote package address because
the module was expecting a version if ``=`` is part of the name value.

Furthermore, the pip module would require either name or requirement to
be a key, although the documentation table said neither was required.
The fact that one of them must be present is not documented in the
documentation leads to confusion. This commit added this fact as part
of description.

In this commit, we resolve the confusion by stating either ``name``
or ``requirement`` is needed. Next, if the user puts remote address
as the value of the ``name`` key, we will not use mirror. Lastly,
if the user uses the remote serivice address as the name of the
package and the user does not supply -e option in extra_vars
(which is the whole point of this commit), we will add -e to
 extra_vars so pip command can run with -e option.

Both modules seboolean and zfs have not been adapted since they defer from the default (either by having a 'null' or special state, or prefering "on"/"off" for state indication.

This updates the following modules to support check_mode:
* apt_key
* apt_repository
* easy_install
* pip - will always report changed due to the way it handles state
* seboolean
* selinux
* slurp - since nothing changes, it just adds that it supports
  check_mode
* subversion - reports changed when checking out new repo and
  when updating.
* supervisorctl
* svr4pkg

See issue #2114.

This allows flexible selection of the Python version to use while
creating the virtualenv.

This updates apt, apt_repository, command, cron, easy_install, facter,
fireball, git, group, mount, ohai, pip, service, setup, subversion,
supervisorctl, svr4pkg, user, and yum to take advantage of run_command
in module_common.py.

- Do not silently ignore malformed pip requirements files.
- Properly reports changed when removing packages.
- "latest" i.e. --upgrade is *not* incompatible with requirements files.
- Less branchy, simpler logic.
- Removed pointless variable "initializations", Python doesn't need that.
  Other code simplifications.
- Fun fact; pip install is (kind of) case insensitive, pip freeze is not.
  So, 'sqlalchemy' will be reported as installed by install, but missing
  by freeze.

The perhaps controversial change and the one that led to finding /
fixing above issues...

Instead of adding command parameters 'index', and 'find', and 'mirrors',
and etc.  Added 'extra_args' which are passed onto pip.

The use case for --index-url is having a private pypi repo, like
http://pypi.python.org/pypi/localshop, to which you publish private
packages.  I'm sure most every pip option has a use case for someone.
extra_args handles all those. Can reserve ansible command parameters for
the most common.

Tested with pip 1.1.

In a virtualenv, pip is called just pip.  This fixes the pip module to
search for the virtualenv pip first before trying the pip-python and
python-pip variants.  Without this, pip module would not install to the
virtualenv when that parameter is provided.

Older versions of pip (anything less than 1.0?) do not support
--use-mirrors flag.  This makes it configurable.  Default is yes.

This updates _is_package_installed() to accept a requirements file
as an argument.  This is used later in main() to check if python libs
specified in a requirements file are already installed.  I updated
main() to consolidate the handling of install/uninstall in a single
block.  This should help if someone wants to remove packages specified
by a requirements file.