Homebrew · UniqMartin · Apr 17, 2016 · Apr 17, 2016 · Apr 17, 2016 · Apr 17, 2016
diff --git a/Library/Homebrew/cmd/--cache.rb b/Library/Homebrew/cmd/--cache.rb
@@ -1,3 +1,9 @@
+#:  * `--cache`:
+#:    Display Homebrew's download cache. See also `HOMEBREW_CACHE`.
+#:
+#:  * `--cache` <formula>:
+#:    Display the file or directory used to cache <formula>.
+
 require "cmd/fetch"
 
 module Homebrew

diff --git a/Library/Homebrew/cmd/--cellar.rb b/Library/Homebrew/cmd/--cellar.rb
@@ -1,3 +1,11 @@
+#:  * `--cellar`:
+#:    Display Homebrew's Cellar path. *Default:* `$(brew --prefix)/Cellar`, or if
+#:    that directory doesn't exist, `$(brew --repository)/Cellar`.
+#:
+#:  * `--cellar` <formula>:
+#:    Display the location in the cellar where <formula> would be installed,
+#:    without any sort of versioned directory as the last path.
+
 module Homebrew
   def __cellar
     if ARGV.named.empty?

diff --git a/Library/Homebrew/cmd/--env.rb b/Library/Homebrew/cmd/--env.rb
@@ -1,3 +1,6 @@
+#:  * `--env`:
+#:    Show a summary of the Homebrew build environment.
+
 require "extend/ENV"
 require "build_environment"
 

diff --git a/Library/Homebrew/cmd/--prefix.rb b/Library/Homebrew/cmd/--prefix.rb
@@ -1,3 +1,9 @@
+#:  * `--prefix`:
+#:    Display Homebrew's install path. *Default:* `/usr/local`
+#:
+#:  * `--prefix` <formula>:
+#:    Display the location in the cellar where <formula> is or would be installed.
+
 module Homebrew
   def __prefix
     if ARGV.named.empty?

diff --git a/Library/Homebrew/cmd/--repository.rb b/Library/Homebrew/cmd/--repository.rb
@@ -1,3 +1,10 @@
+#:  * `--repository`:
+#:    Display where Homebrew's `.git` directory is located. For standard installs,
+#:    the `prefix` and `repository` are the same directory.
+#:
+#:  * `--repository` <user>`/`<repo>:
+#:    Display where tap <user>`/`<repo>'s directory is located.
+
 require "tap"
 
 module Homebrew

diff --git a/Library/Homebrew/cmd/--version.rb b/Library/Homebrew/cmd/--version.rb
@@ -0,0 +1,12 @@
+#:  * `--version`:
+#:    Print the version number of Homebrew to standard output and exit.
+
+module Homebrew
+  def __version
+    # As a special case, `--version` is implemented directly in `brew.rb`. This
+    # file merely serves as a container for the documentation. It also catches
+    # the case where running `brew --version` with additional arguments would
+    # produce a rather cryptic message about a non-existent `--version` command.
+    raise UsageError
+  end
+end
diff --git a/Library/Homebrew/cmd/help.rb b/Library/Homebrew/cmd/help.rb
@@ -1,18 +1,18 @@
 HOMEBREW_HELP = <<-EOS
 Example usage:
-  brew [info | home | options ] [FORMULA...]
+  brew (info|home|options) [FORMULA...]
   brew install FORMULA...
   brew uninstall FORMULA...
-  brew search [foo]
+  brew search [TEXT|/PATTERN/]
   brew list [FORMULA...]
   brew update
   brew upgrade [FORMULA...]
-  brew pin/unpin [FORMULA...]
+  brew (pin|unpin) [FORMULA...]
 
 Troubleshooting:
   brew doctor
   brew install -vd FORMULA
-  brew [--env | config]
+  brew (--env|config)
 
 Brewing:
   brew create [URL [--no-fetch]]
@@ -21,6 +21,7 @@
 
 Further help:
   man brew
+  brew help [COMMAND]
   brew home
 EOS
 

