diff --git a/lib/puppet/face/catalog.rb b/lib/puppet/face/catalog.rb
index 59356d43f..98f550413 100644
--- a/lib/puppet/face/catalog.rb
+++ b/lib/puppet/face/catalog.rb
@@ -1,49 +1,58 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:catalog, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Compile, save, view, and convert catalogs."
 
-  @longdocs = "This face primarily interacts with the compiling subsystem.
-  By default, it compiles a catalog using the default manifest and the
-  hostname from 'certname', but you can choose to retrieve a catalog from
-  the server by specifying '--from rest'.  You can also choose to print any
-  catalog in 'dot' format (for easy graph viewing with OmniGraffle or Graphviz)
-  with '--format dot'."
+  description <<-EOT
+This face primarily interacts with the compiling subsystem.
+By default, it compiles a catalog using the default manifest and the
+hostname from 'certname', but you can choose to retrieve a catalog from
+the server by specifying '--from rest'.  You can also choose to print any
+catalog in 'dot' format (for easy graph viewing with OmniGraffle or Graphviz)
+with '--format dot'.
+  EOT
 
   action(:apply) do
+    summary "apply a Puppet::Resource::Catalog object"
+
     when_invoked do |catalog, options|
       report = Puppet::Transaction::Report.new("apply")
       report.configuration_version = catalog.version
 
       Puppet::Util::Log.newdestination(report)
 
       begin
         benchmark(:notice, "Finished catalog run") do
           catalog.apply(:report => report)
         end
       rescue => detail
         puts detail.backtrace if Puppet[:trace]
         Puppet.err "Failed to apply catalog: #{detail}"
       end
 
       report.finalize_report
       report
     end
   end
 
   action(:download) do
+    summary "download the catalog given the certname and facts"
+
     when_invoked do |certname, facts, options|
       Puppet::Resource::Catalog.indirection.terminus_class = :rest
       facts_to_upload = {:facts_format => :b64_zlib_yaml, :facts => CGI.escape(facts.render(:b64_zlib_yaml))}
       catalog = nil
       retrieval_duration = thinmark do
         catalog = Puppet::Face[:catalog, '0.0.1'].find(certname, facts_to_upload)
       end
       catalog = catalog.to_ral
       catalog.finalize
       catalog.retrieval_duration = retrieval_duration
       catalog.write_class_file
       catalog
     end
   end
 end
