Documentation Updates

Mike probably wants to cast an eye over all of this, but in summary:

In the Example Formula:
* Updates with a revision example.
* Updates with a mirror mirror (Whoa meta).
* Replaces the bottles with more modern examples.
* Adds the Yosemite binary dependency options.
* Improves the plist documentation

In the Bottles doc:
* Modernises the expected bottle readout.
* Adds double quotes.

In the FAQ:
* Updates the bottle language to reflect Yosemite’s arrival and the
Bot’s new minimum OS bottle generation.

In the Formula-Cookbook:
* Adds a mega block on the OpenSSL situation in Homebrew, complete with
examples and explanation.
* Changes the X11 dependency example to optional to reflect Jack’s
recently-expressed pattern in other formulae.
* Explains why and how formulae are sometimes revisioned, and the
mechanism behind that.
* Updates the Ldapvi `otool` readout to reflect the new usage of
OpenSSL. Setting a good example and all that.
* Updates the Python language to match Tim’s new Python handling.
* Updates the naming block to explain how Homebrew handles name
conflicts, complete with examples.
* Updates (a tiny bit) the sandbox creation in /tmp to reflect the
current style.
* Updates the chmod to move away from +x towards 0555 instead.
* Labels the `enable-ham` option depreciated rather than old. Slightly
firmer.
* Updates the bottle block instructions to reflect Homebrew’s audit
mechanism not crying about it locally.

Closes Homebrew/homebrew#34275.

Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>

5 files changed, 83 insertions, 41 deletions

diff --git a/Library/Contributions/example-formula.rb b/Library/Contributions/example-formula.rb
index b79f01777..107fd837f 100644
--- a/Library/Contributions/example-formula.rb
+++ b/Library/Contributions/example-formula.rb
@@ -11,11 +11,14 @@ require "formula"
 # Homebrew does enforce that the name of the file and the class correspond.
 # Check with `brew search` that the name is free.
 class ExampleFormula < Formula
-  homepage "http://www.example.com" # used by `brew home example-formula`.
+  homepage "https://www.example.com" # used by `brew home example-formula`.
+  revision 1 # This is used when there's no new version but it needs recompiling for another reason.
+             # 0 is default & unwritten.
 
   # The url of the archive. Prefer https (security and proxy issues):
   url "https://packed.sources.and.we.prefer.https.example.com/archive-1.2.3.tar.bz2"
   mirror "https://in.case.the.host.is.down.example.com" # `mirror` is optional.
+  mirror "https://in.case.the.mirror.is.down.example.com" # Mirrors are limitless, but don't go too wild.
 
   # Optionally specify the download strategy `:using => ...`
   #     `:git`, `:hg`, `:svn`, `:bzr`, `:cvs`,
@@ -93,10 +96,9 @@ class ExampleFormula < Formula
     prefix "/opt/homebrew" # Optional HOMEBREW_PREFIX in which the bottles were built.
     cellar "/opt/homebrew/Cellar" # Optional HOMEBREW_CELLAR in which the bottles were built.
     revision 1 # Making the old bottle outdated without bumping the version of the formula.
-    sha1 "d3d13fe6f42416765207503a946db01378131d7b" => :mountain_lion
-    sha1 "cdc48e79de2dee796bb4ba1ad987f6b35ce1c1ee" => :lion
-    sha1 "a19b544c8c645d7daad1d39a070a0eb86dfe9b9c" => :snow_leopard
-    sha1 "583dc9d98604c56983e17d66cfca2076fc56312b" => :snow_leopard_32
+    sha1 "d3d13fe6f42416765207503a946db01378131d7b" => :yosemite
+    sha1 "cdc48e79de2dee796bb4ba1ad987f6b35ce1c1ee" => :mavericks
+    sha1 "a19b544c8c645d7daad1d39a070a0eb86dfe9b9c" => :mountain_lion
   end
 
   def pour_bottle?
@@ -154,6 +156,8 @@ class ExampleFormula < Formula
   depends_on :arch => :ppc # Only builds on PowerPC?
   depends_on :ld64 # Sometimes ld fails on `MacOS.version < :leopard`. Then use this.
   depends_on :x11 # X11/XQuartz components.
+  depends_on :osxfuse # Permits the use of the upstream signed binary or our source package.
+  depends_on :tuntap # Does the same thing as above. This is vital for Yosemite and above.
   depends_on :mysql => :recommended
   # It is possible to only depend on something if
   # `build.with?` or `build.without? "another_formula"`:
@@ -404,10 +408,30 @@ class ExampleFormula < Formula
 
   ## Plist handling
 
+  # Does your plist need to be loaded at startup?
+  plist_options :startup => true
+  # Or only when necessary or desired by the user?
+  plist_options :manual => "foo"
+  # Or perhaps you'd like to give the user a choice? Ooh fancy.
+  plist_options :startup => "true", :manual => "foo start"
+
   # Define this method to provide a plist.
