Add more flags and descriptions to man pages.

6 files changed, 54 insertions, 11 deletions

diff --git a/Library/Homebrew/cmd/install.rb b/Library/Homebrew/cmd/install.rb
index 5a3aeb7b3..c825e2796 100644
--- a/Library/Homebrew/cmd/install.rb
+++ b/Library/Homebrew/cmd/install.rb
@@ -1,4 +1,4 @@
-#:  * `install` [`--debug`] [`--env=`<std>|<super>] [`--ignore-dependencies`] [`--only-dependencies`] [`--cc=`<compiler>] [`--build-from-source`] [`--devel`|`--HEAD`] [`--keep-tmp`] <formula>:
+#:  * `install` [`--debug`] [`--env=`(`std`|`super`)] [`--ignore-dependencies`|`--only-dependencies`] [`--cc=`<compiler>] [`--build-from-source`|`--force-bottle`] [`--devel`|`--HEAD`] [`--keep-tmp`] [`--build-bottle`] <formula>:
 #:    Install <formula>.
 #:
 #:    <formula> is usually the name of the formula to install, but it can be specified
@@ -44,6 +44,9 @@
 #:    If `--keep-tmp` is passed, the temporary files created during installation
 #:    are not deleted.
 #:
+#:    If `--build-bottle` is passed, prepare the formula for eventual bottling
+#:    during installation.
+#:
 #:  * `install` `--interactive` [`--git`] <formula>:
 #:    Download and patch <formula>, then open a shell. This allows the user to
 #:    run `./configure --help` and otherwise determine how to turn the software
diff --git a/Library/Homebrew/cmd/sh.rb b/Library/Homebrew/cmd/sh.rb
index 09e7f435e..249753355 100644
--- a/Library/Homebrew/cmd/sh.rb
+++ b/Library/Homebrew/cmd/sh.rb
@@ -1,9 +1,11 @@
 #:  * `sh` [`--env=std`]:
-#:    Instantiate a Homebrew build environment. Uses our years-battle-hardened
+#:    Start a Homebrew build environment shell. Uses our years-battle-hardened
 #:    Homebrew build logic to help your `./configure && make && make install`
 #:    or even your `gem install` succeed. Especially handy if you run Homebrew
 #:    in an Xcode-only configuration since it adds tools like `make` to your `PATH`
-#:    which otherwise build-systems would not find.
+#:    which otherwise build systems would not find.
+#:
+#:    If `--env=std` is passed, use the standard `PATH` instead of superenv's.
 
 require "extend/ENV"
 require "formula"
@@ -20,13 +22,13 @@ module Homebrew
     end
     ENV.setup_build_environment
     if superenv?
-      # superenv stopped adding brew's bin but generally user's will want it
+      # superenv stopped adding brew's bin but generally users will want it
       ENV["PATH"] = ENV["PATH"].split(File::PATH_SEPARATOR).insert(1, "#{HOMEBREW_PREFIX}/bin").join(File::PATH_SEPARATOR)
     end
     ENV["PS1"] = 'brew \[\033[1;32m\]\w\[\033[0m\]$ '
     ENV["VERBOSE"] = "1"
     puts <<-EOS.undent_________________________________________________________72
-         Your shell has been configured to use Homebrew's build environment:
+         Your shell has been configured to use Homebrew's build environment;
          this should help you build stuff. Notably though, the system versions of
          gem and pip will ignore our configuration and insist on using the
          environment they were built under (mostly). Sadly, scons will also
diff --git a/Library/Homebrew/dev-cmd/bottle.rb b/Library/Homebrew/dev-cmd/bottle.rb
index 91bdcba93..619986f76 100644
--- a/Library/Homebrew/dev-cmd/bottle.rb
+++ b/Library/Homebrew/dev-cmd/bottle.rb
@@ -1,7 +1,29 @@
-#:  * `bottle` [`--verbose`] [`--no-rebuild`] [`--keep-old`] [`--skip-relocation`] [`--root-url=`<URL>] [`--force-core-tap`]:
-#:  * `bottle` `--merge` [`--no-commit`] [`--keep-old`] [`--write`]:
+#:  * `bottle` [`--verbose`] [`--no-rebuild`|`--keep-old`] [`--skip-relocation`] [`--root-url=`<URL>] [`--force-core-tap`] <formulae>:
 #:    Generate a bottle (binary package) from a formula installed with
 #:    `--build-bottle`.
