Note cases when pinned formulae get upgraded.

Fixes #3021.

6 files changed, 14 insertions, 10 deletions

diff --git a/Library/Homebrew/cmd/pin.rb b/Library/Homebrew/cmd/pin.rb
index c5087f6d4..5a14f853c 100644
--- a/Library/Homebrew/cmd/pin.rb
+++ b/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"
 
diff --git a/Library/Homebrew/cmd/unpin.rb b/Library/Homebrew/cmd/unpin.rb
index a669df1ec..e15a156ea 100644
--- a/Library/Homebrew/cmd/unpin.rb
+++ b/Library/Homebrew/cmd/unpin.rb
@@ -1,6 +1,6 @@
 #:  * `unpin` <formulae>:
-#:    Unpin <formulae>, allowing them to be upgraded by `brew upgrade`. See also
-#:    `pin`.
+#:    Unpin <formulae>, allowing them to be upgraded by `brew upgrade <formulae>`.
+#:    See also `pin`.
 
 require "formula"
 
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 23f53d54c..788c49626 100644
--- a/docs/FAQ.md
+++ b/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:
diff --git a/docs/Manpage.md b/docs/Manpage.md
index 49f6bb5ae..0fbaf7fc7 100644
--- a/docs/Manpage.md
+++ b/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
-    `pin`.
+    Unpin `formulae`, allowing them to be upgraded by `brew upgrade `formulae``.
+    See also `pin`.
 
   * `untap` `tap`:
     Remove a tapped repository.
diff --git a/manpages/brew-cask.1 b/manpages/brew-cask.1
index f11d48c09..763d78ebe 100644
--- a/manpages/brew-cask.1
+++ b/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
diff --git a/manpages/brew.1 b/manpages/brew.1
index 2d8ba3f09..fc075ed81 100644
--- a/manpages/brew.1
+++ b/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