-  # Todo: Expand this example with a little demo plist? I dunno.
-  # There is more to startup plists. Help, I suck a plists!
-  def plist; nil; end
+  # Looking for another example? Check out Apple's handy manpage =>
+  # https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man5/plist.5.html
+  def plist; <<-EOS.undent
+    <?xml version="1.0" encoding="UTF-8"?>
+    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+    <plist version="1.0">
+    <dict>
+      <key>Label</key>
+      <string>#{plist_name}</string>
+      <key>RunAtLoad</key>
+      <true/>
+      <key>KeepAlive</key>
+      <true/>
+    </plist>
+    EOS
+  end
 end
 
 __END__
diff --git a/share/doc/homebrew/Acceptable-Formulae.md b/share/doc/homebrew/Acceptable-Formulae.md
index 875fb13c3..232002ad2 100644
--- a/share/doc/homebrew/Acceptable-Formulae.md
+++ b/share/doc/homebrew/Acceptable-Formulae.md
@@ -16,6 +16,10 @@ duplicate tools
 
 There are exceptions:
 
+* OpenSSL - Apple has formally deprecated OpenSSL on OS X in favour of their own Security Framework
+  & consequently the OS X OpenSSL is rarely updated and frequently falls behind important security updates.
+  Homebrew endeavours to use our shipped OpenSSL as much
+   as possible.
 * Programs that a user will regularly interact with directly, like editors and
   language runtimes
 * Libraries that provide functionality or contain security updates not found in
diff --git a/share/doc/homebrew/Bottles.md b/share/doc/homebrew/Bottles.md
index 414d47e66..8b484662c 100644
--- a/share/doc/homebrew/Bottles.md
+++ b/share/doc/homebrew/Bottles.md
@@ -23,24 +23,22 @@ Bottles have a DSL to be used in formulae which is contained in the `bottle do .
 A simple (and typical) example:
 ```ruby
 bottle do
-  sha1 'd3d13fe6f42416765207503a946db01378131d7b' => :mountain_lion
-  sha1 'cdc48e79de2dee796bb4ba1ad987f6b35ce1c1ee' => :lion
-  sha1 'a19b544c8c645d7daad1d39a070a0eb86dfe9b9c' => :snow_leopard
+  sha1 "23ef6a81af2f37166d7d7423b88f7716bf9b0629" => :yosemite
+  sha1 "fdc919d750012fbfeeec8b3f95d07000adc3c946" => :mavericks
+  sha1 "0d08b3ca611f47a25a922b2d942f157f1d6268c1" => :mountain_lion
 end
 ```
 
 A full example:
 ```ruby
 bottle do
-  root_url 'http://mikemcquaid.com'
-  prefix '/opt/homebrew'
-  cellar '/opt/homebrew/Cellar'
+  root_url "http://mikemcquaid.com"
+  prefix "/opt/homebrew"
+  cellar "/opt/homebrew/Cellar"
   revision 4
