Merge branch 'puppetlabs:main' into main

Gemfile

@@ -75,6 +75,7 @@ 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]
 end
 
 if File.exist? "#{__FILE__}.local"

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

lib/puppet/application/filebucket.rb

@@ -76,10 +76,10 @@ def help
       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:

lib/puppet/face/catalog.rb

@@ -29,7 +29,7 @@
     summary _("Retrieve the catalog for the node from which the command is run.")
     arguments "<certname>, <facts>"
     option("--facts_for_catalog") do
-      summary _("Not yet implemented for the CLI; facts will be collected internally.")
+      summary _("Not implemented for the CLI; facts are collected internally.")
     end
     returns <<-'EOT'
       A serialized catalog. When used from the Ruby API, returns a

lib/puppet/face/help.rb

@@ -151,6 +151,33 @@ def legacy_applications
     end.sort
   end
 
+  def generate_summary(appname)
+    if is_face_app?(appname)
+      begin
+        face = Puppet::Face[appname, :current]
+        # Add deprecation message to summary if the face is deprecated
+        summary = face.deprecated? ? face.summary + ' ' + _("(Deprecated)") : face.summary
+        [appname, summary, '  ']
+      rescue StandardError, LoadError
+        error_message = _("!%{sub_command}! Subcommand unavailable due to error.") % { sub_command: appname }
+        error_message += ' ' + _("Check error logs.")
+        [error_message, '', '  ']
+      end
+    else
+      begin
+        summary = Puppet::Application[appname].summary
+        if summary.empty?
+          summary = horribly_extract_summary_from(appname)
+        end
+        [appname, summary, '  ']
+      rescue StandardError, LoadError
+        error_message = _("!%{sub_command}! Subcommand unavailable due to error.") % { sub_command: appname }
+        error_message += ' ' + _("Check error logs.")
+        [error_message, '', '  ']
+      end
+    end
+  end
+
   # Return a list of all applications (both legacy and Face applications), along with a summary
   #  of their functionality.
   # @return [Array] An Array of Arrays.  The outer array contains one entry per application; each
@@ -162,45 +189,38 @@ def all_application_summaries
 
       if appname == COMMON || appname == SPECIALIZED || appname == BLANK
         result << appname
-      elsif is_face_app?(appname)
-        begin
-          face = Puppet::Face[appname, :current]
-          # Add deprecation message to summary if the face is deprecated
-          summary = face.deprecated? ? face.summary + ' ' + _("(Deprecated)") : face.summary
-          result << [appname, summary, '  ']
-        rescue StandardError, LoadError
-          error_message = _("!%{sub_command}! Subcommand unavailable due to error.") % { sub_command: appname }
-          error_message += ' ' + _("Check error logs.")
-          result << [error_message, '', '  ']
-        end
       else
-        begin
-          summary = Puppet::Application[appname].summary
-          if summary.empty?
-            summary = horribly_extract_summary_from(appname)
-          end
-          result << [appname, summary, '  ']
-        rescue StandardError, LoadError
-          error_message = _("!%{sub_command}! Subcommand unavailable due to error.") % { sub_command: appname }
-          error_message += ' ' + _("Check error logs.")
-          result << [error_message, '', '  ']
-        end
+        result << generate_summary(appname)
       end
     end
   end
 
   COMMON = 'Common:'
   SPECIALIZED = 'Specialized:'
   BLANK = "\n"
+  COMMON_APPS = %w[apply agent config help lookup module resource]
   def available_application_names_special_sort
     full_list = Puppet::Application.available_application_names
-    a_list = full_list & %w[apply agent config help lookup module resource]
+    a_list = full_list & COMMON_APPS
     a_list = a_list.sort
     also_ran = full_list - a_list
     also_ran = also_ran.sort
     [[COMMON], a_list, [BLANK], [SPECIALIZED], also_ran].flatten(1)
   end
 
+  def common_app_summaries
+    COMMON_APPS.map do |appname|
+      generate_summary(appname)
+    end
+  end
+
+  def specialized_app_summaries
+    specialized_apps = Puppet::Application.available_application_names - COMMON_APPS
+    specialized_apps.filter_map do |appname|
+      generate_summary(appname) unless exclude_from_docs?(appname)
+    end
+  end
+
   def horribly_extract_summary_from(appname)
     help = Puppet::Application[appname].help.split("\n")
     # Now we find the line with our summary, extract it, and return it.  This

