Give the module more knowledge of the package name structure.
This makes the handling of version-less flavors (like vim--no_x11)
behave properly.

While here sprinkle debug logging that is helpful when testing the
module.

This reverts commit de2f4cf0, reversing
changes made to 2c33737b.

is vim. It can be installed as vim--no_x11 or vim--gtk2.

This fixes an asterisk glob problem in get_package_state() where a file
in /root/ could cause shell expansion if it matched the package name.
The actual problem is solved by running with shell=False.

This diff syncs package_latest() with the changes to package_present().
I have not managed to figure out how to handle the cornercases where
stderr is set but the command has not failed, so leave a FIXME blob for
other adventurers.

* Add '-m' to pkg_add incovation to get access to the "packagename-1.0: ok"
  message.
* Watch for that message if we are about to fail because of stderr in
  package_present().

This fixes a problem when trying to install a package with a specific version
number from a local directory and the local directory is checked after a remote
repository:

Error from http://ftp.eu.openbsd.org/pub/OpenBSD/[...]/packagename-1.0.tgz
ftp: Error retrieving file: 404 Not Found
packagename-1.0: ok

  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

The biggest change has been to package_latest since it was previously
just comparing version numbers before and after an upgrade had run.
We now parse the output from a dry run instead.

Thanks to Johan Belin for triggering the discussion :).

* Code influenced by the service module but without classes.
* Thanks to @dhozac for input and review.
* Thanks to @johanwiren for getting me to push this out the door.