diff --git a/Library/Homebrew/cmd/cleanup.rb b/Library/Homebrew/cmd/cleanup.rb
index 5b46e08724f63e0ae8468ce0b4b8d771f12e62d2..126309579e266538d09d33d7d43150d818b7f2bd 100644
--- a/Library/Homebrew/cmd/cleanup.rb
+++ b/Library/Homebrew/cmd/cleanup.rb
@@ -7,7 +7,7 @@
 #:    If `--dry-run` or `-n` is passed, show what would be removed, but do not
 #:    actually remove anything.
 #:
-#:    If `-s` is passed, scrubs the cache, removing downloads for even the latest
+#:    If `-s` is passed, scrub the cache, removing downloads for even the latest
 #:    versions of formulae. Note downloads for any installed formulae will still not be
 #:    deleted. If you want to delete those too: `rm -rf $(brew --cache)`
 
diff --git a/Library/Homebrew/cmd/desc.rb b/Library/Homebrew/cmd/desc.rb
index 3ef02288bd3c13d5d6abfa04417c62046fd067dc..53291602e1f94a6b9f938e9a0926f8c769dbd821 100644
--- a/Library/Homebrew/cmd/desc.rb
+++ b/Library/Homebrew/cmd/desc.rb
@@ -1,11 +1,10 @@
 #:  * `desc` <formula>:
 #:    Display <formula>'s name and one-line description.
 #:
-#:  * `desc` [`-s`|`-n`|`-d`] <pattern>:
+#:  * `desc` [`-s`|`-n`|`-d`] (<text>|`/`<text>`/`):
 #:    Search both name and description (`-s`), just the names (`-n`), or just  the
-#:    descriptions (`-d`) for `<pattern>`. `<pattern>` is by default interpreted
-#:    as a literal string; if flanked by slashes, it is instead interpreted as a
-#:    regular expression. Formula descriptions are cached; the cache is created on
+#:    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.
 
 require "descriptions"
diff --git a/Library/Homebrew/cmd/info.rb b/Library/Homebrew/cmd/info.rb
index 1850ae003e8f0a3c61eae9508ed07a1b3c7d0b1c..b06d99466658d57db597579cdff3a85fbd320197 100644
--- a/Library/Homebrew/cmd/info.rb
+++ b/Library/Homebrew/cmd/info.rb
@@ -4,7 +4,7 @@
 #:  * `info` `--github` <formula>:
 #:    Open a browser to the GitHub History page for formula <formula>.
 #:
-#:    To view formula history locally: `brew log -p <formula>`.
+#:    To view formula history locally: `brew log -p <formula>`
 #:
 #:  * `info` `--json=`<version> (`--all`|`--installed`|<formulae>):
 #:    Print a JSON representation of <formulae>. Currently the only accepted value
@@ -13,7 +13,7 @@
 #:    Pass `--all` to get information on all formulae, or `--installed` to get
 #:    information on all installed formulae.
 #:
-#:    See the docs for examples of using the JSON:
+#:    See the docs for examples of using the JSON output:
 #:    <http://docs.brew.sh/Querying-Brew.html>
 
 require "blacklist"
diff --git a/Library/Homebrew/cmd/outdated.rb b/Library/Homebrew/cmd/outdated.rb
index 9ed7a0f79a39a57f8f8a58955294ca848909ad75..a18f4e3998c0c86952c2c05d9c3f0ab62f19c988 100644
--- a/Library/Homebrew/cmd/outdated.rb
+++ b/Library/Homebrew/cmd/outdated.rb
@@ -1,4 +1,4 @@
-#:  * `outdated` [`--quiet`|`--verbose`|`--json=v1`] [`--fetch-HEAD`]:
+#:  * `outdated` [`--quiet`|`--verbose`|`--json=`<version>] [`--fetch-HEAD`]:
 #:    Show formulae that have an updated version available.
 #:
 #:    By default, version information is displayed in interactive shells, and
diff --git a/Library/Homebrew/cmd/readall.rb b/Library/Homebrew/cmd/readall.rb
index 7c1a085c9b9262104dc60e2c540ea5cad511839e..3591e0c09aa34e5f7dc23243c77b78c294421a00 100644
--- a/Library/Homebrew/cmd/readall.rb
+++ b/Library/Homebrew/cmd/readall.rb
@@ -4,7 +4,7 @@
 #:
 #:    This can be useful for debugging issues across all formulae
 #:    when making significant changes to `formula.rb`,
-#:    or to determine if any current formulae have Ruby issues
+#:    or to determine if any current formulae have Ruby issues.
 
 require "readall"
 
diff --git a/Library/Homebrew/cmd/search.rb b/Library/Homebrew/cmd/search.rb
index d69164eb9503b5ee88f14d45bb3f9c330355b5ad..e834a00b555387f1af193d94c7a46a00556a365f 100644
--- a/Library/Homebrew/cmd/search.rb
+++ b/Library/Homebrew/cmd/search.rb
@@ -2,7 +2,7 @@
 #:    Display all locally available formulae for brewing (including tapped ones).
 #:    No online search is performed if called without arguments.
 #:
-#:  * `search` [`--desc`] <text>|`/`<text>`/`:
+#:  * `search` [`--desc`] (<text>|`/`<text>`/`):
 #:    Perform a substring search of formula names for <text>. If <text> is
 #:    surrounded with slashes, then it is interpreted as a regular expression.
 #:    The search for <text> is extended online to some popular taps.
diff --git a/Library/Homebrew/cmd/tap-info.rb b/Library/Homebrew/cmd/tap-info.rb
index b46de30c125ffa6ea707c8070255b74c7e9bdb16..225b70097bb94cd8477ed4b75db7224d4d316263 100644
--- a/Library/Homebrew/cmd/tap-info.rb
+++ b/Library/Homebrew/cmd/tap-info.rb
@@ -12,7 +12,7 @@
 #:
 #:    Pass `--installed` to get information on installed taps.
 #:
-#:    See the docs for examples of using the JSON:
+#:    See the docs for examples of using the JSON output:
 #:    <http://docs.brew.sh/Querying-Brew.html>
 
 require "tap"
diff --git a/Library/Homebrew/cmd/unlink.rb b/Library/Homebrew/cmd/unlink.rb
index a105f9c56e8e069202bcb88f13547420d2bd3ab7..3f858b2c45931b593f732258fe218c02c485653a 100644
--- a/Library/Homebrew/cmd/unlink.rb
+++ b/Library/Homebrew/cmd/unlink.rb
@@ -1,7 +1,7 @@
 #:  * `unlink` [`--dry-run`] <formula>:
 #:    Remove symlinks for <formula> from the Homebrew prefix. This can be useful
 #:    for temporarily disabling a formula:
-#:    `brew unlink foo && commands && brew link foo`.
+#:    `brew unlink <formula> && <commands> && brew link <formula>`
 #:
 #:    If `--dry-run` or `-n` is passed, Homebrew will list all files which would
 #:    be unlinked, but will not actually unlink or delete any files.
diff --git a/Library/Homebrew/cmd/unpack.rb b/Library/Homebrew/cmd/unpack.rb
index 4e6584e70b6b238dff0b5d43b56f6db453a2bde6..60d796d9f3464d38c6bd2601815ccc129d496af3 100644
--- a/Library/Homebrew/cmd/unpack.rb
+++ b/Library/Homebrew/cmd/unpack.rb
@@ -1,7 +1,7 @@
 #:  * `unpack` [`--git`|`--patch`] [`--destdir=`<path>] <formulae>:
 #:    Unpack the source files for <formulae> into subdirectories of the current
 #:    working directory. If `--destdir=`<path> is given, the subdirectories will
-#:    be created in the directory named by `<path>` instead.
+#:    be created in the directory named by <path> instead.
 #:
 #:    If `--patch` is passed, patches for <formulae> will be applied to the
 #:    unpacked source.
diff --git a/Library/Homebrew/cmd/uses.rb b/Library/Homebrew/cmd/uses.rb
index 5f6611dfc5093f3bab70cac9e36f36bd80397797..b1122c90a76ddd78e1739ba44d124fd59829f6b8 100644
--- a/Library/Homebrew/cmd/uses.rb
+++ b/Library/Homebrew/cmd/uses.rb
@@ -12,8 +12,8 @@
 #:    `--include-build`. Similarly, pass `--include-optional` to include `:optional`
 #:    dependencies. To skip `:recommended` type dependencies, pass `--skip-recommended`.
 #:
-#:    By default, `uses` shows usages of `formula` by stable builds. To find
-#:    cases where `formula` is used by development or HEAD build, pass
+#:    By default, `uses` shows usages of <formulae> by stable builds. To find
+#:    cases where <formulae> is used by development or HEAD build, pass
 #:    `--devel` or `--HEAD`.
 
 require "formula"
