diff options
| author | nfagerlund <nick.fagerlund@gmail.com> | 2011-06-03 10:28:52 -0700 |
|---|---|---|
| committer | nfagerlund <nick.fagerlund@gmail.com> | 2011-06-07 14:08:39 -0700 |
| commit | 17723634875e308b2752efed8ebdfd3db3239215 (patch) | |
| tree | 7875a3832c4b1a9acccb12ba1609da997c8cac1d /lib/puppet/face/help | |
| parent | 5a9998e41bc442ca66ca2ff151750355d2ef6d6f (diff) | |
| download | puppet-17723634875e308b2752efed8ebdfd3db3239215.tar.gz puppet-17723634875e308b2752efed8ebdfd3db3239215.tar.xz puppet-17723634875e308b2752efed8ebdfd3db3239215.zip | |
(#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.
Diffstat (limited to 'lib/puppet/face/help')
| -rw-r--r-- | lib/puppet/face/help/action.erb | 2 | ||||
| -rw-r--r-- | lib/puppet/face/help/man.erb | 8 |
2 files changed, 5 insertions, 5 deletions
diff --git a/lib/puppet/face/help/action.erb b/lib/puppet/face/help/action.erb index 94b935fed..5242ed218 100644 --- a/lib/puppet/face/help/action.erb +++ b/lib/puppet/face/help/action.erb @@ -2,7 +2,7 @@ USAGE: <%= action.synopsis %> <% end -%> -<%= action.short_description || action.summary || face.summary || "undocumented face" %> +<%= action.short_description || action.summary || face.summary || "undocumented subcommand" %> <% if action.returns -%> RETURNS: <%= action.returns.strip %> diff --git a/lib/puppet/face/help/man.erb b/lib/puppet/face/help/man.erb index 0122d974c..90e27964c 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 || "Undocumented face." %> +puppet-<%= face.name %>(8) -- <%= face.summary || "Undocumented subcommand." %> <%= '=' * (_erbout.length - 1) %> <% if face.synopsis -%> @@ -116,9 +116,9 @@ NOTES <% end # notes if face.respond_to? :indirection -%> -This is an indirector face, which exposes `find`, `search`, `save`, and -`destroy` actions for an indirected subsystem of Puppet. Valid termini -for this face include: +This subcommand is an indirector face, which exposes `find`, `search`, `save`, +and `destroy` actions for an indirected subsystem of Puppet. Valid termini for +this face include: * `<%= face.class.terminus_classes(face.indirection.name).join("`\n* `") %>` |