This is useful when you're pulling PRs where individual bottles can't be
uploaded/built but you still want to pull the PR as a whole anyway.

The existing `brew.1.html` wasn't particularly pleasant to read and
given everything else in `docs/` is a Markdown file it makes sense to
generate a post-processed Markdown file that can in turn be used by
Jekyll to generate a nicely themed HTML file.

Also changes some heading levels so only one primary
heading appears per page.

While GitHub allows a single space to denote a sublist, Jekyll is not
so lenient. It also seems unable to handle ordered sublists.

Unfortunately there's no easy way to share this code with the brew.sh
site but it's at least able to have the `css/`, `img/` (root) and
`_layouts` directories in sync between the two repositories.

Some small CSS tweaks were needed to make these pages render more
attractively.

Closes #2186.

Also update command specifications to match descriptions.

Fixes to spelling and punctuation for consistency and readability.

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.

As requested in https://github.com/Homebrew/homebrew-core/issues/9316.

The "Messaging" heading was failing to be rendered due to a missing newline between it and "Convenience Tools".

This is used to indicate a formula is a version of another formula.
This will be used to provide a consistent interface for older formulae
versions and replaces the use of `conflicts_with`.

These can now be done with just `brew upgrade`, like other upgrades.

Fixes #1818.

resolves https://github.com/Homebrew/brew/issues/1821

There are some formulas in which Homebrew symlinks configuration files
into /usr/local/etc/ instead of copying them, resulting in custom
settings being overwritten on package upgrades. This addition to the
documentation illustrates one way to avoid this behavior by ensuring the
configure script is told where to copy the configuration file(s).

Refs https://github.com/Homebrew/homebrew-core/issues/8711

Fixes #1817.

Unfortunately `brew linkapps` cannot behave nicely with e.g. Spotlight
using either aliases or symlinks and Homebrew formulae do not build
"proper" `.app` bundles that can be relocated. Instead, please consider
using `brew cask` and migrate formulae using `.app`s to casks.