docs: add more missing option descriptions

and improve wording or formatting where necessary.

18 files changed, 173 insertions, 101 deletions

diff --git a/Library/Homebrew/cmd/--env.rb b/Library/Homebrew/cmd/--env.rb
index 90beee89c..e0a2b9f19 100644
--- a/Library/Homebrew/cmd/--env.rb
+++ b/Library/Homebrew/cmd/--env.rb
@@ -1,5 +1,11 @@
-#:  * `--env`:
-#:    Show a summary of the Homebrew build environment.
+#:  * `--env` [`--shell=`(<shell>|`auto`)|`--plain`]:
+#:    Show a summary of the Homebrew build environment as a plain list.
+#:
+#:    Pass `--shell=`<shell> to generate a list of environment variables for the
+#:    specified shell, or `--shell=auto` to detect the current shell.
+#:
+#:    If the command's output is sent through a pipe and no shell is specified,
+#:    the list is formatted for export to `bash`(1) unless `--plain` is passed.
 
 require "extend/ENV"
 require "build_environment"
diff --git a/Library/Homebrew/cmd/desc.rb b/Library/Homebrew/cmd/desc.rb
index 53291602e..ccb7e9925 100644
--- a/Library/Homebrew/cmd/desc.rb
+++ b/Library/Homebrew/cmd/desc.rb
@@ -1,11 +1,12 @@
 #:  * `desc` <formula>:
 #:    Display <formula>'s name and one-line description.
 #:
-#:  * `desc` [`-s`|`-n`|`-d`] (<text>|`/`<text>`/`):
-#:    Search both name and description (`-s`), just the names (`-n`), or just  the
-#:    descriptions (`-d`) for <text>. If <text> is flanked by slashes, it is interpreted
-#:    as a regular expression. Formula descriptions are cached; the cache is created on
-#:    the first search, making that search slower than subsequent ones.
+#:  * `desc` [`--search`|`--name`|`--description`] (<text>|`/`<text>`/`):
+#:    Search both name and description (`--search` or `-s`), just the names
+#:    (`--name` or `-n`), or just the descriptions (`--description` or `-d`) for
+#:    <text>. If <text> is flanked by slashes, it is interpreted as a regular
+#:    expression. Formula descriptions are cached; the cache is created on the
+#:    first search, making that search slower than subsequent ones.
 
 require "descriptions"
 require "cmd/search"
diff --git a/Library/Homebrew/cmd/doctor.rb b/Library/Homebrew/cmd/doctor.rb
index 5ff8aa4eb..4e439fa0a 100644
--- a/Library/Homebrew/cmd/doctor.rb
+++ b/Library/Homebrew/cmd/doctor.rb
@@ -6,7 +6,8 @@
 #:    an issue; just ignore this.
 
 # Undocumented options:
-#     -D activates debugging and profiling of the audit methods (not the same as --debug)
+#     `-D` activates debugging and profiling of the audit methods (not the same as `--debug`)
+#     `--list-checks` lists all audit methods
 
 require "diagnostic"
 
diff --git a/Library/Homebrew/cmd/gist-logs.rb b/Library/Homebrew/cmd/gist-logs.rb
index 9c0302813..630361ca2 100644
--- a/Library/Homebrew/cmd/gist-logs.rb
+++ b/Library/Homebrew/cmd/gist-logs.rb
@@ -4,6 +4,8 @@
 #:    <formula> is usually the name of the formula to install, but it can be specified
 #:    in several different ways. See [SPECIFYING FORMULAE](#specifying-formulae).
 #:
+#:    If `--with-hostname` is passed, include the hostname in the Gist.
+#:
 #:    If `--new-issue` is passed, automatically create a new issue in the appropriate
 #:    GitHub repository as well as creating the Gist.
 #:
diff --git a/Library/Homebrew/cmd/info.rb b/Library/Homebrew/cmd/info.rb
index a78159a15..1eb9fe9fe 100644
--- a/Library/Homebrew/cmd/info.rb
+++ b/Library/Homebrew/cmd/info.rb
@@ -1,8 +1,11 @@
+#:  * `info`:
+#:    Display brief statistics for your Homebrew installation.
+#:
 #:  * `info` <formula>:
 #:    Display information about <formula>.
 #:
 #:  * `info` `--github` <formula>:
-#:    Open a browser to the GitHub History page for formula <formula>.
+#:    Open a browser to the GitHub History page for <formula>.
 #:
 #:    To view formula history locally: `brew log -p <formula>`
 #:
