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.

 - added terse syntax to modules.rst
 - added description of special variables to template module

On Red Hat, CentOS and Fedora systems, the pip binary will be called python-pip
instead of pip. This commit makes the pip module also check for python-pip.

The reason we check for python-pip *first*, is to have ansible fail on not
finding 'pip' and reporting *that*. This is consistent with current behaviour
and will not confuse users of Debian et al., where the 'python-pip' binary
never exists.

Tested on Fedora 18 and Ubuntu 12.04.

Added required as optional argument to get_bin_path(). It defaults to
false.  Updated following modules to use required=True when calling
get_bin_path():  apt_repository, easy_install, group, pip,
supervisorctl, and user.
Also removed _find_supervisorctl() from supervisorctl module and updated
_is_running() to not need it.

* Migraed easy_install, pip, service, setup, and user.
* Updated fail_json message in apt_repository
* Fixed easy_install to not hardcode location of virtualenv in
  /usr/local/bin/.
* Made handling of virtualenv more consistent between easy_install and
  pip.

Retrieve the pip path after creating a non-existent virtualenv.
Prevents the problem of using the wrong pip if virtualenv doesn't
exist yet.

pip failure message sometimes (always?) go to standard out. Return
both standard out and standard error when there's a failure.