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.

1 files changed, 29 insertions, 15 deletions

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