(maint) Guard preserve_configuration in acceptance

It is only useful to attempt to generate a local preserved_config.yml if
you are manually testing and may need to re-run.  Automated tools such
as Jenkins have tripped over this step if the logs or layout are
different, and there is no reason to abort a test run for this step.

This commit changes the behavior of the acceptance harness so that it
only preserves the configuration if you are running the manual
'test_and_preserve_hosts' task, or if you have specified you want this
behavior in your local_options.rb.  It is also a little more resilient
for failures when preserving the configuration.
(doc) Remove outdated notice concerning rdoc and ruby > 1.8.7

This note is deprecated by the following pull requests:

https://github.com/puppetlabs/puppet/pull/2009
https://github.com/puppetlabs/puppet/pull/2187

Relevant redmine ticket:

https://projects.puppetlabs.com/issues/22180
(PUP-2946) Ensure #compare_stream uses binary strings

In Ruby commit 2142287c `FileUtils.compare_stream` was optimized to
produce fewer objects while comparing streams by predeclaring a pair of
strings and reusing them for each iteration of the comparison. However,
this change exposes some inconsistency in how ruby handles IO#read vs
StringIO#read.  When IO#read is passed a length and string, it will copy
the read data into the string, but will convert the encoding from the
expected ASCII-8BIT into the encoding of the string regardless of if the
file was opened as a binary file. However, when StringIO#read is passed
a length and string it will convert the passed string to the expected
ASCII-8BIT. Because of this it's impossible to use `FileUtils.compare_stream`
to compare a binary file and StringIO instance.

To resolve this issue, this commit adds a custom compare_stream method
which sets the encoding of the strings to always be ASCII-8BIT on Ruby
1.9+.
(PUP-2946) Don't use private FileUtils methods

Previously the compare_stream method was using private methods in
FileUtils, which could be subject to change at any time (as private
methods are wont to do). This commit pulls in the implementations of
those methods to isolate ourselves from those potential changes.
Merge pull request #2947 from adrienthebo/issue/master/pup-2946-filebucket-encodings

Issue/master/pup 2946 filebucket encodings
Merge pull request #2948 from jpartlow/maint/master/only-preserve-config-for-local-acceptance-runs

(maint) Guard preserve_configuration in acceptance
Merge pull request #2949 from roidelapluie/Remove_Puppet_Doc_Oudated_Documentation

(doc) Remove outdated notice concerning rdoc and ruby > 1.8.7
(maint) Refactor HTTPS verification tests into a shared examples

This commit refactors the spec tests that ensure puppet displays
meaningful error messages when SSL verification fails, e.g. when the
server certificate doesn't match the hostname we connected to.
(PUP-744) Expand scope of OpenSSL rescue block

The persistent http connection work introduced a regression,
preventing the agent from displaying useful error messages when SSL
verification fails, e.g. the server's SSL certificate doesn't match
the hostname the agent tried to connect to. The connection_spec test
didn't catch the issue, because those tests execute with the
non-caching pool, which always uses non-persistent connections.

The root cause is because the Connection class assumed http
connections are started by ruby in the `Net::HTTP#request`
method, so the OpenSSL rescue block wrapped that call.

However, in order to use persistent http connection, the caller needs
to explicitly start the connection prior to calling Net::HTTP#request,
which happens in the outer `Connection#with_connection` method.

This commit expands the scope of the rescue block. This way we receive
meaningful error messages if the connection is started explicitly for
persistent connections, or on-demand for non-persistent connections. It
also executes the ssl verification tests using persistent connections.

Also note that `with_connection` is private, so the fact that
`Pool#with_connection` or `Net::HTTP#request` can start the connection
is not visible to users of the Connection class.
Merge pull request #2954 from joshcooper/ticket/master/PUP-744-rescue-openssl

(PUP-744) Expand scope of OpenSSL rescue block
Merge branch 'master' into puppet-4