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

Examples showed that modules name is rhnreq_ks, when it actually is rhn_register.

Also ...
 * When unregistering, first unsubscribe from all content

rhnreg_ks command allows users to manage registration to a Red Hat
Network (RHN) (e.g. rhn.redhat.com) server.  The moduel will also
interact with the specified RHN system via XMLRPC as needed.

Before proceeding with registration, the rhnreg_ks module will enable
the system to receive updates from RHN.  This involves enabling the
appropriate RHN yum plugin, as well as disabling an active
subscription-manager yum plugin.

Once enabled, the module will support the following operations:
 * configure
 * register
 * subscribe to custom child channels (see `rhn-channel` command)
 * unregister

The subscription_manager module acts as a wrapper to the command
'subscription-manager'.  The subscription-manager utility allows users
to manage RHN registration, subscription and yum repositories from the
Red Hat Entitlement platform.

Currently, this module supports the following sub-commands:
 * config
 * [un]register
 * subscribe

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.

Signed-off-by: Brian Coca <briancoca+dev@gmail.com>

I have something like:

  apt: pkg={{ item }} state=present
  with_items:
    - python-pysqlite2=2.6.3-*
    - python-paramiko=1.7.7.1-*

But due to the use of *'s in the version specifications, the apt ansible
module always reports changed: true. This patch fixes that.

tweak position & look of Requirements in rst
tweak APT's notes as per anhj's wish

New binary package management should be the default soon in FreeBSD, and
is already fully useable through self generated and non official binary
repositories.

- add support for pkgng
- support specifying the repository url as a parameter
- allow not to update cache

Signed-off-by: bleader <bleader@ratonland.org>

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.