(MAINT) Copy-edited all the user-visible messages

lib/pdk/answer_file.rb

@@ -53,7 +53,7 @@ def [](question)
     # @raise (see #save_to_disk)
     def update!(new_answers = {})
       unless new_answers.is_a?(Hash)
-        raise PDK::CLI::FatalError, _('Answer file can only be updated with a Hash')
+        raise PDK::CLI::FatalError, _('Answer file can be updated only with a Hash')
       end
 
       answers.merge!(new_answers)

lib/pdk/cli.rb

@@ -33,7 +33,7 @@ def self.run(args)
   end
 
   def self.template_url_option(dsl)
-    dsl.option nil, 'template-url', _('Specifies the URL to the template to use when creating new modules, and other parts.'), argument: :required, default: PDK::Generate::Module.default_template_url
+    dsl.option nil, 'template-url', _('Specifies the URL to the template to use when creating new modules or classes.'), argument: :required, default: PDK::Generate::Module.default_template_url
   end
 
   @base_cmd = Cri::Command.define do
@@ -43,21 +43,21 @@ def self.template_url_option(dsl)
     description _('The shortest path to better modules.')
     default_subcommand 'help'
 
-    flag nil, :version, _('show version of pdk') do |_, _|
+    flag nil, :version, _('Show version of pdk.') do |_, _|
       puts PDK::Util::Version.version_string
       exit 0
     end
 
-    flag :h, :help, _('show help for this command') do |_, c|
+    flag :h, :help, _('Show help for this command.') do |_, c|
       puts c.help
       exit 0
     end
 
     format_desc = _(
       "Specify desired output format. Valid formats are '%{available_formats}'. " \
-      'You may also specify a file to which the formatted output will be directed, ' \
+      'You may also specify a file to which the formatted output is sent, ' \
       "for example: '--format=junit:report.xml'. This option may be specified " \
-      'multiple times as long as each option specifies a distinct target file.',
+      'multiple times if each option specifies a distinct target file.',
     ) % { available_formats: PDK::Report.formats.join("', '") }
 
     option :f, :format, format_desc, argument: :required, multiple: true do |values|
@@ -68,7 +68,7 @@ def self.template_url_option(dsl)
       PDK.logger.enable_debug_output
     end
 
-    option nil, 'answer-file', _('Path to an answer file'), argument: :required, hidden: true do |value|
+    option nil, 'answer-file', _('Path to an answer file.'), argument: :required, hidden: true do |value|
       PDK.answer_file = value
     end
   end

lib/pdk/cli/bundle.rb

@@ -4,8 +4,8 @@ module PDK::CLI
     name 'bundle'
     usage _('bundle -- [bundler_options]')
     summary _('escape hatch to bundler')
-    description _('[experimental] For advanced users, this allows to run arbitrary commands in the bundler environment that the pdk manages. ' \
-      'Careless use of this command can lead to errors later which can\'t be recovered by the pdk itself.')
+    description _('[experimental] For advanced users, pdk bundle runs arbitrary commands in the bundler environment that pdk manages.' \
+      'Careless use of this command can lead to errors that pdk can\'t help recover from.')
 
     run do |_opts, args, _cmd|
       PDK::CLI::Util.ensure_in_module!

lib/pdk/cli/errors.rb

@@ -3,7 +3,7 @@ module CLI
     class FatalError < StandardError
       attr_reader :exit_code
 
-      def initialize(msg = _('An unexpected error has occurred, try running the command again with --debug'), exit_code = 1)
+      def initialize(msg = _('An unexpected error has occurred. Try running the command again with --debug'), exit_code = 1)
         @exit_code = exit_code
         super(msg)
       end

lib/pdk/cli/exec.rb

@@ -53,15 +53,15 @@ def self.bundle_bin
 
       def self.try_vendored_bin(vendored_bin_path, fallback)
         unless PDK::Util.package_install?
-          PDK.logger.debug(_("PDK package installation not found, trying '%{fallback}' from the system PATH instead") % { fallback: fallback })
+          PDK.logger.debug(_("PDK package installation not found. Trying '%{fallback}' from the system PATH instead.") % { fallback: fallback })
           return fallback
         end
 
         if File.exist?(File.join(PDK::Util.pdk_package_basedir, vendored_bin_path))
