(doc) Document key purging in the description of the ssh_authorized_key type

This commit puts an explanation of key purging over where people will likely be
looking for it. It also tightens up the description of the user type's
purge_ssh_keys attribute, and adds an example key to the ssh_authorized_key type
(since the way that type breaks up key lines is somewhat unintuitive).

The example public key is a dud, to prevent accidental access grants.
(PUP-2311) OpenBSD uninstall broken when multiple uninstall_options given
(PUP-2458) Tests for providers inheriting from providers of another type

It's sometimes desirable to create new providers that inherit from providers
of a different type to create more specialised types/providers from a common
base.  This adds tests around this already-present functionality.
(PUP-2182) Add virtual_packages feature to package type.

In 3.5.x, the yum package provider changed to accept virtual package
names (packages that provide other package names).

That change in behavior caused some undesirable side-effects. As we did
not give users fair warning that this behavior was changing, we have
decided to change the yum provider back to only accepting "real" package
names by default.

To keep the support for virtual package names, a "virtual_packages"
feature has been implemented on the package type and supported on the
yum package provider.  The feature adds the "allow_virtual" parameter
that controls whether or not virtual package names will be allowed for
install/uninstall.

For now, the default value for this parameter will be false to restore
the previous behavior.  However, a deprecation warning will be issued to
let users know that the default will eventually be changed to true.
Users can prevent the deprecation warning by explicitly setting the
parameter to either true or false.
Merge pull request #2563 from jasperla/openbsd/uninstall

(PUP-2311) OpenBSD uninstall broken when multiple uninstall_options give
Merge pull request #2606 from nfagerlund/docs_ssh_key_purge

(doc) Document key purging in the description of the ssh_authorized_key ...
Merge pull request #2615 from domcleal/tickets/master/pup-2458-inherit-providers

(PUP-2458) Tests for providers inheriting from providers of another type
(PUP-1027) Add warnings for bare words that will be keywords in 4.0

This adds a check for reserved words and makes the words:
private, function, type, and attr reserved.

These warnings are for the --parser current setting in 3x.
(PUP-1027) Change warning for reserved words to a deprecation warning
(PUP-1027) Make it an error to use reserved words in future parser.

This makes it an error to use the reserved words function, private,
attr, and type in the future parser. The same keywords issue warnings
in 3x that they must be quoted. Therefore, the 4x implementation should
make it an error to use them (until there is support for the features
they will represent). If these are not made in to errors the features
can not be introduced without breakage since a deprecation can only be
turned into an error (or something new) in a major release.
(PUP-1027) Improve warning message for reserved words

The original warning about reserved words implied that a user could
always quote the word to be able to use this. Although this is often the
case there are also places where the word is used as a NAME (such as
class function {}) where quoting is not an option. In those cases they
need to select a different name.
Merge pull request #2640 from peterhuene/pup/2182

(PUP-2182) Add virtual_packages feature to package type.
(maint) Fix latent error in parser face

There was an error when the spec/unit/util/rdoc_spec.rb tests were run
before the spec/unit/face/parser_spec.rb tests. In that order the test
for the "parser validate" action would fail when it is supposed to read
text from stdin.

What occured was that the environment from the previous test had created
a @known_resource_types on the current_environment. When the face ran it
didn't make sure that the environment was reset before trying to
validate the code it was given. The validation is done in a very
round-about manner where simply asking the environment for the
known_resource_types is expected to result in perform_initial_import,
which will raise and error if there are syntax errors in the manifest.
However, since the environment already had a @known_resource_types
value, it skipped perform_initial_import and didn't fail as the test
expected.

The fix is to ensure that the environment will reparse the manifests if
needed, which required a small adjustment to the reparse logic on the
environment, since the watching? flag should only control file watching,
not changes to the code setting. The other part is to have the validate
face check that it needs to reparse before assuming that
known_resource_types will automatically cause a parse to occur.

This is still a very awkward way to validate syntax, but it perhaps
slightly better now.
Merge branch 'pr/2636'

* pr/2636:
  (maint) Fix latent error in parser face
  (PUP-1027) Improve warning message for reserved words
  (PUP-1027) Make it an error to use reserved words in future parser.
  (PUP-1027) Change warning for reserved words to a deprecation warning
  (PUP-1027) Add warnings for bare words that will be keywords in 4.0