Per UX review of help output, this commit makes several changes to templates and shared help text:
* Change "unknown" to "undocumented" * Remove copyright from short help * Point readers to the man pages (issue 7773) * Remove examples from short help (issue 7776) * Remove summary from short help and make it a fallback for description * Edit common option summaries to fit on a single 80-col line Signed-off-by: nfagerlund <[email protected]> --- Local-branch: ticket/2.7rc/7764-Faces_help_revisions lib/puppet/face/help/action.erb | 16 ++++------------ lib/puppet/face/help/face.erb | 17 +++++------------ lib/puppet/face/help/man.erb | 14 +++++++++----- lib/puppet/indirector/face.rb | 2 +- 4 files changed, 19 insertions(+), 30 deletions(-) diff --git a/lib/puppet/face/help/action.erb b/lib/puppet/face/help/action.erb index c788f34..94b935f 100644 --- a/lib/puppet/face/help/action.erb +++ b/lib/puppet/face/help/action.erb @@ -1,21 +1,16 @@ -<%= action.summary || face.summary || "unknown face..." %> - <% if action.synopsis -%> USAGE: <%= action.synopsis %> <% end -%> -<% if action.short_description -%> -<%= action.short_description.strip %> +<%= action.short_description || action.summary || face.summary || "undocumented face" %> -<% end -%> <% if action.returns -%> RETURNS: <%= action.returns.strip %> <% end -%> OPTIONS: <%# Remove these options once we can introspect them normally. -%> - --mode MODE - The run mode to use (`user`, `agent`, or - `master`). + --mode MODE - The run mode to use (user, agent, or master). --render-as FORMAT - The rendering format to use. --verbose - Whether to log verbosely. --debug - Whether to log debug information. @@ -26,7 +21,7 @@ OPTIONS: option = action.get_option name -%> <%= " " + option.optparse.join(" | ")[0,(optionroom - 1)].ljust(optionroom) + ' - ' -%> <% if !(option.summary) -%> -unknown option... +undocumented option <% elsif option.summary.length <= summaryroom -%> <%= option.summary %> <% @@ -51,7 +46,4 @@ unknown option... end -%> <% end -%> -<% if action.examples -%> -EXAMPLES: -<%= action.examples %> -<% end -%> +See 'puppet man <%= face.name %>' or 'man puppet-<%= face.name %>' for full help. diff --git a/lib/puppet/face/help/face.erb b/lib/puppet/face/help/face.erb index 2a0f018..870cc54 100644 --- a/lib/puppet/face/help/face.erb +++ b/lib/puppet/face/help/face.erb @@ -1,17 +1,12 @@ -<%= face.summary || "unknown face..." %> - <% if face.synopsis -%> USAGE: <%= face.synopsis %> <% end -%> -<% if face.short_description -%> -<%= face.short_description %> +<%= (face.short_description || face.summary || "undocumented subcommand").strip %> -<% end -%> OPTIONS: <%# Remove these options once we can introspect them normally. -%> - --mode MODE - The run mode to use (`user`, `agent`, or - `master`). + --mode MODE - The run mode to use (user, agent, or master). --render-as FORMAT - The rendering format to use. --verbose - Whether to log verbosely. --debug - Whether to log debug information. @@ -22,7 +17,7 @@ OPTIONS: option = face.get_option name -%> <%= " " + option.optparse.join(" | ")[0,(optionroom - 1)].ljust(optionroom) + ' - ' -%> <% if !(option.summary) -%> -unknown option... +undocumented option <% elsif option.summary.length <= summaryroom -%> <%= option.summary %> <% @@ -54,7 +49,7 @@ ACTIONS: action = face.get_action(actionname) -%> <%= action.name.to_s.ljust(padding) + ' ' -%> <% if !(action.summary) -%> -unknown action... +undocumented action <% elsif action.summary.length <= summaryroom -%> <%= action.summary %> <% else @@ -86,6 +81,4 @@ AUTHOR <%= face.authors.join("\n").gsub(/^/, ' * ') %> <% end -%> -COPYRIGHT AND LICENSE: -<%= face.copyright.gsub(/^/, ' ') %> -<%= face.license.gsub(/^/, ' ') %> +See 'puppet man <%= face.name %>' or 'man puppet-<%= face.name %>' for full help. diff --git a/lib/puppet/face/help/man.erb b/lib/puppet/face/help/man.erb index 6f21fe4..0122d97 100644 --- a/lib/puppet/face/help/man.erb +++ b/lib/puppet/face/help/man.erb @@ -1,4 +1,4 @@ -puppet-<%= face.name %>(8) -- <%= face.summary || "Unknown face." %> +puppet-<%= face.name %>(8) -- <%= face.summary || "Undocumented face." %> <%= '=' * (_erbout.length - 1) %> <% if face.synopsis -%> @@ -32,7 +32,7 @@ configuration options can also be generated by running puppet with and `master`. * --render-as FORMAT: The format in which to render output. The most common formats are `json`, - `s` (string), and `yaml`, but other options such as `dot` are + `s` (string), `yaml`, and `console`, but other options such as `dot` are sometimes available. * --verbose: Whether to log verbosely. @@ -57,12 +57,15 @@ ACTIONS <%= action.synopsis %> <% end -%> -<% if action.description -%> `DESCRIPTION` +<% if action.description -%> <%= action.description.gsub(/^/, ' ') %> -<% end - unique_options = action.options - face.options +<% else -%> + <%= action.summary || "Undocumented action." %> +<% end -%> + +<% unique_options = action.options - face.options unless unique_options.empty? -%> `OPTIONS` @@ -101,6 +104,7 @@ EXAMPLES `<%= action.name.to_s %>` <%= action.examples.strip %> + <% end end -%> diff --git a/lib/puppet/indirector/face.rb b/lib/puppet/indirector/face.rb index 756306a..bb8ce2c 100644 --- a/lib/puppet/indirector/face.rb +++ b/lib/puppet/indirector/face.rb @@ -2,7 +2,7 @@ require 'puppet/face' class Puppet::Indirector::Face < Puppet::Face option "--terminus TERMINUS" do - summary "The indirector terminus to use for this action." + summary "The indirector terminus to use." description <<-EOT Indirector faces expose indirected subsystems of Puppet. These subsystems are each able to retrieve and alter a specific type of data -- 1.7.3.3 -- You received this message because you are subscribed to the Google Groups "Puppet Developers" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/puppet-dev?hl=en.