-          PDK.logger.debug(_("Using '%{vendored_bin_path}' from PDK package") % { vendored_bin_path: vendored_bin_path })
+          PDK.logger.debug(_("Using '%{vendored_bin_path}' from PDK package.") % { vendored_bin_path: vendored_bin_path })
           File.join(PDK::Util.pdk_package_basedir, vendored_bin_path)
         else
-          PDK.logger.debug(_("Could not find '%{vendored_bin_path}' in PDK package, trying '%{fallback}' from the system PATH instead") % { fallback: fallback, vendored_bin_path: vendored_bin_path })
+          PDK.logger.debug(_("Could not find '%{vendored_bin_path}' in PDK package. Trying '%{fallback}' from the system PATH instead.") % { fallback: fallback, vendored_bin_path: vendored_bin_path })
           fallback
         end
       end
@@ -99,7 +99,7 @@ def initialize(*argv)
 
         def context=(new_context)
           unless [:system, :module].include?(new_context)
-            raise ArgumentError, _("Expected execution context to be :system or :module but got '%{context}'") % { context: new_context }
+            raise ArgumentError, _("Expected execution context to be :system or :module but got '%{context}'.") % { context: new_context }
           end
 
           @context = new_context

lib/pdk/cli/new.rb

@@ -4,7 +4,7 @@ module PDK::CLI
     name 'new'
     usage _('new <type> [options]')
     summary _('create a new module, etc.')
-    description _('Creates a new instance of <type> using the options relevant to that type of thing')
+    description _('Creates a new instance of <type> using relevant options.')
     default_subcommand 'help'
   end
 

lib/pdk/cli/util.rb

@@ -6,7 +6,7 @@ module Util
       # @raise [PDK::CLI::FatalError] if the current directory or parents do
       #   not contain a `metadata.json` file.
       def ensure_in_module!
-        message = _('This command must be run from inside a module (no metadata.json found)')
+        message = _('This command must be run from inside a valid module (no metadata.json found).')
         raise PDK::CLI::FatalError, message if PDK::Util.module_root.nil?
       end
       module_function :ensure_in_module!

lib/pdk/cli/validate.rb

@@ -6,16 +6,16 @@ module PDK::CLI
     usage _('validate [validators] [options] [targets]')
     summary _('Run static analysis tests.')
     description _(
-      "Run metadata, puppet, or ruby validation.\n\n" \
-      '[validators] is an optional comma separated list of validators to use. ' \
-      "If not specified, all validators will be used.\n\n" \
-      '[targets] is an optional space separated list of files or directories to be validated. ' \
-      'If not specified, the validators will be run against all applicable files in the module.',
+      "Run metadata, Puppet, or Ruby validation.\n\n" \
+      '[validators] is an optional comma-separated list of validators to use. ' \
+      "If not specified, all validators are used.\n\n" \
+      '[targets] is an optional space-separated list of files or directories to be validated. ' \
+      'If not specified, validators are run against all applicable files in the module.',
     )
 
-    flag nil, :list, _('list all available validators')
-    flag :a, 'auto-correct', _('automatically correct problems (where possible)')
-    flag nil, :parallel, _('run validations in parallel')
+    flag nil, :list, _('List all available validators.')
+    flag :a, 'auto-correct', _('Automatically correct problems where possible.')
+    flag nil, :parallel, _('Run validations in parallel.')
 
     run do |opts, args, _cmd|
       if args == ['help']
@@ -44,7 +44,7 @@ module PDK::CLI
 
           invalid = vals.reject { |v| validator_names.include?(v) }
           invalid.each do |v|
-            PDK.logger.warn(_("Unknown validator '%{v}'. Available validators: %{validators}") % { v: v, validators: validator_names.join(', ') })
+            PDK.logger.warn(_("Unknown validator '%{v}'. Available validators: %{validators}.") % { v: v, validators: validator_names.join(', ') })
           end
         else
           # This is a single item. Check if it's a known validator, or otherwise treat it as a target.

lib/pdk/generators/module.rb

@@ -73,7 +73,7 @@ def self.invoke(opts = {})
         begin
           if FileUtils.mv(temp_target_dir, target_dir)
             PDK.logger.info(_('Module \'%{name}\' generated at path \'%{path}\'.') % { name: opts[:name], path: target_dir })
