Improve the output of cap --help.

Remove options documentation for rake options that aren't applicable
to capistrano, briefly explain correct cap usage, and point users to
http://capistranorb.com.

CHANGELOG.md

@@ -8,6 +8,7 @@ https://github.com/capistrano/capistrano/compare/v3.2.1...HEAD
 
 * Minor Changes
   * Added tests for after/before hooks features (@juanibiapina, @miry)
+  * Improved the output of `cap --help`. (@mbrictson)
 
 ## `3.2.1`
 

README.md

@@ -55,7 +55,7 @@ $ bundle exec cap install STAGES=local,sandbox,qa,production
 ## Usage
 
 ``` sh
-$ bundle exec cap -vT
+$ bundle exec cap -T
 
 $ bundle exec cap staging deploy
 $ bundle exec cap production deploy

lib/capistrano/application.rb

@@ -16,10 +16,44 @@ module Capistrano
     end
 
     def sort_options(options)
+      not_applicable_to_capistrano = %w(quiet silent verbose)
+      options.reject! do |(switch, *)|
+        switch =~ /--#{Regexp.union(not_applicable_to_capistrano)}/
+      end
+
       options.push(version, roles, dry_run, hostfilter)
       super
     end
 
+    def handle_options
+      options.rakelib = ['rakelib']
+      options.trace_output = $stderr
+
+      OptionParser.new do |opts|
+        opts.banner = "See full documentation at http://capistranorb.com/."
+        opts.separator ""
+        opts.separator "Install capistrano in a project:"
+        opts.separator "    bundle exec cap install [STAGES=qa,staging,production,...]"
+        opts.separator ""
+        opts.separator "Show available tasks:"
+        opts.separator "    bundle exec cap -T"
+        opts.separator ""
+        opts.separator "Invoke (or simulate invoking) a task:"
+        opts.separator "    bundle exec cap [--dry-run] STAGE TASK"
+        opts.separator ""
+        opts.separator "Advanced options:"
+
+        opts.on_tail("-h", "--help", "-H", "Display this help message.") do
+          puts opts
+          exit
+        end
+
+        standard_rake_options.each { |args| opts.on(*args) }
+        opts.environment('RAKEOPT')
+      end.parse!
+    end
+
+
     def top_level_tasks
       if tasks_without_stage_dependency.include?(@top_level_tasks.first)
         @top_level_tasks

spec/lib/capistrano/application_spec.rb

@@ -6,11 +6,21 @@ describe Capistrano::Application do
 
   it "provides a --format option which enables the choice of output formatting"
 
-  it "identifies itself as cap and not rake" do
+  let(:help_output) do
     out, _ = capture_io do
       flags '--help', '-h'
     end
-    out.lines.first.should match(/cap \[-f rakefile\]/)
+    out
+  end
+
+  it "displays documentation URL as help banner" do
+    help_output.lines.first.should match(/capistranorb.com/)
+  end
+
+  %w(quiet silent verbose).each do |switch|
+    it "doesn't include --#{switch} in help" do
+      help_output.should_not match(/--#{switch}/)
+    end
   end
 
   it "overrides the rake method, but still prints the rake version" do