-  sha1 'd3d13fe6f42416765207503a946db01378131d7b' => :mountain_lion
-  sha1 'cdc48e79de2dee796bb4ba1ad987f6b35ce1c1ee' => :lion
-  sha1 'a19b544c8c645d7daad1d39a070a0eb86dfe9b9c' => :snow_leopard
-  sha1 '583dc9d98604c56983e17d66cfca2076fc56312b' => :snow_leopard_32
-  sha1 '2ef5f57afae319a3e7618d5723059eae568276fa' => :leopard
+  sha1 "23ef6a81af2f37166d7d7423b88f7716bf9b0629" => :yosemite
+  sha1 "fdc919d750012fbfeeec8b3f95d07000adc3c946" => :mavericks
+  sha1 "0d08b3ca611f47a25a922b2d942f157f1d6268c1" => :mountain_lion
 end
 ```
 
diff --git a/share/doc/homebrew/FAQ.md b/share/doc/homebrew/FAQ.md
index 2f3f4fc98..a52336d8e 100644
--- a/share/doc/homebrew/FAQ.md
+++ b/share/doc/homebrew/FAQ.md
@@ -96,8 +96,8 @@ will use a bottled version of $FORMULA, but
 `brew install $FORMULA —enable-bar` will trigger a source build.
 * The `--build-from-source` option is invoked.
 * The environment variable `HOMEBREW_BUILD_FROM_SOURCE` is set.
-* The machine is not running OS X 10.7+ as all bottled builds are
-generated on Lion or later.
+* The machine is not running OS X 10.8+ as all bottled builds are
+generated on Mountain Lion or later.
 * Homebrew is installed to a prefix other than the standard
 `/usr/local` (although some bottles support this)
 
diff --git a/share/doc/homebrew/Formula-Cookbook.md b/share/doc/homebrew/Formula-Cookbook.md
index ccd5daf31..c0651cdb0 100644
--- a/share/doc/homebrew/Formula-Cookbook.md
+++ b/share/doc/homebrew/Formula-Cookbook.md
@@ -149,7 +149,11 @@ There are plenty of others. Check `/usr/lib` to see.
 
 We try to not duplicate libraries and complicated tools in core Homebrew. We dupe some common tools though. But generally, we avoid dupes because it’s one of Homebrew’s foundations. (And it causes build and usage problems!)
 
-However, we maintain a special [tap that provides dupes](https://github.com/Homebrew/homebrew-dupes).
+The one special exception is OpenSSL. Anything that uses OpenSSL *should* be built using Homebrew’s shipped OpenSSL and our test bot's post-install audit will warn of this when it is detected. (*Of course, there are exceptions to the exception. Not everything can be forced onto our OpenSSL)*.
+
+Because Homebrew’s OpenSSL is `keg_only` to avoid conflicting with the system sometimes formulae need to have environmental variables set or special configuration flags passed to locate our preferred OpenSSL; you can see this mechanism in the [clamav](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/clamav.rb#L28) formula. Usually this is unnecessary because when OpenSSL is specified as a dependency Homebrew temporarily prepends the $PATH with that prefix.
+
+Homebrew maintains a special [tap that provides other useful dupes](https://github.com/Homebrew/homebrew-dupes).
 
 *Important:* Since the introduction of `superenv`, `brew --prefix`/bin is NOT on the `$PATH` during formula installation. If you have dependencies at build time, you must specify them and brew will add them to the `$PATH`. You can test around this with `--env=std`.
 
@@ -162,7 +166,7 @@ class Foo < Formula
   depends_on "gtk+" => :optional
   depends_on "readline" => :recommended
   depends_on "boost" => "with-icu"
-  depends_on :x11
+  depends_on :x11 => :optional
 end
 ```
 
@@ -196,6 +200,15 @@ A Hash specifies a formula dependency with some additional information. Given a
     depends_on "foo" => [:optional, "with-bar"]
     ```
 
+## Formulae Revisions
+
+In Homebrew we sometimes accept formulae updates that don’t include a version bump. These include homepage changes, resource updates, new patches or fixing a security issue with a formula.
+
+Occasionally, these updates require a forced-recompile of the formula itself or its dependents to either ensure formulae continue to function as expected or to close a security issue. This forced-recompile is known as a `revision` and inserted underneath the homepage/url/sha block.
+
+Where a dependent of a formula fails against a new version of that dependency it must receive a `revision`. An example of such failure can be seen [here](https://github.com/Homebrew/homebrew/issues/31195) and the fix [here](https://github.com/Homebrew/homebrew/pull/31207).
+
+`Revisions` are also used for formulae that move from the system OpenSSL to the Homebrew-shipped OpenSSL without any other changes to that formula. This ensures users aren’t left exposed to the potential security issues of the outdated OpenSSL. An example of this can be seen in [this commit](https://github.com/Homebrew/homebrew/commit/6b9d60d474d72b1848304297d91adc6120ea6f96).
 
 ## Double-check for dependencies
 
@@ -205,17 +218,16 @@ You can double-check which libraries a binary links to with the `otool` command
 
     $ otool -L /usr/local/bin/ldapvi
     /usr/local/bin/ldapvi:
-      /usr/lib/libssl.0.9.8.dylib (compatibility version 0.9.8, current version 0.9.8)
-      /usr/lib/libcrypto.0.9.8.dylib (compatibility version 0.9.8, current version 0.9.8)
-      /usr/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.3)
-      /usr/local/Cellar/glib/2.22.4/lib/libglib-2.0.0.dylib (compatibility version 2201.0.0, current version 2201.4.0)
-      /usr/local/Cellar/gettext/0.17/lib/libintl.8.dylib (compatibility version 9.0.0, current version 9.2.0)
-      /usr/local/Cellar/readline/6.0/lib/libreadline.6.0.dylib (compatibility version 6.0.0, current version 6.0.0)
-      /usr/local/Cellar/popt/1.15/lib/libpopt.0.dylib (compatibility version 1.0.0, current version 1.0.0)
-      /usr/lib/libncurses.5.4.dylib (compatibility version 5.4.0, current version 5.4.0)
-      /System/Library/Frameworks/LDAP.framework/Versions/A/LDAP (compatibility version 1.0.0, current version 2.2.0)
-      /usr/lib/libresolv.9.dylib (compatibility version 1.0.0, current version 38.0.0)
-      /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 125.0.0)
+	/usr/local/opt/openssl/lib/libssl.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0)
+	/usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0)
+	/usr/local/lib/libglib-2.0.0.dylib (compatibility version 4201.0.0, current version 4201.0.0)
+	/usr/local/opt/gettext/lib/libintl.8.dylib (compatibility version 10.0.0, current version 10.2.0)
+	/usr/local/opt/readline/lib/libreadline.6.dylib (compatibility version 6.0.0, current version 6.3.0)
+	/usr/local/lib/libpopt.0.dylib (compatibility version 1.0.0, current version 1.0.0)
+	/usr/lib/libncurses.5.4.dylib (compatibility version 5.4.0, current version 5.4.0)
+	/System/Library/Frameworks/LDAP.framework/Versions/A/LDAP (compatibility version 1.0.0, current version 2.4.0)
+	/usr/lib/libresolv.9.dylib (compatibility version 1.0.0, current version 1.0.0)
+	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1213.0.0)
 
 
 ## Specifying gems, Python modules etc. as dependencies
@@ -232,12 +244,12 @@ class Foo < Formula
   end
 
   def install
-    resource("pycrypto").stage { system "python", "setup.py", "install", "--prefix=#{libexec}" }
+    resource("pycrypto").stage { Language::Python.setup_install "python", libexec/"vendor" }
   end
 end
 ```
 
