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>

1 files changed, 32 insertions, 8 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__