From 17723634875e308b2752efed8ebdfd3db3239215 Mon Sep 17 00:00:00 2001 From: nfagerlund Date: Fri, 3 Jun 2011 10:28:52 -0700 Subject: (#7764, 7775, 7778) Revisions to Faces help text Per UX review of help text, this commit makes several changes over the breadth of the Faces help: * Preface API-only action summaries/descriptions with "API only." (issue #7775) * Provide both CLI and API info in "returns," with the CLI info first. (issue #7778) * Summaries should be sentences. (Add punctuation.) * First sentences of descriptions should reiterate summaries. (Summaries and descriptions should be displayed far enough apart that this isn't a problem.) * Standardize on "subcommand" instead of "face" when talking about the entity you invoke at the command line. (Use "face" when describing API use.) * Fix outdated or clunky text in several faces. --- lib/puppet/face/plugin.rb | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) (limited to 'lib/puppet/face/plugin.rb') diff --git a/lib/puppet/face/plugin.rb b/lib/puppet/face/plugin.rb index 541468d39..76c79f38d 100644 --- a/lib/puppet/face/plugin.rb +++ b/lib/puppet/face/plugin.rb @@ -5,13 +5,13 @@ Puppet::Face.define(:plugin, '0.0.1') do summary "Interact with the Puppet plugin system." description <<-'EOT' - This face provides network access to the puppet master's store of + This subcommand provides network access to the puppet master's store of plugins. - EOT - notes <<-'EOT' - The puppet master can serve Ruby code collected from the lib directories + + The puppet master serves Ruby code collected from the `lib` directories of its modules. These plugins can be used on agent nodes to extend - Facter and implement custom types and providers. + Facter and implement custom types and providers. Plugins are normally + downloaded by puppet agent during the course of a run. EOT action :download do @@ -19,12 +19,13 @@ Puppet::Face.define(:plugin, '0.0.1') do description <<-'EOT' Downloads plugins from the configured puppet master. Any plugins downloaded in this way will be used in all subsequent Puppet activity. + This action modifies files on disk. EOT returns <<-'EOT' - A display-formatted list of the files downloaded. If all plugin - files were in sync, this list will be empty. + A list of the files downloaded, or a confirmation that no files were + downloaded. When used from the Ruby API, this action returns an array of + the files downloaded, which will be empty if none were retrieved. EOT - notes "This action modifies files on disk." examples <<-'EOT' Retrieve plugins from the puppet master: -- cgit