diff --git a/lib/puppet/face/certificate.rb b/lib/puppet/face/certificate.rb
index 9ee83d0a2..7f2998da2 100644
--- a/lib/puppet/face/certificate.rb
+++ b/lib/puppet/face/certificate.rb
@@ -1,42 +1,45 @@
 require 'puppet/face/indirector'
 require 'puppet/ssl/host'
 
 Puppet::Face::Indirector.define(:certificate, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "provide access to the CA for certificate management"
 
   option "--ca-location LOCATION" do
     before_action do |action, args, options|
       Puppet::SSL::Host.ca_location = options[:ca_location].to_sym
     end
   end
 
   action :generate do
     summary "Generate a new Certificate Signing Request for HOST"
 
     when_invoked do |name, options|
       host = Puppet::SSL::Host.new(name)
       host.generate_certificate_request
       host.certificate_request.class.indirection.save(host.certificate_request)
     end
   end
 
   action :list do
     summary "List all Certificate Signing Requests"
 
     when_invoked do |options|
       Puppet::SSL::Host.indirection.search("*", {
         :for => :certificate_request,
       }).map { |h| h.inspect }
     end
   end
 
   action :sign do
     summary "Sign a Certificate Signing Request for HOST"
 
     when_invoked do |name, options|
       host = Puppet::SSL::Host.new(name)
       host.desired_state = 'signed'
       Puppet::SSL::Host.indirection.save(host)
     end
   end
 end
diff --git a/lib/puppet/face/certificate_request.rb b/lib/puppet/face/certificate_request.rb
index 4e711b25b..0f7f72205 100644
--- a/lib/puppet/face/certificate_request.rb
+++ b/lib/puppet/face/certificate_request.rb
@@ -1,5 +1,8 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:certificate_request, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Manage certificate requests."
 end
diff --git a/lib/puppet/face/certificate_revocation_list.rb b/lib/puppet/face/certificate_revocation_list.rb
index f111586af..9a8fe303d 100644
--- a/lib/puppet/face/certificate_revocation_list.rb
+++ b/lib/puppet/face/certificate_revocation_list.rb
@@ -1,5 +1,8 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:certificate_revocation_list, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Manage the list of revoked certificates."
 end
diff --git a/lib/puppet/face/config.rb b/lib/puppet/face/config.rb
index d1f6d5a9e..fc685202c 100644
--- a/lib/puppet/face/config.rb
+++ b/lib/puppet/face/config.rb
@@ -1,14 +1,17 @@
 require 'puppet/face'
 
 Puppet::Face.define(:config, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Interact with Puppet configuration options."
 
   action(:print) do
     when_invoked do |*args|
       options = args.pop
       Puppet.settings[:configprint] = args.join(",")
       Puppet.settings.print_config_options
       nil
     end
   end
 end
diff --git a/lib/puppet/face/facts.rb b/lib/puppet/face/facts.rb
index a5a279ddf..88e3c7ba9 100644
--- a/lib/puppet/face/facts.rb
+++ b/lib/puppet/face/facts.rb
@@ -1,20 +1,24 @@
 require 'puppet/face/indirector'
 require 'puppet/node/facts'
 
 Puppet::Face::Indirector.define(:facts, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Retrieve, store, and view facts."
 
-  # Upload our facts to the server
   action(:upload) do
+    summary "upload our facts to the server."
+
     render_as :yaml
 
     when_invoked do |options|
       Puppet::Node::Facts.indirection.terminus_class = :facter
       facts = Puppet::Node::Facts.indirection.find(Puppet[:certname])
       Puppet::Node::Facts.indirection.terminus_class = :rest
       Puppet::Node::Facts.indirection.save(facts)
       Puppet.notice "Uploaded facts for '#{Puppet[:certname]}'"
       nil
     end
   end
 end
diff --git a/lib/puppet/face/file.rb b/lib/puppet/face/file.rb
index 547df3e4f..1b2e62b6d 100644
--- a/lib/puppet/face/file.rb
+++ b/lib/puppet/face/file.rb
@@ -1,7 +1,10 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:file, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Retrieve and store files in a filebucket"
 
   set_indirection_name :file_bucket_file
 end
diff --git a/lib/puppet/face/help.rb b/lib/puppet/face/help.rb
index a762fb02e..07c3ed9b1 100644
--- a/lib/puppet/face/help.rb
+++ b/lib/puppet/face/help.rb
@@ -1,130 +1,133 @@
 require 'puppet/face'
 require 'puppet/util/command_line'
 require 'pathname'
 require 'erb'
 
 Puppet::Face.define(:help, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Displays help about puppet subcommands"
 
   action(:help) do
     summary "Display help about faces and their actions."
 
     option "--version VERSION" do
-      desc "Which version of the interface to show help for"
+      summary "which version of the interface to show help for"
     end
 
     default
     when_invoked do |*args|
       # Check our invocation, because we want varargs and can't do defaults
       # yet.  REVISIT: when we do option defaults, and positional options, we
       # should rewrite this to use those. --daniel 2011-04-04
       options = args.pop
       if options.nil? or args.length > 2 then
         if args.select { |x| x == 'help' }.length > 2 then
           c = "\n !\"'),-./7:;<GIJLST\\_`abcdefhiklmnoprstuwx|}".split('')
           i = <<-'EOT'.gsub(/\s*/, '').to_i(36)
             2s7ytxy5vpj74kbab5xzf1ik2roinzlefaspjrzckiert5xbaxvwlku3a91w7y1rsd
             nenp51gwpulmnrp54nwdil36fjgjarab801y0r5a9nh1hdfgi99arn5c5t3zhxbvzi
             u6wx5r1tb7lun7pro69nrxunqqixsh6qmmv0ms0i0yycqw3pystyzmiita0lpxynqs
             qkbjwadcx82n76wwpzbht8i8rgvqhqick8mk3cs3rvwdjookpgu0rxw4tcezned5sq
             z5x8z9vntyyz0s4h6hjhtwtbytsmmu7ltvdftaixc7fkt276sqm48ab4yv0ot9y26n
             z0xniy4pfl1x300lt6h9c8of49vf799ieuxwnoycsjlmtd4qntzit524j0tdn6n5aj
             mq3z10apjuhkzprvmu53z1gnacymnoforrz5mbqto062kckgw5463pxwzg8liglub4
             ubnr0dln1s6iy3ummxuhim7m5a7yedl3gyy6ow4qqtmsigv27lysooau24zpsccsvx
             ddwygjprqpbwon7i9s1279m1fpinvva8mfh6bgmotrpxsh1c8rc83l3u0utf5i200y
             l7ui0ngcbcjyr4erzdee2tqk3fpjvb82t8xhncruhgn7j5dh2m914qzhb0gkoom47k
             6et7rp4tqjnrv0y2apk5qdl1x1hnbkkxup5ys6ip2ksmtpd3ipmrdtswxr5xwfiqtm
             60uyjr1v79irhnkrbbt4fwhgqjby1qflgwt9c1wpayzzucep6npgbn3f1k6cn4pug3
             1u02wel4tald4hij8m5p49xr8u4ero1ucs5uht42o8nhpmpe7c7xf9t85i85m9m5kk
             tgoqkgbu52gy5aoteyp8jkm3vri9fnkmwa5h60zt8otja72joxjb40p2rz2vp8f8q9
             nnggxt3x90pe5u4048ntyuha78q1oikhhpvw9j083yc3l00hz5ehv9c1au5gvctyap
             zprub289qruve9qsyuh75j04wzkemqw3uhisrfs92u1ahv2qlqxmorgob16c1vbqkx
             ttkoyp2agkt0v5l7lec25p0jqun9y39k41h67aeb5ihiqsftxc9azmg31hc73dk8ur
             lj88vgbmgt8yln9rchw60whgxvnv9zn6cxbr482svctswc5a07atj
           EOT
           607.times{i,x=i.divmod(1035);a,b=x.divmod(23);print(c[a]*b)}
           raise ArgumentError, "Such panic is really not required."
         end
         raise ArgumentError, "help only takes two (optional) arguments, a face name, and an action"
       end
 
       version = :current
       if options.has_key? :version then
         if options[:version].to_s !~ /^current$/i then
           version = options[:version]
         else
           if args.length == 0 then
             raise ArgumentError, "version only makes sense when a face is given"
           end
         end
       end
 
       # Name those parameters...
       facename, actionname = args
 
       if facename then
         if legacy_applications.include? facename then
           actionname and raise ArgumentError, "Legacy subcommands don't take actions"
           return Puppet::Application[facename].help
         else
           face = Puppet::Face[facename.to_sym, version]
           actionname and action = face.get_action(actionname.to_sym)
         end
       end
 
       case args.length
       when 0 then
         template = erb 'global.erb'
       when 1 then
         face or fail ArgumentError, "Unable to load face #{facename}"
         template = erb 'face.erb'
       when 2 then
         face or fail ArgumentError, "Unable to load face #{facename}"
         action or fail ArgumentError, "Unable to load action #{actionname} from #{face}"
         template = erb 'action.erb'
       else
         fail ArgumentError, "Too many arguments to help action"
       end
 
       # Run the ERB template in our current binding, including all the local
       # variables we established just above. --daniel 2011-04-11
       return template.result(binding)
     end
   end
 
   def erb(name)
     template = (Pathname(__FILE__).dirname + "help" + name)
     erb = ERB.new(template.read, nil, '%')
     erb.filename = template.to_s
     return erb
   end
 
   def legacy_applications
     # The list of applications, less those that are duplicated as a face.
     Puppet::Util::CommandLine.available_subcommands.reject do |appname|
       Puppet::Face.face? appname.to_sym, :current or
         # ...this is a nasty way to exclude non-applications. :(
         %w{face_base indirection_base}.include? appname
     end.sort
   end
 
   def horribly_extract_summary_from(appname)
     begin
       require "puppet/application/#{appname}"
       help = Puppet::Application[appname].help.split("\n")
       # Now we find the line with our summary, extract it, and return it.  This
       # depends on the implementation coincidence of how our pages are
       # formatted.  If we can't match the pattern we expect we return the empty
       # string to ensure we don't blow up in the summary. --daniel 2011-04-11
       while line = help.shift do
         if md = /^puppet-#{appname}\([^\)]+\) -- (.*)$/.match(line) then
           return md[1]
         end
       end
     rescue Exception
       # Damn, but I hate this: we just ignore errors here, no matter what
       # class they are.  Meh.
     end
     return ''
   end
 end
diff --git a/lib/puppet/face/help/action.erb b/lib/puppet/face/help/action.erb
index eaf131464..c26958a35 100644
--- a/lib/puppet/face/help/action.erb
+++ b/lib/puppet/face/help/action.erb
@@ -1,3 +1,48 @@
-Use: puppet <%= face.name %> [options] <%= action.name %> [options]
+puppet <%= face.name %><%= action.default? ? '' : " #{action.name}" %>(1) -- <%= action.summary || face.summary %>
+<%= '=' * (_erbout.length - 1) %>
 
-Summary: <%= action.summary %>
+% if action.synopsis
+SYNOPSIS
+--------
+
+<%= action.synopsis %>
+
+% end
+% if action.description
+DESCRIPTION
+-----------
+<%= action.description %>
+
+%end
+% unless action.options.empty?
+OPTIONS
+-------
+%   action.options.sort.each do |name|
+%     option = action.get_option name
+<%= "  " + option.optparse.join(" |" ) %>
+<%= option.summary %>
+<%= option.description %>
+
+%   end
+% end
+% if action.examples
+EXAMPLES
+--------
+<%= action.examples %>
+% end
+% if action.notes
+NOTES
+-----
+<%= action.notes %>
+
+% end
+% unless action.authors.empty?
+AUTHOR
+------
+<%= action.authors.map {|x| " * " + x } .join("\n") %>
+
+%end
+COPYRIGHT AND LICENSE
+---------------------
+<%= action.copyright %>
+<%= action.license   %>
diff --git a/lib/puppet/face/help/face.erb b/lib/puppet/face/help/face.erb
index efe5fd809..b249981de 100644
--- a/lib/puppet/face/help/face.erb
+++ b/lib/puppet/face/help/face.erb
@@ -1,7 +1,48 @@
-Use: puppet <%= face.name %> [options] <action> [options]
+NAME
+  <%= face.name %> -- <%= face.summary || "unknown face..." %>
 
-Available actions:
+% if face.synopsis
+SYNOPSIS
+<%= face.synopsis.gsub(/^/, '  ') %>
+
+% end
+% if face.description
+DESCRIPTION
+<%= face.description.chomp.gsub(/^/, '  ') %>
+
+%end
+% unless face.options.empty?
+OPTIONS
+%   face.options.sort.each do |name|
+%     option = face.get_option name
+<%= "  " + option.optparse.join(" |" ) %>
+<%= option.summary %>
+<%= option.description %>
+
+%   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(16) %>  <%= action.summary %>
+  <%= action.name.to_s.ljust(padding) %>  <%= action.summary %>
 % end
+
+% if face.examples
+EXAMPLES
+<%= face.examples %>
+% end
+% if face.notes
+NOTES
+<%= face.notes %>
+
+% end
+% unless face.authors.empty?
+AUTHOR
+<%= face.authors.join("\n").gsub(/^/, ' * ') %>
+
+%end
+COPYRIGHT AND LICENSE
+<%= face.copyright.gsub(/^/, '  ') %>
+<%= face.license.gsub(/^/, '  ')   %>
+
diff --git a/lib/puppet/face/indirector.rb b/lib/puppet/face/indirector.rb
index 6c7708b51..a7ff7e1f0 100644
--- a/lib/puppet/face/indirector.rb
+++ b/lib/puppet/face/indirector.rb
@@ -1,95 +1,97 @@
 require 'puppet'
 require 'puppet/face'
 
 class Puppet::Face::Indirector < Puppet::Face
   option "--terminus TERMINUS" do
-    desc "REVISIT: You can select a terminus, which has some bigger effect
-that we should describe in this file somehow."
+    description %q{
+REVISIT: You can select a terminus, which has some bigger effect
+that we should describe in this file somehow.
+}.strip
 
     before_action do |action, args, options|
       set_terminus(options[:terminus])
     end
 
     after_action do |action, args, options|
       indirection.reset_terminus_class
     end
   end
 
   def self.indirections
     Puppet::Indirector::Indirection.instances.collect { |t| t.to_s }.sort
   end
 
   def self.terminus_classes(indirection)
     Puppet::Indirector::Terminus.terminus_classes(indirection.to_sym).collect { |t| t.to_s }.sort
   end
 
   def call_indirection_method(method, *args)
     options = args.last
 
     begin
       result = indirection.__send__(method, *args)
     rescue => detail
       puts detail.backtrace if Puppet[:trace]
       raise "Could not call '#{method}' on '#{indirection_name}': #{detail}"
     end
 
     return result
   end
 
   action :destroy do
     when_invoked { |*args| call_indirection_method(:destroy, *args) }
   end
 
   action :find do
     when_invoked { |*args| call_indirection_method(:find, *args) }
   end
 
   action :save do
     when_invoked { |*args| call_indirection_method(:save, *args) }
   end
 
   action :search do
     when_invoked { |*args| call_indirection_method(:search, *args) }
   end
 
   # Print the configuration for the current terminus class
   action :info do
     when_invoked do |*args|
       if t = indirection.terminus_class
         puts "Run mode '#{Puppet.run_mode.name}': #{t}"
       else
         $stderr.puts "No default terminus class for run mode '#{Puppet.run_mode.name}'"
       end
     end
   end
 
   attr_accessor :from
 
   def indirection_name
     @indirection_name || name.to_sym
   end
 
   # Here's your opportunity to override the indirection name.  By default it
   # will be the same name as the face.
   def set_indirection_name(name)
     @indirection_name = name
   end
 
   # Return an indirection associated with a face, if one exists;
   # One usually does.
   def indirection
     unless @indirection
       @indirection = Puppet::Indirector::Indirection.instance(indirection_name)
       @indirection or raise "Could not find terminus for #{indirection_name}"
     end
     @indirection
   end
 
   def set_terminus(from)
     begin
       indirection.terminus_class = from
     rescue => detail
       raise "Could not set '#{indirection.name}' terminus to '#{from}' (#{detail}); valid terminus types are #{self.class.terminus_classes(indirection.name).join(", ") }"
     end
   end
 end
diff --git a/lib/puppet/face/key.rb b/lib/puppet/face/key.rb
index c85345167..5d1a9ab26 100644
--- a/lib/puppet/face/key.rb
+++ b/lib/puppet/face/key.rb
@@ -1,8 +1,14 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:key, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Create, save, and remove certificate keys."
 
-  @longdocs = "Keys are created for you automatically when certificate
-  requests are generated with 'puppet certificate generate'."
+  description <<-EOT
+Keys are created for you automatically when certificate
+requests are generated with 'puppet certificate generate'.
+  EOT
+
 end
diff --git a/lib/puppet/face/node.rb b/lib/puppet/face/node.rb
index 7032debc3..3591dd92b 100644
--- a/lib/puppet/face/node.rb
+++ b/lib/puppet/face/node.rb
@@ -1,7 +1,11 @@
 require 'puppet/face/indirector'
 Puppet::Face::Indirector.define(:node, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "View and manage nodes"
 
-  @longdocs = "It defaults to using whatever your node
-  terminus is set as."
+  description <<-EOT
+It defaults to using whatever your node terminus is set as.
+  EOT
 end
diff --git a/lib/puppet/face/parser.rb b/lib/puppet/face/parser.rb
index bea146f81..c4c3fb55e 100644
--- a/lib/puppet/face/parser.rb
+++ b/lib/puppet/face/parser.rb
@@ -1,22 +1,25 @@
 require 'puppet/face'
 require 'puppet/parser'
 
 Puppet::Face.define(:parser, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Interact directly with the parser"
 
   action :validate do
     when_invoked do |*args|
       args.pop
       files = args
       if files.empty?
         files << Puppet[:manifest]
         Puppet.notice "No manifest specified. Validating the default manifest #{Puppet[:manifest]}"
       end
       files.each do |file|
         Puppet[:manifest] = file
         Puppet::Node::Environment.new(Puppet[:environment]).known_resource_types.clear
       end
       nil
     end
   end
 end
diff --git a/lib/puppet/face/plugin.rb b/lib/puppet/face/plugin.rb
index 4d95bd93b..19060942a 100644
--- a/lib/puppet/face/plugin.rb
+++ b/lib/puppet/face/plugin.rb
@@ -1,16 +1,19 @@
 require 'puppet/face'
 Puppet::Face.define(:plugin, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Interact with the Puppet plugin system"
 
   action :download do
     summary "Download plugins from the configured master"
 
     when_invoked do |options|
       require 'puppet/configurer/downloader'
       Puppet::Configurer::Downloader.new("plugin",
                                          Puppet[:plugindest],
                                          Puppet[:pluginsource],
                                          Puppet[:pluginsignore]).evaluate
     end
   end
 end
diff --git a/lib/puppet/face/report.rb b/lib/puppet/face/report.rb
index 4de25ef92..9855f3d2d 100644
--- a/lib/puppet/face/report.rb
+++ b/lib/puppet/face/report.rb
@@ -1,17 +1,20 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:report, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Create, display, and submit reports"
 
   action(:submit) do
     when_invoked do |report, options|
       begin
         Puppet::Transaction::Report.terminus_class = :rest
         report.save
       rescue => detail
         puts detail.backtrace if Puppet[:trace]
         Puppet.err "Could not send report: #{detail}"
       end
     end
   end
 end
diff --git a/lib/puppet/face/resource.rb b/lib/puppet/face/resource.rb
index 908b2e462..55a14f280 100644
--- a/lib/puppet/face/resource.rb
+++ b/lib/puppet/face/resource.rb
@@ -1,5 +1,8 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:resource, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Interact directly with resources via the RAL, like ralsh"
 end
diff --git a/lib/puppet/face/resource_type.rb b/lib/puppet/face/resource_type.rb
index fe86eb873..8776dc105 100644
--- a/lib/puppet/face/resource_type.rb
+++ b/lib/puppet/face/resource_type.rb
@@ -1,5 +1,8 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:resource_type, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "View resource types, classes, and nodes from all manifests"
 end
diff --git a/lib/puppet/face/secret_agent.rb b/lib/puppet/face/secret_agent.rb
index af7ffb7b7..50018cb13 100644
--- a/lib/puppet/face/secret_agent.rb
+++ b/lib/puppet/face/secret_agent.rb
@@ -1,19 +1,24 @@
 require 'puppet/face'
 
 Puppet::Face.define(:secret_agent, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Provides agent-like behavior, with no plugin downloading or reporting."
 
   action(:synchronize) do
+    summary "run the secret agent, which makes the catalog and system match..."
+
     when_invoked do |certname, options|
       Puppet::Face[:plugin, '0.0.1'].download
 
       facts   = Puppet::Face[:facts, '0.0.1'].find(certname)
       catalog = Puppet::Face[:catalog, '0.0.1'].download(certname, facts)
       report  = Puppet::Face[:catalog, '0.0.1'].apply(catalog)
 
       Puppet::Face[:report, '0.0.1'].submit(report)
 
       return report
     end
   end
 end
diff --git a/lib/puppet/face/status.rb b/lib/puppet/face/status.rb
index 2a0956ee3..d35d7e1b3 100644
--- a/lib/puppet/face/status.rb
+++ b/lib/puppet/face/status.rb
@@ -1,5 +1,8 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:status, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "View status information"
 end
diff --git a/lib/puppet/interface.rb b/lib/puppet/interface.rb
index ba68ac65b..c7a167d3a 100644
--- a/lib/puppet/interface.rb
+++ b/lib/puppet/interface.rb
@@ -1,157 +1,173 @@
 require 'puppet'
 require 'puppet/util/autoload'
+require 'puppet/interface/documentation'
+require 'prettyprint'
 
 class Puppet::Interface
+  include FullDocs
+
   require 'puppet/interface/face_collection'
 
   require 'puppet/interface/action_manager'
   include Puppet::Interface::ActionManager
   extend Puppet::Interface::ActionManager
 
   require 'puppet/interface/option_manager'
   include Puppet::Interface::OptionManager
   extend Puppet::Interface::OptionManager
 
   include Puppet::Util
 
   class << self
     # This is just so we can search for actions.  We only use its
     # list of directories to search.
     # Can't we utilize an external autoloader, or simply use the $LOAD_PATH? -pvb
     def autoloader
       @autoloader ||= Puppet::Util::Autoload.new(:application, "puppet/face")
     end
 
     def faces
       Puppet::Interface::FaceCollection.faces
     end
 
     def register(instance)
       Puppet::Interface::FaceCollection.register(instance)
     end
 
     def define(name, version, &block)
       face = Puppet::Interface::FaceCollection[name, version]
       if face.nil? then
         face = self.new(name, version)
         Puppet::Interface::FaceCollection.register(face)
         # REVISIT: Shouldn't this be delayed until *after* we evaluate the
         # current block, not done before? --daniel 2011-04-07
         face.load_actions
       end
 
       face.instance_eval(&block) if block_given?
 
       return face
     end
 
     def face?(name, version)
       Puppet::Interface::FaceCollection[name, version]
     end
 
     def [](name, version)
       unless face = Puppet::Interface::FaceCollection[name, version]
         if current = Puppet::Interface::FaceCollection[name, :current]
           raise Puppet::Error, "Could not find version #{version} of #{name}"
         else
           raise Puppet::Error, "Could not find Puppet Face #{name.inspect}"
         end
       end
       face
     end
   end
 
   def set_default_format(format)
     Puppet.warning("set_default_format is deprecated (and ineffective); use render_as on your actions instead.")
   end
 
+
   ########################################################################
   # Documentation.  We currently have to rewrite both getters because we share
   # the same instance between build-time and the runtime instance.  When that
   # splits out this should merge into a module that both the action and face
   # include. --daniel 2011-04-17
-  attr_accessor :summary, :description
-  def summary(value = nil)
-    self.summary = value unless value.nil?
-    @summary
-  end
-  def summary=(value)
-    value = value.to_s
-    value =~ /\n/ and
-      raise ArgumentError, "Face summary should be a single line; put the long text in 'description' instead."
-
-    @summary = value
-  end
-
-  def description(value = nil)
-    self.description = value unless value.nil?
-    @description
+  def synopsis
+    output = PrettyPrint.format do |s|
+      s.text("puppet #{name} <action>")
+      s.breakable
+
+      options.each do |option|
+        option = get_option(option)
+        wrap = option.required? ? %w{ < > } : %w{ [ ] }
+
+        s.group(0, *wrap) do
+          option.optparse.each do |item|
+            unless s.current_group.first?
+              s.breakable
+              s.text '|'
+              s.breakable
+            end
+            s.text item
+          end
+        end
+      end
+    end
   end
 
 
   ########################################################################
   attr_reader :name, :version
 
   def initialize(name, version, &block)
     unless Puppet::Interface::FaceCollection.validate_version(version)
       raise ArgumentError, "Cannot create face #{name.inspect} with invalid version number '#{version}'!"
     end
 
-    @name = Puppet::Interface::FaceCollection.underscorize(name)
+    @name    = Puppet::Interface::FaceCollection.underscorize(name)
     @version = version
 
+    # The few bits of documentation we actually demand.  The default license
+    # is a favour to our end users; if you happen to get that in a core face
+    # report it as a bug, please. --daniel 2011-04-26
+    @authors  = []
+    @license  = 'All Rights Reserved'
+
     instance_eval(&block) if block_given?
   end
 
   # Try to find actions defined in other files.
   def load_actions
     Puppet::Interface.autoloader.search_directories.each do |dir|
       Dir.glob(File.join(dir, "puppet/face/#{name}", "*.rb")).each do |file|
         action = file.sub(dir, '').sub(/^[\\\/]/, '').sub(/\.rb/, '')
         Puppet.debug "Loading action '#{action}' for '#{name}' from '#{dir}/#{action}.rb'"
         require(action)
       end
     end
   end
 
   def to_s
     "Puppet::Face[#{name.inspect}, #{version.inspect}]"
   end
 
   ########################################################################
   # Action decoration, whee!  You are not expected to care about this code,
   # which exists to support face building and construction.  I marked these
   # private because the implementation is crude and ugly, and I don't yet know
   # enough to work out how to make it clean.
   #
   # Once we have established that these methods will likely change radically,
   # to be unrecognizable in the final outcome.  At which point we will throw
   # all this away, replace it with something nice, and work out if we should
   # be making this visible to the outside world... --daniel 2011-04-14
   private
   def __invoke_decorations(type, action, passed_args = [], passed_options = {})
     [:before, :after].member?(type) or fail "unknown decoration type #{type}"
 
     # Collect the decoration methods matching our pass.
     methods = action.options.select do |name|
       passed_options.has_key? name
     end.map do |name|
       action.get_option(name).__decoration_name(type)
     end
 
     # Exceptions here should propagate up; this implements a hook we can use
     # reasonably for option validation.
     methods.each do |hook|
       respond_to? hook and self.__send__(hook, action, passed_args, passed_options)
     end
   end
 
   def __add_method(name, proc)
     meta_def(name, &proc)
     method(name).unbind
   end
   def self.__add_method(name, proc)
     define_method(name, proc)
     instance_method(name)
   end
 end
diff --git a/lib/puppet/interface/action.rb b/lib/puppet/interface/action.rb
index 464b2a738..ac66d2946 100644
--- a/lib/puppet/interface/action.rb
+++ b/lib/puppet/interface/action.rb
@@ -1,252 +1,272 @@
-# -*- coding: utf-8 -*-
 require 'puppet/interface'
-require 'puppet/interface/option'
+require 'puppet/interface/documentation'
+require 'prettyprint'
 
 class Puppet::Interface::Action
+  include Puppet::Interface::FullDocs
+
   def initialize(face, name, attrs = {})
     raise "#{name.inspect} is an invalid action name" unless name.to_s =~ /^[a-z]\w*$/
     @face    = face
     @name    = name.to_sym
+
+    # The few bits of documentation we actually demand.  The default license
+    # is a favour to our end users; if you happen to get that in a core face
+    # report it as a bug, please. --daniel 2011-04-26
+    @authors = []
+    @license  = 'All Rights Reserved'
+
     attrs.each do |k, v| send("#{k}=", v) end
 
     @options        = {}
     @when_rendering = {}
   end
 
   # This is not nice, but it is the easiest way to make us behave like the
   # Ruby Method object rather than UnboundMethod.  Duplication is vaguely
   # annoying, but at least we are a shallow clone. --daniel 2011-04-12
   def __dup_and_rebind_to(to)
     bound_version = self.dup
     bound_version.instance_variable_set(:@face, to)
     return bound_version
   end
 
   def to_s() "#{@face}##{@name}" end
 
   attr_reader   :name
   attr_accessor :default
   def default?
     !!@default
   end
 
-  attr_accessor :summary
-
+  ########################################################################
+  # Documentation...
+  def synopsis
+    output = PrettyPrint.format do |s|
+      s.text("puppet #{@face.name}")
+      s.text(" #{name}") unless default?
+      s.breakable
+
+      options.each do |option|
+        option = get_option(option)
+        wrap = option.required? ? %w{ < > } : %w{ [ ] }
+
+        s.group(0, *wrap) do
+          option.optparse.each do |item|
+            unless s.current_group.first?
+              s.breakable
+              s.text '|'
+              s.breakable
+            end
+            s.text item
+          end
+        end
+      end
+    end
+  end
 
   ########################################################################
   # Support for rendering formats and all.
   def when_rendering(type)
     unless type.is_a? Symbol
       raise ArgumentError, "The rendering format must be a symbol, not #{type.class.name}"
     end
     return unless @when_rendering.has_key? type
     return @when_rendering[type].bind(@face)
   end
   def set_rendering_method_for(type, proc)
     unless proc.is_a? Proc
       msg = "The second argument to set_rendering_method_for must be a Proc"
       msg += ", not #{proc.class.name}" unless proc.nil?
       raise ArgumentError, msg
     end
     if proc.arity != 1 then
       msg = "when_rendering methods take one argument, the result, not "
       if proc.arity < 0 then
         msg += "a variable number"
       else
         msg += proc.arity.to_s
       end
       raise ArgumentError, msg
     end
     unless type.is_a? Symbol
       raise ArgumentError, "The rendering format must be a symbol, not #{type.class.name}"
     end
     if @when_rendering.has_key? type then
       raise ArgumentError, "You can't define a rendering method for #{type} twice"
     end
     # Now, the ugly bit.  We add the method to our interface object, and
     # retrieve it, to rotate through the dance of getting a suitable method
     # object out of the whole process. --daniel 2011-04-18
     @when_rendering[type] =
       @face.__send__( :__add_method, __render_method_name_for(type), proc)
   end
 
   def __render_method_name_for(type)
     :"#{name}_when_rendering_#{type}"
   end
   private :__render_method_name_for
 
 
   attr_accessor :render_as
   def render_as=(value)
     @render_as = value.to_sym
   end
 
 
-  ########################################################################
-  # Documentation stuff, whee!
-  attr_accessor :summary, :description
-  def summary=(value)
-    value = value.to_s
-    value =~ /\n/ and
-      raise ArgumentError, "Face summary should be a single line; put the long text in 'description' instead."
-
-    @summary = value
-  end
-
-
   ########################################################################
   # Initially, this was defined to allow the @action.invoke pattern, which is
   # a very natural way to invoke behaviour given our introspection
   # capabilities.   Heck, our initial plan was to have the faces delegate to
   # the action object for invocation and all.
   #
   # It turns out that we have a binding problem to solve: @face was bound to
   # the parent class, not the subclass instance, and we don't pass the
   # appropriate context or change the binding enough to make this work.
   #
   # We could hack around it, by either mandating that you pass the context in
   # to invoke, or try to get the binding right, but that has probably got
   # subtleties that we don't instantly think of – especially around threads.
   #
   # So, we are pulling this method for now, and will return it to life when we
   # have the time to resolve the problem.  For now, you should replace...
   #
   #     @action = @face.get_action(name)
   #     @action.invoke(arg1, arg2, arg3)
   #
   # ...with...
   #
   #     @action = @face.get_action(name)
   #     @face.send(@action.name, arg1, arg2, arg3)
   #
   # I understand that is somewhat cumbersome, but it functions as desired.
   # --daniel 2011-03-31
   #
   # PS: This code is left present, but commented, to support this chunk of
   # documentation, for the benefit of the reader.
   #
   # def invoke(*args, &block)
   #   @face.send(name, *args, &block)
   # end
 
 
   # We need to build an instance method as a wrapper, using normal code, to be
   # able to expose argument defaulting between the caller and definer in the
   # Ruby API.  An extra method is, sadly, required for Ruby 1.8 to work since
   # it doesn't expose bind on a block.
   #
   # Hopefully we can improve this when we finally shuffle off the last of Ruby
   # 1.8 support, but that looks to be a few "enterprise" release eras away, so
   # we are pretty stuck with this for now.
   #
   # Patches to make this work more nicely with Ruby 1.9 using runtime version
   # checking and all are welcome, provided that they don't change anything
   # outside this little ol' bit of code and all.
   #
   # Incidentally, we though about vendoring evil-ruby and actually adjusting
   # the internal C structure implementation details under the hood to make
   # this stuff work, because it would have been cleaner.  Which gives you an
   # idea how motivated we were to make this cleaner.  Sorry.
   # --daniel 2011-03-31
   def when_invoked=(block)
 
     internal_name = "#{@name} implementation, required on Ruby 1.8".to_sym
 
     arity = block.arity
     if arity == 0 then
       # This will never fire on 1.8.7, which treats no arguments as "*args",
       # but will on 1.9.2, which treats it as "no arguments".  Which bites,
       # because this just begs for us to wind up in the horrible situation
       # where a 1.8 vs 1.9 error bites our end users. --daniel 2011-04-19
       raise ArgumentError, "action when_invoked requires at least one argument (options)"
     elsif arity > 0 then
       range = Range.new(1, arity - 1)
       decl = range.map { |x| "arg#{x}" } << "options = {}"
       optn = ""
       args = "[" + (range.map { |x| "arg#{x}" } << "options").join(", ") + "]"
     else
       range = Range.new(1, arity.abs - 1)
       decl = range.map { |x| "arg#{x}" } << "*rest"
       optn = "rest << {} unless rest.last.is_a?(Hash)"
       if arity == -1 then
         args = "rest"
       else
         args = "[" + range.map { |x| "arg#{x}" }.join(", ") + "] + rest"
       end
     end
 
     file    = __FILE__ + "+eval[wrapper]"
     line    = __LINE__ + 2 # <== points to the same line as 'def' in the wrapper.
     wrapper = <<WRAPPER
 def #{@name}(#{decl.join(", ")})
   #{optn}
   args = #{args}
   options = args.last
 
   action = get_action(#{name.inspect})
   action.validate_args(args)
   __invoke_decorations(:before, action, args, options)
   rval = self.__send__(#{internal_name.inspect}, *args)
   __invoke_decorations(:after, action, args, options)
   return rval
 end
 WRAPPER
 
     if @face.is_a?(Class)
       @face.class_eval do eval wrapper, nil, file, line end
       @face.define_method(internal_name, &block)
     else
       @face.instance_eval do eval wrapper, nil, file, line end
       @face.meta_def(internal_name, &block)
     end
   end
 
   def add_option(option)
     option.aliases.each do |name|
       if conflict = get_option(name) then
         raise ArgumentError, "Option #{option} conflicts with existing option #{conflict}"
       elsif conflict = @face.get_option(name) then
         raise ArgumentError, "Option #{option} conflicts with existing option #{conflict} on #{@face}"
       end
     end
 
     option.aliases.each do |name|
       @options[name] = option
     end
 
     option
   end
 
   def option?(name)
     @options.include? name.to_sym
   end
 
   def options
     (@options.keys + @face.options).sort
   end
 
   def get_option(name, with_inherited_options = true)
     option = @options[name.to_sym]
     if option.nil? and with_inherited_options
       option = @face.get_option(name)
     end
     option
   end
 
   def validate_args(args)
     required = options.map do |name|
       get_option(name)
     end.select(&:required?).collect(&:name) - args.last.keys
 
     return if required.empty?
     raise ArgumentError, "The following options are required: #{required.join(', ')}"
   end
 
   ########################################################################
   # Support code for action decoration; see puppet/interface.rb for the gory
   # details of why this is hidden away behind private. --daniel 2011-04-15
   private
   def __add_method(name, proc)
     @face.__send__ :__add_method, name, proc
   end
 end
diff --git a/lib/puppet/interface/action_manager.rb b/lib/puppet/interface/action_manager.rb
index 440be2d1b..c5eb8e08a 100644
--- a/lib/puppet/interface/action_manager.rb
+++ b/lib/puppet/interface/action_manager.rb
@@ -1,65 +1,67 @@
-require 'puppet/interface/action_builder'
+require 'puppet/interface/action'
 
 module Puppet::Interface::ActionManager
   # Declare that this app can take a specific action, and provide
   # the code to do so.
   def action(name, &block)
+    require 'puppet/interface/action_builder'
+
     @actions ||= {}
     @default_action ||= nil
     raise "Action #{name} already defined for #{self}" if action?(name)
     action = Puppet::Interface::ActionBuilder.build(self, name, &block)
     if action.default
       raise "Actions #{@default_action.name} and #{name} cannot both be default" if @default_action
       @default_action = action
     end
     @actions[action.name] = action
   end
 
   # This is the short-form of an action definition; it doesn't use the
   # builder, just creates the action directly from the block.
   def script(name, &block)
     @actions ||= {}
     raise "Action #{name} already defined for #{self}" if action?(name)
     @actions[name] = Puppet::Interface::Action.new(self, name, :when_invoked => block)
   end
 
   def actions
     @actions ||= {}
     result = @actions.keys
 
     if self.is_a?(Class) and superclass.respond_to?(:actions)
       result += superclass.actions
     elsif self.class.respond_to?(:actions)
       result += self.class.actions
     end
     result.sort
   end
 
   def get_action(name)
     @actions ||= {}
     result = @actions[name.to_sym]
     if result.nil?
       if self.is_a?(Class) and superclass.respond_to?(:get_action)
         found = superclass.get_action(name)
       elsif self.class.respond_to?(:get_action)
         found = self.class.get_action(name)
       end
 
       if found then
         # This is not the nicest way to make action equivalent to the Ruby
         # Method object, rather than UnboundMethod, but it will do for now,
         # and we only have to make this change in *one* place. --daniel 2011-04-12
         result = @actions[name.to_sym] = found.__dup_and_rebind_to(self)
       end
     end
     return result
   end
 
   def get_default_action
     @default_action
   end
 
   def action?(name)
     actions.include?(name.to_sym)
   end
 end
diff --git a/lib/puppet/interface/documentation.rb b/lib/puppet/interface/documentation.rb
new file mode 100644
index 000000000..d0bfbb261
--- /dev/null
+++ b/lib/puppet/interface/documentation.rb
@@ -0,0 +1,172 @@
+class Puppet::Interface
+  module TinyDocs
+    attr_accessor :summary
+    def summary(value = nil)
+      self.summary = value unless value.nil?
+      @summary
+    end
+    def summary=(value)
+      value = value.to_s
+      value =~ /\n/ and
+        raise ArgumentError, "Face summary should be a single line; put the long text in 'description' instead."
+
+      @summary = value
+    end
+
+    attr_accessor :description
+    def description(value = nil)
+      self.description = value unless value.nil?
+      @description
+    end
+  end
+
+  module FullDocs
+    include TinyDocs
+
+    attr_accessor :examples
+    def examples(value = nil)
+      self.examples = value unless value.nil?
+      @examples
+    end
+
+    attr_accessor :short_description
+    def short_description(value = nil)
+      self.short_description = value unless value.nil?
+      if @short_description.nil? then
+        return nil if @description.nil?
+        lines = @description.split("\n")
+        grab  = [5, lines.index('') || 5].min
+        @short_description = lines[0, grab].join("\n")
+      end
+      @short_description
+    end
+
+    def author(value = nil)
+      unless value.nil? then
+        unless value.is_a? String
+          raise ArgumentError, 'author must be a string; use multiple statements for multiple authors'
+        end
+
+        if value =~ /\n/ then
+          raise ArgumentError, 'author should be a single line; use multiple statements for multiple authors'
+        end
+        @authors.push(value)
+      end
+      @authors.empty? ? nil : @authors.join("\n")
+    end
+    def author=(value)
+      if Array(value).any? {|x| x =~ /\n/ } then
+        raise ArgumentError, 'author should be a single line; use multiple statements'
+      end
+      @authors = Array(value)
+    end
+    def authors
+      @authors
+    end
+    def authors=(value)
+      if Array(value).any? {|x| x =~ /\n/ } then
+        raise ArgumentError, 'author should be a single line; use multiple statements'
+      end
+      @authors = Array(value)
+    end
+
+    attr_accessor :notes
+    def notes(value = nil)
+      @notes = value unless value.nil?
+      @notes
+    end
+
+    attr_accessor :license
+    def license(value = nil)
+      @license = value unless value.nil?
+      @license
+    end
+
+    def copyright(owner = nil, years = nil)
+      if years.nil? and not owner.nil? then
+        raise ArgumentError, 'copyright takes the owners names, then the years covered'
+      end
+      self.copyright_owner = owner unless owner.nil?
+      self.copyright_years = years unless years.nil?
+
+      if self.copyright_years or self.copyright_owner then
+        "Copyright #{self.copyright_years} by #{self.copyright_owner}"
+      else
+        "Unknown copyright owner and years."
+      end
+    end
+
+    attr_accessor :copyright_owner
+    def copyright_owner=(value)
+      case value
+      when String then @copyright_owner = value
+      when Array  then @copyright_owner = value.join(", ")
+      else
+        raise ArgumentError, "copyright owner must be a string or an array of strings"
+      end
+      @copyright_owner
+    end
+
+    attr_accessor :copyright_years
+    def copyright_years=(value)
+      years = munge_copyright_year value
+      years = (years.is_a?(Array) ? years : [years]).
+        sort_by do |x| x.is_a?(Range) ? x.first : x end
+
+      @copyright_years = years.map do |year|
+        if year.is_a? Range then
+          "#{year.first}-#{year.last}"
+        else
+          year
+        end
+      end.join(", ")
+    end
+
+    def munge_copyright_year(input)
+      case input
+      when Range then input
+      when Integer then
+        if input < 1970 then
+          fault = "before 1970"
+        elsif input > (future = Time.now.year + 2) then
+          fault = "after #{future}"
+        end
+        if fault then
+          raise ArgumentError, "copyright with a year #{fault} is very strange; did you accidentally add or subtract two years?"
+        end
+
+        input
+
+      when String then
+        input.strip.split(/,/).map do |part|
+          part = part.strip
+          if part =~ /^\d+$/ then
+            part.to_i
+          elsif found = part.split(/-/) then
+            unless found.length == 2 and found.all? {|x| x.strip =~ /^\d+$/ }
+              raise ArgumentError, "#{part.inspect} is not a good copyright year or range"
+            end
+            Range.new(found[0].to_i, found[1].to_i)
+          else
+            raise ArgumentError, "#{part.inspect} is not a good copyright year or range"
+          end
+        end
+
+      when Array then
+        result = []
+        input.each do |item|
+          item = munge_copyright_year item
+          if item.is_a? Array
+            result.concat item
+          else
+            result << item
+          end
+        end
+        result
+
+      else
+        raise ArgumentError, "#{input.inspect} is not a good copyright year, set, or range"
+      end
+    end
+  end
+end
diff --git a/lib/puppet/interface/option.rb b/lib/puppet/interface/option.rb
index 3d3840ff6..b68bdeb12 100644
--- a/lib/puppet/interface/option.rb
+++ b/lib/puppet/interface/option.rb
@@ -1,106 +1,110 @@
 require 'puppet/interface'
 
 class Puppet::Interface::Option
+  include Puppet::Interface::TinyDocs
+  # For compatibility, deprecated, and should go fairly soon...
+  ['', '='].each { |x| alias :"desc#{x}" :"description#{x}" }
+
   def initialize(parent, *declaration, &block)
     @parent   = parent
     @optparse = []
 
     # Collect and sort the arguments in the declaration.
     dups = {}
     declaration.each do |item|
       if item.is_a? String and item.to_s =~ /^-/ then
         unless item =~ /^-[a-z]\b/ or item =~ /^--[^-]/ then
           raise ArgumentError, "#{item.inspect}: long options need two dashes (--)"
         end
         @optparse << item
 
         # Duplicate checking...
         name = optparse_to_name(item)
         if dup = dups[name] then
           raise ArgumentError, "#{item.inspect}: duplicates existing alias #{dup.inspect} in #{@parent}"
         else
           dups[name] = item
         end
       else
         raise ArgumentError, "#{item.inspect} is not valid for an option argument"
       end
     end
 
     if @optparse.empty? then
       raise ArgumentError, "No option declarations found while building"
     end
 
     # Now, infer the name from the options; we prefer the first long option as
     # the name, rather than just the first option.
     @name = optparse_to_name(@optparse.find do |a| a =~ /^--/ end || @optparse.first)
     @aliases = @optparse.map { |o| optparse_to_name(o) }
 
     # Do we take an argument?  If so, are we consistent about it, because
     # incoherence here makes our life super-difficult, and we can more easily
     # relax this rule later if we find a valid use case for it. --daniel 2011-03-30
     @argument = @optparse.any? { |o| o =~ /[ =]/ }
     if @argument and not @optparse.all? { |o| o =~ /[ =]/ } then
       raise ArgumentError, "Option #{@name} is inconsistent about taking an argument"
     end
 
     # Is our argument optional?  The rules about consistency apply here, also,
     # just like they do to taking arguments at all. --daniel 2011-03-30
     @optional_argument = @optparse.any? { |o| o=~/[ =]\[/ }
     @optional_argument and raise ArgumentError, "Options with optional arguments are not supported"
     if @optional_argument and not @optparse.all? { |o| o=~/[ =]\[/ } then
       raise ArgumentError, "Option #{@name} is inconsistent about the argument being optional"
     end
   end
 
   # to_s and optparse_to_name are roughly mirrored, because they are used to
   # transform options to name symbols, and vice-versa.  This isn't a full
   # bidirectional transformation though. --daniel 2011-04-07
   def to_s
     @name.to_s.tr('_', '-')
   end
 
   def optparse_to_name(declaration)
     unless found = declaration.match(/^-+(?:\[no-\])?([^ =]+)/) then
       raise ArgumentError, "Can't find a name in the declaration #{declaration.inspect}"
     end
     name = found.captures.first.tr('-', '_')
     raise "#{name.inspect} is an invalid option name" unless name.to_s =~ /^[a-z]\w*$/
     name.to_sym
   end
 
 
   def takes_argument?
     !!@argument
   end
   def optional_argument?
     !!@optional_argument
   end
   def required?
     !!@required
   end
 
   attr_reader   :parent, :name, :aliases, :optparse
-  attr_accessor :required, :desc
+  attr_accessor :required
 
   attr_accessor :before_action
   def before_action=(proc)
     proc.is_a? Proc or raise ArgumentError, "before action hook for #{self} is a #{proc.class.name.inspect}, not a proc"
     @before_action =
       @parent.__send__(:__add_method, __decoration_name(:before), proc)
   end
 
   attr_accessor :after_action
   def after_action=(proc)
     proc.is_a? Proc or raise ArgumentError, "after action hook for #{self} is a #{proc.class.name.inspect}, not a proc"
     @after_action =
       @parent.__send__(:__add_method, __decoration_name(:after), proc)
   end
 
   def __decoration_name(type)
     if @parent.is_a? Puppet::Interface::Action then
       :"option #{name} from #{parent.name} #{type} decoration"
     else
       :"option #{name} #{type} decoration"
     end
   end
 end
diff --git a/spec/integration/faces/documentation_spec.rb b/spec/integration/faces/documentation_spec.rb
new file mode 100755
index 000000000..9ddf2f1b3
--- /dev/null
+++ b/spec/integration/faces/documentation_spec.rb
@@ -0,0 +1,55 @@
+#!/usr/bin/env rspec
+require 'spec_helper'
+require 'puppet/face'
+
+describe "documentation of faces" do
+  it "should generate global help" do
+    help = nil
+    expect { help = Puppet::Face[:help, :current].help }.not_to raise_error
+    help.should be_an_instance_of String
+    help.length.should be > 200
+  end
+
+  ########################################################################
+  # Can we actually generate documentation for the face, and the actions it
+  # has?  This avoids situations where the ERB template turns out to have a
+  # bug in it, triggered in something the user might do.
+  Puppet::Face.faces.sort.each do |face_name|
+    # REVISIT: We should walk all versions of the face here...
+    let :help do Puppet::Face[:help, :current] end
+
+    context "generating help" do
+      it "for #{face_name}" do
+        expect {
+          text = help.help(face_name)
+          text.should be_an_instance_of String
+          text.length.should be > 100
+        }.not_to raise_error
+      end
+
+      Puppet::Face[face_name, :current].actions.sort.each do |action_name|
+        it "for #{face_name}.#{action_name}" do
+          expect {
+            text = help.help(face_name, action_name)
+            text.should be_an_instance_of String
+            text.length.should be > 100
+          }.not_to raise_error
+        end
+      end
+    end
+
+    ########################################################################
+    # Ensure that we have authorship and copyright information in *our* faces;
+    # if you apply this to third party faces you might well be disappointed.
+    context "licensing of Puppet Labs face '#{face_name}'" do
+      subject { Puppet::Face[face_name, :current] }
+      its :license   do should =~ /Apache\s*2/ end
+      its :copyright do should =~ /Puppet Labs/ end
+
+      # REVISIT: This is less that ideal, I think, but right now I am more
+      # comfortable watching us ship with some copyright than without any; we
+      # can redress that when it becomes appropriate. --daniel 2011-04-27
+      its :copyright do should =~ /2011/ end
+    end
+  end
+end
diff --git a/spec/lib/puppet/face/basetest.rb b/spec/lib/puppet/face/basetest.rb
index a98bc382f..41a4ef3f9 100755
--- a/spec/lib/puppet/face/basetest.rb
+++ b/spec/lib/puppet/face/basetest.rb
@@ -1,33 +1,35 @@
 require 'puppet/face'
 
 Puppet::Face.define(:basetest, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
   summary "This is just so tests don't fail"
 
   option "--[no-]boolean"
   option "--mandatory ARGUMENT"
 
   action :foo do
     option("--action")
     when_invoked do |*args| args.length end
   end
 
   action :return_true do
     summary "just returns true"
     when_invoked do |options| true end
   end
 
   action :return_false do
     summary "just returns false"
     when_invoked do |options| false end
   end
 
   action :return_nil do
     summary "just returns nil"
     when_invoked do |options| nil end
   end
 
   action :raise do
     summary "just raises an exception"
     when_invoked do |options| raise ArgumentError, "your failure" end
   end
 end
diff --git a/spec/lib/puppet/face/huzzah.rb b/spec/lib/puppet/face/huzzah.rb
index 3428c6816..2c2b7aa8d 100755
--- a/spec/lib/puppet/face/huzzah.rb
+++ b/spec/lib/puppet/face/huzzah.rb
@@ -1,5 +1,7 @@
 require 'puppet/face'
 Puppet::Face.define(:huzzah, '2.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
   summary "life is a thing for celebration"
   action :bar do "is where beer comes from" end
 end
diff --git a/spec/lib/puppet/face/version_matching.rb b/spec/lib/puppet/face/version_matching.rb
index bfd0013f7..52bc71dbd 100644
--- a/spec/lib/puppet/face/version_matching.rb
+++ b/spec/lib/puppet/face/version_matching.rb
@@ -1,10 +1,12 @@
 require 'puppet/face'
 
 # The set of versions here are used explicitly in the interface_spec; if you
 # change this you need to ensure that is still correct. --daniel 2011-04-21
 ['1.0.0', '1.0.1', '1.1.0', '1.1.1', '2.0.0'].each do |version|
   Puppet::Face.define(:version_matching, version) do
+    copyright "Puppet Labs", 2011
+    license   "Apache 2 license; see COPYING"
     summary "version matching face #{version}"
     script :version do version end
   end
 end
diff --git a/spec/shared_behaviours/documentation_on_faces.rb b/spec/shared_behaviours/documentation_on_faces.rb
index 41b4015c9..dd2bd3110 100644
--- a/spec/shared_behaviours/documentation_on_faces.rb
+++ b/spec/shared_behaviours/documentation_on_faces.rb
@@ -1,35 +1,217 @@
 # encoding: UTF-8
 shared_examples_for "documentation on faces" do
-  context "description" do
-    describe "#summary" do
-      it "should accept a summary" do
-        text = "this is my summary"
-        expect { subject.summary = text }.to_not raise_error
-        subject.summary.should == text
+  defined?(Attrs) or
+    Attrs = [:summary, :description, :examples, :short_description, :notes, :author]
+
+  defined?(SingleLineAttrs) or
+    SingleLineAttrs = [:summary, :author]
+
+  # Simple, procedural tests that apply to a bunch of methods.
+  Attrs.each do |attr|
+    it "should accept a #{attr}" do
+      expect { subject.send("#{attr}=", "hello") }.not_to raise_error
+      subject.send(attr).should == "hello"
+    end
+
+    it "should accept a long (single line) value for #{attr}" do
+      text = "I never know when to stop with the word banana" + ("na" * 1000)
+      expect { subject.send("#{attr}=", text) }.to_not raise_error
+      subject.send(attr).should == text
+    end
+  end
+
+  # Should they accept multiple lines?
+  Attrs.each do |attr|
+    text = "with\nnewlines"
+
+    if SingleLineAttrs.include? attr then
+      it "should not accept multiline values for #{attr}" do
+        expect { subject.send("#{attr}=", text) }.
+          to raise_error ArgumentError, /#{attr} should be a single line/
+        subject.send(attr).should be_nil
+      end
+    else
+      it "should accept multiline values for #{attr}" do
+        expect { subject.send("#{attr}=", text) }.not_to raise_error
+        subject.send(attr).should == text
+      end
+    end
+  end
+
+  describe "#short_description" do
+    it "should return the set value if set after description" do
+      subject.description = "hello\ngoodbye"
+      subject.short_description = "whatever"
+      subject.short_description.should == "whatever"
+    end
+
+    it "should return the set value if set before description" do
+      subject.short_description = "whatever"
+      subject.description = "hello\ngoodbye"
+      subject.short_description.should == "whatever"
+    end
+
+    it "should return nothing if not set and no description" do
+      subject.short_description.should be_nil
+    end
+
+    it "should return the first paragraph of description if not set (where it is one line long)" do
+      subject.description = "hello"
+      subject.short_description.should == subject.description
+    end
+
+    it "should return the first paragraph of description if not set (where there is no paragraph break)" do
+      subject.description = "hello\ngoodbye"
+      subject.short_description.should == subject.description
+    end
+
+    it "should return the first paragraph of description if not set (where there is a paragraph break)" do
+      subject.description = "hello\ngoodbye\n\nmore\ntext\nhere\n\nfinal\nparagraph"
+      subject.short_description.should == "hello\ngoodbye"
+    end
+
+    it "should trim a very, very long first paragraph" do
+      line = "this is a very, very, very long long line full of text\n"
+      subject.description = line * 20 + "\n\nwhatever, dude."
+
+      subject.short_description.should == (line * 5).chomp
+    end
+  end
+
+  describe "multiple authors" do
+    authors = %w{John Paul George Ringo}
+
+    context "in the DSL" do
+      it "should support multiple authors" do
+
+        authors.each {|name| subject.author name }
+        subject.authors.should =~ authors
+
+        subject.author.should == authors.join("\n")
+      end
+
+      it "should reject author as an array" do
+        expect { subject.author ["Foo", "Bar"] }.
+          to raise_error ArgumentError, /author must be a string/
+      end
+    end
+
+    context "#author=" do
+      it "should accept a single name" do
+        subject.author = "Fred"
+        subject.author.should == "Fred"
       end
 
-      it "should accept a long, long, long summary" do
-        text = "I never know when to stop with the word banana" + ("na" * 1000)
-        expect { subject.summary = text }.to_not raise_error
-        subject.summary.should == text
+      it "should accept an array of names" do
+        subject.author = authors
+        subject.authors.should =~ authors
+        subject.author.should == authors.join("\n")
+      end
+
+      it "should not append when set multiple times" do
+        subject.author = "Fred"
+        subject.author = "John"
+        subject.author.should == "John"
+      end
+
+      it "should reject arrays with embedded newlines" do
+        expect { subject.author = ["Fred\nJohn"] }.
+          to raise_error ArgumentError, /author should be a single line/
+      end
+    end
+  end
+
+  describe "#license" do
+    it "should default to reserving rights" do
+      subject.license.should =~ /All Rights Reserved/
+    end
+
+    it "should accept an arbitrary license string on the object" do
+      subject.license = "foo"
+      subject.license.should == "foo"
+    end
+
+    it "should accept symbols to specify existing licenses..."
+  end
+
+  describe "#copyright" do
+    it "should fail with just a name" do
+      expect { subject.copyright("invalid") }.
+        to raise_error ArgumentError, /copyright takes the owners names, then the years covered/
+    end
+
+    [1997, "1997"].each do |year|
+      it "should accept an entity name and a #{year.class.name} year" do
+        subject.copyright("me", year)
+        subject.copyright.should =~ /\bme\b/
+        subject.copyright.should =~ /#{year}/
       end
 
-      it "should reject a summary with a newline" do
-        expect { subject.summary = "with\nnewlines" }.
-          to raise_error ArgumentError, /summary should be a single line/
+      it "should accept multiple entity names and a #{year.class.name} year" do
+        subject.copyright ["me", "you"], year
+        subject.copyright.should =~ /\bme\b/
+        subject.copyright.should =~ /\byou\b/
+        subject.copyright.should =~ /#{year}/
       end
     end
 
-    describe "#description" do
-      it "should accept a description" do
-        subject.description = "hello"
-        subject.description.should == "hello"
+    ["1997-2003", "1997 - 2003", 1997..2003].each do |range|
+      it "should accept a #{range.class.name} range of years" do
+        subject.copyright("me", range)
+        subject.copyright.should =~ /\bme\b/
+        subject.copyright.should =~ /1997-2003/
+      end
+
+      it "should accept a #{range.class.name} range of years" do
+        subject.copyright ["me", "you"], range
+        subject.copyright.should =~ /\bme\b/
+        subject.copyright.should =~ /\byou\b/
+        subject.copyright.should =~ /1997-2003/
+      end
+    end
+
+    [[1997, 2003], ["1997", 2003], ["1997", "2003"]].each do |input|
+      it "should accept the set of years #{input.inspect} in an array" do
+        subject.copyright "me", input
+        subject.copyright.should =~ /\bme\b/
+        subject.copyright.should =~ /1997, 2003/
+      end
+
+      it "should accept the set of years #{input.inspect} in an array" do
+        subject.copyright ["me", "you"], input
+        subject.copyright.should =~ /\bme\b/
+        subject.copyright.should =~ /\byou\b/
+        subject.copyright.should =~ /1997, 2003/
+      end
+    end
+
+    it "should warn if someone does math accidentally on the range of years" do
+      expect { subject.copyright "me", 1997-2003 }.
+        to raise_error ArgumentError, /copyright with a year before 1970 is very strange; did you accidentally add or subtract two years\?/
+    end
+
+    it "should accept complex copyright years" do
+      years = [1997, 1999, 2000..2002, 2005].reverse
+      subject.copyright "me", years
+      subject.copyright.should =~ /\bme\b/
+      subject.copyright.should =~ /1997, 1999, 2000-2002, 2005/
+    end
+  end
+
+  # Things that are automatically generated.
+  [:name, :options, :synopsis].each do |attr|
+    describe "##{attr}" do
+      it "should not allow you to set #{attr}" do
+        subject.should_not respond_to :"#{attr}="
+      end
+
+      it "should have a #{attr}" do
+        subject.send(attr).should_not be_nil
       end
 
-      it "should accept a description with a newline" do
-        subject.description = "hello \n my \n fine \n friend"
-        subject.description.should == "hello \n my \n fine \n friend"
+      it "'s #{attr} should not be empty..." do
+        subject.send(attr).should_not == ''
       end
     end
   end
 end
diff --git a/spec/shared_behaviours/things_that_declare_options.rb b/spec/shared_behaviours/things_that_declare_options.rb
index 5300a159a..3d33bab7f 100755
--- a/spec/shared_behaviours/things_that_declare_options.rb
+++ b/spec/shared_behaviours/things_that_declare_options.rb
@@ -1,145 +1,147 @@
 # encoding: UTF-8
 shared_examples_for "things that declare options" do
   it "should support options without arguments" do
     thing = add_options_to { option "--bar" }
     thing.should be_option :bar
   end
 
   it "should support options with an empty block" do
     thing = add_options_to do
       option "--foo" do
         # this section deliberately left blank
       end
     end
     thing.should be
     thing.should be_option :foo
   end
 
   { "--foo=" => :foo }.each do |input, option|
     it "should accept #{name.inspect}" do
       thing = add_options_to { option input }
       thing.should be_option option
     end
   end
 
   it "should support option documentation" do
     text = "Sturm und Drang (German pronunciation: [ˈʃtʊʁm ʊnt ˈdʁaŋ]) …"
 
     thing = add_options_to do
       option "--foo" do
         desc text
+        description text
+        summary text
       end
     end
 
     thing.get_option(:foo).desc.should == text
   end
 
   it "should list all the options" do
     thing = add_options_to do
       option "--foo"
       option "--bar"
     end
     thing.options.should =~ [:foo, :bar]
   end
 
   it "should detect conflicts in long options" do
     expect {
       add_options_to do
         option "--foo"
         option "--foo"
       end
     }.should raise_error ArgumentError, /Option foo conflicts with existing option foo/i
   end
 
   it "should detect conflicts in short options" do
     expect {
       add_options_to do
         option "-f"
         option "-f"
       end
     }.should raise_error ArgumentError, /Option f conflicts with existing option f/
   end
 
   ["-f", "--foo"].each do |option|
     ["", " FOO", "=FOO", " [FOO]", "=[FOO]"].each do |argument|
       input = option + argument
       it "should detect conflicts within a single option like #{input.inspect}" do
         expect {
           add_options_to do
             option input, input
           end
         }.should raise_error ArgumentError, /duplicates existing alias/
       end
     end
   end
 
 
   # Verify the range of interesting conflicts to check for ordering causing
   # the behaviour to change, or anything exciting like that.
   [ %w{--foo}, %w{-f}, %w{-f --foo}, %w{--baz -f},
     %w{-f --baz}, %w{-b --foo}, %w{--foo -b}
   ].each do |conflict|
     base = %w{--foo -f}
     it "should detect conflicts between #{base.inspect} and #{conflict.inspect}" do
       expect {
         add_options_to do
           option *base
           option *conflict
         end
       }.should raise_error ArgumentError, /conflicts with existing option/
     end
   end
 
   it "should fail if we are not consistent about taking an argument" do
     expect { add_options_to do option "--foo=bar", "--bar" end }.
       should raise_error ArgumentError, /inconsistent about taking an argument/
   end
 
   it "should not accept optional arguments" do
     expect do
       thing = add_options_to do option "--foo=[baz]", "--bar=[baz]" end
       [:foo, :bar].each do |name|
         thing.should be_option name
       end
     end.to raise_error(ArgumentError, /optional arguments are not supported/)
   end
 
   describe "#takes_argument?" do
     it "should detect an argument being absent" do
       thing = add_options_to do option "--foo" end
       thing.get_option(:foo).should_not be_takes_argument
     end
     ["=FOO", " FOO"].each do |input|
       it "should detect an argument given #{input.inspect}" do
         thing = add_options_to do option "--foo#{input}" end
         thing.get_option(:foo).should be_takes_argument
       end
     end
   end
 
   describe "#optional_argument?" do
     it "should be false if no argument is present" do
       option = add_options_to do option "--foo" end.get_option(:foo)
       option.should_not be_takes_argument
       option.should_not be_optional_argument
     end
 
     ["=FOO", " FOO"].each do |input|
       it "should be false if the argument is mandatory (like #{input.inspect})" do
         option = add_options_to do option "--foo#{input}" end.get_option(:foo)
       option.should be_takes_argument
       option.should_not be_optional_argument
       end
     end
 
     ["=[FOO]", " [FOO]"].each do |input|
       it "should fail if the argument is optional (like #{input.inspect})" do
         expect do
           option = add_options_to do option "--foo#{input}" end.get_option(:foo)
           option.should be_takes_argument
           option.should be_optional_argument
         end.to raise_error(ArgumentError, /optional arguments are not supported/)
       end
     end
   end
 end
diff --git a/spec/unit/interface/option_builder_spec.rb b/spec/unit/interface/option_builder_spec.rb
index e9346852c..3e91c683b 100755
--- a/spec/unit/interface/option_builder_spec.rb
+++ b/spec/unit/interface/option_builder_spec.rb
@@ -1,75 +1,77 @@
 require 'puppet/interface/option_builder'
 
 describe Puppet::Interface::OptionBuilder do
   let :face do Puppet::Interface.new(:option_builder_testing, '0.0.1') end
 
   it "should be able to construct an option without a block" do
     Puppet::Interface::OptionBuilder.build(face, "--foo").
       should be_an_instance_of Puppet::Interface::Option
   end
 
   it "should work with an empty block" do
     option = Puppet::Interface::OptionBuilder.build(face, "--foo") do
       # This block deliberately left blank.
     end
 
     option.should be_an_instance_of Puppet::Interface::Option
   end
 
-  it "should support documentation declarations" do
-    text = "this is the description"
-    option = Puppet::Interface::OptionBuilder.build(face, "--foo") do
-      desc text
+  [:description, :summary].each do |doc|
+    it "should support #{doc} declarations" do
+      text = "this is the #{doc}"
+      option = Puppet::Interface::OptionBuilder.build(face, "--foo") do
+        self.send doc, text
+      end
+      option.should be_an_instance_of Puppet::Interface::Option
+      option.send(doc).should == text
     end
-    option.should be_an_instance_of Puppet::Interface::Option
-    option.desc.should == text
   end
 
   context "before_action hook" do
     it "should support a before_action hook" do
       option = Puppet::Interface::OptionBuilder.build(face, "--foo") do
         before_action do |a,b,c| :whatever end
       end
       option.before_action.should be_an_instance_of UnboundMethod
     end
 
     it "should fail if the hook block takes too few arguments" do
       expect do
         Puppet::Interface::OptionBuilder.build(face, "--foo") do
           before_action do |one, two| true end
         end
       end.to raise_error ArgumentError, /takes three arguments/
     end
 
     it "should fail if the hook block takes too many arguments" do
       expect do
         Puppet::Interface::OptionBuilder.build(face, "--foo") do
           before_action do |one, two, three, four| true end
         end
       end.to raise_error ArgumentError, /takes three arguments/
     end
 
     it "should fail if the hook block takes a variable number of arguments" do
       expect do
         Puppet::Interface::OptionBuilder.build(face, "--foo") do
           before_action do |*blah| true end
         end
       end.to raise_error ArgumentError, /takes three arguments/
     end
 
     it "should support simple required declarations" do
       opt = Puppet::Interface::OptionBuilder.build(face, "--foo") do
         required
       end
       opt.should be_required
     end
 
     it "should support arguments to the required property" do
       opt = Puppet::Interface::OptionBuilder.build(face, "--foo") do
         required(false)
       end
       opt.should_not be_required
     end
 
   end
 end
diff --git a/spec/unit/interface_spec.rb b/spec/unit/interface_spec.rb
index a1d70cf64..27da39766 100755
--- a/spec/unit/interface_spec.rb
+++ b/spec/unit/interface_spec.rb
@@ -1,220 +1,224 @@
 require 'spec_helper'
 require 'puppet/face'
 require 'puppet/interface'
 
 describe Puppet::Interface do
   subject { Puppet::Interface }
 
   before :each do
     @faces = Puppet::Interface::FaceCollection.
       instance_variable_get("@faces").dup
     @dq = $".dup
     $".delete_if do |path| path =~ %r{/face/.*\.rb$} end
     Puppet::Interface::FaceCollection.instance_variable_get("@faces").clear
   end
 
   after :each do
     Puppet::Interface::FaceCollection.instance_variable_set("@faces", @faces)
     $".clear ; @dq.each do |item| $" << item end
   end
 
   describe "#[]" do
     it "should fail when no version is requested" do
       expect { subject[:huzzah] }.should raise_error ArgumentError
     end
 
     it "should raise an exception when the requested version is unavailable" do
       expect { subject[:huzzah, '17.0.0'] }.should raise_error, Puppet::Error
     end
 
     it "should raise an exception when the requested face doesn't exist" do
       expect { subject[:burrble_toot, :current] }.should raise_error, Puppet::Error
     end
 
     describe "version matching" do
       { '1'     => '1.1.1',
         '1.0'   => '1.0.1',
         '1.0.1' => '1.0.1',
         '1.1'   => '1.1.1',
         '1.1.1' => '1.1.1'
       }.each do |input, expect|
         it "should match #{input.inspect} to #{expect.inspect}" do
           face = subject[:version_matching, input]
           face.should be
           face.version.should == expect
         end
       end
 
       %w{1.0.2 1.2}.each do |input|
         it "should not match #{input.inspect} to any version" do
           expect { subject[:version_matching, input] }.
             to raise_error Puppet::Error, /Could not find version/
         end
       end
     end
   end
 
   describe "#define" do
     it "should register the face" do
       face  = subject.define(:face_test_register, '0.0.1')
       face.should == subject[:face_test_register, '0.0.1']
     end
 
     it "should load actions" do
       subject.any_instance.expects(:load_actions)
       subject.define(:face_test_load_actions, '0.0.1')
     end
 
     it "should require a version number" do
       expect { subject.define(:no_version) }.to raise_error ArgumentError
     end
 
     it "should support summary builder and accessor methods" do
       subject.new(:foo, '1.0.0').should respond_to(:summary).with(0).arguments
       subject.new(:foo, '1.0.0').should respond_to(:summary=).with(1).arguments
     end
 
     # Required documentation methods...
     { :summary     => "summary",
-      :description => "This is the description of the stuff\n\nWhee"
+      :description => "This is the description of the stuff\n\nWhee",
+      :examples    => "This is my example",
+      :short_description => "This is my custom short description",
+      :notes       => "These are my notes...",
+      :author      => "This is my authorship data",
     }.each do |attr, value|
       it "should support #{attr} in the builder" do
         face = subject.new(:builder, '1.0.0') do
           self.send(attr, value)
         end
         face.send(attr).should == value
       end
     end
   end
 
   describe "#initialize" do
     it "should require a version number" do
       expect { subject.new(:no_version) }.to raise_error ArgumentError
     end
 
     it "should require a valid version number" do
       expect { subject.new(:bad_version, 'Rasins') }.
         should raise_error ArgumentError
     end
 
     it "should instance-eval any provided block" do
       face = subject.new(:face_test_block, '0.0.1') do
         action(:something) do
           when_invoked { "foo" }
         end
       end
 
       face.something.should == "foo"
     end
   end
 
   it "should have a name" do
     subject.new(:me, '0.0.1').name.should == :me
   end
 
   it "should stringify with its own name" do
     subject.new(:me, '0.0.1').to_s.should =~ /\bme\b/
   end
 
   # Why?
   it "should create a class-level autoloader" do
     subject.autoloader.should be_instance_of(Puppet::Util::Autoload)
   end
 
   it "should try to require faces that are not known" do
     pending "mocking require causes random stack overflow"
     subject::FaceCollection.expects(:require).with "puppet/face/foo"
     subject[:foo, '0.0.1']
   end
 
   it "should be able to load all actions in all search paths"
 
 
   it_should_behave_like "things that declare options" do
     def add_options_to(&block)
       subject.new(:with_options, '0.0.1', &block)
     end
   end
 
   describe "with face-level options" do
     it "should not return any action-level options" do
       face = subject.new(:with_options, '0.0.1') do
         option "--foo"
         option "--bar"
         action :baz do
           option "--quux"
         end
       end
       face.options.should =~ [:foo, :bar]
     end
 
     it "should fail when a face option duplicates an action option" do
       expect {
         subject.new(:action_level_options, '0.0.1') do
           action :bar do option "--foo" end
           option "--foo"
         end
       }.should raise_error ArgumentError, /Option foo conflicts with existing option foo on/i
     end
 
     it "should work when two actions have the same option" do
       face = subject.new(:with_options, '0.0.1') do
         action :foo do option "--quux" end
         action :bar do option "--quux" end
       end
 
       face.get_action(:foo).options.should =~ [:quux]
       face.get_action(:bar).options.should =~ [:quux]
     end
   end
 
   describe "with inherited options" do
     let :parent do
       parent = Class.new(subject)
       parent.option("--inherited")
       parent.action(:parent_action) do end
       parent
     end
 
     let :face do
       face = parent.new(:example, '0.2.1')
       face.option("--local")
       face.action(:face_action) do end
       face
     end
 
     describe "#options" do
       it "should list inherited options" do
         face.options.should =~ [:inherited, :local]
       end
 
       it "should see all options on face actions" do
         face.get_action(:face_action).options.should =~ [:inherited, :local]
       end
 
       it "should see all options on inherited actions accessed on the subclass" do
         face.get_action(:parent_action).options.should =~ [:inherited, :local]
       end
 
       it "should not see subclass actions on the parent class" do
         parent.options.should =~ [:inherited]
       end
 
       it "should not see subclass actions on actions accessed on the parent class" do
         parent.get_action(:parent_action).options.should =~ [:inherited]
       end
     end
 
     describe "#get_option" do
       it "should return an inherited option object" do
         face.get_option(:inherited).should be_an_instance_of subject::Option
       end
     end
   end
 
   it_should_behave_like "documentation on faces" do
     subject do
       Puppet::Interface.new(:face_documentation, '0.0.1')
     end
   end
 end