Optimise/simplify `brew help`

Be more useful by being more concise. I referenced dozens of other mature commands’ usage to figure out what to do here.

Also separated out the help into its own command for consistency.

4 files changed, 51 insertions, 53 deletions

diff --git a/Library/Contributions/manpages/brew.1.md b/Library/Contributions/manpages/brew.1.md
index 5e7738df1..a26805706 100644
--- a/Library/Contributions/manpages/brew.1.md
+++ b/Library/Contributions/manpages/brew.1.md
@@ -56,12 +56,12 @@ didn't include with OS X.
     If `--git` is passed, Homebrew will create a Git repository, useful for
     creating patches to the software.
 
-  * `-S`, `search` <text>|/<text>/:
+  * `search`, `-S` <text>|/<text>/:
     Perform a substring search of formula names for <text>. If <text> is
     surrounded with slashes, then it is interpreted as a regular expression.
     If no search term is given, all available formula are displayed.
 
-  * `-S --macports`|`--fink` <text>:
+  * `search --macports`|`--fink` <text>:
     Search for <text> on the MacPorts or Fink package search page.
 
   * `update`:
@@ -96,14 +96,14 @@ didn't include with OS X.
     If `--force` is passed, and there are multiple versions of <formula>
     installed, delete all installed versions.
 
-  * `create [--cache]` <URL>:
+  * `create [--no-fetch]` <URL>:
     Generate a formula for the downloadable file at <URL> and opens it in
     $EDITOR. Homebrew will attempt to automatically derive the formula name
     and version, if it fails, you'll have to make your own template. I suggest
     copying wget's.
 
-    If `--cache` is passed, Homebrew will download the <URL> to the cache and
-    add the MD5 to the formula for you.
+    If `--no-fetch` is passed, Homebrew will not download <URL> to the cache and
+    will thus not add the MD5 to the formula for you.
 
   * `edit` <formula>:
     Open <formula> in $EDITOR.
diff --git a/Library/Homebrew/cmd/help.rb b/Library/Homebrew/cmd/help.rb
new file mode 100644
index 000000000..3e7cc75b9
--- /dev/null
+++ b/Library/Homebrew/cmd/help.rb
@@ -0,0 +1,40 @@
+HOMEBREW_HELP = <<-EOS
+Example usage:
+  brew install FORMULA...
+  brew uninstall FORMULA...
+  brew search [foo]
+  brew list [FORMULA...]
+  brew update
+  brew outdated
+  brew [info | home] [FORMULA...]
+
+Troubleshooting:
+  brew doctor
+  brew install -vd FORMULA
+  brew [--env | --config]
+
+Brewing:
+  brew create [URL [--no-fetch]]
+  brew edit [FORMULA...]
+  open https://github.com/mxcl/homebrew/wiki/Formula-Cookbook
+
+Further help:
+  man brew
+  brew home
+EOS
+
+# NOTE Keep the lenth of vanilla --help less than 25 lines!
+# This is because the default Terminal height is 25 lines. Scrolling sucks
+# and concision is important. If more help is needed we should start
+# specialising help like the gem command does.
+# NOTE Keep lines less than 80 characters! Wrapping is just not cricket.
+# NOTE The reason the string is at the top is so 25 lines is easy to measure!
+
+module Homebrew extend self
+  def help
+    puts HOMEBREW_HELP
+  end
+  def help_s
+    HOMEBREW_HELP
+  end
+end
diff --git a/Library/Homebrew/extend/ARGV.rb b/Library/Homebrew/extend/ARGV.rb
index 603239a34..604ef27dc 100644
--- a/Library/Homebrew/extend/ARGV.rb
+++ b/Library/Homebrew/extend/ARGV.rb
@@ -67,51 +67,9 @@ module HomebrewArgvExtension
     return false
   end
 
-  def usage; <<-EOS.undent
-    Usage: brew [-v|--version] [--prefix [formula]] [--cache [formula]]
-                [--cellar [formula]] [--config] [--env] [--repository]
-                [-h|--help] COMMAND [formula] ...
-
-    Principal Commands:
-      install formula ... [--ignore-dependencies] [--HEAD]
-      list [--unbrewed|--versions] [formula] ...
-      search [/regex/] [substring]
-      uninstall formula ...
-      update
-
-    Other Commands:
-      info formula [--github]
-      options formula
-      deps formula
-      uses formula [--installed]
-      home formula ...
-      cleanup [formula]
-      link formula ...
-      unlink formula ...
-      outdated
-      missing
-      prune
-      doctor
-
-    Informational:
-      --version
-      --config
-      --prefix [formula]
-      --cache [formula]
-
-    Commands useful when contributing:
-      create URL
-      edit [formula]
-      audit [formula]
-      log formula
-      install formula [-vd|-i]
-
-    For more information:
-      man brew
-
-    To visit the Homebrew homepage type:
-      brew home
-    EOS
+  def usage
+    require 'cmd/help'
+    Homebrew.help_s
   end
 
   private
diff --git a/share/man/man1/brew.1 b/share/man/man1/brew.1
index 8742ed17e..0827baa18 100644
--- a/share/man/man1/brew.1
+++ b/share/man/man1/brew.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW" "1" "February 2011" "Homebrew" "brew"
+.TH "BREW" "1" "March 2011" "Homebrew" "brew"
 .
 .SH "NAME"
 \fBbrew\fR \- The missing package manager for OS X
@@ -60,11 +60,11 @@ Download and patch \fIformula\fR, then open a shell\. This allows the user to ru
 If \fB\-\-git\fR is passed, Homebrew will create a Git repository, useful for creating patches to the software\.
 .
 .TP
-\fB\-S\fR, \fBsearch\fR \fItext\fR|/\fItext\fR/
+\fBsearch\fR, \fB\-S\fR \fItext\fR|/\fItext\fR/
 Perform a substring search of formula names for \fItext\fR\. If \fItext\fR is surrounded with slashes, then it is interpreted as a regular expression\. If no search term is given, all available formula are displayed\.
 .
 .TP
-\fB\-S \-\-macports\fR|\fB\-\-fink\fR \fItext\fR
+\fBsearch \-\-macports\fR|\fB\-\-fink\fR \fItext\fR
 Search for \fItext\fR on the MacPorts or Fink package search page\.
 .
 .TP