Note cases when pinned formulae get upgraded.

Fixes #3021.

Library/Homebrew/cmd/pin.rb

@@ -1,6 +1,7 @@
 #:  * `pin` <formulae>:
 #:    Pin the specified <formulae>, preventing them from being upgraded when
-#:    issuing the `brew upgrade` command. See also `unpin`.
+#:    issuing the `brew upgrade <formulae>` command (but can still be upgraded
+#:    as dependencies for other formulae). See also `unpin`.
 
 require "formula"
 

Library/Homebrew/cmd/unpin.rb

@@ -1,6 +1,6 @@
 #:  * `unpin` <formulae>:
-#:    Unpin <formulae>, allowing them to be upgraded by `brew upgrade`. See also
+#:    Unpin <formulae>, allowing them to be upgraded by `brew upgrade <formulae>`.
-#:    `pin`.
+#:    See also `pin`.
 
 require "formula"
 

docs/FAQ.md

@@ -26,6 +26,8 @@ To allow that formulae to update again:
 
     brew unpin <formula>
 
+Note that pinned, outdated formulae that are depended on by another formula will be upgraded when required as we do not allow formulae to be built against non-latest versions.
+
 ## How do I uninstall old versions of a formula?
 By default, Homebrew does not uninstall old versions of a formula, so
 over time you will accumulate old versions. To remove them, simply use:

docs/Manpage.md

@@ -364,7 +364,8 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
 
   * `pin` `formulae`:
     Pin the specified `formulae`, preventing them from being upgraded when
-    issuing the `brew upgrade` command. See also `unpin`.
+    issuing the `brew upgrade `formulae`` command (but can still be upgraded
+    as dependencies for other formulae). See also `unpin`.
 
   * `postinstall` `formula`:
     Rerun the post-install steps for `formula`.
@@ -529,8 +530,8 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
     source. This is useful for creating patches for the software.
 
   * `unpin` `formulae`:
-    Unpin `formulae`, allowing them to be upgraded by `brew upgrade`. See also
+    Unpin `formulae`, allowing them to be upgraded by `brew upgrade `formulae``.
-    `pin`.
+    See also `pin`.
 
   * `untap` `tap`:
     Remove a tapped repository.

manpages/brew-cask.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW\-CASK" "1" "July 2017" "Homebrew" "brew-cask"
+.TH "BREW\-CASK" "1" "August 2017" "Homebrew" "brew-cask"
 .
 .SH "NAME"
 \fBbrew\-cask\fR \- a friendly binary installer for macOS

manpages/brew.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW" "1" "July 2017" "Homebrew" "brew"
+.TH "BREW" "1" "August 2017" "Homebrew" "brew"
 .
 .SH "NAME"
 \fBbrew\fR \- The missing package manager for macOS
@@ -378,7 +378,7 @@ If \fB\-\-fetch\-HEAD\fR is passed, fetch the upstream repository to detect if t
 .
 .TP
 \fBpin\fR \fIformulae\fR
-Pin the specified \fIformulae\fR, preventing them from being upgraded when issuing the \fBbrew upgrade\fR command\. See also \fBunpin\fR\.
+Pin the specified \fIformulae\fR, preventing them from being upgraded when issuing the \fBbrew upgrade <formulae>\fR command (but can still be upgraded as dependencies for other formulae)\. See also \fBunpin\fR\.
 .
 .TP
 \fBpostinstall\fR \fIformula\fR
@@ -549,7 +549,7 @@ If \fB\-\-git\fR (or \fB\-g\fR) is passed, a Git repository will be initialized
 .
 .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 <formulae>\fR\. See also \fBpin\fR\.
 .
 .TP
 \fBuntap\fR \fItap\fR