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. Signed-off-by: nfagerlund <[email protected]> --- Local-branch: ticket/2.7.x/7561-help_for_all_faces lib/puppet/face/help.rb | 2 +- lib/puppet/face/help/action.erb | 65 +++++++++++++++----- lib/puppet/face/help/face.erb | 115 +++++++++++++++++++++++----------- lib/puppet/face/help/global.erb | 16 +++--- lib/puppet/face/help/man.erb | 133 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 271 insertions(+), 60 deletions(-) create mode 100644 lib/puppet/face/help/man.erb diff --git a/lib/puppet/face/help.rb b/lib/puppet/face/help.rb index 7a382b8..9376adf 100644 --- a/lib/puppet/face/help.rb +++ b/lib/puppet/face/help.rb @@ -95,7 +95,7 @@ Puppet::Face.define(:help, '0.0.1') do def erb(name) template = (Pathname(__FILE__).dirname + "help" + name) - erb = ERB.new(template.read, nil, '%') + erb = ERB.new(template.read, nil, '-') erb.filename = template.to_s return erb end diff --git a/lib/puppet/face/help/action.erb b/lib/puppet/face/help/action.erb index aab7f25..c788f34 100644 --- a/lib/puppet/face/help/action.erb +++ b/lib/puppet/face/help/action.erb @@ -1,22 +1,57 @@ -puppet <%= face.name %><%= action.default? ? '' : " #{action.name}" %> - <%= action.summary || face.summary %> +<%= action.summary || face.summary || "unknown face..." %> -% if action.synopsis -usage: <%= action.synopsis %> +<% if action.synopsis -%> +USAGE: <%= action.synopsis %> -% end -% if action.description or action.short_description -<%= action.short_description %> +<% end -%> +<% if action.short_description -%> +<%= action.short_description.strip %> -%end -% unless action.options.empty? +<% end -%> +<% if action.returns -%> +RETURNS: <%= action.returns.strip %> + +<% end -%> OPTIONS: -% action.options.sort.each do |name| -% option = action.get_option name -<%= " " + option.optparse.join(" |" ) %> - <%= option.summary %> +<%# Remove these options once we can introspect them normally. -%> + --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. +<% unless action.options.empty? + optionroom = 30 + summaryroom = 80 - 5 - optionroom + action.options.sort.each do |name| + option = action.get_option name -%> +<%= " " + option.optparse.join(" | ")[0,(optionroom - 1)].ljust(optionroom) + ' - ' -%> +<% if !(option.summary) -%> +unknown option... +<% elsif option.summary.length <= summaryroom -%> +<%= option.summary %> +<% + else + words = option.summary.split + wrapped = [''] + i = 0 + words.each do |word| + if wrapped[i].length + word.length <= summaryroom + wrapped[i] << word + ' ' + else + i += 1 + wrapped[i] = word + ' ' + end + end +-%> +<%= wrapped.shift.strip %> +<% wrapped.each do |line| -%> +<%= (' ' * (optionroom + 5) ) + line.strip %> +<% end + end + end -%> +<% end -%> -% end -% end -% if action.examples +<% if action.examples -%> EXAMPLES: <%= action.examples %> -% end +<% end -%> diff --git a/lib/puppet/face/help/face.erb b/lib/puppet/face/help/face.erb index b249981..2a0f018 100644 --- a/lib/puppet/face/help/face.erb +++ b/lib/puppet/face/help/face.erb @@ -1,48 +1,91 @@ -NAME - <%= face.name %> -- <%= face.summary || "unknown face..." %> +<%= face.summary || "unknown face..." %> -% if face.synopsis -SYNOPSIS -<%= face.synopsis.gsub(/^/, ' ') %> +<% if face.synopsis -%> +USAGE: <%= face.synopsis %> -% end -% if face.description -DESCRIPTION -<%= face.description.chomp.gsub(/^/, ' ') %> +<% end -%> +<% if face.short_description -%> +<%= face.short_description %> -%end -% unless face.options.empty? -OPTIONS -% face.options.sort.each do |name| -% option = face.get_option name -<%= " " + option.optparse.join(" |" ) %> +<% end -%> +OPTIONS: +<%# Remove these options once we can introspect them normally. -%> + --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. +<% unless face.options.empty? + optionroom = 30 + summaryroom = 80 - 5 - optionroom + face.options.sort.each do |name| + option = face.get_option name -%> +<%= " " + option.optparse.join(" | ")[0,(optionroom - 1)].ljust(optionroom) + ' - ' -%> +<% if !(option.summary) -%> +unknown option... +<% elsif option.summary.length <= summaryroom -%> <%= option.summary %> -<%= option.description %> +<% + else + words = option.summary.split + wrapped = [''] + i = 0 + words.each do |word| + if wrapped[i].length + word.length <= summaryroom + wrapped[i] << word + ' ' + else + i += 1 + wrapped[i] = word + ' ' + end + end +-%> +<%= wrapped.shift.strip %> +<% wrapped.each do |line| -%> +<%= (' ' * (optionroom + 5) ) + line.strip %> +<% end + end + end -%> +<% end -%> -% end -% end -ACTIONS -% padding = face.actions.map{|x| x.to_s.length}.max + 2 -% face.actions.each do |actionname| -% action = face.get_action(actionname) - <%= action.name.to_s.ljust(padding) %> <%= action.summary %> -% end +ACTIONS: +<% padding = face.actions.map{|x| x.to_s.length}.max + 2 + summaryroom = 80 - (padding + 4) + face.actions.each do |actionname| + action = face.get_action(actionname) -%> + <%= action.name.to_s.ljust(padding) + ' ' -%> +<% if !(action.summary) -%> +unknown action... +<% elsif action.summary.length <= summaryroom -%> +<%= action.summary %> +<% else + words = action.summary.split + wrapped = [''] + i = 0 + words.each do |word| + if wrapped[i].length + word.length <= summaryroom + wrapped[i] << word + ' ' + else + i += 1 + wrapped[i] = word + ' ' + end + end +-%> +<%= wrapped.shift.strip %> +<% wrapped.each do |line| -%> +<%= (' ' * (padding + 4) ) + line.strip %> +<% end + end +end -%> -% if face.examples -EXAMPLES -<%= face.examples %> -% end -% if face.notes -NOTES -<%= face.notes %> +<% if face.respond_to? :indirection -%> +TERMINI: <%= face.class.terminus_classes(face.indirection.name).join(", ") %> -% end -% unless face.authors.empty? +<% end + unless face.authors.empty? -%> AUTHOR <%= face.authors.join("\n").gsub(/^/, ' * ') %> -%end -COPYRIGHT AND LICENSE +<% end -%> +COPYRIGHT AND LICENSE: <%= face.copyright.gsub(/^/, ' ') %> <%= face.license.gsub(/^/, ' ') %> - diff --git a/lib/puppet/face/help/global.erb b/lib/puppet/face/help/global.erb index 80c77ad..c5a9ec9 100644 --- a/lib/puppet/face/help/global.erb +++ b/lib/puppet/face/help/global.erb @@ -1,18 +1,18 @@ Usage: puppet <subcommand> [options] <action> [options] Available subcommands, from Puppet Faces: -% Puppet::Face.faces.sort.each do |name| -% face = Puppet::Face[name, :current] +<% Puppet::Face.faces.sort.each do |name| + face = Puppet::Face[name, :current] -%> <%= face.name.to_s.ljust(16) %> <%= face.summary %> -% end +<% end -%> -% unless legacy_applications.empty? then # great victory when this is true! +<% unless legacy_applications.empty? then # great victory when this is true! -%> Available applications, soon to be ported to Faces: -% legacy_applications.each do |appname| -% summary = horribly_extract_summary_from appname +<% legacy_applications.each do |appname| + summary = horribly_extract_summary_from appname -%> <%= appname.to_s.ljust(16) %> <%= summary %> -% end -% end +<% end + end -%> See 'puppet help <subcommand> <action>' for help on a specific subcommand action. See 'puppet help <subcommand>' for help on a specific subcommand. diff --git a/lib/puppet/face/help/man.erb b/lib/puppet/face/help/man.erb new file mode 100644 index 0000000..899d016 --- /dev/null +++ b/lib/puppet/face/help/man.erb @@ -0,0 +1,133 @@ +puppet-<%= face.name %>(8) -- <%= face.summary || "Unknown face." %> +<%= '=' * (_erbout.length - 1) %> + +<% if face.synopsis -%> +SYNOPSIS +-------- +<%= face.synopsis %> + +<% end + if face.description -%> +DESCRIPTION +----------- +<%= face.description.strip %> + +<% end -%> +OPTIONS +------- +Note that any configuration parameter that's valid in the configuration +file is also a valid long argument, although it may or may not be +relevant to the present action. For example, `server` is a valid +configuration parameter, so you can specify `--server <servername>` as +an argument. + +See the configuration file documentation at +<http://docs.puppetlabs.com/references/stable/configuration.html> for the +full list of acceptable parameters. A commented list of all +configuration options can also be generated by running puppet with +`--genconfig`. + +* --mode MODE: + The run mode to use for the current action. Valid modes are `user`, `agent`, + 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 + sometimes available. +* --verbose: + Whether to log verbosely. +* --debug: + Whether to log debug information. +<% unless face.options.empty? + face.options.sort.each do |name| + option = face.get_option name -%> +<%= "* " + option.optparse.join(" | " ) %>: +<%= option.description.gsub(/^/, ' ') || ' ' + option.summary %> +<% end + end -%> + +ACTIONS +------- +<% face.actions.each do |actionname| + action = face.get_action(actionname) -%> +* `<%= action.name.to_s %>` - <%= action.summary %>: +<% if action.synopsis -%> + `SYNOPSIS` + + <%= action.synopsis %> + +<% end -%> +<% if action.description -%> + `DESCRIPTION` + +<%= action.description.gsub(/^/, ' ') %> +<% end + unique_options = action.options - face.options + unless unique_options.empty? -%> + `OPTIONS` + +<% unique_options.sort.each do |name| + option = action.get_option name + text = option.description || option.summary -%> + <%= '<' + option.optparse.join("> | <") + '>' %> - +<%= text.gsub(/^/, ' ') %> +<% end -%> + +<% end -%> +<% if action.returns -%> + `RETURNS` + +<%= action.returns.gsub(/^/, ' ') %> + +<% end + if action.notes -%> + `NOTES` + +<%= action.notes.gsub(/^/, ' ') %> + +<% end + end + if face.examples or face.actions.any? {|actionname| face.get_action(actionname).examples} -%> +EXAMPLES +-------- +<% end + if face.examples -%> +<%= face.examples %> + +<% end + face.actions.each do |actionname| + action = face.get_action(actionname) + if action.examples -%> +`<%= action.name.to_s %>` + +<%= action.examples.strip %> +<% end + end -%> + +<% if face.notes or face.respond_to? :indirection -%> +NOTES +----- +<% if face.notes -%> +<%= face.notes.strip %> + +<% 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: + +* `<%= face.class.terminus_classes(face.indirection.name).join("`\n* `") %>` + +<% end # indirection + end # notes or indirection + unless face.authors.empty? -%> +AUTHOR +------ +<%= face.authors.join("\n").gsub(/^/, ' * ') %> + +<% end -%> +COPYRIGHT AND LICENSE +--------------------- +<%= face.copyright %> +<%= face.license %> + -- 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.
