Document --env=std

Library/Contributions/manpages/brew.1.md

@@ -142,14 +142,20 @@ Note that these flags should only appear after a command.
   * `info` <URL>:
     Print the name and version that will be detected for <URL>.
 
-  * `install [--debug] [--ignore-dependencies] [--fresh] [--use-clang|--use-gcc|--use-llvm] [--build-from-source] [--devel|--HEAD]` <formula>:
+  * `install [--debug] [--env=<std|super>] [--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 it can be specified
     several different ways. See [SPECIFYING FORMULAE][].
 
-    If `--debug` is passed and brewing fails, open a shell inside the
+    If `--debug` is passed and brewing fails, open an interactive debugging
-    temporary directory used for compiling.
+    session with access to IRB, ruby-debug, or a shell inside the temporary
+    build directory.
+
+    If `--env=std` is passed, use the standard build environment instead of superenv.
+
+    If `--env=super` is passed, use superenv even if the formula specifies the
+    standard build environment.
 
     If `--ignore-dependencies` is passed, skip installing any dependencies of
     any kind. If they are not already present, the formula will probably fail
@@ -214,7 +220,7 @@ Note that these flags should only appear after a command.
 
     If `--pinned` is passed, show the versions of pinned formulae, or only the
     specified (pinned) formulae if <formulae> are given.
-    See also [`pin`][], [`unpin`][].
+    See also `pin`, `unpin`.
 
   * `log [git-log-options]` <formula> ...:
     Show the git log for the given formulae. Options that `git-log`(1)
@@ -243,7 +249,7 @@ Note that these flags should only appear after a command.
 
   * `pin` <formulae>:
     Pin the specified <formulae>, preventing them from being upgraded when
-    issuing the `brew upgrade` command without arguments. See also [`unpin`][].
+    issuing the `brew upgrade` command without arguments. See also `unpin`.
 
   * `prune`:
     Remove dead symlinks from the Homebrew prefix. This is generally not
@@ -294,7 +300,7 @@ Note that these flags should only appear after a command.
 
   * `unpin` <formulae>:
     Unpin <formulae>, allowing them to be upgraded by `brew upgrade`. See also
-    [`pin`][].
+    `pin`.
 
   * `untap` <tap>:
     Remove a tapped repository.
@@ -305,11 +311,13 @@ Note that these flags should only appear after a command.
 
     If `--rebase` is specified then `git pull --rebase` is used.
 
-  * `upgrade` [<formulae>]:
+  * `upgrade [install-options]` [<formulae>]:
-    Upgrade outdated, non-pinned brews.
+    Upgrade outdated, unpinned brews.
+
+    Options for the `install` command are also valid here.
 
     If <formulae> are given, upgrade only the specified brews (but do so even
-    if they are pinned; see [`pin`][], [`unpin`][]).
+    if they are pinned; see `pin`, `unpin`).
 
   * `uses [--installed] [--recursive]` <formula>:
     Show the formulae that specify <formula> as a dependency.

share/man/man1/brew.1

@@ -164,14 +164,20 @@ To view formula history locally: \fBbrew log \-p <formula>\fR\.
 Print the name and version that will be detected for \fIURL\fR\.
 .
 .TP
-\fBinstall [\-\-debug] [\-\-ignore\-dependencies] [\-\-fresh] [\-\-use\-clang|\-\-use\-gcc|\-\-use\-llvm] [\-\-build\-from\-source] [\-\-devel|\-\-HEAD]\fR \fIformula\fR
+\fBinstall [\-\-debug] [\-\-env=<std|super>] [\-\-ignore\-dependencies] [\-\-fresh] [\-\-use\-clang|\-\-use\-gcc|\-\-use\-llvm] [\-\-build\-from\-source] [\-\-devel|\-\-HEAD]\fR \fIformula\fR
 Install \fIformula\fR\.
 .
 .IP
 \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\-\-debug\fR is passed and brewing fails, open a shell inside the temporary directory used for compiling\.
+If \fB\-\-debug\fR is passed and brewing fails, open an interactive debugging session with access to IRB, ruby\-debug, or a shell inside the temporary build directory\.
+.
+.IP
+If \fB\-\-env=std\fR is passed, use the standard build environment instead of superenv\.
+.
+.IP
+If \fB\-\-env=super\fR is passed, use superenv even if the formula specifies the standard build environment\.
 .
 .IP
 If \fB\-\-ignore\-dependencies\fR is passed, skip installing any dependencies of any kind\. If they are not already present, the formula will probably fail to install\.
@@ -234,7 +240,7 @@ If \fB\-\-unbrewed\fR is passed, list all files in the Homebrew prefix not insta
 If \fB\-\-versions\fR is passed, show the version number for installed formulae, or only the specified formulae if \fIformulae\fR are given\.
 .
 .IP
-If \fB\-\-pinned\fR is passed, show the versions of pinned formulae, or only the specified (pinned) formulae if \fIformulae\fR are given\. See also [\fBpin\fR][], [\fBunpin\fR][]\.
+If \fB\-\-pinned\fR is passed, show the versions of pinned formulae, or only the specified (pinned) formulae if \fIformulae\fR are given\. See also \fBpin\fR, \fBunpin\fR\.
 .
 .TP
 \fBlog [git\-log\-options]\fR \fIformula\fR \.\.\.
@@ -269,7 +275,7 @@ If \fB\-\-quiet\fR is passed, list only the names of outdated brews\. Otherwise,
 .
 .TP
 \fBpin\fR \fIformulae\fR
-Pin the specified \fIformulae\fR, preventing them from being upgraded when issuing the \fBbrew upgrade\fR command without arguments\. See also [\fBunpin\fR][]\.
+Pin the specified \fIformulae\fR, preventing them from being upgraded when issuing the \fBbrew upgrade\fR command without arguments\. See also \fBunpin\fR\.
 .
 .TP
 \fBprune\fR
@@ -320,7 +326,7 @@ Unsymlink \fIformula\fR from the Homebrew prefix\. This can be useful for tempor
 .
 .TP
 \fBunpin\fR \fIformulae\fR
-Unpin \fIformulae\fR, allowing them to be upgraded by \fBbrew upgrade\fR\. See also [\fBpin\fR][]\.
+Unpin \fIformulae\fR, allowing them to be upgraded by \fBbrew upgrade\fR\. See also \fBpin\fR\.
 .
 .TP
 \fBuntap\fR \fItap\fR
@@ -334,11 +340,14 @@ Fetch the newest version of Homebrew and all formulae from GitHub using \fBgit\f
 If \fB\-\-rebase\fR is specified then \fBgit pull \-\-rebase\fR is used\.
 .
 .TP
-\fBupgrade\fR [\fIformulae\fR]
+\fBupgrade [install\-options]\fR [\fIformulae\fR]
-Upgrade outdated, non\-pinned brews\.
+Upgrade outdated, unpinned brews\.
 .
 .IP
-If \fIformulae\fR are given, upgrade only the specified brews (but do so even if they are pinned; see [\fBpin\fR][], [\fBunpin\fR][])\.
+Options for the \fBinstall\fR command are also valid here\.
+.
+.IP
+If \fIformulae\fR are given, upgrade only the specified brews (but do so even if they are pinned; see \fBpin\fR, \fBunpin\fR)\.
 .
 .TP
 \fBuses [\-\-installed] [\-\-recursive]\fR \fIformula\fR