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.

3 files changed, 49 insertions, 17 deletions

diff --git a/Library/Homebrew/cmd/help.rb b/Library/Homebrew/cmd/help.rb
index f729c0e8c..76eef90a8 100644
--- a/Library/Homebrew/cmd/help.rb
+++ b/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
diff --git a/Library/Homebrew/cmd/man.rb b/Library/Homebrew/cmd/man.rb
index a3f95f53f..785e2cf65 100644
--- a/Library/Homebrew/cmd/man.rb
+++ b/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|
-        args = %W[
-          --pipe
-          --organization=Homebrew
-          --manual=brew
-          #{source_file}
-        ]
-        page = File.basename(source_file, ".md")
-
-        target_html = DOC_PATH/"#{page}.html"
-        target_html.atomic_write Utils.popen_read("ronn", "--fragment", *args)
-
-        target_man = TARGET_PATH/page
-        target_man.atomic_write Utils.popen_read("ronn", "--roff", *args)
-      end
+      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_PATH}/brew.1.md
+      ]
+
+      target_html = DOC_PATH/"brew.1.html"
+      target_html.atomic_write Utils.popen_read("ronn", "--fragment", *args)
+
+      target_man = TARGET_PATH/"brew.1"
+      target_man.atomic_write Utils.popen_read("ronn", "--roff", *args)
     end
   end
 end
diff --git a/Library/Homebrew/cmd/update.sh b/Library/Homebrew/cmd/update.sh
index 8ffd2eadb..2c04664c3 100644
--- a/Library/Homebrew/cmd/update.sh
+++ b/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; exit $? ;;
+      --help) brew help update; exit $? ;;
       --verbose) HOMEBREW_VERBOSE=1 ;;
       --debug) HOMEBREW_DEBUG=1;;
       --rebase) HOMEBREW_REBASE=1 ;;