diff --git a/Library/Homebrew/dev-cmd/boneyard-formula-pr.rb b/Library/Homebrew/dev-cmd/boneyard-formula-pr.rb
index 3066d2ee6bcc777359dc508148e9893c8608f85e..7531ef9cf5dd622598bce3ef0f49db1d271877a2 100644
--- a/Library/Homebrew/dev-cmd/boneyard-formula-pr.rb
+++ b/Library/Homebrew/dev-cmd/boneyard-formula-pr.rb
@@ -1,5 +1,5 @@
 #: @hide_from_man_page
-#:  * `boneyard-formula-pr` [`--dry-run`] [`--local`] [`--reason=<reason>`] <formula-name> :
+#:  * `boneyard-formula-pr` [`--dry-run`] [`--local`] [`--reason=<reason>`] <formula> :
 #:    Creates a pull request to boneyard a formula.
 #:
 #:    If `--dry-run` is passed, print what would be done rather than doing it.
diff --git a/Library/Homebrew/dev-cmd/bottle.rb b/Library/Homebrew/dev-cmd/bottle.rb
index 7367e5c372a3bac89daef14816cca666c4415bd2..91bdcba93d7689080a21604498721a806a8bede8 100644
--- a/Library/Homebrew/dev-cmd/bottle.rb
+++ b/Library/Homebrew/dev-cmd/bottle.rb
@@ -1,6 +1,5 @@
-#:  * `bottle` [`--verbose`] [`--no-rebuild`] [`--keep-old`] [`--skip-relocation`] [`--root-url=<root_url>`] [`--force-core-tap`]:
+#:  * `bottle` [`--verbose`] [`--no-rebuild`] [`--keep-old`] [`--skip-relocation`] [`--root-url=`<URL>] [`--force-core-tap`]:
 #:  * `bottle` `--merge` [`--no-commit`] [`--keep-old`] [`--write`]:
-#:
 #:    Generate a bottle (binary package) from a formula installed with
 #:    `--build-bottle`.
 
diff --git a/Library/Homebrew/dev-cmd/bump-formula-pr.rb b/Library/Homebrew/dev-cmd/bump-formula-pr.rb
index bfe9c777674112b77dd04b2d9f354d5dbc80d7ed..6c7b7d5b5e6ad7cb2bd07f4159efaadae862932b 100644
--- a/Library/Homebrew/dev-cmd/bump-formula-pr.rb
+++ b/Library/Homebrew/dev-cmd/bump-formula-pr.rb
@@ -1,8 +1,7 @@
-#:  * `bump-formula-pr` [`--devel`] [`--dry-run`] [`--audit`|`--strict`] [`--message=`<message>] `--url=`<url> `--sha256=`<sha-256> <formula>:
-#:  * `bump-formula-pr` [`--devel`] [`--dry-run`] [`--audit`|`--strict`] [`--message=`<message>] `--tag=`<tag> `--revision=`<revision> <formula>:
-#:    Creates a pull request to update the formula with a new url or a new tag.
+#:  * `bump-formula-pr` [`--devel`] [`--dry-run` [`--write`]] [`--audit`|`--strict`] [`--mirror=`<URL>] [`--version=`<version>] [`--message=`<message>] (`--url=`<URL> `--sha256=`<sha-256>|`--tag=`<tag> `--revision=`<revision>) <formula>:
+#:    Creates a pull request to update the formula with a new URL or a new tag.
 #:
-#:    If a <url> is specified, the <sha-256> checksum of the new download must
+#:    If a <URL> is specified, the <sha-256> checksum of the new download must
 #:    also be specified. A best effort to determine the <sha-256> and <formula>
 #:    name will be made if either or both values are not supplied by the user.
 #:
@@ -21,17 +20,17 @@
 #:
 #:    If `--strict` is passed, run `brew audit --strict` before opening the PR.
 #:
-#:    If `--mirror=`<url> is passed, use the value as a mirror url.
+#:    If `--mirror=`<URL> is passed, use the value as a mirror URL.
 #:
 #:    If `--version=`<version> is passed, use the value to override the value
-#:    parsed from the url or tag. Note that `--version=0` can be used to delete
+#:    parsed from the URL or tag. Note that `--version=0` can be used to delete
 #:    an existing `version` override from a formula if it has become redundant.
 #:
 #:    If `--message=`<message> is passed, append <message> to the default PR
 #:    message.
 #:
 #:    Note that this command cannot be used to transition a formula from a
-#:    url-and-sha256 style specification into a tag-and-revision style
+#:    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.
 
diff --git a/Library/Homebrew/dev-cmd/create.rb b/Library/Homebrew/dev-cmd/create.rb
index b4cda0fad51e5c9d3d23c818c38fc4a08c1305b3..9c58dc71a3348e171205b84e01c22ee7ae4b6e9e 100644
--- a/Library/Homebrew/dev-cmd/create.rb
+++ b/Library/Homebrew/dev-cmd/create.rb
@@ -3,8 +3,7 @@
 #:    Homebrew will attempt to automatically derive the formula name
 #:    and version, but if it fails, you'll have to make your own template. The `wget`
 #:    formula serves as a simple example. For the complete API have a look at
-#:
-#:    <http://www.rubydoc.info/github/Homebrew/brew/master/Formula>
+#:    <http://www.rubydoc.info/github/Homebrew/brew/master/Formula>.
 #:
 #:    If `--autotools` is passed, create a basic template for an Autotools-style build.
 #:    If `--cmake` is passed, create a basic template for a CMake-style build.
diff --git a/Library/Homebrew/dev-cmd/formula.rb b/Library/Homebrew/dev-cmd/formula.rb
index 71687dfa781c132de9fd5dd86f835eef97ed1a90..67d11edce2a375e7467700fd351626ba35ab6a29 100644
--- a/Library/Homebrew/dev-cmd/formula.rb
+++ b/Library/Homebrew/dev-cmd/formula.rb
@@ -1,5 +1,5 @@
 #:  * `formula` <formula>:
-#:    Display the path where <formula> is
+#:    Display the path where <formula> is located.
 
 require "formula"
 
diff --git a/Library/Homebrew/dev-cmd/linkage.rb b/Library/Homebrew/dev-cmd/linkage.rb
index 44e0f224eec441d859618eb69047898bc6c1aa23..e4da827f24508b7987fc814af406c8d7ad754990 100644
--- a/Library/Homebrew/dev-cmd/linkage.rb
+++ b/Library/Homebrew/dev-cmd/linkage.rb
@@ -1,4 +1,4 @@
-#:  * `linkage` [`--test`] [`--reverse`]  <formula-name>:
+#:  * `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/Library/Homebrew/dev-cmd/mirror.rb b/Library/Homebrew/dev-cmd/mirror.rb
index bd5868726fa14679c74b9d365a368dee3628673a..10811493c2c5cf436527d4d9cd6f76f815bbd123 100644
--- a/Library/Homebrew/dev-cmd/mirror.rb
+++ b/Library/Homebrew/dev-cmd/mirror.rb
@@ -1,5 +1,5 @@
 #: @hide_from_man_page
-#:  * `mirror` [`--test`] <formula-name> [<formula-name> ...]:
+#:  * `mirror` [`--test`] <formulae>:
 #:    Reuploads the stable URL for a formula to Bintray to use it as a mirror.
 
 module Homebrew
diff --git a/Library/Homebrew/dev-cmd/release-notes.rb b/Library/Homebrew/dev-cmd/release-notes.rb
index 9192437648ac6c05e6538689fc67a27f7feaad72..eb398fcfb9b5b50a986a2514d96712b436825422 100644
--- a/Library/Homebrew/dev-cmd/release-notes.rb
+++ b/Library/Homebrew/dev-cmd/release-notes.rb
@@ -1,7 +1,7 @@
-#:  * `release-notes` [<previous_tag>] [<end_ref>]:
+#:  * `release-notes` [`--markdown`] [<previous_tag>] [<end_ref>]:
 #:    Output the merged pull requests on Homebrew/brew between two Git refs.
-#:    If no `previous_tag` is provided it defaults to the newest tag.
-#:    If no `end_ref` is provided it defaults to `origin/master`.
+#:    If no <previous_tag> is provided it defaults to the newest tag.
+#:    If no <end_ref> is provided it defaults to `origin/master`.
 #:
 #:    If `--markdown` is passed, output as a Markdown list.
 
diff --git a/Library/Homebrew/dev-cmd/tests.rb b/Library/Homebrew/dev-cmd/tests.rb
index 6276d1c1b7f22e945f6f8764f439a61262a3632a..0c8621a01de9f2d5b4cddf5d2b86e87dd7d40f8f 100644
--- a/Library/Homebrew/dev-cmd/tests.rb
+++ b/Library/Homebrew/dev-cmd/tests.rb
@@ -1,4 +1,4 @@
-#:  * `tests` [`-v`] [`--coverage`] [`--generic`] [`--no-compat`] [`--only=`<test_script:test_method>] [`--seed` <seed>] [`--trace`] [`--online`] [`--official-cmd-taps`]:
+#:  * `tests` [`-v`] [`--coverage`] [`--generic`] [`--no-compat`] [`--only=`<test_script>`:`<test_method>] [`--seed` <seed>] [`--trace`] [`--online`] [`--official-cmd-taps`]:
 #:    Run Homebrew's unit and integration tests.
 
 require "fileutils"