diff --git a/Library/Homebrew/cmd/man.rb b/Library/Homebrew/cmd/man.rb
@@ -44,7 +44,7 @@ def build_man_page
     variables = OpenStruct.new
 
     variables[:commands] = Pathname.glob("#{HOMEBREW_LIBRARY_PATH}/cmd/*.{rb,sh}").
-      sort_by { |source_file| source_file.basename.sub(/\.(rb|sh)$/, "") }.
+      sort_by { |source_file| sort_key_for_path(source_file) }.
       map { |source_file|
         source_file.read.lines.
           grep(/^#:/).
@@ -56,6 +56,11 @@ def build_man_page
     ERB.new(template, nil, ">").result(variables.instance_eval{ binding })
   end
 
+  def sort_key_for_path(path)
+    # Options after regular commands (`~` comes after `z` in ASCII table).
+    path.basename.to_s.sub(/\.(rb|sh)$/, "").sub(/^--/, "~~")
+  end
+
   def convert_man_page(markup, target)
     shared_args = %W[
       --pipe

diff --git a/Library/Homebrew/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb
@@ -50,39 +50,6 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
 
 <%= commands.join("\n") %>
 
-  * `--cache`:
-    Display Homebrew's download cache. See also `HOMEBREW_CACHE`.
-
-  * `--cache` <formula>:
-    Display the file or directory used to cache <formula>.
-
-  * `--cellar`:
-    Display Homebrew's Cellar path. *Default:* `$(brew --prefix)/Cellar`, or if
-    that directory doesn't exist, `$(brew --repository)/Cellar`.
-
-  * `--cellar` <formula>:
-    Display the location in the cellar where <formula> would be installed,
-    without any sort of versioned directory as the last path.
-
-  * `--env`:
-    Show a summary of the Homebrew build environment.
-
-  * `--prefix`:
-    Display Homebrew's install path. *Default:* `/usr/local`
-
-  * `--prefix` <formula>:
-    Display the location in the cellar where <formula> is or would be installed.
-
-  * `--repository`:
-    Display where Homebrew's `.git` directory is located. For standard installs,
-    the `prefix` and `repository` are the same directory.
-
-  * `--repository` <user>`/`<repo>:
-    Display where tap <user>`/`<repo>'s directory is located.
-
-  * `--version`:
-    Print the version number of brew to standard error and exit.
-
 ## EXTERNAL COMMANDS
 
 Homebrew, like `git`(1), supports external commands. These are executable

diff --git a/share/doc/homebrew/brew.1.html b/share/doc/homebrew/brew.1.html
@@ -410,7 +410,7 @@ <h2 id="COMMANDS">COMMANDS</h2>
 <dt><code>--repository</code></dt><dd><p>Display where Homebrew's <code>.git</code> directory is located. For standard installs,
 the <code>prefix</code> and <code>repository</code> are the same directory.</p></dd>
 <dt><code>--repository</code> <var>user</var><code>/</code><var>repo</var></dt><dd><p>Display where tap <var>user</var><code>/</code><var>repo</var>'s directory is located.</p></dd>
-<dt><code>--version</code></dt><dd><p>Print the version number of brew to standard error and exit.</p></dd>
+<dt><code>--version</code></dt><dd><p>Print the version number of Homebrew to standard output and exit.</p></dd>
 </dl>
 
 

diff --git a/share/man/man1/brew.1 b/share/man/man1/brew.1
@@ -586,7 +586,7 @@ Display where tap \fIuser\fR\fB/\fR\fIrepo\fR\'s directory is located\.
 .
 .TP
 \fB\-\-version\fR
-Print the version number of brew to standard error and exit\.
+Print the version number of Homebrew to standard output and exit\.
 .
 .SH "EXTERNAL COMMANDS"
 Homebrew, like \fBgit\fR(1), supports external commands\. These are executable scripts that reside somewhere in the \fBPATH\fR, named \fBbrew\-\fR\fIcmdname\fR or \fBbrew\-\fR\fIcmdname\fR\fB\.rb\fR, which can be invoked like \fBbrew\fR \fIcmdname\fR\. This allows you to create your own commands without modifying Homebrew\'s internals\.