standardize the recommended upgrade command

in both docs and error messages.

Recent bug reports indicate that `cleanup` commands are essential
in some situations.

USAGE.md

@@ -126,7 +126,10 @@ It is generally safe to run updates from within an Application.
 
 When a new version homebrew-cask is released, it will appear in the output of
 `brew outdated` after running `brew update`.  You can upgrade it via the normal
-Homebrew workflow: `brew upgrade brew-cask`.
+Homebrew `brew upgrade` workflow:
+```bash
+$ brew update && brew upgrade brew-cask && brew cleanup && brew cask cleanup
+```
 
 ## Additional Taps (optional)
 

doc/TAP_MIGRATION.md

@@ -29,7 +29,7 @@ All users should upgrade to the latest Homebrew (0.9.5 or better), and the
 latest Homebrew-cask (0.34.0 or better):
 
 ```bash
-$ brew update && brew upgrade brew-cask
+$ brew update && brew upgrade brew-cask && brew cleanup && brew cask cleanup
 ```
 
 The first time you execute a `brew cask` command, all Tap migrations

doc/src/brew-cask.1.md

@@ -154,7 +154,7 @@ in a future version.
 Homebrew-cask is implemented as a external command for Homebrew.  That means
 this project is entirely built upon the Homebrew infrastructure.  For
 example, upgrades to the Homebrew-cask tool are received through Homebrew:
-    brew update && brew upgrade brew-cask
+    brew update && brew upgrade brew-cask && brew cleanup && brew cask cleanup
 
 And updates to individual Cask definitions are received whenever you issue
 the Homebrew command:

lib/cask.rb

@@ -90,7 +90,7 @@ class Cask
     begin
       Homebrew.send(:rename_taps_dir_if_necessary)
     rescue StandardError
-      opoo %q{Trouble with automatic Tap migration. You may need to run "brew update && brew upgrade brew-cask"}
+      opoo %q{Trouble with automatic Tap migration. You may need to run "brew update && brew upgrade brew-cask && brew cleanup && brew cask cleanup"}
     end
 
     # transitional: help with our own move to new GitHub project, May 2014

lib/cask/artifact/pkg.rb

@@ -16,7 +16,7 @@ class Cask::Artifact::Pkg < Cask::Artifact::Base
     permitted_keys = [:args, :input, :executable, :must_succeed]
     unknown_keys = script_arguments.keys - permitted_keys
     unless unknown_keys.empty?
-      opoo "Unknown arguments to uninstall :#{key} -- :#{unknown_keys.join(", :")} (ignored). Running `brew update; brew upgrade brew-cask` will likely fix it.'"
+      opoo %Q{Unknown arguments to uninstall :#{key} -- :#{unknown_keys.join(", :")} (ignored). Running "brew update && brew upgrade brew-cask && brew cleanup && brew cask cleanup" will likely fix it.}
     end
     script_arguments.reject! {|k,v| ! permitted_keys.include?(k)}
 
@@ -88,7 +88,7 @@ class Cask::Artifact::Pkg < Cask::Artifact::Base
     uninstall_set.each do |uninstall_options|
       unknown_keys = uninstall_options.keys - [:early_script, :launchctl, :quit, :signal, :kext, :script, :pkgutil, :files]
       unless unknown_keys.empty?
-        opoo "Unknown arguments to uninstall: #{unknown_keys.join(", ")}. Running `brew update; brew upgrade brew-cask` will likely fix it.'"
+        opoo %Q{Unknown arguments to uninstall: #{unknown_keys.join(", ")}. Running "brew update && brew upgrade brew-cask && brew cleanup && brew cask cleanup" will likely fix it.}
       end
     end
 

lib/cask/caveats.rb

@@ -179,7 +179,10 @@ class Cask::CaveatsDSL
 
         If you are working on #{@cask}, this may point to a typo. Otherwise
         it probably means this Cask is using a new feature. If that feature
-        has been released, running `brew update; brew upgrade brew-cask`
+        has been released, running
+
+          brew update && brew upgrade brew-cask && brew cleanup && brew cask cleanup
+
         should fix it. Otherwise you should wait to use #{@cask} until the
         new feature is released.
     EOPOO

lib/cask/dsl.rb

@@ -154,7 +154,10 @@ module Cask::DSL
 
           If you are working on #{self}, this may point to a typo. Otherwise
           it probably means this Cask is using a new feature. If that feature
-          has been released, running `brew update; brew upgrade brew-cask`
+          has been released, running
+
+            brew update && brew upgrade brew-cask && brew cleanup && brew cask cleanup
+
           should fix it. Otherwise you should wait to use #{self} until the
           new feature is released.
       EOPOO

lib/cask/utils.rb

@@ -33,7 +33,7 @@ class Hash
   def assert_valid_keys(*valid_keys)
     unknown_keys = self.keys - valid_keys
     unless unknown_keys.empty?
-      raise CaskError.new "Unknown keys: #{unknown_keys.inspect}. Running `brew update; brew upgrade brew-cask` will likely fix it."
+      raise CaskError.new %Q{Unknown keys: #{unknown_keys.inspect}. Running "brew update && brew upgrade brew-cask && brew cleanup && brew cask cleanup" will likely fix it.}
     end
   end
 end

test/cask/dsl_test.rb

@@ -31,7 +31,10 @@ describe Cask::DSL do
         Warning:#{' '}
         Warning:   If you are working on UnexpectedMethodCask, this may point to a typo. Otherwise
         Warning:   it probably means this Cask is using a new feature. If that feature
-        Warning:   has been released, running `brew update; brew upgrade brew-cask`
+        Warning:   has been released, running
+        Warning:#{' '}
+        Warning:     brew update && brew upgrade brew-cask && brew cleanup && brew cask cleanup
+        Warning:#{' '}
         Warning:   should fix it. Otherwise you should wait to use UnexpectedMethodCask until the
         Warning:   new feature is released.
       WARNING