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.

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.

Fixed minor typo -- missing preposition.

This way analytics related settings and parameters (currently
analyticsdisabled, analyticsmessage and analyticsuuid) are all kept in
the same place.

Note that in this commit we offer a path of migration: if
~/.homebrew_analytics_user_uuid already exists, read the UUID from it,
write to homebrew.analyticsuuid, and remove it.

See more detailed discussions in #145.

Closes #162.

Signed-off-by: Martin Afanasjew <martin@afanasjew.de>

* Clarify opt-out commands

* Partially rewrite opt-out paragraph

Closes #150.

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

Closes #149.

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

Provide a single command that can be run to disable analytics, run it if
`HOMEBREW_NO_ANALYTICS` is ever set and remove the user UUID file in
that case too.

References https://github.com/Homebrew/brew/issues/142.

Make sure that users are notified on the first run of `brew update`
after we enabled analytics about how it works and how to opt-out. This
will be shown to all users who have not already seen this message from
`brew update` or through a new Homebrew installation.

References https://github.com/Homebrew/install/pull/42
References https://github.com/Homebrew/brew/issues/142

For more information and opt-out instructions please read:
https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Analytics.md#analytics

- add `HOMEBREW_PRODUCT` global variable
- only differentiate between `/usr/local` and `non-/usr/local` Homebrew
  prefixes to avoid sharing sensitive user information
- note if e.g. build errors are occurring under CI
- Add `HOMEBREW_NO_ANALYTICS` variable (this will be how people opt-out
  when this is enabled for everyone)
- Add `HOMEBREW_ANALYTICS_DEBUG` variable to output all the analytics
  that are sent
- Move Bash analytics code to `Library/Homebrew/utils/analytics.sh`
- Add documentation for our analytics and why/what/when/how and opt-out
- Only official Homebrew commands are reported
- Ruby analytics are now reported in a forked, background process