--version: move help to documentation comment

This implies that `--version` is treated in most places like a regular
command, e.g. being suggested in shell completion. Also fix the help
text that claimed output goes to standard error, while it actually goes
to standard output.

4 files changed, 14 insertions, 5 deletions

diff --git a/Library/Homebrew/cmd/--version.rb b/Library/Homebrew/cmd/--version.rb
new file mode 100644
index 000000000..9a571abe1
--- /dev/null
+++ 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/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb
index b6726089e..92acb86ee 100644
--- a/Library/Homebrew/manpages/brew.1.md.erb
+++ b/Library/Homebrew/manpages/brew.1.md.erb
@@ -50,9 +50,6 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
 
 <%= commands.join("\n") %>
 
-  * `--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
index 682e33d62..ed7957c01 100644
--- a/share/doc/homebrew/brew.1.html
+++ b/share/doc/homebrew/brew.1.html
@@ -410,7 +410,7 @@ without any sort of versioned directory as the last path.</p></dd>
 <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
index be2540ff4..18f92e5ac 100644
--- 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\.