-            PDK.logger.info(_('In your new module directory, add classes with the \'pdk new class\' command.'))
+            PDK.logger.info(_('In your module directory, add classes with the \'pdk new class\' command.'))
           end
         rescue Errno::EACCES => e
           raise PDK::CLI::FatalError, _("Failed to move '%{source}' to '%{target}': %{message}") % {
@@ -90,7 +90,7 @@ def self.username_from_login
         login_clean = 'username' if login_clean.empty?
 
         if login_clean != login
-          PDK.logger.warn _('Your username is not a valid Forge username, proceeding with the username %{username}. You can fix this afterwards in metadata.json.') % {
+          PDK.logger.warn _('Your username is not a valid Forge username. Proceeding with the username %{username}. You can fix this later in metadata.json.') % {
             username: login_clean,
           }
         end
@@ -163,7 +163,7 @@ def self.module_interview(metadata, opts = {})
           {
             name:     'author',
             question: _('Who wrote this module?'),
-            help:     _('This will be used to credit the module\'s author.'),
+            help:     _('This is used to credit the module\'s author.'),
             required: true,
             default:  metadata.data['author'],
           },
@@ -176,28 +176,28 @@ def self.module_interview(metadata, opts = {})
           },
           {
             name:     'summary',
-            question: _('Please summarize the purpose of this module in a single sentence.'),
-            help:     _('This will help other Puppet users understand what the module does.'),
+            question: _('Summarize the purpose of this module in a single sentence.'),
+            help:     _('This helps other Puppet users understand what the module does.'),
             required: true,
             default:  metadata.data['summary'],
           },
           {
             name:     'source',
             question: _('If there is a source code repository for this module, enter the URL here.'),
-            help:     _('Skip this if none exists yet, you can update this later in the metadata.json.'),
+            help:     _('Skip this if no repository exists yet. You can update this later in the metadata.json.'),
             required: true,
             default:  metadata.data['source'],
           },
           {
             name:     'project_page',
             question: _('If there is a URL where others can learn more about this module, enter it here.'),
-            help:     _('Optional. As with all questions above, you can update this later in the metadata.json.'),
+            help:     _('Optional. You can update this later in the metadata.json.'),
             default:  metadata.data['project_page'],
           },
           {
             name:     'issues_url',
             question: _('If there is a public issue tracker for this module, enter its URL here.'),
-            help:     _('Optional. As with all questions above, you can update this later in the metadata.json.'),
+            help:     _('Optional. You can update this later in the metadata.json.'),
             default:  metadata.data['issues_url'],
           },
         ]
@@ -211,17 +211,17 @@ def self.module_interview(metadata, opts = {})
         interview.add_questions(questions)
 
         puts _(
-          "\nWe need to create a metadata.json file for this module, so we\'re going to ask you %{count} quick " \
+          "\nWe need to create a metadata.json file for this module, so we\'re going to ask you %{count} " \
           "questions.\n" \
-          'If the question is not applicable to this module, simply leave the answer blank and skip. A default option ' \
-          'is shown after each question. You can modify this or any other answers at any time by manually updating ' \
+          'If the question is not applicable to this module, accept the default option ' \
+          'shown after each question. You can modify any answers at any time by manually updating ' \
           "the metadata.json file.\n\n",
         ) % { count: interview.num_questions }
 
         answers = interview.run
 
         if answers.nil?
-          PDK.logger.info _('Interview cancelled, not generating the module.')
+          PDK.logger.info _('Interview cancelled; not generating the module.')
           exit 0
         end
 
@@ -238,7 +238,7 @@ def self.module_interview(metadata, opts = {})
         puts
 
         continue = prompt.yes?(_('About to generate this module; continue?')) do |q|
-          q.validate(proc { |value| [true, false].include?(value) || value =~ %r{\A(?:yes|y|no|n)\Z}i }, _('Please answer "yes" or "no"'))
+          q.validate(proc { |value| [true, false].include?(value) || value =~ %r{\A(?:yes|y|no|n)\Z}i }, _('Answer "Y" to continue or "n" to cancel.'))
         end
 
         unless continue

lib/pdk/generators/puppet_class.rb

