This commit makes the following changes: * Changes wrapping on some "returns" blocks to accomodate the way we prepend "RETURNS: " to the first line in short help. * Overrides description for save on faces where save is invalid. (Since save has an inherited description, the description was contradicting the summary.) * Adds notes on dummy arguments to short_description where applicable, so as to show up in short help. * Adds the termini list to the action short help template. * Removes the authors block from short help for faces. (Save it for the man page.) * Several trivial wording changes. Reviewed-By: Jacob Helwig <jacob@puppetlabs.com>
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.
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
This is a rebase of the following commits: * (#7563) Add a template for manpages In order to generate manpages in a reasonably maintainable way, we need to format text from the Faces help API for use with Ronn (https://github.com/rtomayko/ronn/). This commit adds a man template to the help templates folder; it has been verified to generate Ronn-friendly input text. It isn't currently called by any applications, but can be demonstrated by exchanging it for face.erb. * (#7634) Change ERB trim mode used in the Faces help API <%= something -%> tags (note the minus) are unavoidably necessary at at least one point in the Faces help templates. ERB objects instantiated with the % trim mode will blow up horribly whenever one of these tags appears. This commit changes the trim mode to `-` and refactors all help templates accordingly. * (#7563) Refactor short help templates This commit attempts to bring the short face and action help templates closer to the goals of fitting cleanly on one screen, fitting the prevailing *nix aesthetic, and being useful without overwhelming the user.
Faces help output relies on input from the documentation methods in each of the faces to be documented. This commit calls those methods in each of our faces, with varying levels of detail depending on their complexity.
We haven't implemented the `man` action yet, so let's not mention it until we have.
This addresses two of the four points: we now quote the subcommand name, and emit 'Usage: ' before the usage information on the puppet command line. Reviewed-By: Nick Lewis <nick@puppetlabs.com>
This extends the last of the documentation support, down into options, so they can be described as expected. In the process we split out the modular docs API into a full and short version options only want short docs, but the behaviours are identical to the full version.
This adds the remaining documentation mechanisms to the Face instances, allowing them to build and report correct documentation, licensing and ownership for the help face to build on.
After some discussion we decided that most uses of the Puppet Face infrastructure were about single faces on their own, not about the collection, and so we were better referring to Puppet::Face[...] in code. This implements that by translating names and references in the Ruby code to the new, s-less, name.