Document how formula arguments can be specified

Closes Homebrew#11037.

Signed-off-by: Jack Nagel <[email protected]>

Author: jacknagel

Library/Contributions/manpages/brew.1.md

@@ -142,8 +142,8 @@ For the full command list, see the COMMANDS section.
   * `install [--force] [--debug] [--ignore-dependencies] [--fresh] [--use-clang] [--use-gcc] [--use-llvm] [--build-from-source] [--devel] [--HEAD]` <formula>:
     Install <formula>.
 
-    <formula> is usually the name of the formula to install, but may also be
-    the URL for an arbitrary formula.
+    <formula> is usually the name of the formula to install, but it can be specified
+    several different ways. See [SPECIFYING FORMULAE][].
 
     If `--force` is passed, will install <formula> if it exists, even if it
     is blacklisted.
@@ -338,6 +338,24 @@ Documentation for the included external commands as well as instructions for
 creating your own can be found on the wiki:
 <http://wiki.github.com/mxcl/homebrew/External-Commands>
 
+## SPECIFYING FORMULAE
+
+Many Homebrew commands accept one or more <formula> arguments. These arguments
+can take several different forms:
+
+  * The name of a formula:
+    e.g. `git`, `node`, `wget`.
+
+  * The fully-qualified name of a tapped formula:
+    Sometimes a formula from a tapped repository may conflict with one in mxcl/master.
+    You can still access these formulae by using a special syntax, e.g.
+    `homebrew/dupes/vim` or `homebrew/versions/node4`.
+
+  * An arbitrary URL:
+    Homebrew can install formulae via URL, e.g.
+    `https://raw.github.com/mxcl/homebrew/master/Library/Formula/git.rb`.
+    The formula file will be cached for later use.
+
 ## ENVIRONMENT
 
   * HOMEBREW\_BUILD\_FROM\_SOURCE:

share/man/man1/brew.1

@@ -165,7 +165,7 @@ Print the name and version that will be detected for \fIURL\fR\.
 Install \fIformula\fR\.
 .
 .IP
-\fIformula\fR is usually the name of the formula to install, but may also be the URL for an arbitrary formula\.
+\fIformula\fR is usually the name of the formula to install, but it can be specified several different ways\. See \fISPECIFYING FORMULAE\fR\.
 .
 .IP
 If \fB\-\-force\fR is passed, will install \fIformula\fR if it exists, even if it is blacklisted\.
@@ -379,6 +379,21 @@ $ ls `brew \-\-repository`/Library/Contributions/cmds
 .P
 Documentation for the included external commands as well as instructions for creating your own can be found on the wiki: \fIhttp://wiki\.github\.com/mxcl/homebrew/External\-Commands\fR
 .
+.SH "SPECIFYING FORMULAE"
+Many Homebrew commands accept one or more \fIformula\fR arguments\. These arguments can take several different forms:
+.
+.TP
+The name of a formula
+e\.g\. \fBgit\fR, \fBnode\fR, \fBwget\fR\.
+.
+.TP
+The fully\-qualified name of a tapped formula
+Sometimes a formula from a tapped repository may conflict with one in mxcl/master\. You can still access these formulae by using a special syntax, e\.g\. \fBhomebrew/dupes/vim\fR or \fBhomebrew/versions/node4\fR\.
+.
+.TP
+An arbitrary URL
+Homebrew can install formulae via URL, e\.g\. \fBhttps://raw\.github\.com/mxcl/homebrew/master/Library/Formula/git\.rb\fR\. The formula file will be cached for later use\.
+.
 .SH "ENVIRONMENT"
 .
 .TP