diff --git a/Library/Homebrew/dev-cmd/update-test.rb b/Library/Homebrew/dev-cmd/update-test.rb
index 3b8dc11f9d633ea257e23ba3c0ee64af1b565f38..9704426ddd7dd1bbfd110e275429fd0c939ccbd8 100644
--- a/Library/Homebrew/dev-cmd/update-test.rb
+++ b/Library/Homebrew/dev-cmd/update-test.rb
@@ -1,14 +1,14 @@
-#:  * `update-test` [`--commit=<commit>`] [`--before=<date>`] [`--keep-tmp`]:
+#:  * `update-test` [`--commit=`<commit>] [`--before=`<date>] [`--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.
 #:
-#:    If `--commit=<commit>` is passed, use `<commit>` as the start commit.
+#:    If `--commit=`<commit> is passed, use <commit> as the start commit.
 #:
-#:    If `--before=<date>` is passed, use the commit at `<date>` as the
+#:    If `--before=`<date> is passed, use the commit at <date> as the
 #:    start commit.
 #:
-#:    If `--to-tag` is passed, set HOMEBREW_UPDATE_TO_TAG to test updating
+#:    If `--to-tag` is passed, set `HOMEBREW_UPDATE_TO_TAG` to test updating
 #:    between tags.
 #:
 #:    If `--keep-tmp` is passed, retain the temporary directory containing
diff --git a/Library/Homebrew/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb
index a7f099e9daf64fe7ac854a619a26d14f3fee05e7..05fc1cb2370364c7aa4e175468268669170f2acd 100644
--- a/Library/Homebrew/manpages/brew.1.md.erb
+++ b/Library/Homebrew/manpages/brew.1.md.erb
@@ -40,7 +40,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
   * `list`:
     List all installed formulae.
 
-  * `search` <text>|`/`<text>`/`:
+  * `search` (<text>|`/`<text>`/`):
     Perform a substring search of formula names for <text>. If <text> is
     surrounded with slashes, then it is interpreted as a regular expression.
     The search for <text> is extended online to some popular taps.
@@ -214,7 +214,7 @@ can take several different forms:
     to insecure HTTP.
 
     While ensuring your downloads are fully secure, this is likely
-    to cause from-source Sourceforge, some GNU & GNOME based
+    to cause from-source SourceForge, some GNU & GNOME based
     formulae to fail to download.
 
   * `HOMEBREW_NO_GITHUB_API`:
diff --git a/README.md b/README.md
index 195566f37567b9f362fe249d4072e5749f941485..1175c65f0a4c87b5a209e04f42b63824dba1cf3e 100644
--- a/README.md
+++ b/README.md
@@ -40,8 +40,7 @@ This is our PGP key which is valid until May 24, 2017.
 ## Who Are You?
 Homebrew's lead maintainer is [Mike McQuaid](https://github.com/mikemcquaid).
 
