Fixes https://github.com/Homebrew/homebrew-test-bot/issues/3

Closes #402.

- Reorder listed commands to better reflect a typical workflow (search,
  then query for details via `info` and friends, then install, later
  update and upgrade, at last maybe uninstall).
- Remove niche `pin` and `unpin` commands.
- Drop `--env` in the Troubleshooting section.

And use `/REGEX/` instead of `/PATTERN/` to be clearer what is expected.

Closes #177.

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

Instead of always printing the generic help text, print command-specific
help if it is available and a command raised the `UsageError` exception.
Put the error message underneath the help text (was above) to avoid that
it scrolls off the screen.

Thereby fix a regression where handling the invalid usage would fail to
access `ARGV.usage` removed in c6536066.

Turns out making `empty_argv` a boolean argument for `Homebrew.help` was
not the best idea and having command-to-path mapping and help extraction
in a single method is not flexible enough.

Also only complain about missing help text when `HOMEBREW_DEVELOPER=1`
and otherwise just print the generic help text.

Format the usage examples more consistently (particularly parentheses
instead of square brackets where one of several alternatives has to be
picked). And add the now much more useful `brew help <command>`.

Closes #113.

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

Also remove related helper method `Homebrew.help_s`.

Keep the footprint of `brew.rb` small. Handle fetching/displaying an
appropriate help text (taking into account various external conditions)
in the `help` command.

Closes #68.

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

Before this fix
```
$ brew --help ls
Error: Unknown command: ls
```

After this fix
```
$ brew --help ls
brew list, ls
<snip>
```

This is also used by `brew <cmd> --help`. The basic idea is to have the
documentation as a top level comment in each command file. To find these
comments, they have to be like this `#:`.

This is also used by the `brew man` command to keep the documentation
DRY, and for that there are now a header and footer for the man page.

Closes Homebrew/homebrew#42354.

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

Closes Homebrew/homebrew#40706.

Closes Homebrew/homebrew#33211.

Closes Homebrew/homebrew#23267.

Signed-off-by: Adam Vandenberg <flangy@gmail.com>

Also, move the line containing `info`, `home` and `options` to the top of the
list as users should be running these before installation.

Ref. Homebrew/homebrew#13224.

Consequence: you can no longer install when something is already installed, you must upgrade it. This doesn't apply if the formula in question was unlinked. You can still --force installs though.

Rationale: the old way of installing over the top would leave symlinks to multiple versions in /usr/local if the old version had a file the newer version didn't. The new upgrade command handles everything properly.

Be more useful by being more concise. I referenced dozens of other mature commands’ usage to figure out what to do here.

Also separated out the help into its own command for consistency.