-See [ansible](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/ansible.rb) for an example of a formula that does this well. The end-result means the user doesn't have to faff with `pip` or Python and can just run `ansible`.
+See [jrnl](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/jrnl.rb) for an example of a formula that does this well. The end-result means the user doesn't have to faff with `pip` or Python and can just run `jrnl`.
 
 [This script](https://raw.githubusercontent.com/tdsmith/labmisc/master/mkpydeps) can help you generate resource stanzas for the dependencies of your Python application.
 
@@ -292,7 +304,11 @@ If you’re not sure about the name check the homepage, and check the Wikipedia
 
 [ALSO CHECK WHAT DEBIAN CALLS IT!](http://www.debian.org/distrib/packages)
 
-If you’re *still* not sure, just commit. I’ll apply some arbitrary rule and make a decision ;)
+Where Homebrew already has a formula called `foo` we typically do not accept requests to replace that formula with something else also named `foo`. This is to avoid both confusing and surprising users’ expectation.
+
+When two formulae share an upstream name, e.g. [`AESCrypt`](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/aescrypt.rb) and [`AESCrypt`](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/aescrypt-packetizer.rb) the newer formula must typically adapt the name to avoid conflict with the current formula.
+
+If you’re *still* not sure, just commit. We’ll apply some arbitrary rule and make a decision ;)
 
 When importing classes, Homebrew will require the formula and then create an instance of the class. It does this by assuming the formula name can be directly converted to the class name using a `regexp`. The rules are simple:
 
@@ -360,7 +376,7 @@ If a commit touches multiple files, or isn’t one logical bug fix, or a file is
 
 *   The result of `Formula.download_strategy` is instantiated.
 *   `DownloadStrategy.fetch` is called (downloads tarball, checks out git repository, etc.)
-*   A temporary sandbox is created in `/tmp/homebrew`
+*   A temporary sandbox is created in `/tmp/$formulaname`
 *   `DownloadStrategy.stage` is called (extracts tarball to above sandbox, exports git repository to sandbox, etc.)
 *   Patches are applied
 *   Current directory is changed to the stage root (so when you `system make`, it works)
@@ -393,7 +409,7 @@ end
 
 ## bin.install "foo"
 
-You’ll see stuff like that in other formulae. This installs the file foo into the Formula’s `bin` directory (`/usr/local/Cellar/pkg/0.1/bin`) and makes it executable (`chmod +x foo`).
+You’ll see stuff like that in other formulae. This installs the file foo into the Formula’s `bin` directory (`/usr/local/Cellar/pkg/0.1/bin`) and makes it executable (`chmod 0555 foo`).
 
 ## inreplace
 
@@ -823,7 +839,7 @@ if build.without? "ham"
 end
 
 if build.include? "enable-ham"
-  # the old style, only useful for options other than `with`/`without` style
+  # the deprecated style, only useful for options other than `with`/`without` style
 end
 ```
 
@@ -860,7 +876,7 @@ Homebrew provides two Formula methods for launchd plist files. `plist_name` will
 
 ## Updating formulae
 
-Eventually a new version of the software will be released. In this case you should update the `url` and `sha1`/`sha256`. Even although it will warn on your local machine please leave the `bottle do ... end`  block as-is; our CI system will update it when we pull your change.
+Eventually a new version of the software will be released. In this case you should update the `url` and `sha1`/`sha256`. Please leave the `bottle do ... end`  block as-is; our CI system will update it when we pull your change.
 
 Check if the formula you are updating is a dependency for any other formulae by running `brew uses UPDATED_FORMULA`. If it is a dependency please `brew reinstall` all the dependencies after it is installed and verify they work correctly.