lib/puppet/reference/configuration.rb

@@ -43,6 +43,8 @@
       val = "the Host's fully qualified domain name, as determined by Facter"
     when 'srv_domain'
       val = 'example.com'
+    when 'http_user_agent'
+      val = 'Puppet/<version> Ruby/<version> (<architecture>)'
     end
 
     # Leave out the section information; it was apparently confusing people.

lib/puppet/settings.rb

@@ -81,11 +81,11 @@ def self.default_certname
   end
 
   def self.hostname_fact
-    Puppet.runtime[:facter].value 'networking.hostname'
+    ENV['PUPPET_REFERENCES_HOSTNAME'] || Puppet.runtime[:facter].value('networking.hostname')
   end
 
   def self.domain_fact
-    Puppet.runtime[:facter].value 'networking.domain'
+    ENV['PUPPET_REFERENCES_DOMAIN'] || Puppet.runtime[:facter].value('networking.domain')
   end
 
   def self.default_config_file_name

locales/puppet.pot

@@ -6,11 +6,11 @@
 #, fuzzy
 msgid ""
 msgstr ""
-"Project-Id-Version: Puppet automation framework 8.8.0-40-gb8ac6f49a3\n"
+"Project-Id-Version: Puppet automation framework 8.8.0-49-gd70f906d86\n"
 "\n"
 "Report-Msgid-Bugs-To: https://tickets.puppetlabs.com\n"
-"POT-Creation-Date: 2024-08-14 00:21+0000\n"
-"PO-Revision-Date: 2024-08-14 00:21+0000\n"
+"POT-Creation-Date: 2024-08-29 16:36+0000\n"
+"PO-Revision-Date: 2024-08-29 16:36+0000\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <[email protected]>\n"
 "Language: \n"
@@ -797,7 +797,7 @@ msgid "Retrieve the catalog for the node from which the command is run."
 msgstr ""
 
 #: ../lib/puppet/face/catalog.rb:32
-msgid "Not yet implemented for the CLI; facts will be collected internally."
+msgid "Not implemented for the CLI; facts are collected internally."
 msgstr ""
 
 #: ../lib/puppet/face/catalog.rb:103

man/man5/puppet.conf.5

@@ -973,7 +973,7 @@ The time to wait for data to be read from an HTTP connection\. If nothing is rea
 The HTTP User\-Agent string to send when making network requests\.
 .
 .IP "\(bu" 4
-\fIDefault\fR: \fBPuppet/8\.9\.0 Ruby/3\.1\.1\-p18 (x86_64\-linux)\fR
+\fIDefault\fR: \fBPuppet/<version> Ruby/<version> (<architecture>)\fR
 .
 .IP "" 0
 .

man/man8/puppet-catalog.8

@@ -122,7 +122,7 @@ puppet catalog find [\-\-terminus _TERMINUS] [\-\-facts_for_catalog] \fIcertname
 Retrieve the catalog for the node from which the command is run\.
 .
 .IP
-\fBOPTIONS\fR \fI\-\-facts_for_catalog\fR \- Not yet implemented for the CLI; facts will be collected internally\.
+\fBOPTIONS\fR \fI\-\-facts_for_catalog\fR \- Not implemented for the CLI; facts are collected internally\.
 .
 .IP
 \fBRETURNS\fR

man/man8/puppet-filebucket.8

@@ -37,7 +37,7 @@ This is a stand\-alone filebucket client for sending files to a local or central
 Note that \'filebucket\' defaults to using a network\-based filebucket available on the server named \'puppet\'\. To use this, you\'ll have to be running as a user with valid Puppet certificates\. Alternatively, you can use your local file bucket by specifying \'\-\-local\', or by specifying \'\-\-bucket\' with a local path\.
 .
 .P
-\fBNote\fR: 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:
+\fBImportant\fR: 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:
 .
 .IP "\(bu" 4
 Use a \fBfind\fR command and \fBcrontab\fR entry to retain only the last X days of file backups\. For example:

man/man8/puppet.8

@@ -4,25 +4,144 @@
 .TH "PUPPET" "8" "August 2024" "Puppet, Inc." "Puppet manual"
 .
 .SH "NAME"