@@ -28,8 +28,8 @@ def target_object_path
         end
       end
 
-      # Calculates the path to the file that the tests for the new class will
-      # be written to.
+      # Calculates the path to the file where the tests for the new class will
+      # be written.
       #
       # @return [String] the path where the tests for the new class will be
       # written.

lib/pdk/generators/puppet_object.rb

@@ -85,7 +85,7 @@ def object_type
       def run
         [target_object_path, target_spec_path].each do |target_file|
           if File.exist?(target_file)
-            raise PDK::CLI::FatalError, _("Unable to generate class, '%{file}' already exists.") % { file: target_file }
+            raise PDK::CLI::FatalError, _("Unable to generate class; '%{file}' already exists.") % { file: target_file }
           end
         end
 
@@ -165,7 +165,7 @@ def with_templates
               # TODO: refactor to a search-and-execute form instead
               return # work is done # rubocop:disable Lint/NonLocalExitFromIterator
             elsif template[:allow_fallback]
-              PDK.logger.debug(_('Unable to find a %{type} template in %{url}, trying next template directory') % { type: object_type, url: template[:url] })
+              PDK.logger.debug(_('Unable to find a %{type} template in %{url}; trying next template directory.') % { type: object_type, url: template[:url] })
             else
               raise PDK::CLI::FatalError, _('Unable to find the %{type} template in %{url}.') % { type: object_type, url: template[:url] }
             end

lib/pdk/module/metadata.rb

@@ -44,11 +44,11 @@ def initialize(params = {})
 
       def self.from_file(metadata_json_path)
         unless File.file?(metadata_json_path)
-          raise ArgumentError, _("'%{file}' does not exist or is not a file") % { file: metadata_json_path }
+          raise ArgumentError, _("'%{file}' does not exist or is not a file.") % { file: metadata_json_path }
         end
 
         unless File.readable?(metadata_json_path)
-          raise ArgumentError, _("Unable to open '%{file}' for reading") % { file: metadata_json_path }
+          raise ArgumentError, _("Unable to open '%{file}' for reading.") % { file: metadata_json_path }
         end
 
         begin
@@ -90,13 +90,13 @@ def validate_name(name)
 
         err = case modname
               when nil, '', :namespace_missing
-                _('the field must be a dash-separated username and module name')
+                _('Field must be a dash-separated user name and module name.')
               when %r{[^a-z0-9_]}i
-                _('the module name contains non-alphanumeric (or underscore) characters')
+                _('Module name must contain only alphanumeric or underscore characters.')
               when %r{^[^a-z]}i
-                _('the module name must begin with a letter')
+                _('Module name must begin with a letter.')
               else
-                _('the namespace contains non-alphanumeric characters')
+                _('Namespace must contain only alphanumeric characters.')
               end
 
         raise ArgumentError, _("Invalid 'name' field in metadata.json: %{err}") % { err: err }

lib/pdk/module/templatedir.rb

@@ -52,7 +52,7 @@ def initialize(path_or_url, module_metadata = {})
           unless clone_result[:exit_code].zero?
             PDK.logger.error clone_result[:stdout]
             PDK.logger.error clone_result[:stderr]
-            raise PDK::CLI::FatalError, _("Unable to clone git repository '%{repo}' to '%{dest}'") % { repo: path_or_url, dest: temp_dir }
+            raise PDK::CLI::FatalError, _("Unable to clone git repository '%{repo}' to '%{dest}'.") % { repo: path_or_url, dest: temp_dir }
           end
 
           @path = PDK::Util.canonical_path(temp_dir)
@@ -178,11 +178,11 @@ def object_config
       # @api private
       def validate_module_template!
         unless File.directory?(@path)
-          raise ArgumentError, _("The specified template '%{path}' is not a directory") % { path: @path }
+          raise ArgumentError, _("The specified template '%{path}' is not a directory.") % { path: @path }
         end
 
         unless File.directory?(@moduleroot_dir) # rubocop:disable Style/GuardClause
-          raise ArgumentError, _("The template at '%{path}' does not contain a 'moduleroot/' directory") % { path: @path }
+          raise ArgumentError, _("The template at '%{path}' does not contain a 'moduleroot/' directory.") % { path: @path }
         end
       end