Implement the brew help command

This is also used by `brew <cmd> --help`. The basic idea is to have the
documentation as a top level comment in each command file. To find these
comments, they have to be like this `#:`.

This is also used by the `brew man` command to keep the documentation
DRY, and for that there are now a header and footer for the man page.

Library/Homebrew/cmd/help.rb

@@ -39,4 +39,23 @@ module Homebrew
   def help_s
     HOMEBREW_HELP
   end
+
+  def help_for_command(cmd)
+    cmd_path = if File.exist?(HOMEBREW_LIBRARY_PATH/"cmd/#{cmd}.sh")
+      HOMEBREW_LIBRARY_PATH/"cmd/#{cmd}.sh"
+    elsif ARGV.homebrew_developer? && File.exist?(HOMEBREW_LIBRARY_PATH/"dev-cmd/#{cmd}.sh")
+      HOMEBREW_LIBRARY_PATH/"dev-cmd/#{cmd}.sh"
+    elsif File.exist?(HOMEBREW_LIBRARY_PATH/"cmd/#{cmd}.rb")
+      HOMEBREW_LIBRARY_PATH/"cmd/#{cmd}.rb"
+    elsif ARGV.homebrew_developer? && File.exist?(HOMEBREW_LIBRARY_PATH/"dev-cmd/#{cmd}.rb")
+      HOMEBREW_LIBRARY_PATH/"dev-cmd/#{cmd}.rb"
+    end
+    return if cmd_path.nil?
+
+    cmd_path.read.
+      split("\n").
+      grep(/^#:/).
+      map { |line| line.slice(2..-1).delete("`").sub(/^  \* /, "brew ") }.
+      join("\n")
+  end
 end

Library/Homebrew/cmd/man.rb

@@ -25,21 +25,35 @@ module Homebrew
       puts "Writing HTML fragments to #{DOC_PATH}"
       puts "Writing manpages to #{TARGET_PATH}"
 
-      Dir["#{SOURCE_PATH}/*.md"].each do |source_file|
+      header = (SOURCE_PATH/"header.1.md").read
+      footer = (SOURCE_PATH/"footer.1.md").read
+      sub_commands = Pathname.glob("#{HOMEBREW_LIBRARY_PATH}/cmd/*.{rb,sh}").
+        sort_by { |source_file| source_file.basename.sub(/\.(rb|sh)$/, "") }.
+        map { |source_file|
+          source_file.read.
+            split("\n").
+            grep(/^#:/).
+            map { |line| line.slice(2..-1) }.
+            join("\n")
+        }.
+        reject { |s| s.strip.empty? }.
+        join("\n\n")
+
+      target_md = SOURCE_PATH/"brew.1.md"
+      target_md.atomic_write(header + sub_commands + footer)
+
       args = %W[
         --pipe
         --organization=Homebrew
         --manual=brew
-          #{source_file}
+        #{SOURCE_PATH}/brew.1.md
       ]
-        page = File.basename(source_file, ".md")
 
-        target_html = DOC_PATH/"#{page}.html"
+      target_html = DOC_PATH/"brew.1.html"
       target_html.atomic_write Utils.popen_read("ronn", "--fragment", *args)
 
-        target_man = TARGET_PATH/page
+      target_man = TARGET_PATH/"brew.1"
       target_man.atomic_write Utils.popen_read("ronn", "--roff", *args)
     end
   end
 end
-end

Library/Homebrew/cmd/update.sh

@@ -220,8 +220,7 @@ homebrew-update() {
   for option in "$@"
   do
     case "$option" in
-      # TODO: - `brew update --help` should display update subcommand help
+      --help) brew help update; exit $? ;;
-      --help) brew --help; exit $? ;;
       --verbose) HOMEBREW_VERBOSE=1 ;;
       --debug) HOMEBREW_DEBUG=1;;
       --rebase) HOMEBREW_REBASE=1 ;;

Library/brew.rb

@@ -69,15 +69,27 @@ begin
   # It should never affect external commands so they can handle usage
   # arguments themselves.
 
-  if empty_argv || (help_flag && (cmd.nil? || internal_cmd))
-    # TODO: - `brew help cmd` should display subcommand help
-    require "cmd/help"
   if empty_argv
     $stderr.puts ARGV.usage
-    else
+    exit 1
+  elsif help_flag
+    if cmd.nil?
       puts ARGV.usage
+      exit 0
+    else
+      # Handle both internal ruby and shell commands
+      require "cmd/help"
+      help_text = Homebrew.help_for_command(cmd)
+      if help_text.nil?
+        # External command, let it handle help by itself
+      elsif help_text.empty?
+        puts "No help available for #{cmd}"
+        exit 1
+      else
+        puts help_text
+        exit 0
+      end
     end
-    exit ARGV.any? ? 0 : 1
   end
 
   if internal_cmd