Documentation Updates

Acceptable-Formulae:

* Makes the language around stable versions stricter.
* Fixes the Homebrew/Head-only lack-of-hyphen.
* Adds Homebrew/Devel-only.

Formula-Cookbook:
* Adds a link to Interesting-Taps-&-Branches.
* Fixes the Python language to match Tim’s latest guidelines.
* Adds a note on options that aren’t ` build-with? ` or `
build-without? `.

Interesting-Taps-&-Branches:
* Slightly modifies the Versions language to better match what the
repository actually ships.
* Adds Homebrew/Devel-only to the language.

Closes Homebrew/homebrew#35298.

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

3 files changed, 12 insertions, 7 deletions

diff --git a/share/doc/homebrew/Acceptable-Formulae.md b/share/doc/homebrew/Acceptable-Formulae.md
index 92a25ec67..ee9a4e5e9 100644
--- a/share/doc/homebrew/Acceptable-Formulae.md
+++ b/share/doc/homebrew/Acceptable-Formulae.md
@@ -62,13 +62,13 @@ from source. Binary-only formulae should go to
 [Homebrew/homebrew-binary](https://github.com/Homebrew/homebrew-binary).
 
 ### Stable versions
-Formulae in the core repository should have a stable version tagged by
+Formulae in the core repository must have a stable version tagged by
 the upstream project. Tarballs are preferred to git checkouts, and
 tarballs should include the version in the filename whenever possible.
 
 Software that does not provide a stable, tagged version, or had guidance to
 always install the most recent version, should be put in
-[Homebrew/homebrew-headonly](https://github.com/Homebrew/homebrew-headonly).
+[Homebrew/homebrew-head-only](https://github.com/Homebrew/homebrew-headonly) or [homebrew/devel-only](https://github.com/Homebrew/homebrew-devel-only).
 
 ### Bindings
 First check that there is not already a binding available via
diff --git a/share/doc/homebrew/Formula-Cookbook.md b/share/doc/homebrew/Formula-Cookbook.md
index 41bb00de8..9b9b0bae5 100644
--- a/share/doc/homebrew/Formula-Cookbook.md
+++ b/share/doc/homebrew/Formula-Cookbook.md
@@ -64,7 +64,7 @@ Before contributing, make sure your package:
 *   isn't in another [Homebrew tap](https://github.com/Homebrew)
 *   isn't already waiting to be merged (check the [issue tracker](http://github.com/Homebrew/homebrew/issues))
 *   is still supported by upstream
-*   has a stable, tagged version (i.e. not just a GitHub repository with no versions)
+*   has a stable, tagged version (i.e. not just a GitHub repository with no versions). See [Interesting-Taps-&-Branches](Interesting-Taps-&-Branches.md) for where pre-release and head-only versions belong.
 
 Make sure you search thoroughly (all aliases!). We don’t want you to waste your time.
 
@@ -242,7 +242,7 @@ class Foo < Formula
   end
 
   def install
-    resource("pycrypto").stage { Language::Python.setup_install "python", libexec/"vendor" }
+    resource("pycrypto").stage { system "python", *Language::Python.setup_install_args(libexec/"vendor") }
   end
 end
 ```
@@ -843,6 +843,8 @@ end
 
 Option names should be prefixed with one of the words `with`, `without`, `no`, or a verb in the imperative tense describing the action to be taken. For example, an option to run a test suite should be named `--with-test` or `--with-check` rather than `--test`, and an option to enable a shared library should be named `--enable-shared` rather than `--shared`.
 
+Note that options that aren’t ` build.with? ` or ` build.without? ` should be actively deprecated where possible. See [wget](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/wget.rb#L27-L31) for an example.
+
 See the [graphviz](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/graphviz.rb) formula for an example.
 
 
diff --git a/share/doc/homebrew/Interesting-Taps-&-Branches.md b/share/doc/homebrew/Interesting-Taps-&-Branches.md
index e70e86832..f70d853cb 100644
--- a/share/doc/homebrew/Interesting-Taps-&-Branches.md
+++ b/share/doc/homebrew/Interesting-Taps-&-Branches.md
@@ -11,7 +11,7 @@ Homebrew has the capability to add (and remove) multiple taps to your local inst
     - Need GDB or a newer Tk? System duplicates go here.
 
 *   [homebrew/versions](https://github.com/Homebrew/homebrew-versions)
-    - Need e.g. older or newer versions of Python? Newer versions of GCC?
+    - Need e.g. older or newer versions of Postgresql? Older versions of GCC?
 
 *   [homebrew/games](https://github.com/Homebrew/homebrew-games)
     - Game or gaming-emulation related formulae.
@@ -19,8 +19,11 @@ Homebrew has the capability to add (and remove) multiple taps to your local inst
 *   [homebrew/apache](https://github.com/Homebrew/homebrew-apache)
     - A tap for Apache modules, extending OS X's built-in Apache. These brews may require unconventional additional setup, as explained in the caveats.
 
-*   [homebrew/headonly](https://github.com/Homebrew/homebrew-headonly)
-    - A tap for brews that don't have stable versions.
+*   [homebrew/head-only](https://github.com/Homebrew/homebrew-head-only)
+    - A tap for brews that only have unstable, unreleased versions.
+
+*   [homebrew/devel-only](https://github.com/Homebrew/homebrew-devel-only)
+    - A tap for brews that only have pre-release/development versions.
 
 *   [homebrew/php](https://github.com/Homebrew/homebrew-php)
     - Repository for php-related formulae.