(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