-Homebrew's current maintainers are [Alyssa Ross](https://github.com/alyssais), [Andrew Janke](https://github.com/apjanke), [Baptiste Fontaine](https://github.com/bfontaine), [Alex Dunn](https://github.com/dunn),
-[FX Coudert](https://github.com/fxcoudert), [ilovezfs](https://github.com/ilovezfs), [Josh Hagins](https://github.com/jawshooah), [JCount](https://github.com/jcount), [Misty De Meo](https://github.com/mistydemeo), [Tomasz Pajor](https://github.com/nijikon), [Markus Reiter](https://github.com/reitermarkus), [Tim Smith](https://github.com/tdsmith), [Tom Schoonjans](https://github.com/tschoonj), [Uladzislau Shablinski](https://github.com/vladshablinsky) and [William Woodruff](https://github.com/woodruffw).
+Homebrew's current maintainers are [Alyssa Ross](https://github.com/alyssais), [Andrew Janke](https://github.com/apjanke), [Baptiste Fontaine](https://github.com/bfontaine), [Alex Dunn](https://github.com/dunn), [FX Coudert](https://github.com/fxcoudert), [ilovezfs](https://github.com/ilovezfs), [Josh Hagins](https://github.com/jawshooah), [JCount](https://github.com/jcount), [Misty De Meo](https://github.com/mistydemeo), [Tomasz Pajor](https://github.com/nijikon), [Markus Reiter](https://github.com/reitermarkus), [Tim Smith](https://github.com/tdsmith), [Tom Schoonjans](https://github.com/tschoonj), [Uladzislau Shablinski](https://github.com/vladshablinsky) and [William Woodruff](https://github.com/woodruffw).
 
 Former maintainers with significant contributions include [Xu Cheng](https://github.com/xu-cheng), [Martin Afanasjew](https://github.com/UniqMartin), [Dominyk Tiller](https://github.com/DomT4), [Brett Koonce](https://github.com/asparagui), [Jack Nagel](https://github.com/jacknagel), [Adam Vandenberg](https://github.com/adamv) and Homebrew's creator: [Max Howell](https://github.com/mxcl).
 
diff --git a/docs/brew.1.html b/docs/brew.1.html
index 77a58de7b59706b12bcbc1069a649b516a924b6a..ff2d6105cf691847ecbe3fb6420c7e70aa1e7850 100644
--- a/docs/brew.1.html
+++ b/docs/brew.1.html
@@ -25,7 +25,7 @@ didn't include with macOS.</p>
 <dt><code>uninstall</code> <var>formula</var></dt><dd><p>Uninstall <var>formula</var>.</p></dd>
 <dt class="flush"><code>update</code></dt><dd><p>Fetch the newest version of Homebrew from GitHub using <code>git</code>(1).</p></dd>
 <dt class="flush"><code>list</code></dt><dd><p>List all installed formulae.</p></dd>
-<dt><code>search</code> <var>text</var>|<code>/</code><var>text</var><code>/</code></dt><dd><p>Perform a substring search of formula names for <var>text</var>. If <var>text</var> is
+<dt><code>search</code> (<var>text</var>|<code>/</code><var>text</var><code>/</code>)</dt><dd><p>Perform a substring search of formula names for <var>text</var>. If <var>text</var> is
 surrounded with slashes, then it is interpreted as a regular expression.
 The search for <var>text</var> is extended online to some popular taps.
 If no search term is given, all locally available formulae are listed.</p></dd>
@@ -48,7 +48,7 @@ cellar. In addition, old downloads from the Homebrew download-cache are deleted.
 <p>If <code>--dry-run</code> or <code>-n</code> is passed, show what would be removed, but do not
 actually remove anything.</p>
 
-<p>If <code>-s</code> is passed, scrubs the cache, removing downloads for even the latest
+<p>If <code>-s</code> is passed, scrub the cache, removing downloads for even the latest
 versions of formulae. Note downloads for any installed formulae will still not be
 deleted. If you want to delete those too: <code>rm -rf $(brew --cache)</code></p></dd>
 <dt><code>command</code> <var>cmd</var></dt><dd><p>Display the path to the file which is used when invoking <code>brew</code> <var>cmd</var>.</p></dd>
@@ -93,10 +93,9 @@ dependencies of that formula.</p>
 <p>The <var>filters</var> placeholder is any combination of options <code>--include-build</code>,
 <code>--include-optional</code>, and <code>--skip-recommended</code> as documented above.</p></dd>
 <dt><code>desc</code> <var>formula</var></dt><dd><p>Display <var>formula</var>'s name and one-line description.</p></dd>
-<dt><code>desc</code> [<code>-s</code>|<code>-n</code>|<code>-d</code>] <var>pattern</var></dt><dd><p>Search both name and description (<code>-s</code>), just the names (<code>-n</code>), or just  the
-descriptions (<code>-d</code>) for <code>&lt;pattern></code>. <code>&lt;pattern></code> is by default interpreted
-as a literal string; if flanked by slashes, it is instead interpreted as a
-regular expression. Formula descriptions are cached; the cache is created on
+<dt><code>desc</code> [<code>-s</code>|<code>-n</code>|<code>-d</code>] (<var>text</var>|<code>/</code><var>text</var><code>/</code>)</dt><dd><p>Search both name and description (<code>-s</code>), just the names (<code>-n</code>), or just  the
+descriptions (<code>-d</code>) for <var>text</var>. If <var>text</var> 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.</p></dd>
 <dt><code>diy</code> [<code>--name=</code><var>name</var>] [<code>--version=</code><var>version</var>]</dt><dd><p>Automatically determine the installation prefix for non-Homebrew software.</p>
 
@@ -144,14 +143,14 @@ GitHub repository as well as creating the Gist.</p>
 <dt><code>info</code> <var>formula</var></dt><dd><p>Display information about <var>formula</var>.</p></dd>
 <dt><code>info</code> <code>--github</code> <var>formula</var></dt><dd><p>Open a browser to the GitHub History page for formula <var>formula</var>.</p>
 
-<p>To view formula history locally: <code>brew log -p &lt;formula></code>.</p></dd>
+<p>To view formula history locally: <code>brew log -p &lt;formula></code></p></dd>
 <dt><code>info</code> <code>--json=</code><var>version</var> (<code>--all</code>|<code>--installed</code>|<var>formulae</var>)</dt><dd><p>Print a JSON representation of <var>formulae</var>. Currently the only accepted value
 for <var>version</var> is <code>v1</code>.</p>
 
 <p>Pass <code>--all</code> to get information on all formulae, or <code>--installed</code> to get
 information on all installed formulae.</p>
 
-<p>See the docs for examples of using the JSON:
+<p>See the docs for examples of using the JSON output:
 <a href="http://docs.brew.sh/Querying-Brew.html" data-bare-link="true">http://docs.brew.sh/Querying-Brew.html</a></p></dd>
 <dt><code>install</code> [<code>--debug</code>] [<code>--env=</code><var>std</var>|<var>super</var>] [<code>--ignore-dependencies</code>] [<code>--only-dependencies</code>] [<code>--cc=</code><var>compiler</var>] [<code>--build-from-source</code>] [<code>--devel</code>|<code>--HEAD</code>] [<code>--keep-tmp</code>] <var>formula</var></dt><dd><p>Install <var>formula</var>.</p>
 
@@ -265,7 +264,7 @@ spaces.</p>
 <p>If <code>--all</code> is passed, show options for all formulae.</p>
 
 <p>If <code>--installed</code> is passed, show options for all installed formulae.</p></dd>
-<dt><code>outdated</code> [<code>--quiet</code>|<code>--verbose</code>|<code>--json=v1</code>] [<code>--fetch-HEAD</code>]</dt><dd><p>Show formulae that have an updated version available.</p>
+<dt><code>outdated</code> [<code>--quiet</code>|<code>--verbose</code>|<code>--json=</code><var>version</var>] [<code>--fetch-HEAD</code>]</dt><dd><p>Show formulae that have an updated version available.</p>
 
 <p>By default, version information is displayed in interactive shells, and
 suppressed otherwise.</p>
@@ -295,7 +294,7 @@ actually remove anything.</p></dd>
 <dt><code>reinstall</code> <var>formula</var></dt><dd><p>Uninstall and then install <var>formula</var>.</p></dd>
 <dt><code>search</code>, <code>-S</code></dt><dd><p>Display all locally available formulae for brewing (including tapped ones).
 No online search is performed if called without arguments.</p></dd>
-<dt><code>search</code> [<code>--desc</code>] <var>text</var>|<code>/</code><var>text</var><code>/</code></dt><dd><p>Perform a substring search of formula names for <var>text</var>. If <var>text</var> is
+<dt><code>search</code> [<code>--desc</code>] (<var>text</var>|<code>/</code><var>text</var><code>/</code>)</dt><dd><p>Perform a substring search of formula names for <var>text</var>. If <var>text</var> is
 surrounded with slashes, then it is interpreted as a regular expression.
 The search for <var>text</var> is extended online to some popular taps.</p>
 
@@ -353,7 +352,7 @@ for <var>version</var> is <code>v1</code>.</p>
 
 <p>Pass <code>--installed</code> to get information on installed taps.</p>
 
-<p>See the docs for examples of using the JSON:
+<p>See the docs for examples of using the JSON output:
 <a href="http://docs.brew.sh/Querying-Brew.html" data-bare-link="true">http://docs.brew.sh/Querying-Brew.html</a></p></dd>
 <dt><code>tap-pin</code> <var>tap</var></dt><dd><p>Pin <var>tap</var>, prioritizing its formulae over core when formula names are supplied
 by the user. See also <code>tap-unpin</code>.</p></dd>
@@ -367,7 +366,7 @@ installed, delete all installed versions.</p>
 formulae depending on <var>formula</var> would still be installed.</p></dd>
 <dt><code>unlink</code> [<code>--dry-run</code>] <var>formula</var></dt><dd><p>Remove symlinks for <var>formula</var> from the Homebrew prefix. This can be useful
 for temporarily disabling a formula:
-<code>brew unlink foo &amp;&amp; commands &amp;&amp; brew link foo</code>.</p>
+<code>brew unlink &lt;formula> &amp;&amp; &lt;commands> &amp;&amp; brew link &lt;formula></code></p>
 
 <p>If <code>--dry-run</code> or <code>-n</code> is passed, Homebrew will list all files which would
 be unlinked, but will not actually unlink or delete any files.</p></dd>
@@ -387,7 +386,7 @@ directory instead of the system directory.</p>
 would be removed, but will not actually delete any files.</p></dd>
 <dt><code>unpack</code> [<code>--git</code>|<code>--patch</code>] [<code>--destdir=</code><var>path</var>] <var>formulae</var></dt><dd><p>Unpack the source files for <var>formulae</var> into subdirectories of the current
 working directory. If <code>--destdir=</code><var>path</var> is given, the subdirectories will
-be created in the directory named by <code>&lt;path></code> instead.</p>
+be created in the directory named by <var>path</var> instead.</p>
 
 <p>If <code>--patch</code> is passed, patches for <var>formulae</var> will be applied to the
 unpacked source.</p>
@@ -431,8 +430,8 @@ or recommended dependency. To include the <code>:build</code> type dependencies,
 <code>--include-build</code>. Similarly, pass <code>--include-optional</code> to include <code>:optional</code>
 dependencies. To skip <code>:recommended</code> type dependencies, pass <code>--skip-recommended</code>.</p>
 
-<p>By default, <code>uses</code> shows usages of <code>formula</code> by stable builds. To find
-cases where <code>formula</code> is used by development or HEAD build, pass
+<p>By default, <code>uses</code> shows usages of <var>formulae</var> by stable builds. To find
+cases where <var>formulae</var> is used by development or HEAD build, pass
 <code>--devel</code> or <code>--HEAD</code>.</p></dd>
 <dt class="flush"><code>--cache</code></dt><dd><p>Display Homebrew's download cache. See also <code>HOMEBREW_CACHE</code>.</p></dd>
 <dt><code>--cache</code> <var>formula</var></dt><dd><p>Display the file or directory used to cache <var>formula</var>.</p></dd>
@@ -479,15 +478,12 @@ name of the file or formula being audited, to make the output easy to grep.</p>
 
 <p><code>audit</code> exits with a non-zero status if any errors are found. This is useful,
 for instance, for implementing pre-commit hooks.</p></dd>
-<dt><code>bottle</code> [<code>--verbose</code>] [<code>--no-rebuild</code>] [<code>--keep-old</code>] [<code>--skip-relocation</code>] [<code>--root-url=&lt;root_url></code>] [<code>--force-core-tap</code>]:</dt><dd><p></p></dd>
-<dt><code>bottle</code> <code>--merge</code> [<code>--no-commit</code>] [<code>--keep-old</code>] [<code>--write</code>]:</dt><dd><p></p>
-
-<p>Generate a bottle (binary package) from a formula installed with
+<dt><code>bottle</code> [<code>--verbose</code>] [<code>--no-rebuild</code>] [<code>--keep-old</code>] [<code>--skip-relocation</code>] [<code>--root-url=</code><var>URL</var>] [<code>--force-core-tap</code>]:</dt><dd><p></p></dd>
+<dt><code>bottle</code> <code>--merge</code> [<code>--no-commit</code>] [<code>--keep-old</code>] [<code>--write</code>]</dt><dd><p>Generate a bottle (binary package) from a formula installed with
 <code>--build-bottle</code>.</p></dd>
-<dt><code>bump-formula-pr</code> [<code>--devel</code>] [<code>--dry-run</code>] [<code>--audit</code>|<code>--strict</code>] [<code>--message=</code><var>message</var>] <code>--url=</code><var>url</var> <code>--sha256=</code><var>sha-256</var> <var>formula</var>:</dt><dd><p></p></dd>
-<dt><code>bump-formula-pr</code> [<code>--devel</code>] [<code>--dry-run</code>] [<code>--audit</code>|<code>--strict</code>] [<code>--message=</code><var>message</var>] <code>--tag=</code><var>tag</var> <code>--revision=</code><var>revision</var> <var>formula</var></dt><dd><p>Creates a pull request to update the formula with a new url or a new tag.</p>
+<dt><code>bump-formula-pr</code> [<code>--devel</code>] [<code>--dry-run</code> [<code>--write</code>]] [<code>--audit</code>|<code>--strict</code>] [<code>--mirror=</code><var>URL</var>] [<code>--version=</code><var>version</var>] [<code>--message=</code><var>message</var>] (<code>--url=</code><var>URL</var> <code>--sha256=</code><var>sha-256</var>|<code>--tag=</code><var>tag</var> <code>--revision=</code><var>revision</var>) <var>formula</var></dt><dd><p>Creates a pull request to update the formula with a new URL or a new tag.</p>
 
-<p>If a <var>url</var> is specified, the <var>sha-256</var> checksum of the new download must
+<p>If a <var>URL</var> is specified, the <var>sha-256</var> checksum of the new download must
 also be specified. A best effort to determine the <var>sha-256</var> and <var>formula</var>
 name will be made if either or both values are not supplied by the user.</p>
 
@@ -506,25 +502,24 @@ making the expected file modifications but not taking any git actions.</p>
 
 <p>If <code>--strict</code> is passed, run <code>brew audit --strict</code> before opening the PR.</p>
 
-<p>If <code>--mirror=</code><var>url</var> is passed, use the value as a mirror url.</p>
+<p>If <code>--mirror=</code><var>URL</var> is passed, use the value as a mirror URL.</p>
 
 <p>If <code>--version=</code><var>version</var> is passed, use the value to override the value
-parsed from the url or tag. Note that <code>--version=0</code> can be used to delete
+parsed from the URL or tag. Note that <code>--version=0</code> can be used to delete
 an existing <code>version</code> override from a formula if it has become redundant.</p>
 
 <p>If <code>--message=</code><var>message</var> is passed, append <var>message</var> to the default PR
 message.</p>
 
 <p>Note that this command cannot be used to transition a formula from a
-url-and-sha256 style specification into a tag-and-revision style
+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.</p></dd>
 <dt><code>create</code> <var>URL</var> [<code>--autotools</code>|<code>--cmake</code>|<code>--meson</code>] [<code>--no-fetch</code>] [<code>--set-name</code> <var>name</var>] [<code>--set-version</code> <var>version</var>] [<code>--tap</code> <var>user</var><code>/</code><var>repo</var>]</dt><dd><p>Generate a formula for the downloadable file at <var>URL</var> and open it in the editor.
 Homebrew will attempt to automatically derive the formula name
 and version, but if it fails, you'll have to make your own template. The <code>wget</code>
-formula serves as a simple example. For the complete API have a look at</p>
-
-<p><a href="http://www.rubydoc.info/github/Homebrew/brew/master/Formula" data-bare-link="true">http://www.rubydoc.info/github/Homebrew/brew/master/Formula</a></p>
+formula serves as a simple example. For the complete API have a look at
+<a href="http://www.rubydoc.info/github/Homebrew/brew/master/Formula" data-bare-link="true">http://www.rubydoc.info/github/Homebrew/brew/master/Formula</a>.</p>
 
 <p>If <code>--autotools</code> is passed, create a basic template for an Autotools-style build.
 If <code>--cmake</code> is passed, create a basic template for a CMake-style build.
@@ -540,8 +535,8 @@ you to explicitly set the name and version of the package you are creating.</p>
 the specified tap.</p></dd>
 <dt class="flush"><code>edit</code></dt><dd><p>Open all of Homebrew for editing.</p></dd>
 <dt><code>edit</code> <var>formula</var></dt><dd><p>Open <var>formula</var> in the editor.</p></dd>
-<dt><code>formula</code> <var>formula</var></dt><dd><p>Display the path where <var>formula</var> is</p></dd>
-<dt><code>linkage</code> [<code>--test</code>] [<code>--reverse</code>]  <var>formula-name</var></dt><dd><p>Checks the library links of an installed formula.</p>
+<dt><code>formula</code> <var>formula</var></dt><dd><p>Display the path where <var>formula</var> is located.</p></dd>
+<dt><code>linkage</code> [<code>--test</code>] [<code>--reverse</code>]  <var>formula</var></dt><dd><p>Checks the library links of an installed formula.</p>
 
 <p>Only works on installed formulae. An error is raised if it is run on
 uninstalled formulae.</p>
@@ -558,44 +553,47 @@ status code if changes are detected in the manpage outputs.
 This can be used for CI to be notified when the manpages are out of date.
 Additionally, the date used in new manpages will match those in the existing
 manpages (to allow comparison without factoring in the date).</p></dd>
-</dl>
-
+<dt><code>pull</code> [<code>--bottle</code>] [<code>--bump</code>] [<code>--clean</code>] [<code>--ignore-whitespace</code>] [<code>--resolve</code>] [<code>--branch-okay</code>] [<code>--no-pbcopy</code>] [<code>--no-publish</code>] <var>patch-source</var> [<var>patch-source</var>]</dt><dd><p>Gets a patch from a GitHub commit or pull request and applies it to Homebrew.
+Optionally, installs the formulae changed by the patch.</p>
 
-<p> <code>pull</code> [<code>--bottle</code>] [<code>--bump</code>] [<code>--clean</code>] [<code>--ignore-whitespace</code>] [<code>--resolve</code>] [<code>--branch-okay</code>] [<code>--no-pbcopy</code>] [<code>--no-publish</code>] <var>patch-source</var> [<var>patch-source</var>]</p>
+<p>Each <var>patch-source</var> may be one of:</p>
 
-<pre><code>Gets a patch from a GitHub commit or pull request and applies it to Homebrew.
-Optionally, installs the formulae changed by the patch.
+<p>  ~ The ID number of a PR (pull request) in the homebrew/core GitHub
+    repository</p>
 
-Each &lt;patch-source> may be one of:
-  * The ID number of a PR (Pull Request) in the homebrew/core GitHub
-    repository
-  * The URL of a PR on GitHub, using either the web page or API URL
+<p>  ~ The URL of a PR on GitHub, using either the web page or API URL
     formats. In this form, the PR may be on Homebrew/brew,
-    Homebrew/homebrew-core or any tap.
-  * The URL of a commit on GitHub
-  * A "http://bot.brew.sh/job/..." string specifying a testing job ID
-</code></pre>
+    Homebrew/homebrew-core or any tap.</p>
 
-<p>   If <code>--bottle</code> was passed, handle bottles, pulling the bottle-update
-   commit and publishing files on Bintray.
-   If <code>--bump</code> was passed, for one-formula PRs, automatically reword
-   commit message to our preferred format.
-   If <code>--clean</code> was passed, do not rewrite or otherwise modify the
-   commits found in the pulled PR.
-   If <code>--ignore-whitespace</code> was passed, silently ignore whitespace
-   discrepancies when applying diffs.
-   If <code>--resolve</code> was passed, when a patch fails to apply, leave in
-   progress and allow user to
-                  resolve, instead of aborting.
-   If <code>--branch-okay</code> was passed, do not warn if pulling to a branch
-   besides master (useful for testing).
-   If <code>--no-pbcopy</code> was passed, do not copy anything to the system
-   If <code>--no-publish</code> was passed, do not publish bottles to Bintray.</p>
+<p>  ~ The URL of a commit on GitHub</p>
 
-<dl>
-<dt><code>release-notes</code> [<var>previous_tag</var>] [<var>end_ref</var>]</dt><dd><p>Output the merged pull requests on Homebrew/brew between two Git refs.
-If no <code>previous_tag</code> is provided it defaults to the newest tag.
-If no <code>end_ref</code> is provided it defaults to <code>origin/master</code>.</p>
+<p>  ~ A "http://bot.brew.sh/job/..." string specifying a testing job ID</p>
+
+<p>If <code>--bottle</code> is passed, handle bottles, pulling the bottle-update
+commit and publishing files on Bintray.</p>
+
+<p>If <code>--bump</code> is passed, for one-formula PRs, automatically reword
+commit message to our preferred format.</p>
+
+<p>If <code>--clean</code> is passed, do not rewrite or otherwise modify the
+commits found in the pulled PR.</p>
+
+<p>If <code>--ignore-whitespace</code> is passed, silently ignore whitespace
+discrepancies when applying diffs.</p>
+
+<p>If <code>--resolve</code> is passed, when a patch fails to apply, leave in
+progress and allow user to resolve, instead of aborting.</p>
+
+<p>If <code>--branch-okay</code> is passed, do not warn if pulling to a branch
+besides master (useful for testing).</p>
+
+<p>If <code>--no-pbcopy</code> is passed, do not copy anything to the system
+clipboard.</p>
+
+<p>If <code>--no-publish</code> is passed, do not publish bottles to Bintray.</p></dd>
+<dt><code>release-notes</code> [<code>--markdown</code>] [<var>previous_tag</var>] [<var>end_ref</var>]</dt><dd><p>Output the merged pull requests on Homebrew/brew between two Git refs.
+If no <var>previous_tag</var> is provided it defaults to the newest tag.
+If no <var>end_ref</var> is provided it defaults to <code>origin/master</code>.</p>
 
 <p>If <code>--markdown</code> is passed, output as a Markdown list.</p></dd>
 <dt><code>tap-new</code> <var>user</var><code>/</code><var>repo</var></dt><dd><p>Generate the template files for a new tap.</p></dd>
@@ -614,17 +612,17 @@ launched with access to IRB or a shell inside the temporary test directory.</p>
 not deleted.</p>
 
 <p>Example: <code>brew install jruby &amp;&amp; brew test jruby</code></p></dd>
-<dt><code>tests</code> [<code>-v</code>] [<code>--coverage</code>] [<code>--generic</code>] [<code>--no-compat</code>] [<code>--only=</code>&lt;test_script:test_method>] [<code>--seed</code> <var>seed</var>] [<code>--trace</code>] [<code>--online</code>] [<code>--official-cmd-taps</code>]</dt><dd><p>Run Homebrew's unit and integration tests.</p></dd>
-<dt><code>update-test</code> [<code>--commit=&lt;commit></code>] [<code>--before=&lt;date></code>] [<code>--keep-tmp</code>]</dt><dd><p>Runs a test of <code>brew update</code> with a new repository clone.</p>
+<dt><code>tests</code> [<code>-v</code>] [<code>--coverage</code>] [<code>--generic</code>] [<code>--no-compat</code>] [<code>--only=</code><var>test_script</var><code>:</code><var>test_method</var>] [<code>--seed</code> <var>seed</var>] [<code>--trace</code>] [<code>--online</code>] [<code>--official-cmd-taps</code>]</dt><dd><p>Run Homebrew's unit and integration tests.</p></dd>
+<dt><code>update-test</code> [<code>--commit=</code><var>commit</var>] [<code>--before=</code><var>date</var>] [<code>--keep-tmp</code>]</dt><dd><p>Runs a test of <code>brew update</code> with a new repository clone.</p>
 
 <p>If no arguments are passed, use <code>origin/master</code> as the start commit.</p>
 
-<p>If <code>--commit=&lt;commit></code> is passed, use <code>&lt;commit></code> as the start commit.</p>
+<p>If <code>--commit=</code><var>commit</var> is passed, use <var>commit</var> as the start commit.</p>
 
-<p>If <code>--before=&lt;date></code> is passed, use the commit at <code>&lt;date></code> as the
+<p>If <code>--before=</code><var>date</var> is passed, use the commit at <var>date</var> as the
 start commit.</p>
 
-<p>If <code>--to-tag</code> is passed, set HOMEBREW_UPDATE_TO_TAG to test updating
+<p>If <code>--to-tag</code> is passed, set <code>HOMEBREW_UPDATE_TO_TAG</code> to test updating
 between tags.</p>
 
 <p>If <code>--keep-tmp</code> is passed, retain the temporary directory containing
@@ -742,7 +740,7 @@ successful build.</p>
 to insecure HTTP.</p>
 
 <p>While ensuring your downloads are fully secure, this is likely
-to cause from-source Sourceforge, some GNU &amp; GNOME based
+to cause from-source SourceForge, some GNU &amp; GNOME based
 formulae to fail to download.</p></dd>
 <dt><code>HOMEBREW_NO_GITHUB_API</code></dt><dd><p>If set, Homebrew will not use the GitHub API for e.g searches or
 fetching relevant issues on a failed install.</p></dd>
@@ -791,7 +789,7 @@ your shell profile, or you can use it before a brew command:</p>
 
 <p>Homebrew's lead maintainer is Mike McQuaid.</p>
 
-<p>Homebrew's current maintainers are Alyssa Ross, Andrew Janke, Baptiste Fontaine, [Alex Dunn](https://github.</p>
+<p>Homebrew's current maintainers are Alyssa Ross, Andrew Janke, Baptiste Fontaine, Alex Dunn, FX Coudert, ilovezfs, Josh Hagins, JCount, Misty De Meo, Tomasz Pajor, Markus Reiter, Tim Smith, Tom Schoonjans, Uladzislau Shablinski and William Woodruff.</p>
 
 <p>Former maintainers with significant contributions include Xu Cheng, Martin Afanasjew, Dominyk Tiller, Brett Koonce, Jack Nagel, Adam Vandenberg and Homebrew's creator: Max Howell.</p>
 
diff --git a/manpages/brew.1 b/manpages/brew.1
index 5decd142f423e4d1783c5b54bcb57e6052707d31..0899007b58f2ccda090ede26151c320d5025d8e3 100644
--- a/manpages/brew.1
+++ b/manpages/brew.1
@@ -38,7 +38,7 @@ Fetch the newest version of Homebrew from GitHub using \fBgit\fR(1)\.
 List all installed formulae\.
 .
 .TP
-\fBsearch\fR \fItext\fR|\fB/\fR\fItext\fR\fB/\fR
+\fBsearch\fR (\fItext\fR|\fB/\fR\fItext\fR\fB/\fR)
 Perform a substring search of formula names for \fItext\fR\. If \fItext\fR is surrounded with slashes, then it is interpreted as a regular expression\. The search for \fItext\fR is extended online to some popular taps\. If no search term is given, all locally available formulae are listed\.
 .
 .SH "COMMANDS"
@@ -70,7 +70,7 @@ If \fB\-\-prune=\fR\fIdays\fR is specified, remove all cache files older than \f
 If \fB\-\-dry\-run\fR or \fB\-n\fR is passed, show what would be removed, but do not actually remove anything\.
 .
 .IP
-If \fB\-s\fR is passed, scrubs the cache, removing downloads for even the latest versions of formulae\. Note downloads for any installed formulae will still not be deleted\. If you want to delete those too: \fBrm \-rf $(brew \-\-cache)\fR
+If \fB\-s\fR is passed, scrub the cache, removing downloads for even the latest versions of formulae\. Note downloads for any installed formulae will still not be deleted\. If you want to delete those too: \fBrm \-rf $(brew \-\-cache)\fR
 .
 .TP
 \fBcommand\fR \fIcmd\fR
@@ -131,8 +131,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] \fIpattern\fR
-Search both name and description (\fB\-s\fR), just the names (\fB\-n\fR), or just the descriptions (\fB\-d\fR) for \fB<pattern>\fR\. \fB<pattern>\fR is by default interpreted as a literal string; if flanked by slashes, it is instead 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\-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\.
 .
 .TP
 \fBdiy\fR [\fB\-\-name=\fR\fIname\fR] [\fB\-\-version=\fR\fIversion\fR]
@@ -203,7 +203,7 @@ Display information about \fIformula\fR\.
 Open a browser to the GitHub History page for formula \fIformula\fR\.
 .
 .IP
-To view formula history locally: \fBbrew log \-p <formula>\fR\.
+To view formula history locally: \fBbrew log \-p <formula>\fR
 .
 .TP
 \fBinfo\fR \fB\-\-json=\fR\fIversion\fR (\fB\-\-all\fR|\fB\-\-installed\fR|\fIformulae\fR)
@@ -213,7 +213,7 @@ Print a JSON representation of \fIformulae\fR\. Currently the only accepted valu
 Pass \fB\-\-all\fR to get information on all formulae, or \fB\-\-installed\fR to get information on all installed formulae\.
 .
 .IP
-See the docs for examples of using the JSON: \fIhttp://docs\.brew\.sh/Querying\-Brew\.html\fR
+See the docs for examples of using the JSON output: \fIhttp://docs\.brew\.sh/Querying\-Brew\.html\fR
 .
 .TP
 \fBinstall\fR [\fB\-\-debug\fR] [\fB\-\-env=\fR\fIstd\fR|\fIsuper\fR] [\fB\-\-ignore\-dependencies\fR] [\fB\-\-only\-dependencies\fR] [\fB\-\-cc=\fR\fIcompiler\fR] [\fB\-\-build\-from\-source\fR] [\fB\-\-devel\fR|\fB\-\-HEAD\fR] [\fB\-\-keep\-tmp\fR] \fIformula\fR
@@ -352,7 +352,7 @@ If \fB\-\-all\fR is passed, show options for all formulae\.
 If \fB\-\-installed\fR is passed, show options for all installed formulae\.
 .
 .TP
-\fBoutdated\fR [\fB\-\-quiet\fR|\fB\-\-verbose\fR|\fB\-\-json=v1\fR] [\fB\-\-fetch\-HEAD\fR]
+\fBoutdated\fR [\fB\-\-quiet\fR|\fB\-\-verbose\fR|\fB\-\-json=\fR\fIversion\fR] [\fB\-\-fetch\-HEAD\fR]
 Show formulae that have an updated version available\.
 .
 .IP
@@ -394,7 +394,7 @@ Uninstall and then install \fIformula\fR\.
 Display all locally available formulae for brewing (including tapped ones)\. No online search is performed if called without arguments\.
 .
 .TP
-\fBsearch\fR [\fB\-\-desc\fR] \fItext\fR|\fB/\fR\fItext\fR\fB/\fR
+\fBsearch\fR [\fB\-\-desc\fR] (\fItext\fR|\fB/\fR\fItext\fR\fB/\fR)
 Perform a substring search of formula names for \fItext\fR\. If \fItext\fR is surrounded with slashes, then it is interpreted as a regular expression\. The search for \fItext\fR is extended online to some popular taps\.
 .
 .IP
@@ -479,7 +479,7 @@ Print a JSON representation of \fItaps\fR\. Currently the only accepted value fo
 Pass \fB\-\-installed\fR to get information on installed taps\.
 .
 .IP
-See the docs for examples of using the JSON: \fIhttp://docs\.brew\.sh/Querying\-Brew\.html\fR
+See the docs for examples of using the JSON output: \fIhttp://docs\.brew\.sh/Querying\-Brew\.html\fR
 .
 .TP
 \fBtap\-pin\fR \fItap\fR
@@ -501,7 +501,7 @@ If \fB\-\-ignore\-dependencies\fR is passed, uninstalling won\'t fail, even if f
 .
 .TP
 \fBunlink\fR [\fB\-\-dry\-run\fR] \fIformula\fR
-Remove symlinks for \fIformula\fR from the Homebrew prefix\. This can be useful for temporarily disabling a formula: \fBbrew unlink foo && commands && brew link foo\fR\.
+Remove symlinks for \fIformula\fR from the Homebrew prefix\. This can be useful for temporarily disabling a formula: \fBbrew unlink <formula> && <commands> && brew link <formula>\fR
 .
 .IP
 If \fB\-\-dry\-run\fR or \fB\-n\fR is passed, Homebrew will list all files which would be unlinked, but will not actually unlink or delete any files\.
@@ -524,7 +524,7 @@ If \fB\-\-dry\-run\fR or \fB\-n\fR is passed, Homebrew will list all symlinks wh
 .
 .TP
 \fBunpack\fR [\fB\-\-git\fR|\fB\-\-patch\fR] [\fB\-\-destdir=\fR\fIpath\fR] \fIformulae\fR
-Unpack the source files for \fIformulae\fR into subdirectories of the current working directory\. If \fB\-\-destdir=\fR\fIpath\fR is given, the subdirectories will be created in the directory named by \fB<path>\fR instead\.
+Unpack the source files for \fIformulae\fR into subdirectories of the current working directory\. If \fB\-\-destdir=\fR\fIpath\fR is given, the subdirectories will be created in the directory named by \fIpath\fR instead\.
 .
 .IP
 If \fB\-\-patch\fR is passed, patches for \fIformulae\fR will be applied to the unpacked source\.
@@ -580,7 +580,7 @@ If \fB\-\-installed\fR is passed, only list installed formulae\.
 By default, \fBuses\fR shows all formulae that specify \fIformulae\fR as a required or recommended dependency\. To include the \fB:build\fR type dependencies, pass \fB\-\-include\-build\fR\. Similarly, pass \fB\-\-include\-optional\fR to include \fB:optional\fR dependencies\. To skip \fB:recommended\fR type dependencies, pass \fB\-\-skip\-recommended\fR\.
 .
 .IP
-By default, \fBuses\fR shows usages of \fBformula\fR by stable builds\. To find cases where \fBformula\fR is used by development or HEAD build, pass \fB\-\-devel\fR or \fB\-\-HEAD\fR\.
+By default, \fBuses\fR shows usages of \fIformulae\fR by stable builds\. To find cases where \fIformulae\fR is used by development or HEAD build, pass \fB\-\-devel\fR or \fB\-\-HEAD\fR\.
 .
 .TP
 \fB\-\-cache\fR
@@ -653,25 +653,19 @@ If \fB\-\-display\-filename\fR is passed, every line of output is prefixed with
 \fBaudit\fR exits with a non\-zero status if any errors are found\. This is useful, for instance, for implementing pre\-commit hooks\.
 .
 .TP
-\fBbottle\fR [\fB\-\-verbose\fR] [\fB\-\-no\-rebuild\fR] [\fB\-\-keep\-old\fR] [\fB\-\-skip\-relocation\fR] [\fB\-\-root\-url=<root_url>\fR] [\fB\-\-force\-core\-tap\fR]:
+\fBbottle\fR [\fB\-\-verbose\fR] [\fB\-\-no\-rebuild\fR] [\fB\-\-keep\-old\fR] [\fB\-\-skip\-relocation\fR] [\fB\-\-root\-url=\fR\fIURL\fR] [\fB\-\-force\-core\-tap\fR]:
 
 .
 .TP
-\fBbottle\fR \fB\-\-merge\fR [\fB\-\-no\-commit\fR] [\fB\-\-keep\-old\fR] [\fB\-\-write\fR]:
-.
-.IP
+\fBbottle\fR \fB\-\-merge\fR [\fB\-\-no\-commit\fR] [\fB\-\-keep\-old\fR] [\fB\-\-write\fR]
 Generate a bottle (binary package) from a formula installed with \fB\-\-build\-bottle\fR\.
 .
 .TP
-\fBbump\-formula\-pr\fR [\fB\-\-devel\fR] [\fB\-\-dry\-run\fR] [\fB\-\-audit\fR|\fB\-\-strict\fR] [\fB\-\-message=\fR\fImessage\fR] \fB\-\-url=\fR\fIurl\fR \fB\-\-sha256=\fR\fIsha\-256\fR \fIformula\fR:
-
-.
-.TP
-\fBbump\-formula\-pr\fR [\fB\-\-devel\fR] [\fB\-\-dry\-run\fR] [\fB\-\-audit\fR|\fB\-\-strict\fR] [\fB\-\-message=\fR\fImessage\fR] \fB\-\-tag=\fR\fItag\fR \fB\-\-revision=\fR\fIrevision\fR \fIformula\fR
-Creates a pull request to update the formula with a new url or a new tag\.
+\fBbump\-formula\-pr\fR [\fB\-\-devel\fR] [\fB\-\-dry\-run\fR [\fB\-\-write\fR]] [\fB\-\-audit\fR|\fB\-\-strict\fR] [\fB\-\-mirror=\fR\fIURL\fR] [\fB\-\-version=\fR\fIversion\fR] [\fB\-\-message=\fR\fImessage\fR] (\fB\-\-url=\fR\fIURL\fR \fB\-\-sha256=\fR\fIsha\-256\fR|\fB\-\-tag=\fR\fItag\fR \fB\-\-revision=\fR\fIrevision\fR) \fIformula\fR
+Creates a pull request to update the formula with a new URL or a new tag\.
 .
 .IP
-If a \fIurl\fR is specified, the \fIsha\-256\fR checksum of the new download must also be specified\. A best effort to determine the \fIsha\-256\fR and \fIformula\fR name will be made if either or both values are not supplied by the user\.
+If a \fIURL\fR is specified, the \fIsha\-256\fR checksum of the new download must also be specified\. A best effort to determine the \fIsha\-256\fR and \fIformula\fR name will be made if either or both values are not supplied by the user\.
 .
 .IP
 If a \fItag\fR is specified, the git commit \fIrevision\fR corresponding to that tag must also be specified\.
@@ -692,23 +686,20 @@ If \fB\-\-audit\fR is passed, run \fBbrew audit\fR before opening the PR\.
 If \fB\-\-strict\fR is passed, run \fBbrew audit \-\-strict\fR before opening the PR\.
 .
 .IP
-If \fB\-\-mirror=\fR\fIurl\fR is passed, use the value as a mirror url\.
+If \fB\-\-mirror=\fR\fIURL\fR is passed, use the value as a mirror URL\.
 .
 .IP
-If \fB\-\-version=\fR\fIversion\fR is passed, use the value to override the value parsed from the url or tag\. Note that \fB\-\-version=0\fR can be used to delete an existing \fBversion\fR override from a formula if it has become redundant\.
+If \fB\-\-version=\fR\fIversion\fR is passed, use the value to override the value parsed from the URL or tag\. Note that \fB\-\-version=0\fR can be used to delete an existing \fBversion\fR override from a formula if it has become redundant\.
 .
 .IP
 If \fB\-\-message=\fR\fImessage\fR is passed, append \fImessage\fR to the default PR message\.
 .
 .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\.
+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
 \fBcreate\fR \fIURL\fR [\fB\-\-autotools\fR|\fB\-\-cmake\fR|\fB\-\-meson\fR] [\fB\-\-no\-fetch\fR] [\fB\-\-set\-name\fR \fIname\fR] [\fB\-\-set\-version\fR \fIversion\fR] [\fB\-\-tap\fR \fIuser\fR\fB/\fR\fIrepo\fR]
-Generate a formula for the downloadable file at \fIURL\fR and open it in the editor\. Homebrew will attempt to automatically derive the formula name and version, but if it fails, you\'ll have to make your own template\. The \fBwget\fR formula serves as a simple example\. For the complete API have a look at
-.
-.IP
-\fIhttp://www\.rubydoc\.info/github/Homebrew/brew/master/Formula\fR
+Generate a formula for the downloadable file at \fIURL\fR and open it in the editor\. Homebrew will attempt to automatically derive the formula name and version, but if it fails, you\'ll have to make your own template\. The \fBwget\fR formula serves as a simple example\. For the complete API have a look at \fIhttp://www\.rubydoc\.info/github/Homebrew/brew/master/Formula\fR\.
 .
 .IP
 If \fB\-\-autotools\fR is passed, create a basic template for an Autotools\-style build\. If \fB\-\-cmake\fR is passed, create a basic template for a CMake\-style build\. If \fB\-\-meson\fR is passed, create a basic template for a Meson\-style build\.
@@ -732,10 +723,10 @@ Open \fIformula\fR in the editor\.
 .
 .TP
 \fBformula\fR \fIformula\fR
-Display the path where \fIformula\fR is
+Display the path where \fIformula\fR is located\.
 .
 .TP
-\fBlinkage\fR [\fB\-\-test\fR] [\fB\-\-reverse\fR] \fIformula\-name\fR
+\fBlinkage\fR [\fB\-\-test\fR] [\fB\-\-reverse\fR] \fIformula\fR
 Checks the library links of an installed formula\.
 .
 .IP
@@ -754,35 +745,52 @@ Generate Homebrew\'s manpages\.
 .IP
 If \fB\-\-fail\-if\-changed\fR is passed, the command will return a failing status code if changes are detected in the manpage outputs\. This can be used for CI to be notified when the manpages are out of date\. Additionally, the date used in new manpages will match those in the existing manpages (to allow comparison without factoring in the date)\.
 .
-.P
+.TP
 \fBpull\fR [\fB\-\-bottle\fR] [\fB\-\-bump\fR] [\fB\-\-clean\fR] [\fB\-\-ignore\-whitespace\fR] [\fB\-\-resolve\fR] [\fB\-\-branch\-okay\fR] [\fB\-\-no\-pbcopy\fR] [\fB\-\-no\-publish\fR] \fIpatch\-source\fR [\fIpatch\-source\fR]
+Gets a patch from a GitHub commit or pull request and applies it to Homebrew\. Optionally, installs the formulae changed by the patch\.
 .
-.IP "" 4
+.IP
+Each \fIpatch\-source\fR may be one of:
 .
-.nf
-
-Gets a patch from a GitHub commit or pull request and applies it to Homebrew\.
-Optionally, installs the formulae changed by the patch\.
-
-Each <patch\-source> may be one of:
-  * The ID number of a PR (Pull Request) in the homebrew/core GitHub
-    repository
-  * The URL of a PR on GitHub, using either the web page or API URL
-    formats\. In this form, the PR may be on Homebrew/brew,
-    Homebrew/homebrew\-core or any tap\.
-  * The URL of a commit on GitHub
-  * A "http://bot\.brew\.sh/job/\.\.\." string specifying a testing job ID
+.IP
+~ The ID number of a PR (pull request) in the homebrew/core GitHub repository
 .
-.fi
+.IP
+~ The URL of a PR on GitHub, using either the web page or API URL formats\. In this form, the PR may be on Homebrew/brew, Homebrew/homebrew\-core or any tap\.
 .
-.IP "" 0
+.IP
+~ The URL of a commit on GitHub
 .
-.P
-If \fB\-\-bottle\fR was passed, handle bottles, pulling the bottle\-update commit and publishing files on Bintray\. If \fB\-\-bump\fR was passed, for one\-formula PRs, automatically reword commit message to our preferred format\. If \fB\-\-clean\fR was passed, do not rewrite or otherwise modify the commits found in the pulled PR\. If \fB\-\-ignore\-whitespace\fR was passed, silently ignore whitespace discrepancies when applying diffs\. If \fB\-\-resolve\fR was passed, when a patch fails to apply, leave in progress and allow user to resolve, instead of aborting\. If \fB\-\-branch\-okay\fR was passed, do not warn if pulling to a branch besides master (useful for testing)\. If \fB\-\-no\-pbcopy\fR was passed, do not copy anything to the system If \fB\-\-no\-publish\fR was passed, do not publish bottles to Bintray\.
+.IP
+~ A "http://bot\.brew\.sh/job/\.\.\." string specifying a testing job ID
+.
+.IP
+If \fB\-\-bottle\fR is passed, handle bottles, pulling the bottle\-update commit and publishing files on Bintray\.
+.
+.IP
+If \fB\-\-bump\fR is passed, for one\-formula PRs, automatically reword commit message to our preferred format\.
+.
+.IP
+If \fB\-\-clean\fR is passed, do not rewrite or otherwise modify the commits found in the pulled PR\.
+.
+.IP
+If \fB\-\-ignore\-whitespace\fR is passed, silently ignore whitespace discrepancies when applying diffs\.
+.
+.IP
+If \fB\-\-resolve\fR is passed, when a patch fails to apply, leave in progress and allow user to resolve, instead of aborting\.
+.
+.IP
+If \fB\-\-branch\-okay\fR is passed, do not warn if pulling to a branch besides master (useful for testing)\.
+.
+.IP
+If \fB\-\-no\-pbcopy\fR is passed, do not copy anything to the system clipboard\.
+.
+.IP
+If \fB\-\-no\-publish\fR is passed, do not publish bottles to Bintray\.
 .
 .TP
-\fBrelease\-notes\fR [\fIprevious_tag\fR] [\fIend_ref\fR]
-Output the merged pull requests on Homebrew/brew between two Git refs\. If no \fBprevious_tag\fR is provided it defaults to the newest tag\. If no \fBend_ref\fR is provided it defaults to \fBorigin/master\fR\.
+\fBrelease\-notes\fR [\fB\-\-markdown\fR] [\fIprevious_tag\fR] [\fIend_ref\fR]
+Output the merged pull requests on Homebrew/brew between two Git refs\. If no \fIprevious_tag\fR is provided it defaults to the newest tag\. If no \fIend_ref\fR is provided it defaults to \fBorigin/master\fR\.
 .
 .IP
 If \fB\-\-markdown\fR is passed, output as a Markdown list\.
@@ -808,24 +816,24 @@ If \fB\-\-keep\-tmp\fR is passed, the temporary files created for the test are n
 Example: \fBbrew install jruby && brew test jruby\fR
 .
 .TP
-\fBtests\fR [\fB\-v\fR] [\fB\-\-coverage\fR] [\fB\-\-generic\fR] [\fB\-\-no\-compat\fR] [\fB\-\-only=\fR<test_script:test_method>] [\fB\-\-seed\fR \fIseed\fR] [\fB\-\-trace\fR] [\fB\-\-online\fR] [\fB\-\-official\-cmd\-taps\fR]
+\fBtests\fR [\fB\-v\fR] [\fB\-\-coverage\fR] [\fB\-\-generic\fR] [\fB\-\-no\-compat\fR] [\fB\-\-only=\fR\fItest_script\fR\fB:\fR\fItest_method\fR] [\fB\-\-seed\fR \fIseed\fR] [\fB\-\-trace\fR] [\fB\-\-online\fR] [\fB\-\-official\-cmd\-taps\fR]
 Run Homebrew\'s unit and integration tests\.
 .
 .TP
-\fBupdate\-test\fR [\fB\-\-commit=<commit>\fR] [\fB\-\-before=<date>\fR] [\fB\-\-keep\-tmp\fR]
+\fBupdate\-test\fR [\fB\-\-commit=\fR\fIcommit\fR] [\fB\-\-before=\fR\fIdate\fR] [\fB\-\-keep\-tmp\fR]
 Runs a test of \fBbrew update\fR with a new repository clone\.
 .
 .IP
 If no arguments are passed, use \fBorigin/master\fR as the start commit\.
 .
 .IP
-If \fB\-\-commit=<commit>\fR is passed, use \fB<commit>\fR as the start commit\.
+If \fB\-\-commit=\fR\fIcommit\fR is passed, use \fIcommit\fR as the start commit\.
 .
 .IP
-If \fB\-\-before=<date>\fR is passed, use the commit at \fB<date>\fR as the start commit\.
+If \fB\-\-before=\fR\fIdate\fR is passed, use the commit at \fIdate\fR as the start commit\.
 .
 .IP
-If \fB\-\-to\-tag\fR is passed, set HOMEBREW_UPDATE_TO_TAG to test updating between tags\.
+If \fB\-\-to\-tag\fR is passed, set \fBHOMEBREW_UPDATE_TO_TAG\fR to test updating between tags\.
 .
 .IP
 If \fB\-\-keep\-tmp\fR is passed, retain the temporary directory containing the new repository clone\.
@@ -985,7 +993,7 @@ If set, Homebrew will not print the \fBHOMEBREW_INSTALL_BADGE\fR on a successful
 If set, Homebrew will not permit redirects from secure HTTPS to insecure HTTP\.
 .
 .IP
-While ensuring your downloads are fully secure, this is likely to cause from\-source Sourceforge, some GNU & GNOME based formulae to fail to download\.
+While ensuring your downloads are fully secure, this is likely to cause from\-source SourceForge, some GNU & GNOME based formulae to fail to download\.
 .
 .TP
 \fBHOMEBREW_NO_GITHUB_API\fR
@@ -1056,7 +1064,7 @@ Homebrew Documentation: \fIhttps://github\.com/Homebrew/brew/blob/master/docs/\f
 Homebrew\'s lead maintainer is Mike McQuaid\.
 .
 .P
-Homebrew\'s current maintainers are Alyssa Ross, Andrew Janke, Baptiste Fontaine, [Alex Dunn](https://github\.
+Homebrew\'s current maintainers are Alyssa Ross, Andrew Janke, Baptiste Fontaine, Alex Dunn, FX Coudert, ilovezfs, Josh Hagins, JCount, Misty De Meo, Tomasz Pajor, Markus Reiter, Tim Smith, Tom Schoonjans, Uladzislau Shablinski and William Woodruff\.
 .
 .P
 Former maintainers with significant contributions include Xu Cheng, Martin Afanasjew, Dominyk Tiller, Brett Koonce, Jack Nagel, Adam Vandenberg and Homebrew\'s creator: Max Howell\.