-\fBpuppet\fR
+\fBpuppet\fR \- an automated configuration management tool
+.
+.SH "SYNOPSIS"
+\fBpuppet\fR \fIsubcommand\fR [options] \fIaction\fR [options]
+.
+.SH "DESCRIPTION"
+Puppet, an automated administrative engine for your Linux, Unix, and Windows systems, performs administrative tasks (such as adding users, installing packages, and updating server configurations) based on a centralized specification\.
+.
+.SH "COMMANDS"
+.
+.SS "Common"
+\fBapply\fR
+.
+.br
+\~\~\~\~Apply Puppet manifests locally
+.
+.P
+\fBagent\fR
+.
+.br
+\~\~\~\~The puppet agent daemon
+.
+.P
+\fBconfig\fR
+.
+.br
+\~\~\~\~Interact with Puppet\'s settings\.
+.
+.P
+\fBhelp\fR
+.
+.br
+\~\~\~\~Display Puppet help\.
+.
+.P
+\fBlookup\fR
+.
+.br
+\~\~\~\~Interactive Hiera lookup
+.
+.P
+\fBmodule\fR
+.
+.br
+\~\~\~\~Creates, installs and searches for modules on the Puppet Forge\.
+.
+.P
+\fBresource\fR
+.
+.br
+\~\~\~\~The resource abstraction layer shell
+.
+.SS "Specialized"
+\fBstrings\fR
+.
+.br
+\~\~\~\~Generate Puppet documentation with YARD\.
+.
+.P
+\fBcatalog\fR
+.
+.br
+\~\~\~\~Compile, save, view, and convert catalogs\.
 .
 .P
-Usage: puppet \fIsubcommand\fR [options] \fIaction\fR [options]
+\fBdescribe\fR
+.
+.br
+\~\~\~\~Display help about resource types
+.
+.P
+\fBdevice\fR
+.
+.br
+\~\~\~\~Manage remote network devices
 .
 .P
-Available subcommands:
+\fBdoc\fR
+.
+.br
+\~\~\~\~Generate Puppet references
 .
 .P
-Common:
+\fBepp\fR
 .
 .br
-agent The puppet agent daemon apply Apply Puppet manifests locally config Interact with Puppet\'s settings\. help Display Puppet help\. lookup Interactive Hiera lookup module Creates, installs and searches for modules on the Puppet Forge\. resource The resource abstraction layer shell
+\~\~\~\~Interact directly with the EPP template parser/renderer\.
 .
 .P
-Specialized:
+\fBfacts\fR
 .
 .br
-catalog Compile, save, view, and convert catalogs\. describe Display help about resource types device Manage remote network devices doc Generate Puppet references epp Interact directly with the EPP template parser/renderer\. facts Retrieve and store facts\. filebucket Store and retrieve files in a filebucket generate Generates Puppet code from Ruby definitions\. node View and manage node definitions\. parser Interact directly with the parser\. plugin Interact with the Puppet plugin system\. script Run a puppet manifests as a script without compiling a catalog ssl Manage SSL keys and certificates for puppet SSL clients
+\~\~\~\~Retrieve and store facts\.
+.
+.P
+\fBfilebucket\fR
+.
+.br
+\~\~\~\~Store and retrieve files in a filebucket
+.
+.P
+\fBgenerate\fR
+.
+.br
+\~\~\~\~Generates Puppet code from Ruby definitions\.
+.
+.P
+\fBnode\fR
+.
+.br
+\~\~\~\~View and manage node definitions\.
+.
+.P
+\fBparser\fR
+.
+.br
+\~\~\~\~Interact directly with the parser\.
+.
+.P
+\fBplugin\fR
+.
+.br
+\~\~\~\~Interact with the Puppet plugin system\.
+.
+.P
+\fBscript\fR
+.
+.br
+\~\~\~\~Run a puppet manifests as a script without compiling a catalog
+.
+.P
+\fBssl\fR
+.
+.br
+\~\~\~\~Manage SSL keys and certificates for puppet SSL clients
+.
+.SH "SEE ALSO"
+See \fBpuppet help <subcommand>\fR for help on a specific subcommand\.
 .
 .P
-See \'puppet help \fIsubcommand\fR \fIaction\fR\' for help on a specific subcommand action\. See \'puppet help \fIsubcommand\fR\' for help on a specific subcommand\. Puppet v8\.9\.0
+See \fBpuppet help <subcommand> <action>\fR for help on a specific subcommand action\.