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>
Keep the footprint of `brew.rb` small. Handle fetching/displaying an
appropriate help text (taking into account various external conditions)
in the `help` command.
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.
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.
