Bare URLs are auto-linked on GitHub but not on docs.brew.sh, so I added
angle brackets around them where appropriate. Also converted
Markdown-linked URLs for clarity.

GitHub now nicely generates a documentation site for us at
http://brew.sh/brew based on our docs folder. Optimise the output of
this and the GitHub docs directory for readability and the various user
groupings.

Mostly related to the newer ways we’re handling versions and the
incoming deprecation of devel-only, head-only and versions.

After Issue #985 was merged, bottles for Mavericks are no longer
being built, meaning installations are triggering builds.

Update the FAQ to show that builds will most likely now be
triggers on Mavericks since their bottles are not being generated.

### Is there a glossary of terms around?
All your terminology needs can be [found here](docs/Formula-Cookbook.md#homebrew-terminology). results in 404 error

Addressing a few spots where I looked for terminology and did not find what I was looking for. Input based on a recent [podcast with Mike](https://changelog.com/podcast/223)

Closes #1040.

Not quite a mass replacement as I've used OS X and Mac OS X where
describing specific older versions and added compatibility methods
for things in the DSL.

Closes #71.

Signed-off-by: Andrew Janke <andrew@apjanke.net>

Closes Homebrew/homebrew#50632.

Signed-off-by: Xu Cheng <xucheng@me.com>

Closes Homebrew/homebrew#49281.

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

Closes Homebrew/homebrew#48794.

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

Closes Homebrew/homebrew#47523.

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

Remove duplication, link to the API documentation more often,
tweak wording, add `@UniqMartin` as a maintainer, note `@jacknagel`'s
and `@adamv`'s significant past contributions to Homebrew, delete some
outdated or unneeded documentation, add some missing `Formula` API.
entries and simplify/improve `CONTRIBUTING.md`.

Closes Homebrew/homebrew#46179.

Closes Homebrew/homebrew#46618.

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

Always use the `<user/repo>` format as used by the `brew tap` command.
Also fixed a link to `homebrew/head-only` and sorted a list in `FAQ.md`
in alphabetical order.

Closes Homebrew/homebrew#45535.

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

The --all parameter was reverted in commit https://github.com/Homebrew/homebrew/commit/a45a34db0b2c66f626f3724ae9a52563b4aa94b5


This should be updated in the documentation :)

Closes Homebrew/homebrew#41773.

Signed-off-by: Xu Cheng <xucheng@me.com>

Closes Homebrew/homebrew#40478.

Signed-off-by: Dominyk Tiller <dominyktiller@gmail.com>

Closes Homebrew/homebrew#39262.

Signed-off-by: Tim D. Smith <git@tim-smith.us>

Closes Homebrew/homebrew#38457.

Signed-off-by: Xu Cheng <xucheng@me.com>

Fixes Homebrew/homebrew#37698.

Closes Homebrew/homebrew#35529.

Signed-off-by: Jack Nagel <jacknagel@gmail.com>

More proposed documentation updates.

Acceptable Formulae:

* Adds Perl to the list of stuff we offer Dupes of in the Core.
* Notes that OS X’s OpenSSL is usually horribly outdated.
* Removes the incorrect space between font and forge.

Common Issues:

* We said three issues, we listed four. Oops.

External Commands:

* The cache is usually at /Library rather than ~/Library, and the rest
of the documentation says /Library, so this makes the referencing
consistent.

FAQ:

* Adds a tiny section on pinning formulae.

Interesting-Taps-And-Branches:
* Notes gaming-emulation software belongs in Homebrew/Games as well.
* nolith/Embedded hasn’t been touched for 28 months. I’ve cut it.
* anarchivist/forensics hasn’t been touched for 35 months. I’ve cut it.
* codebutler’s GTK+ experiment seems to have been terminated after one
commit. I’ve cut it.
* paxam/linux hasn’t been touched for 34 months. I’ve cut it.
* rmyers/homebrew hasn’t been touched in 42 months. I’ve cut it.
* nddrylliog/winbrew has moved, I’ve changed the URL to the new one.

Winbrew.md:
* Removed. It’s referenced in the prior file, and doesn’t really need
its own.

Closes Homebrew/homebrew#34599.

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

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>

The bigger, uglier brother of Homebrew/homebrew#34090.

Closes Homebrew/homebrew#34106.

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

It was causing a command to not display correctly.

Closes Homebrew/homebrew#33686.

Signed-off-by: Jack Nagel <jacknagel@gmail.com>

Closes Homebrew/homebrew#33211.