Clarify brew search usage. (#270)

* Include --desc in brew search help text.
* Update brew search --desc text in README.
* Remove mention of alias in brew search help text to avoid any
  confusion.

Library/Homebrew/cmd/search.rb

-#:  * `search`, `-S`:
+#:  * `search`:
 #:    Display all locally available formulae for brewing (including tapped ones).
 #:    No online search is performed if called without arguments.
 #:
-#:  * `search`, `-S` <text>|`/`<text>`/`:
+#:  * `search` [`--desc`] <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.
 #:    The search for <text> is extended online to some popular taps.
 #:
+#:    If `--desc` is passed, browse available packages matching <text> including a
+#:    description for each.
+#:
 #:  * `search` (`--debian`|`--fedora`|`--fink`|`--macports`|`--opensuse`|`--ubuntu`) <text>:
 #:    Search for <text> in the given package manager's list.
 

README.md

@@ -4,7 +4,7 @@ Features, usage and installation instructions are [summarised on the homepage](h
 ## What Packages Are Available?
 1. Type `brew search` for a list.
 2. Or visit [braumeister.org](http://braumeister.org) to browse packages online.
-3. Or use `brew search --desc` to browse packages from the command line.
+3. Or use `brew search --desc <keyword>` to browse packages from the command line.
 
 ## More Documentation
 `brew help`, `man brew` or check [our documentation](https://github.com/Homebrew/brew/tree/master/share/doc/homebrew#readme).

share/doc/homebrew/brew.1.html

@@ -314,11 +314,14 @@ created by <code>brew linkapps</code>.</p>
 <p>If <code>--dry-run</code> or <code>-n</code> is passed, show what would be removed, but do not
 actually remove anything.</p></dd>
 <dt><code>reinstall</code> <var>formula</var></dt><dd><p>Uninstall then install <var>formula</var></p></dd>
-<dt><code>search</code>, <code>-S</code></dt><dd><p>Display all locally available formulae for brewing (including tapped ones).
+<dt class="flush"><code>search</code></dt><dd><p>Display all locally available formulae for brewing (including tapped ones).
 No online search is performed if called without arguments.</p></dd>
-<dt><code>search</code>, <code>-S</code> <var>text</var>|<code>/</code><var>text</var><code>/</code></dt><dd><p>Perform a substring search of formula names for <var>text</var>. If <var>text</var> is
+<dt><code>search</code> [<code>--desc</code>] <var>text</var>|<code>/</code><var>text</var><code>/</code></dt><dd><p>Perform a substring search of formula names for <var>text</var>. If <var>text</var> is
 surrounded with slashes, then it is interpreted as a regular expression.
-The search for <var>text</var> is extended online to some popular taps.</p></dd>
+The search for <var>text</var> is extended online to some popular taps.</p>
+
+<p>If <code>--desc</code> is passed, browse available packages matching <var>text</var> including a
+description for each.</p></dd>
 <dt><code>search</code> (<code>--debian</code>|<code>--fedora</code>|<code>--fink</code>|<code>--macports</code>|<code>--opensuse</code>|<code>--ubuntu</code>) <var>text</var></dt><dd><p>Search for <var>text</var> in the given package manager's list.</p></dd>
 <dt><code>sh</code> [<code>--env=std</code>]</dt><dd><p>Instantiate a Homebrew build environment. Uses our years-battle-hardened
 Homebrew build logic to help your <code>./configure &amp;&amp; make &amp;&amp; make install</code>

share/man/man1/brew.1

@@ -426,13 +426,16 @@ If \fB\-\-dry\-run\fR or \fB\-n\fR is passed, show what would be removed, but do
 Uninstall then install \fIformula\fR
 .
 .TP
-\fBsearch\fR, \fB\-S\fR
+\fBsearch\fR
 Display all locally available formulae for brewing (including tapped ones)\. No online search is performed if called without arguments\.
 .
 .TP
-\fBsearch\fR, \fB\-S\fR \fItext\fR|\fB/\fR\fItext\fR\fB/\fR
+\fBsearch\fR [\fB\-\-desc\fR] \fItext\fR|\fB/\fR\fItext\fR\fB/\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\. The search for \fItext\fR is extended online to some popular taps\.
 .
+.IP
+If \fB\-\-desc\fR is passed, browse available packages matching \fItext\fR including a description for each\.
+.
 .TP
 \fBsearch\fR (\fB\-\-debian\fR|\fB\-\-fedora\fR|\fB\-\-fink\fR|\fB\-\-macports\fR|\fB\-\-opensuse\fR|\fB\-\-ubuntu\fR) \fItext\fR
 Search for \fItext\fR in the given package manager\'s list\.