(#22643) Document the file_metadata endpoint.

This patch documents the file_metadata endpoint (a find operation)
and the file_metadatas endpoint (a search operation).  It includes a
json schema for the returned file_metadata object, and spec tests
for validating some variants of file metadata against that schema.
(maint) Instead of two indent-stripping methods, let's have one

This was unDRY, AND the methods had differing behavior. (The faces one didn't
make exceptions for first-line underhang, which demanded unintuitive source
formatting.)

This commit just replaces the implementation of the faces scrubber with a
scrub() call.

Spec test change: This method trims trailing newlines from strings.
(maint) Refactor Puppet::Util::Docs.scrub

It was hard to understand what this method was doing, and once I got it, I
noticed it wasn't quite doing what it claimed. (It was cheating -- grabbing the
indent of the second line with text and assuming that was the least common
indent. This meant you could break it by starting a doc fragment with a line of
text, two newlines, and an indented block of example code.)

This commit replaces it with something more clear and correct, as well as some
comments explaining what we expect it to do. We also trim trailing whitespace,
while we're at it; this costs some speed, but should make it even more
reliable/useful.

We also add tests for scrub in this commit, at spec/unit/util/docs_spec.rb.
(#22489) Fix mangled setting descriptions in config reference and genconfig output

This commit:

- Makes the BaseSetting class stop mangling @desc values. This should offer a
  tiny performance win when Puppet initializes its settings, to the tune of
  about 200 gsub calls. Setting descriptions are now tainted with least-common
  hanging indentation, the same way type, parameter, property, and provider
  descriptions are; we expect anyone consuming these strings to scrub them.
- Makes genconfig scrub hanging indentation from setting descriptions. Swaps a
  few (slow) +=s for (fast) <<s.
- Makes the configuration reference scrub setting descriptions instead of
  further mangling them by deleting all linebreaks. This fixes bug #22489 and
  allows us to use block-level Markdown formatting in setting descriptions.
(maint) Adjust wrapping and indent of a bunch of setting descriptions

Since we reliably handle the hanging indent style now, we can clean up this file
a bit and stop coding these descriptions so paranoiacally. (Trivia: This might
also result in a tiny win when initializing settings, as it replaces about 50
pointless method calls with literal newlines, but it's probably not enough for
anyone to notice.)
(maint) Fix sloppy indent in schedule type
(maint) Fix docs indent breakage in yumrepo type
(maint) Reduce object creation in several string concatenations

Change += to << where applicable, and use interpolation instead of +.
(maint) Prevent possible formatting problems on indirection reference

- Use scrub to protect against indentation comedy, even though we seem fine
  at the moment.
- Adjust wonky Markdown in the foreword.
(maint) Avoid accidental outdenting when appending stuff to doc fragments

When appending:

* Value collection summaries to parameter docs
* Dochook blurbs to provider docs

...we would sometimes cause an "outdent" if the original fragment ended with a
newline. Like so:

First line
    hanging indent
    hanging indent
  appended blurb

When we ran scrub() on that fragment later, we would get the wrong amount of
space removed. This silently sorta succeeded when scrub() was being lazy about
finding least common indent, but making scrub() work as expected made any sloppy
appends break the formatting.

This commit adds some scrub calls and makes our appends more predictable. This
will result in a certain amount of double-scrubbing, but that's okay.
(#22643) Fix lists and remove non-ascii characters
(maint) Use default rspec formatter for Travis CI

Without this commit, Travis CI can't display the full output of rspec
because Travis CI won't display the output of extremely long test runs.
This is problematic because a build can fail in Travis CI but the actual
failure in a broken build can be very hard to find and link to.

This commit changes the spec command to use the default formatter so
that the rspec output is less verbose and we can easily find and link to
failures in the Travis CI build.
(packaging) Update PUPPETVERSION for 3.3.1
Merge branch 'stable'

* stable:
  (packaging) Update PUPPETVERSION for 3.3.1
(maint) Don't default `rake spec` to documentation format
Merge pull request #1976 from adrienthebo/maint/travis/change-rspec-formatter

(maint) Use default rspec formatter for Travis CI
(#22642) Added install_options to the RPM provider

Install options are available for use with the rpm provider, for
example, the --prefix flag.  Without this patch, there is no way to
provide these flags through puppet.

After this patch, the RPM provider accepts the install_options
parameter.  Parameters can be provided as a String, Array, or Hash.
Merge pull request #1932 from mklauber/fix/master/rpm_install_options

#22642 Adding install_options to RPM package provider
(maint) Correct spelling in method name
(#22768) Add documentation for certificate_revocation_list endpoint.