puppet 8.8.1 → 8.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f89da386754e99d82576c50391217640d9d740f5aa41df6d0a091aafd35377b1
-  data.tar.gz: bfb37d9f9f20cc9607976f782622fb16ff6146cdef2642ad5cd46e55b31d7f40
+  metadata.gz: '08fa93960fb1b1b45faf01adeada66909e0e3312ba1de1d90c44aba5812c728b'
+  data.tar.gz: 045f5f6ce8cb20b9c8ed0428a0126e4bf917d0feebc02b70539874586d69bee8
 SHA512:
-  metadata.gz: 43d308cfe325c7985ff9d0a6310ee36a7d23f3c4080bd97445375d0d01ed59ed9cbed104efd5a40824b0cef277b2934976df028a827965612eac1c2a97659b9c
-  data.tar.gz: 87293cc2c9f04ec783873109a65d30162d02698ddc5947287a71a3662c53041e5b6eefbc166595fc3a014f18025311d3117ef93bd8cc07fa5f4c1d5da73082da
+  metadata.gz: 5501e4ef60157bc7d9868ee781ed4f2920f4f91d9f4ec2dc0db42f881414d96351b64506e89fc1a8154f886555c2f82a847d442714edea6350068d1fde6c9906
+  data.tar.gz: 28cd5445dde17a7b25f560161f301e176298b98c5e11e3fb909810a0623ea668be9785fb69ec1199106b814fc42578b8b32fe1d6e2ecee032e85c5d19c55b64f

data/Gemfile

@@ -75,6 +75,8 @@ end
 group(:documentation, optional: true) do
   gem 'gettext-setup', '~> 1.0', require: false, platforms: [:ruby]
   gem 'ronn', '~> 0.7.3', require: false, platforms: [:ruby]
+  gem 'puppet-strings', require: false, platforms: [:ruby]
+  gem 'pandoc-ruby', require: false, platforms: [:ruby]
 end
 
 if File.exist? "#{__FILE__}.local"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    puppet (8.8.1)
+    puppet (8.9.0)
       concurrent-ruby (~> 1.0)
       deep_merge (~> 1.0)
       facter (>= 4.3.0, < 5)
@@ -27,7 +27,7 @@ GEM
     base64 (0.2.0)
     bigdecimal (3.1.8)
     coderay (1.1.3)
-    concurrent-ruby (1.3.3)
+    concurrent-ruby (1.3.4)
     crack (1.0.0)
       bigdecimal
       rexml
@@ -39,13 +39,13 @@ GEM
       rake (>= 12.0.0, < 14.0.0)
     docopt (0.6.1)
     erubi (1.13.0)
-    facter (4.8.0)
+    facter (4.9.0)
       hocon (~> 1.3)
       thor (>= 1.0.1, < 1.3)
-    faraday (2.10.0)
-      faraday-net_http (>= 2.0, < 3.2)
+    faraday (2.11.0)
+      faraday-net_http (>= 2.0, < 3.4)
       logger
-    faraday-net_http (3.1.0)
+    faraday-net_http (3.3.0)
       net-http
     fast_gettext (2.4.0)
       prime
@@ -62,22 +62,22 @@ GEM
       fast_gettext (~> 2.1)
       gettext (~> 3.4)
       locale
-    google-apis-core (0.15.0)
+    google-apis-core (0.15.1)
       addressable (~> 2.5, >= 2.5.1)
       googleauth (~> 1.9)
-      httpclient (>= 2.8.1, < 3.a)
+      httpclient (>= 2.8.3, < 3.a)
       mini_mime (~> 1.0)
+      mutex_m
       representable (~> 3.0)
       retriable (>= 2.0, < 4.a)
-      rexml
     google-apis-iamcredentials_v1 (0.21.0)
       google-apis-core (>= 0.15.0, < 2.a)
-    google-apis-storage_v1 (0.40.0)
+    google-apis-storage_v1 (0.44.0)
       google-apis-core (>= 0.15.0, < 2.a)
-    google-cloud-core (1.7.0)
+    google-cloud-core (1.7.1)
       google-cloud-env (>= 1.0, < 3.a)
       google-cloud-errors (~> 1.0)
-    google-cloud-env (2.1.1)
+    google-cloud-env (2.2.0)
       faraday (>= 1.0, < 3.a)
     google-cloud-errors (1.4.0)
     google-cloud-storage (1.52.0)
@@ -96,7 +96,7 @@ GEM
       multi_json (~> 1.11)
       os (>= 0.9, < 2.0)
       signet (>= 0.16, < 2.a)