diff --git a/Library/Homebrew/cmd/install.rb b/Library/Homebrew/cmd/install.rb
index 575dbc4b3..e1e4712ea 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`|`--force-bottle`] [`--devel`|`--HEAD`] [`--keep-tmp`] [`--build-bottle`] <formula> [<options> ...]:
+#:  * `install` [`--debug`] [`--env=`(`std`|`super`)] [`--ignore-dependencies`|`--only-dependencies`] [`--cc=`<compiler>] [`--build-from-source`|`--force-bottle`] [`--devel`|`--HEAD`] [`--keep-tmp`] [`--build-bottle`] [`--force`] [`--verbose`] <formula> [<options> ...]:
 #:    Install <formula>.
 #:
 #:    <formula> is usually the name of the formula to install, but it can be specified
@@ -47,6 +47,11 @@
 #:    If `--build-bottle` is passed, prepare the formula for eventual bottling
 #:    during installation.
 #:
+#:    If `--force` (or `-f`) is passed, install without checking for previously
+#:    installed keg-only or non-migrated versions
+#:
+#:    If `--verbose` (or `-v`) is passed, print the verification and postinstall steps.
+#:
 #:    Installation options specific to <formula> may be appended to the command,
 #:    and can be listed with `brew options` <formula>.
 #:
diff --git a/Library/Homebrew/cmd/list.rb b/Library/Homebrew/cmd/list.rb
index 1f90a3ac3..482100ba2 100644
--- a/Library/Homebrew/cmd/list.rb
+++ b/Library/Homebrew/cmd/list.rb
@@ -6,7 +6,7 @@
 #:  * `list`, `ls` `--unbrewed`:
 #:    List all files in the Homebrew prefix not installed by Homebrew.
 #:
-#:  * `list`, `ls` [`--versions` [`--multiple`]] [`--pinned`] [<formulae>]:
+#:  * `list`, `ls` [`--verbose`] [`--versions` [`--multiple`]] [`--pinned`] [<formulae>]:
 #:    List the installed files for <formulae>. Combined with `--verbose`, recursively
 #:    list the contents of all subdirectories in each <formula>'s keg.
 #:
diff --git a/Library/Homebrew/cmd/outdated.rb b/Library/Homebrew/cmd/outdated.rb
index f163212e1..97367ca1e 100644
--- a/Library/Homebrew/cmd/outdated.rb
+++ b/Library/Homebrew/cmd/outdated.rb
@@ -9,8 +9,8 @@
 #:
 #:    If `--verbose` (or `-v`) is passed, display detailed version information.
 #:
-#:    If `--json=`<version> is passed, the output will be in JSON format. The only
-#:    valid version is `v1`.
+#:    If `--json=`<version> is passed, the output will be in JSON format.
+#:    Currently the only accepted value for <version> is `v1`.
 #:
 #:    If `--fetch-HEAD` is passed, fetch the upstream repository to detect if
 #:    the HEAD installation of the formula is outdated. Otherwise, the
diff --git a/Library/Homebrew/cmd/readall.rb b/Library/Homebrew/cmd/readall.rb
index 3bde16e7e..0a581c383 100644
--- a/Library/Homebrew/cmd/readall.rb
+++ b/Library/Homebrew/cmd/readall.rb
@@ -1,9 +1,13 @@
-#:  * `readall` [tap]:
-#:    Import all formulae from specified taps (defaults to all installed taps).
+#:  * `readall` [`--aliases`] [`--syntax`] [<taps>]:
+#:    Import all formulae from specified <taps> (defaults to all installed taps).
 #:
 #:    This can be useful for debugging issues across all formulae when making
 #:    significant changes to `formula.rb`, testing the performance of loading
 #:    all formulae or to determine if any current formulae have Ruby issues.
+#:
+#:    If `--aliases` is passed, also verify any alias symlinks in each tap.
+#:
+#:    If `--syntax` is passed, also syntax-check all of Homebrew's Ruby files.
 
 require "readall"
 
diff --git a/Library/Homebrew/cmd/style.rb b/Library/Homebrew/cmd/style.rb
index 89484d67d..1f0d385de 100644
--- a/Library/Homebrew/cmd/style.rb
+++ b/Library/Homebrew/cmd/style.rb
@@ -1,19 +1,19 @@
-#:  * `style` [`--fix`] [`--display-cop-names`] [`--only-cops=`[COP1,COP2..]|`--except-cops=`[COP1,COP2..]] [<files>|<taps>|<formulae>]:
+#:  * `style` [`--fix`] [`--display-cop-names`] [`--only-cops=`<cops>|`--except-cops=`<cops>] [<files>|<taps>|<formulae>]:
 #:    Check formulae or files for conformance to Homebrew style guidelines.
 #:
-#:    <formulae> and <files> may not be combined. If both are omitted, style will run
-#:    style checks on the whole Homebrew `Library`, including core code and all
-#:    formulae.
+#:    Lists of <files>, <taps> and <formulae> may not be combined. If none are
+#:    provided, `style` will run style checks on the whole Homebrew library,
+#:    including core code and all formulae.
 #:
-#:    If `--fix` is passed, style violations will be automatically fixed using
-#:    RuboCop's `--auto-correct` feature.
+#:    If `--fix` is passed, automatically fix style violations using RuboCop's
+#:    auto-correct feature.
 #:
-#:    If `--display-cop-names` is passed, the RuboCop cop name for each violation
-#:    is included in the output.
+#:    If `--display-cop-names` is passed, include the RuboCop cop name for each
+#:    violation in the output.
 #:
-#:    If `--only-cops` is passed, only the given Rubocop cop(s)' violations would be checked.
-#:
-#:    If `--except-cops` is passed, the given Rubocop cop(s)' checks would be skipped.
+#:    Passing `--only-cops=`<cops> will check for violations of only the listed
+#:    RuboCop <cops>, while `--except-cops=`<cops> will skip checking the listed
+#:    <cops>. For either option <cops> should be a comma-separated list of cop names.
 #:
 #:    Exits with a non-zero status if any style violations are found.
 
diff --git a/Library/Homebrew/cmd/update-report.rb b/Library/Homebrew/cmd/update-report.rb
index 98823a152..055c55a84 100644
--- a/Library/Homebrew/cmd/update-report.rb
+++ b/Library/Homebrew/cmd/update-report.rb
@@ -1,5 +1,5 @@
 #: @hide_from_man_page
-#:  * `update_report`:
+#:  * `update_report` [`--preinstall`]:
 #:    The Ruby implementation of `brew update`. Never called manually.
 
 require "formula_versions"
diff --git a/Library/Homebrew/dev-cmd/audit.rb b/Library/Homebrew/dev-cmd/audit.rb
index 9d0ed3c59..da80c42ad 100644
--- a/Library/Homebrew/dev-cmd/audit.rb
+++ b/Library/Homebrew/dev-cmd/audit.rb
@@ -1,4 +1,4 @@
-#:  * `audit` [`--strict`] [`--fix`] [`--online`] [`--new-formula`] [`--display-cop-names`] [`--display-filename`] [`--only=`<method>|`--except=`<method>] [`--only-cops=`[COP1,COP2..]|`--except-cops=`[COP1,COP2..]] [<formulae>]:
+#:  * `audit` [`--strict`] [`--fix`] [`--online`] [`--new-formula`] [`--display-cop-names`] [`--display-filename`] [`--only=`<method>|`--except=`<method>] [`--only-cops=`<cops>|`--except-cops=`<cops>] [<formulae>]:
 #:    Check <formulae> for Homebrew coding style violations. This should be
 #:    run before submitting a new formula.
 #:
@@ -8,7 +8,7 @@
 #:    style checks.
 #:
 #:    If `--fix` is passed, style violations will be
-#:    automatically fixed using RuboCop's `--auto-correct` feature.
+#:    automatically fixed using RuboCop's auto-correct feature.
 #:
 #:    If `--online` is passed, additional slower checks that require a network
 #:    connection are run.
@@ -23,19 +23,19 @@
 #:    If `--display-filename` is passed, every line of output is prefixed with the
 #:    name of the file or formula being audited, to make the output easy to grep.
 #:
-#:    If `--only` is passed, only the methods named `audit_<method>` will be run.
+#:    Passing `--only=`<method> will run only the methods named `audit_<method>`,
+#:    while `--except=`<method> will skip the methods named `audit_<method>`.
+#:    For either option <method> should be a comma-separated list.
 #:
-#:    If `--except` is passed, the methods named `audit_<method>` will not be run.
-#:
-#:    If `--only-cops` is passed, only the given Rubocop cop(s)' violations would be checked.
-#:
-#:    If `--except-cops` is passed, the given Rubocop cop(s)' checks would be skipped.
+#:    Passing `--only-cops=`<cops> will check for violations of only the listed
+#:    RuboCop <cops>, while `--except-cops=`<cops> will skip checking the listed
+#:    <cops>. For either option <cops> should be a comma-separated list of cop names.
 #:
 #:    `audit` exits with a non-zero status if any errors are found. This is useful,
 #:    for instance, for implementing pre-commit hooks.
 
 # Undocumented options:
-#     -D activates debugging and profiling of the audit methods (not the same as --debug)
+#     `-D` activates debugging and profiling of the audit methods (not the same as `--debug`)
 
 require "formula"
 require "formula_versions"
diff --git a/Library/Homebrew/dev-cmd/bottle.rb b/Library/Homebrew/dev-cmd/bottle.rb
index 204e7cef9..a233dfb57 100644
--- a/Library/Homebrew/dev-cmd/bottle.rb
+++ b/Library/Homebrew/dev-cmd/bottle.rb
@@ -25,6 +25,10 @@
 #:    If `--write` is passed, write the changes to the formula file. A new
 #:    commit will then be generated unless `--no-commit` is passed.
 
+# Undocumented options:
+#     `--json` writes bottle information to a JSON file, which can be used as
+#     the argument for `--merge`.
+
 require "formula"
 require "utils/bottles"
 require "tab"
diff --git a/Library/Homebrew/dev-cmd/bump-formula-pr.rb b/Library/Homebrew/dev-cmd/bump-formula-pr.rb
index 7da0f9321..1f44fa549 100644
--- a/Library/Homebrew/dev-cmd/bump-formula-pr.rb
+++ b/Library/Homebrew/dev-cmd/bump-formula-pr.rb
@@ -33,6 +33,9 @@
 #:    which opens the pull request URL in a browser. Instead, output it to the
 #:    command line.
 #:
+#:    If `--quiet` is passed, don't output replacement messages or warn about
+#:    duplicate pull requests.
+#:
 #:    Note that this command cannot be used to transition a formula from a
 #:    URL-and-sha256 style specification into a tag-and-revision style
 #:    specification, nor vice versa. It must use whichever style specification
diff --git a/Library/Homebrew/dev-cmd/linkage.rb b/Library/Homebrew/dev-cmd/linkage.rb
index e4da827f2..31e9bd103 100644
--- a/Library/Homebrew/dev-cmd/linkage.rb
+++ b/Library/Homebrew/dev-cmd/linkage.rb
@@ -1,4 +1,4 @@
-#:  * `linkage` [`--test`] [`--reverse`]  <formula>:
+#:  * `linkage` [`--test`] [`--reverse`] <formula>:
 #:    Checks the library links of an installed formula.
 #:
 #:    Only works on installed formulae. An error is raised if it is run on
diff --git a/docs/Manpage.md b/docs/Manpage.md
index cd3f87452..05735224c 100644
--- a/docs/Manpage.md
+++ b/docs/Manpage.md
@@ -126,11 +126,12 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
   * `desc` `formula`:
     Display `formula`'s name and one-line description.
 
-  * `desc` [`-s`|`-n`|`-d`] (`text`|`/``text``/`):
-    Search both name and description (`-s`), just the names (`-n`), or just  the
-    descriptions (`-d`) for `text`. If `text` is flanked by slashes, it is interpreted
-    as a regular expression. Formula descriptions are cached; the cache is created on
-    the first search, making that search slower than subsequent ones.
+  * `desc` [`--search`|`--name`|`--description`] (`text`|`/``text``/`):
+    Search both name and description (`--search` or `-s`), just the names
+    (`--name` or `-n`), or just the descriptions (`--description` or `-d`) for
+    `text`. If `text` is flanked by slashes, it is interpreted as a regular
+    expression. Formula descriptions are cached; the cache is created on the
+    first search, making that search slower than subsequent ones.
 
   * `diy` [`--name=``name`] [`--version=``version`]:
     Automatically determine the installation prefix for non-Homebrew software.
@@ -179,6 +180,8 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
     `formula` is usually the name of the formula to install, but it can be specified
     in several different ways. See [SPECIFYING FORMULAE](#specifying-formulae).
 
+    If `--with-hostname` is passed, include the hostname in the Gist.
+
     If `--new-issue` is passed, automatically create a new issue in the appropriate
     GitHub repository as well as creating the Gist.
 
@@ -190,11 +193,14 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
   * `home` `formula`:
     Open `formula`'s homepage in a browser.
 
+  * `info`:
+    Display brief statistics for your Homebrew installation.
+
   * `info` `formula`:
     Display information about `formula`.
 
   * `info` `--github` `formula`:
-    Open a browser to the GitHub History page for formula `formula`.
+    Open a browser to the GitHub History page for `formula`.
 
     To view formula history locally: `brew log -p `formula``
 
@@ -208,7 +214,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
     See the docs for examples of using the JSON output:
     <https://docs.brew.sh/Querying-Brew.html>
 
-  * `install` [`--debug`] [`--env=`(`std`|`super`)] [`--ignore-dependencies`|`--only-dependencies`] [`--cc=``compiler`] [`--build-from-source`|`--force-bottle`] [`--devel`|`--HEAD`] [`--keep-tmp`] [`--build-bottle`] `formula` [`options` ...]:
+  * `install` [`--debug`] [`--env=`(`std`|`super`)] [`--ignore-dependencies`|`--only-dependencies`] [`--cc=``compiler`] [`--build-from-source`|`--force-bottle`] [`--devel`|`--HEAD`] [`--keep-tmp`] [`--build-bottle`] [`--force`] [`--verbose`] `formula` [`options` ...]:
     Install `formula`.
 
     `formula` is usually the name of the formula to install, but it can be specified
@@ -257,6 +263,11 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
     If `--build-bottle` is passed, prepare the formula for eventual bottling
     during installation.
 
+    If `--force` (or `-f`) is passed, install without checking for previously
+    installed keg-only or non-migrated versions
+
+    If `--verbose` (or `-v`) is passed, print the verification and postinstall steps.
+
     Installation options specific to `formula` may be appended to the command,
     and can be listed with `brew options` `formula`.
 
@@ -299,7 +310,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
   * `list`, `ls` `--unbrewed`:
     List all files in the Homebrew prefix not installed by Homebrew.
 
-  * `list`, `ls` [`--versions` [`--multiple`]] [`--pinned`] [`formulae`]:
+  * `list`, `ls` [`--verbose`] [`--versions` [`--multiple`]] [`--pinned`] [`formulae`]:
     List the installed files for `formulae`. Combined with `--verbose`, recursively
     list the contents of all subdirectories in each `formula`'s keg.
 
@@ -350,8 +361,8 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
 
     If `--verbose` (or `-v`) is passed, display detailed version information.
 
-    If `--json=``version` is passed, the output will be in JSON format. The only
-    valid version is `v1`.
+    If `--json=``version` is passed, the output will be in JSON format.
+    Currently the only accepted value for `version` is `v1`.
 
     If `--fetch-HEAD` is passed, fetch the upstream repository to detect if
     the HEAD installation of the formula is outdated. Otherwise, the
@@ -375,13 +386,17 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
     If `--dry-run` or `-n` is passed, show what would be removed, but do not
     actually remove anything.
 
-  * `readall` [tap]:
-    Import all formulae from specified taps (defaults to all installed taps).
+  * `readall` [`--aliases`] [`--syntax`] [`taps`]:
+    Import all formulae from specified `taps` (defaults to all installed taps).
 
     This can be useful for debugging issues across all formulae when making
     significant changes to `formula.rb`, testing the performance of loading
     all formulae or to determine if any current formulae have Ruby issues.
 
+    If `--aliases` is passed, also verify any alias symlinks in each tap.
+
+    If `--syntax` is passed, also syntax-check all of Homebrew's Ruby files.
+
   * `reinstall` `formula`:
     Uninstall and then install `formula` (with existing install options).
 
@@ -409,22 +424,22 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
 
     If `--env=std` is passed, use the standard `PATH` instead of superenv's.
 
-  * `style` [`--fix`] [`--display-cop-names`] [`--only-cops=`[COP1,COP2..]|`--except-cops=`[COP1,COP2..]] [`files`|`taps`|`formulae`]:
+  * `style` [`--fix`] [`--display-cop-names`] [`--only-cops=``cops`|`--except-cops=``cops`] [`files`|`taps`|`formulae`]:
     Check formulae or files for conformance to Homebrew style guidelines.
 
-    `formulae` and `files` may not be combined. If both are omitted, style will run
-    style checks on the whole Homebrew `Library`, including core code and all
-    formulae.
-
-    If `--fix` is passed, style violations will be automatically fixed using
-    RuboCop's `--auto-correct` feature.
+    Lists of `files`, `taps` and `formulae` may not be combined. If none are
+    provided, `style` will run style checks on the whole Homebrew library,
+    including core code and all formulae.
 
-    If `--display-cop-names` is passed, the RuboCop cop name for each violation
-    is included in the output.
+    If `--fix` is passed, automatically fix style violations using RuboCop's
+    auto-correct feature.
 
-    If `--only-cops` is passed, only the given Rubocop cop(s)' violations would be checked.
+    If `--display-cop-names` is passed, include the RuboCop cop name for each
+    violation in the output.
 
-    If `--except-cops` is passed, the given Rubocop cop(s)' checks would be skipped.
+    Passing `--only-cops=``cops` will check for violations of only the listed
+    RuboCop `cops`, while `--except-cops=``cops` will skip checking the listed
+    `cops`. For either option `cops` should be a comma-separated list of cop names.
 
     Exits with a non-zero status if any style violations are found.
 
@@ -585,8 +600,14 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
     Display the location in the cellar where `formula` would be installed,
     without any sort of versioned directory as the last path.
 
-  * `--env`:
-    Show a summary of the Homebrew build environment.
+  * `--env` [`--shell=`(`shell`|`auto`)|`--plain`]:
+    Show a summary of the Homebrew build environment as a plain list.
+
+    Pass `--shell=``shell` to generate a list of environment variables for the
+    specified shell, or `--shell=auto` to detect the current shell.
+
+    If the command's output is sent through a pipe and no shell is specified,
+    the list is formatted for export to `bash`(1) unless `--plain` is passed.
 
   * `--prefix`:
     Display Homebrew's install path. *Default:* `/usr/local`
@@ -605,7 +626,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
 
 ## DEVELOPER COMMANDS
 
-  * `audit` [`--strict`] [`--fix`] [`--online`] [`--new-formula`] [`--display-cop-names`] [`--display-filename`] [`--only=``method`|`--except=``method`] [`--only-cops=`[COP1,COP2..]|`--except-cops=`[COP1,COP2..]] [`formulae`]:
+  * `audit` [`--strict`] [`--fix`] [`--online`] [`--new-formula`] [`--display-cop-names`] [`--display-filename`] [`--only=``method`|`--except=``method`] [`--only-cops=``cops`|`--except-cops=``cops`] [`formulae`]:
     Check `formulae` for Homebrew coding style violations. This should be
     run before submitting a new formula.
 
@@ -615,7 +636,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
     style checks.
 
     If `--fix` is passed, style violations will be
-    automatically fixed using RuboCop's `--auto-correct` feature.
+    automatically fixed using RuboCop's auto-correct feature.
 
     If `--online` is passed, additional slower checks that require a network
     connection are run.
@@ -630,13 +651,13 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
     If `--display-filename` is passed, every line of output is prefixed with the
     name of the file or formula being audited, to make the output easy to grep.
 
-    If `--only` is passed, only the methods named `audit_`method`` will be run.
+    Passing `--only=``method` will run only the methods named `audit_`method``,
+    while `--except=``method` will skip the methods named `audit_`method``.
+    For either option `method` should be a comma-separated list.
 
-    If `--except` is passed, the methods named `audit_`method`` will not be run.
-
-    If `--only-cops` is passed, only the given Rubocop cop(s)' violations would be checked.
-
-    If `--except-cops` is passed, the given Rubocop cop(s)' checks would be skipped.
+    Passing `--only-cops=``cops` will check for violations of only the listed
+    RuboCop `cops`, while `--except-cops=``cops` will skip checking the listed
+    `cops`. For either option `cops` should be a comma-separated list of cop names.
 
     `audit` exits with a non-zero status if any errors are found. This is useful,
     for instance, for implementing pre-commit hooks.
@@ -703,6 +724,9 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
     which opens the pull request URL in a browser. Instead, output it to the
     command line.
 
+    If `--quiet` is passed, don't output replacement messages or warn about
+    duplicate pull requests.
+
     Note that this command cannot be used to transition a formula from a
     URL-and-sha256 style specification into a tag-and-revision style
     specification, nor vice versa. It must use whichever style specification
@@ -738,7 +762,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
   * `formula` `formula`:
     Display the path where `formula` is located.
 
-  * `linkage` [`--test`] [`--reverse`]  `formula`:
+  * `linkage` [`--test`] [`--reverse`] `formula`:
     Checks the library links of an installed formula.
 
     Only works on installed formulae. An error is raised if it is run on
diff --git a/manpages/brew-cask.1 b/manpages/brew-cask.1
index 1261a4018..29905fcce 100644
--- a/manpages/brew-cask.1
+++ b/manpages/brew-cask.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW\-CASK" "1" "January 2018" "Homebrew" "brew-cask"
+.TH "BREW\-CASK" "1" "February 2018" "Homebrew" "brew-cask"
 .
 .SH "NAME"
 \fBbrew\-cask\fR \- a friendly binary installer for macOS
diff --git a/manpages/brew.1 b/manpages/brew.1
index 10f58d294..5dfe230e7 100644
--- a/manpages/brew.1
+++ b/manpages/brew.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW" "1" "January 2018" "Homebrew" "brew"
+.TH "BREW" "1" "February 2018" "Homebrew" "brew"
 .
 .SH "NAME"
 \fBbrew\fR \- The missing package manager for macOS
@@ -137,8 +137,8 @@ The \fIfilters\fR placeholder is any combination of options \fB\-\-include\-buil
 Display \fIformula\fR\'s name and one\-line description\.
 .
 .TP
-\fBdesc\fR [\fB\-s\fR|\fB\-n\fR|\fB\-d\fR] (\fItext\fR|\fB/\fR\fItext\fR\fB/\fR)
-Search both name and description (\fB\-s\fR), just the names (\fB\-n\fR), or just the descriptions (\fB\-d\fR) for \fItext\fR\. If \fItext\fR is flanked by slashes, it is interpreted as a regular expression\. Formula descriptions are cached; the cache is created on the first search, making that search slower than subsequent ones\.
+\fBdesc\fR [\fB\-\-search\fR|\fB\-\-name\fR|\fB\-\-description\fR] (\fItext\fR|\fB/\fR\fItext\fR\fB/\fR)
+Search both name and description (\fB\-\-search\fR or \fB\-s\fR), just the names (\fB\-\-name\fR or \fB\-n\fR), or just the descriptions (\fB\-\-description\fR or \fB\-d\fR) for \fItext\fR\. If \fItext\fR is flanked by slashes, it is interpreted as a regular expression\. Formula descriptions are cached; the cache is created on the first search, making that search slower than subsequent ones\.
 .
 .TP
 \fBdiy\fR [\fB\-\-name=\fR\fIname\fR] [\fB\-\-version=\fR\fIversion\fR]
@@ -187,6 +187,9 @@ Upload logs for a failed build of \fIformula\fR to a new Gist\.
 \fIformula\fR is usually the name of the formula to install, but it can be specified in several different ways\. See \fISPECIFYING FORMULAE\fR\.
 .
 .IP
+If \fB\-\-with\-hostname\fR is passed, include the hostname in the Gist\.
+.
+.IP
 If \fB\-\-new\-issue\fR is passed, automatically create a new issue in the appropriate GitHub repository as well as creating the Gist\.
 .
 .IP
@@ -201,12 +204,16 @@ Open Homebrew\'s own homepage in a browser\.
 Open \fIformula\fR\'s homepage in a browser\.
 .
 .TP
+\fBinfo\fR
+Display brief statistics for your Homebrew installation\.
+.
+.TP
 \fBinfo\fR \fIformula\fR
 Display information about \fIformula\fR\.
 .
 .TP
 \fBinfo\fR \fB\-\-github\fR \fIformula\fR
-Open a browser to the GitHub History page for formula \fIformula\fR\.
+Open a browser to the GitHub History page for \fIformula\fR\.
 .
 .IP
 To view formula history locally: \fBbrew log \-p <formula>\fR
@@ -222,7 +229,7 @@ Pass \fB\-\-all\fR to get information on all formulae, or \fB\-\-installed\fR to
 See the docs for examples of using the JSON output: \fIhttps://docs\.brew\.sh/Querying\-Brew\.html\fR
 .
 .TP
-\fBinstall\fR [\fB\-\-debug\fR] [\fB\-\-env=\fR(\fBstd\fR|\fBsuper\fR)] [\fB\-\-ignore\-dependencies\fR|\fB\-\-only\-dependencies\fR] [\fB\-\-cc=\fR\fIcompiler\fR] [\fB\-\-build\-from\-source\fR|\fB\-\-force\-bottle\fR] [\fB\-\-devel\fR|\fB\-\-HEAD\fR] [\fB\-\-keep\-tmp\fR] [\fB\-\-build\-bottle\fR] \fIformula\fR [\fIoptions\fR \.\.\.]
+\fBinstall\fR [\fB\-\-debug\fR] [\fB\-\-env=\fR(\fBstd\fR|\fBsuper\fR)] [\fB\-\-ignore\-dependencies\fR|\fB\-\-only\-dependencies\fR] [\fB\-\-cc=\fR\fIcompiler\fR] [\fB\-\-build\-from\-source\fR|\fB\-\-force\-bottle\fR] [\fB\-\-devel\fR|\fB\-\-HEAD\fR] [\fB\-\-keep\-tmp\fR] [\fB\-\-build\-bottle\fR] [\fB\-\-force\fR] [\fB\-\-verbose\fR] \fIformula\fR [\fIoptions\fR \.\.\.]
 Install \fIformula\fR\.
 .
 .IP
@@ -268,6 +275,12 @@ If \fB\-\-keep\-tmp\fR is passed, the temporary files created during installatio
 If \fB\-\-build\-bottle\fR is passed, prepare the formula for eventual bottling during installation\.
 .
 .IP
+If \fB\-\-force\fR (or \fB\-f\fR) is passed, install without checking for previously installed keg\-only or non\-migrated versions
+.
+.IP
+If \fB\-\-verbose\fR (or \fB\-v\fR) is passed, print the verification and postinstall steps\.
+.
+.IP
 Installation options specific to \fIformula\fR may be appended to the command, and can be listed with \fBbrew options\fR \fIformula\fR\.
 .
 .TP
@@ -310,7 +323,7 @@ List all installed formulae\. If \fB\-\-full\-name\fR is passed, print formulae
 List all files in the Homebrew prefix not installed by Homebrew\.
 .
 .TP
-\fBlist\fR, \fBls\fR [\fB\-\-versions\fR [\fB\-\-multiple\fR]] [\fB\-\-pinned\fR] [\fIformulae\fR]
+\fBlist\fR, \fBls\fR [\fB\-\-verbose\fR] [\fB\-\-versions\fR [\fB\-\-multiple\fR]] [\fB\-\-pinned\fR] [\fIformulae\fR]
 List the installed files for \fIformulae\fR\. Combined with \fB\-\-verbose\fR, recursively list the contents of all subdirectories in each \fIformula\fR\'s keg\.
 .
 .IP
@@ -364,7 +377,7 @@ If \fB\-\-quiet\fR is passed, list only the names of outdated brews (takes prece
 If \fB\-\-verbose\fR (or \fB\-v\fR) is passed, display detailed version information\.
 .
 .IP
-If \fB\-\-json=\fR\fIversion\fR is passed, the output will be in JSON format\. The only valid version is \fBv1\fR\.
+If \fB\-\-json=\fR\fIversion\fR is passed, the output will be in JSON format\. Currently the only accepted value for \fIversion\fR is \fBv1\fR\.
 .
 .IP
 If \fB\-\-fetch\-HEAD\fR is passed, fetch the upstream repository to detect if the HEAD installation of the formula is outdated\. Otherwise, the repository\'s HEAD will be checked for updates when a new stable or devel version has been released\.
@@ -385,12 +398,18 @@ Remove dead symlinks from the Homebrew prefix\. This is generally not needed, bu
 If \fB\-\-dry\-run\fR or \fB\-n\fR is passed, show what would be removed, but do not actually remove anything\.
 .
 .TP
-\fBreadall\fR [tap]
-Import all formulae from specified taps (defaults to all installed taps)\.
+\fBreadall\fR [\fB\-\-aliases\fR] [\fB\-\-syntax\fR] [\fItaps\fR]
+Import all formulae from specified \fItaps\fR (defaults to all installed taps)\.
 .
 .IP
 This can be useful for debugging issues across all formulae when making significant changes to \fBformula\.rb\fR, testing the performance of loading all formulae or to determine if any current formulae have Ruby issues\.
 .
+.IP
+If \fB\-\-aliases\fR is passed, also verify any alias symlinks in each tap\.
+.
+.IP
+If \fB\-\-syntax\fR is passed, also syntax\-check all of Homebrew\'s Ruby files\.
+.
 .TP
 \fBreinstall\fR \fIformula\fR
 Uninstall and then install \fIformula\fR (with existing install options)\.
@@ -418,23 +437,20 @@ Start a Homebrew build environment shell\. Uses our years\-battle\-hardened Home
 If \fB\-\-env=std\fR is passed, use the standard \fBPATH\fR instead of superenv\'s\.
 .
 .TP
-\fBstyle\fR [\fB\-\-fix\fR] [\fB\-\-display\-cop\-names\fR] [\fB\-\-only\-cops=\fR[COP1,COP2\.\.]|\fB\-\-except\-cops=\fR[COP1,COP2\.\.]] [\fIfiles\fR|\fItaps\fR|\fIformulae\fR]
+\fBstyle\fR [\fB\-\-fix\fR] [\fB\-\-display\-cop\-names\fR] [\fB\-\-only\-cops=\fR\fIcops\fR|\fB\-\-except\-cops=\fR\fIcops\fR] [\fIfiles\fR|\fItaps\fR|\fIformulae\fR]
 Check formulae or files for conformance to Homebrew style guidelines\.
 .
 .IP
-\fIformulae\fR and \fIfiles\fR may not be combined\. If both are omitted, style will run style checks on the whole Homebrew \fBLibrary\fR, including core code and all formulae\.
+Lists of \fIfiles\fR, \fItaps\fR and \fIformulae\fR may not be combined\. If none are provided, \fBstyle\fR will run style checks on the whole Homebrew library, including core code and all formulae\.
 .
 .IP
-If \fB\-\-fix\fR is passed, style violations will be automatically fixed using RuboCop\'s \fB\-\-auto\-correct\fR feature\.
+If \fB\-\-fix\fR is passed, automatically fix style violations using RuboCop\'s auto\-correct feature\.
 .
 .IP
-If \fB\-\-display\-cop\-names\fR is passed, the RuboCop cop name for each violation is included in the output\.
+If \fB\-\-display\-cop\-names\fR is passed, include the RuboCop cop name for each violation in the output\.
 .
 .IP
-If \fB\-\-only\-cops\fR is passed, only the given Rubocop cop(s)\' violations would be checked\.
-.
-.IP
-If \fB\-\-except\-cops\fR is passed, the given Rubocop cop(s)\' checks would be skipped\.
+Passing \fB\-\-only\-cops=\fR\fIcops\fR will check for violations of only the listed RuboCop \fIcops\fR, while \fB\-\-except\-cops=\fR\fIcops\fR will skip checking the listed \fIcops\fR\. For either option \fIcops\fR should be a comma\-separated list of cop names\.
 .
 .IP
 Exits with a non\-zero status if any style violations are found\.
@@ -602,8 +618,14 @@ Display Homebrew\'s Cellar path\. \fIDefault:\fR \fB$(brew \-\-prefix)/Cellar\fR
 Display the location in the cellar where \fIformula\fR would be installed, without any sort of versioned directory as the last path\.
 .
 .TP
-\fB\-\-env\fR
-Show a summary of the Homebrew build environment\.
+\fB\-\-env\fR [\fB\-\-shell=\fR(\fIshell\fR|\fBauto\fR)|\fB\-\-plain\fR]
+Show a summary of the Homebrew build environment as a plain list\.
+.
+.IP
+Pass \fB\-\-shell=\fR\fIshell\fR to generate a list of environment variables for the specified shell, or \fB\-\-shell=auto\fR to detect the current shell\.
+.
+.IP
+If the command\'s output is sent through a pipe and no shell is specified, the list is formatted for export to \fBbash\fR(1) unless \fB\-\-plain\fR is passed\.
 .
 .TP
 \fB\-\-prefix\fR
@@ -628,7 +650,7 @@ Print the version number of Homebrew to standard output and exit\.
 .SH "DEVELOPER COMMANDS"
 .
 .TP
-\fBaudit\fR [\fB\-\-strict\fR] [\fB\-\-fix\fR] [\fB\-\-online\fR] [\fB\-\-new\-formula\fR] [\fB\-\-display\-cop\-names\fR] [\fB\-\-display\-filename\fR] [\fB\-\-only=\fR\fImethod\fR|\fB\-\-except=\fR\fImethod\fR] [\fB\-\-only\-cops=\fR[COP1,COP2\.\.]|\fB\-\-except\-cops=\fR[COP1,COP2\.\.]] [\fIformulae\fR]
+\fBaudit\fR [\fB\-\-strict\fR] [\fB\-\-fix\fR] [\fB\-\-online\fR] [\fB\-\-new\-formula\fR] [\fB\-\-display\-cop\-names\fR] [\fB\-\-display\-filename\fR] [\fB\-\-only=\fR\fImethod\fR|\fB\-\-except=\fR\fImethod\fR] [\fB\-\-only\-cops=\fR\fIcops\fR|\fB\-\-except\-cops=\fR\fIcops\fR] [\fIformulae\fR]
 Check \fIformulae\fR for Homebrew coding style violations\. This should be run before submitting a new formula\.
 .
 .IP
@@ -638,7 +660,7 @@ If no \fIformulae\fR are provided, all of them are checked\.
 If \fB\-\-strict\fR is passed, additional checks are run, including RuboCop style checks\.
 .
 .IP
-If \fB\-\-fix\fR is passed, style violations will be automatically fixed using RuboCop\'s \fB\-\-auto\-correct\fR feature\.
+If \fB\-\-fix\fR is passed, style violations will be automatically fixed using RuboCop\'s auto\-correct feature\.
 .
 .IP
 If \fB\-\-online\fR is passed, additional slower checks that require a network connection are run\.
@@ -653,16 +675,10 @@ If \fB\-\-display\-cop\-names\fR is passed, the RuboCop cop name for each violat
 If \fB\-\-display\-filename\fR is passed, every line of output is prefixed with the name of the file or formula being audited, to make the output easy to grep\.
 .
 .IP
-If \fB\-\-only\fR is passed, only the methods named \fBaudit_<method>\fR will be run\.
+Passing \fB\-\-only=\fR\fImethod\fR will run only the methods named \fBaudit_<method>\fR, while \fB\-\-except=\fR\fImethod\fR will skip the methods named \fBaudit_<method>\fR\. For either option \fImethod\fR should be a comma\-separated list\.
 .
 .IP
-If \fB\-\-except\fR is passed, the methods named \fBaudit_<method>\fR will not be run\.
-.
-.IP
-If \fB\-\-only\-cops\fR is passed, only the given Rubocop cop(s)\' violations would be checked\.
-.
-.IP
-If \fB\-\-except\-cops\fR is passed, the given Rubocop cop(s)\' checks would be skipped\.
+Passing \fB\-\-only\-cops=\fR\fIcops\fR will check for violations of only the listed RuboCop \fIcops\fR, while \fB\-\-except\-cops=\fR\fIcops\fR will skip checking the listed \fIcops\fR\. For either option \fIcops\fR should be a comma\-separated list of cop names\.
 .
 .IP
 \fBaudit\fR exits with a non\-zero status if any errors are found\. This is useful, for instance, for implementing pre\-commit hooks\.
@@ -731,6 +747,9 @@ If \fB\-\-message=\fR\fImessage\fR is passed, append \fImessage\fR to the defaul
 If \fB\-\-no\-browse\fR is passed, don\'t pass the \fB\-\-browse\fR argument to \fBhub\fR which opens the pull request URL in a browser\. Instead, output it to the command line\.
 .
 .IP
+If \fB\-\-quiet\fR is passed, don\'t output replacement messages or warn about duplicate pull requests\.
+.
+.IP
 Note that this command cannot be used to transition a formula from a URL\-and\-sha256 style specification into a tag\-and\-revision style specification, nor vice versa\. It must use whichever style specification the preexisting formula already uses\.
 .
 .TP