+#:
+#:    If the formula specifies a rebuild version, it will be incremented in the
+#:    generated DSL. Passing `--keep-old` will attempt to keep it at its
+#:    original value, while `--no-rebuild` will remove it.
+#:
+#:    If `--verbose` is passed, print the bottling commands and any warnings
+#:    encountered.
+#:
+#:    If `--skip-relocation` is passed, do not check if the bottle can be marked
+#:    as relocatable.
+#:
+#:    If `--root-url` is passed, use the specified <URL> as the root of the
+#:    bottle's URL instead of Homebrew's default.
+#:
+#:    If `--force-core-tap` is passed, build a bottle even if <formula> is not
+#:    in homebrew/core or any installed taps.
+#:
+#:  * `bottle` `--merge` [`--keep-old`] [`--write` [`--no-commit`]] <formulae>:
+#:    Generate a bottle from a formula and print the new DSL merged into the
+#:    existing formula.
+#:
+#:    If `--write` is passed, write the changes to the formula file. A new
+#:    commit will then be generated unless `--no-commit` is passed.
 
 require "formula"
 require "utils/bottles"
diff --git a/Library/Homebrew/dev-cmd/tests.rb b/Library/Homebrew/dev-cmd/tests.rb
index b66d8db16..4f7f9e771 100644
--- a/Library/Homebrew/dev-cmd/tests.rb
+++ b/Library/Homebrew/dev-cmd/tests.rb
@@ -1,5 +1,21 @@
-#:  * `tests` [`-v`] [`--coverage`] [`--generic`] [`--no-compat`] [`--only=`<test_script>`:`<line_number>] [`--seed` <seed>] [`--online`] [`--official-cmd-taps`]:
-#:    Run Homebrew's unit and integration tests.
+#:  * `tests` [`--verbose`] [`--coverage`] [`--generic`] [`--no-compat`] [`--only=`<test_script>[`:`<line_number>]] [`--seed` <seed>] [`--online`] [`--official-cmd-taps`]:
+#:    Run Homebrew's unit and integration tests. If provided,
+#:    `--only=`<test_script> runs only <test_script>_spec.rb, and `--seed`
+#:    randomizes tests with the provided value instead of a random seed.
+#:
+#:    If `--verbose` is passed, print the command that runs the tests.
+#:
+#:    If `--coverage` is passed, also generate code coverage reports.
+#:
+#:    If `--generic` is passed, only run OS-agnostic tests.
+#:
+#:    If `--no-compat` is passed, do not load the compatibility layer when
+#:    running tests.
+#:
+#:    If `--online` is passed, include tests that use the GitHub API.
+#:
+#:    If `--official-cmd-taps` is passed, include tests that use any of the
+#:    taps for official external commands.
 
 require "fileutils"
 require "tap"
diff --git a/Library/Homebrew/dev-cmd/update-test.rb b/Library/Homebrew/dev-cmd/update-test.rb
index 9704426dd..2ff168669 100644
--- a/Library/Homebrew/dev-cmd/update-test.rb
+++ b/Library/Homebrew/dev-cmd/update-test.rb
@@ -1,4 +1,4 @@
-#:  * `update-test` [`--commit=`<commit>] [`--before=`<date>] [`--keep-tmp`]:
+#:  * `update-test` [`--commit=`<commit>] [`--before=`<date>] [`--to-tag`] [`--keep-tmp`]:
 #:    Runs a test of `brew update` with a new repository clone.
 #:
 #:    If no arguments are passed, use `origin/master` as the start commit.
diff --git a/Library/Homebrew/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb
index 05fc1cb23..5b0228e3f 100644
--- a/Library/Homebrew/manpages/brew.1.md.erb
+++ b/Library/Homebrew/manpages/brew.1.md.erb
@@ -65,7 +65,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
     <https://github.com/caskroom/homebrew-cask>
 
   * `services`:
-    Integrates Homebrew formulae with macOS's `launchctl` manager:
+    Integrates Homebrew formulae with macOS's `launchctl`(1) manager:
     <https://github.com/Homebrew/homebrew-services>
 
 ## CUSTOM EXTERNAL COMMANDS