-    hashdiff (1.1.0)
+    hashdiff (1.1.1)
     hiera-eyaml (4.1.0)
       highline (~> 2.1)
       optimist (~> 3.1)
@@ -111,28 +111,32 @@ GEM
       base64
     language_server-protocol (3.17.0.3)
     locale (2.1.4)
-    logger (1.6.0)
+    logger (1.6.1)
     memory_profiler (1.0.2)
     method_source (1.1.0)
     mini_mime (1.1.5)
-    minitar (0.9)
+    minitar (0.12.1)
     msgpack (1.7.2)
     multi_json (1.15.0)
     mustache (1.1.1)
+    mutex_m (0.2.0)
     net-http (0.4.1)
       uri
     nkf (0.2.0)
     optimist (3.1.0)
     os (1.1.4)
-    packaging (0.120.0)
+    packaging (0.122.0)
       artifactory (~> 3)
       csv (>= 3.1.5)
       google-cloud-storage
       googleauth
       rake (>= 12.3)
       release-metrics
-    parallel (1.25.1)
-    parser (3.3.4.0)
+      retriable (~> 3.1, >= 3.1.2)
+      rexml
+    pandoc-ruby (2.1.10)
+    parallel (1.26.3)
+    parser (3.3.5.0)
       ast (~> 2.4.1)
       racc
     prime (0.1.2)
@@ -144,6 +148,9 @@ GEM
     public_suffix (6.0.1)
     puppet-resource_api (1.9.0)
       hocon (>= 1.0)
+    puppet-strings (4.1.3)
+      rgen (~> 0.9)
+      yard (~> 0.9, < 0.9.37)
     puppetserver-ca (2.7.0)
       facter (>= 2.0.1, < 5)
     racc (1.5.2)
@@ -160,8 +167,8 @@ GEM
       trailblazer-option (>= 0.1.1, < 0.2.0)
       uber (< 0.2.0)
     retriable (3.1.2)
-    rexml (3.3.2)
-      strscan
+    rexml (3.3.7)
+    rgen (0.9.1)
     ronn (0.7.3)
       hpricot (>= 0.8.2)
       mustache (>= 0.7.0)
@@ -170,9 +177,9 @@ GEM
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.0)
+    rspec-core (3.13.1)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.1)
+    rspec-expectations (3.13.2)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-its (1.3.0)
@@ -182,18 +189,17 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.1)
-    rubocop (1.65.0)
+    rubocop (1.66.1)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.4, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
+      rubocop-ast (>= 1.32.2, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.31.3)
+    rubocop-ast (1.32.3)
       parser (>= 3.3.1.0)
     rubocop-capybara (2.21.0)
       rubocop (~> 1.41)
@@ -223,15 +229,15 @@ GEM
       jwt (>= 1.5, < 3.0)
       multi_json (~> 1.10)
     singleton (0.2.0)
-    strscan (3.1.0)
     syslog (0.1.2)
     text (1.3.1)
     thor (1.2.2)
     trailblazer-option (0.1.2)
     uber (0.1.0)
     unicode-display_width (2.5.0)
-    uri (0.13.0)
-    vcr (6.2.0)
+    uri (0.13.1)
+    vcr (6.3.1)
+      base64
     webmock (3.23.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
@@ -255,9 +261,11 @@ DEPENDENCIES
   minitar (~> 0.9)
   msgpack (~> 1.2)
   packaging (~> 0.113)
+  pandoc-ruby
   pry
   puppet!
   puppet-resource_api (~> 1.5)
+  puppet-strings
   puppetserver-ca (~> 2.0)
   racc (= 1.5.2)
   rake (~> 13.0)

data/ext/project_data.yaml

@@ -6,3 +6,15 @@ gem_rdoc_options:
   - --main
   - README.md
   - --line-numbers
+# Array of files to include when building source tarballs
+files:
+  - '[A-Z]*'
+  - install.rb
+  - bin
+  - lib
+  - conf
+  - man
+  - examples
+  - ext
+  - tasks
+  - locales

data/install.rb

@@ -36,14 +36,6 @@ require 'tempfile'
 require 'optparse'
 require 'ostruct'
 
-begin
-  require 'rdoc/rdoc'
-  $haverdoc = true
-rescue LoadError
-  puts "Missing rdoc; skipping documentation"
-  $haverdoc = false
-end
-
 PREREQS = %w{openssl facter cgi}
 MIN_FACTER_VERSION = 1.5
 
@@ -140,25 +132,9 @@ def prepare_installation
   InstallOptions.check_prereqs = true
   InstallOptions.batch_files = true
 
-  # Only try to do docs if we're sure they have rdoc
-  if $haverdoc
-    InstallOptions.rdoc  = true
-    InstallOptions.ri  = true
-  else
-    InstallOptions.rdoc  = false
-    InstallOptions.ri  = false
-  end
-
-
   ARGV.options do |opts|
     opts.banner = "Usage: #{File.basename($0)} [options]"
     opts.separator ""
-    opts.on('--[no-]rdoc', 'Prevents the creation of RDoc output.', 'Default on.') do |onrdoc|
-      InstallOptions.rdoc = onrdoc
-    end
-    opts.on('--[no-]ri', 'Prevents the creation of RI output.', 'Default off on mswin32.') do |onri|
-      InstallOptions.ri = onri
-    end
     opts.on('--[no-]configs', 'Prevents the installation of config files', 'Default off.') do |ontest|
       InstallOptions.configs = ontest
     end
@@ -205,14 +181,8 @@ def prepare_installation
       InstallOptions.batch_files = false
     end
     opts.on('--quick', 'Performs a quick installation. Only the', 'installation is done.') do |quick|
-      InstallOptions.rdoc    = false
-      InstallOptions.ri      = false
-      InstallOptions.configs = true
-    end
-    opts.on('--full', 'Performs a full installation. All', 'optional installation steps are run.') do |full|
-      InstallOptions.rdoc    = true
-      InstallOptions.ri      = true
       InstallOptions.configs = true
+      warn "--quick is deprecated. Use --configs"
     end
     opts.separator("")
     opts.on_tail('--help', "Shows this help text.") do
@@ -223,9 +193,6 @@ def prepare_installation
     opts.parse!
   end
 
-  version = [RbConfig::CONFIG["MAJOR"], RbConfig::CONFIG["MINOR"]].join(".")
-  libdir = File.join(RbConfig::CONFIG["libdir"], "ruby", version)
-
   # Mac OS X 10.5 and higher declare bindir
   # /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/bin
   # which is not generally where people expect executables to be installed
@@ -312,7 +279,8 @@ def prepare_installation
     if sitelibdir.nil?
       sitelibdir = $LOAD_PATH.find { |x| x =~ /site_ruby/ }
       if sitelibdir.nil?
-        sitelibdir = File.join(libdir, "site_ruby")
+        version = [RbConfig::CONFIG["MAJOR"], RbConfig::CONFIG["MINOR"]].join(".")
+        sitelibdir = File.join(RbConfig::CONFIG["libdir"], "ruby", version, "site_ruby")
       elsif sitelibdir !~ Regexp.quote(version)
         sitelibdir = File.join(sitelibdir, version)
       end
@@ -328,10 +296,6 @@ def prepare_installation
   # This is the new way forward
   if not InstallOptions.destdir.nil?
     destdir = InstallOptions.destdir
-  # To be deprecated once people move over to using --destdir option
-  elsif not ENV['DESTDIR'].nil?
-    destdir = ENV['DESTDIR']
-    warn "DESTDIR is deprecated. Use --destdir instead."
   else
     destdir = ''
   end
@@ -362,7 +326,6 @@ def prepare_installation
   InstallOptions.codedir = codedir
   InstallOptions.config_dir = configdir
   InstallOptions.bin_dir = bindir
-  InstallOptions.lib_dir = libdir
   InstallOptions.man_dir = mandir
   InstallOptions.var_dir = vardir
   InstallOptions.public_dir = publicdir
@@ -381,36 +344,6 @@ def join(basedir, dir)
   "#{basedir}#{dir}"
 end
 
-##
-# Build the rdoc documentation. Also, try to build the RI documentation.
-#
-def build_rdoc(files)
-  return unless $haverdoc
-  begin
-    r = RDoc::RDoc.new
-    r.document(["--main", "README", "--title", "Puppet -- Site Configuration Management", "--line-numbers"] + files)
-  rescue RDoc::RDocError => e
-    $stderr.puts e.message
-  rescue Exception => e
-    $stderr.puts "Couldn't build RDoc documentation\n#{e.message}"
-  end
-end
-
-def build_ri(files)
-  return unless $haverdoc
-  return if $osname == "windows"
-  begin
-    ri = RDoc::RDoc.new
-    #ri.document(["--ri-site", "--merge"] + files)
-    ri.document(["--ri-site"] + files)
-  rescue RDoc::RDocError => e
-    $stderr.puts e.message
-  rescue Exception => e
-    $stderr.puts "Couldn't build Ri documentation\n#{e.message}"
-    $stderr.puts "Continuing with install..."
-  end
-end
-
 ##
 # Install file(s) from ./bin to RbConfig::CONFIG['bindir']. Patch it on the way
 # to insert a #! line; on a Unix install, the command is named as expected
@@ -476,8 +409,6 @@ FileUtils.cd File.dirname(__FILE__) do
   # Set these values to what you want installed.
   configs = glob(%w{conf/puppet.conf conf/hiera.yaml})
   bins  = glob(%w{bin/*})
-  #rdoc  = glob(%w{bin/* lib/**/*.rb README* }).reject { |e| e=~ /\.(bat|cmd)$/ }
-  #ri    = glob(%w{bin/*.rb lib/**/*.rb}).reject { |e| e=~ /\.(bat|cmd)$/ }
   man   = glob(%w{man/man[0-9]/*})
   libs  = glob(%w{lib/**/*})
   locales = glob(%w{locales/**/*})
@@ -488,8 +419,6 @@ FileUtils.cd File.dirname(__FILE__) do
     windows_bins = glob(%w{ext/windows/*bat})
   end
 
-  #build_rdoc(rdoc) if InstallOptions.rdoc
-  #build_ri(ri) if InstallOptions.ri
   do_configs(configs, InstallOptions.config_dir) if InstallOptions.configs
   do_bins(bins, InstallOptions.bin_dir)
   do_bins(windows_bins, InstallOptions.bin_dir, 'ext/windows/') if $osname == "windows" && InstallOptions.batch_files

data/lib/puppet/application/apply.rb

@@ -153,6 +153,7 @@ class Puppet::Application::Apply < Puppet::Application
 
       EXAMPLE
       -------
+          $ puppet apply -e 'notify { "hello world": }'
           $ puppet apply -l /tmp/manifest.log manifest.pp
           $ puppet apply --modulepath=/root/dev/modules -e "include ntpd::server"
           $ puppet apply --catalog catalog.json

data/lib/puppet/application/filebucket.rb

@@ -76,10 +76,11 @@ class Puppet::Application::Filebucket < Puppet::Application
       use your local file bucket by specifying '--local', or by specifying
       '--bucket' with a local path.
 
-      > **Note**: Enabling and using the backup option, and by extension the
-        filebucket resource, requires appropriate planning and management to ensure
-        that sufficient disk space is available for the file backups. Generally, you
-        can implement this using one of the following two options:
+      **Important**: When you enable and use the backup option, and by extension
+      the filebucket resource, you must ensure that sufficient disk space is
+      available for the file backups. Generally, you can provide the disk space
+      by using one of the following two options:
+
         - Use a `find` command and `crontab` entry to retain only the last X days
         of file backups. For example:
 
@@ -187,6 +188,7 @@ class Puppet::Application::Filebucket < Puppet::Application
 
           $ puppet filebucket -l -t "2015-05-11 09:30:00" list
           d43a6ecaa892a1962398ac9170ea9bf2 2015-05-11 09:27:56 /tmp/TestFile
+
           ## Manage files in a specific local filebucket
           $ puppet filebucket -b /tmp/TestBucket backup /tmp/TestFile2
           /tmp/TestFile2: d41d8cd98f00b204e9800998ecf8427e

data/lib/puppet/application/ssl.rb

@@ -57,13 +57,13 @@ class Puppet::Application::Ssl < Puppet::Application
       * submit_request:
         Generate a certificate signing request (CSR) and submit it to the CA. If
         a private and public key pair already exist, they will be used to generate
-        the CSR. Otherwise a new key pair will be generated. If a CSR has already
+        the CSR. Otherwise, a new key pair will be generated. If a CSR has already
         been submitted with the given `certname`, then the operation will fail.
 
       * generate_request:
-        Generate a certificate signing request (CSR). If
-        a private and public key pair already exist, they will be used to generate
-        the CSR. Otherwise a new key pair will be generated.
+        Generate a certificate signing request (CSR). If a private and public key
+        pair exist, they will be used to generate the CSR. Otherwise a new key
+        pair will be generated.
 
       * download_cert:
         Download a certificate for this host. If the current private key matches

data/lib/puppet/defaults.rb

@@ -7,6 +7,7 @@ module Puppet
     '-u'
   end
 
+  # If you modify this, update puppet/type/file/checksum.rb too
   def self.default_digest_algorithm
     'sha256'
   end
@@ -161,8 +162,8 @@ module Puppet
     :skip_logging_catalog_request_destination => {
       :default => false,
       :type    => :boolean,
-      :desc    => "If you wish to suppress the notice of which compiler supplied the
-        catalog",
+      :desc => "Specifies whether to suppress the notice of which compiler
+        supplied the catalog. A value of `true` suppresses the notice.",
     },
     :merge_dependency_warnings => {
       :default => false,
@@ -417,13 +418,15 @@ module Puppet
       :type     => :boolean,
       :default  => true,
       :desc     => <<-'EOT'
-      When versioned_environment_dirs is `true` Puppet will readlink the environmentpath
-      when constructing the environment's modulepath. The full readlinked path is referred
-      to as the "resolved path" and the configured path potentially containing symlinks is
-      the "configured path". When reporting where resources come from users may choose
-      between the configured or resolved path.
-
-      When set to false, the resolved paths are reported instead of the configured paths.
+      Specifies how environment paths are reported. When the value of
+      `versioned_environment_dirs` is `true`, Puppet applies the readlink function to
+      the `environmentpath` setting when constructing the environment's modulepath. The
+      full readlinked path is referred to as the "resolved path," and the configured
+      path potentially containing symlinks is the "configured path." When reporting
+      where resources come from, users may choose between the configured and resolved
+      path.
+
+      When set to `false`, the resolved paths are reported instead of the configured paths.
       EOT
     },
     :use_last_environment => {
@@ -1204,17 +1207,18 @@ EOT
     :ca_refresh_interval => {
       :default    => "1d",
       :type       => :duration,
-      :desc       => "How often the Puppet agent refreshes its local CA certs. By
-         default the CA certs are refreshed once every 24 hours. If a different
-         duration is specified, then the agent will refresh its CA certs whenever
-         it next runs and the elapsed time since the certs were last refreshed
-         exceeds the duration.
-
-         In general, the duration should be greater than the `runinterval`.
-         Setting it to 0 or an equal or lesser value than `runinterval`,
-         will cause the CA certs to be refreshed on every run.
-
-         If the agent downloads new CA certs, the agent will use it for subsequent
+      :desc       => "How often the Puppet agent refreshes its local CA
+         certificates. By default, CA certificates are refreshed every 24 hours. If a
+         different interval is specified, the agent refreshes its CA certificates during
+         the next agent run if the elapsed time since the certificates were last
+         refreshed exceeds the specified duration.
+
+         In general, the interval should be greater than the `runinterval`
+         value. Setting the `ca_refresh_interval` value to 0 or an equal or
+         lesser value than `runinterval` causes the CA certificates to be
+         refreshed on every run.
+
+         If the agent downloads new CA certs, the agent uses those for subsequent
          network requests. If the refresh request fails or if the CA certs are
          unchanged on the server, then the agent run will continue using the
          local CA certs it already has. #{AS_DURATION}",
@@ -1222,15 +1226,15 @@ EOT
     :crl_refresh_interval => {
       :default    => "1d",
       :type       => :duration,
-      :desc       => "How often the Puppet agent refreshes its local CRL. By
-         default the CRL is refreshed once every 24 hours. If a different
-         duration is specified, then the agent will refresh its CRL whenever
-         it next runs and the elapsed time since the CRL was last refreshed
-         exceeds the duration.
+      :desc       => "How often the Puppet agent refreshes its local Certificate
+         Revocation List (CRL). By default, the CRL is refreshed every 24 hours. If
+         a different interval is specified, the agent refreshes its CRL on the next
+         Puppet agent run if the elapsed time since the CRL was last refreshed
+         exceeds the specified interval.
 
-         In general, the duration should be greater than the `runinterval`.
-         Setting it to 0 or an equal or lesser value than `runinterval`,
-         will cause the CRL to be refreshed on every run.
+         In general, the interval should be greater than the `runinterval` value.
+         Setting the `crl_refresh_interval` value to 0 or an equal or lesser value
+         than `runinterval` causes the CRL to be refreshed on every run.
 
          If the agent downloads a new CRL, the agent will use it for subsequent
          network requests. If the refresh request fails or if the CRL is
@@ -1240,18 +1244,19 @@ EOT
     :hostcert_renewal_interval => {
       :default => "30d",
       :type    => :duration,
-      :desc    => "When the Puppet agent refreshes its client certificate.
-         By default the client certificate will refresh 30 days before the certificate
-         expires. If a different duration is specified, then the agent will refresh its
-         client certificate whenever it next runs and if the client certificate expires
-         within the duration specified.
+      :desc => "How often the Puppet agent renews its client certificate. By
+         default, the client certificate is renewed 30 days before the certificate
+         expires. If a different interval is specified, the agent renews its client
+         certificate during the next agent run, assuming that the client certificate has
+         expired within the specified duration.
 
-         In general, the duration should be greater than the `runinterval`.
-         Setting it to 0 will disable automatic renewal.
+         In general, the `hostcert_renewal_interval` value should be greater than the
+         `runinterval` value. Setting the `hostcert_renewal_interval` value to 0 disables
+         automatic renewal.
 
-         If the agent downloads a new certificate, the agent will use it for subsequent
-         network requests. If the refresh request fails, then the agent run will continue using the
-         certificate it already has. #{AS_DURATION}",
+         If the agent downloads a new certificate, the agent will use it
+         for subsequent network requests. If the refresh request fails, the agent run
+         continues to use its existing certificate. #{AS_DURATION}",
     },
     :keylength => {
       :default    => 4096,
@@ -1492,8 +1497,10 @@ EOT
     :exclude_unchanged_resources => {
       :default => true,
       :type => :boolean,
-      :desc => 'When set to true, resources that have had no changes after catalog application
-        will not have corresponding unchanged resource status updates listed in the report.'
+      :desc => "Specifies how unchanged resources are listed in reports. When
+        set to `true`, resources that have had no changes after catalog application
+        will not have corresponding unchanged resource status updates listed in a
+        report."
     },
     :reportdir => {
       :default => "$vardir/reports",
@@ -1745,11 +1752,12 @@ EOT
     :allow_pson_serialization => {
       :default    => false,
       :type       => :boolean,
-      :desc       => "Whether when unable to serialize to JSON or other formats,
-        Puppet falls back to PSON. This option affects both puppetserver's
-        configuration management service responses and when the agent saves its
-        cached catalog. This option is useful in preventing the loss of data because
-        rich data cannot be serialized via PSON.",
+      :desc => "Whether to allow PSON serialization. When unable to serialize to
+        JSON or other formats, Puppet falls back to PSON. This option affects the
+        configuration management service responses of Puppet Server and the process by
+        which the agent saves its cached catalog. With a default value of `false`, this
+        option is useful in preventing the loss of data because rich data cannot be
+        serialized via PSON.",
     },
     :agent_catalog_run_lockfile => {
       :default    => "$statedir/agent_catalog_run.lock",
@@ -1775,7 +1783,7 @@ EOT
       :type       => :boolean,
       :default    => false,
       :desc       => "Whether to include legacy facts when requesting a catalog. This
-        option can be set to false provided all puppet manifests, hiera.yaml and hiera
+        option can be set to `false` if all puppet manifests, hiera.yaml, and hiera
         configuration layers no longer access legacy facts, such as `$osfamily`, and
         instead access structured facts, such as `$facts['os']['family']`."
     },
@@ -2091,12 +2099,12 @@ EOT
     :preprocess_deferred => {
       :default => false,
       :type => :boolean,
-      :desc => "Whether puppet should call deferred functions before applying
-        the catalog. If set to `true`, then all prerequisites needed for the
-        deferred function must be satisfied prior to puppet running. If set to
-        `false`, then deferred functions will follow puppet relationships and
-        ordering. This allows puppet to install prerequisites needed for a
-        deferred function and call the deferred function in the same run."
+      :desc => "Whether Puppet should call deferred functions before applying
+        the catalog. If set to `true`, all prerequisites required for the
+        deferred function must be satisfied before the Puppet run. If set to
+        `false`, deferred functions follow Puppet relationships and
+        ordering. In this way, Puppet can install the prerequisites required for a
+        deferred function and call the deferred function in the same run.",
     },
     :summarize => {
         :default  => false,
@@ -2118,10 +2126,12 @@ EOT
           can produce node information. The command must:
 
           * Take the name of a node as a command-line argument.
+
           * Return a YAML hash with up to three keys:
             * `classes` --- A list of classes, as an array or hash.
             * `environment` --- A string.
             * `parameters` --- A list of top-scope variables to set, as a hash.
+
           * For unknown nodes, exit with a non-zero exit code.
 
           Generally, an ENC script makes requests to an external data source.