Update brew's man page formatting and grammar

Also update command specifications to match descriptions.

24 files changed, 172 insertions, 171 deletions

diff --git a/Library/Homebrew/cmd/cleanup.rb b/Library/Homebrew/cmd/cleanup.rb
index 5b46e0872..126309579 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 3ef02288b..53291602e 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 1850ae003..b06d99466 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 9ed7a0f79..a18f4e399 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 7c1a085c9..3591e0c09 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 d69164eb9..e834a00b5 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 b46de30c1..225b70097 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 a105f9c56..3f858b2c4 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 4e6584e70..60d796d9f 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 5f6611dfc..b1122c90a 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 3066d2ee6..7531ef9cf 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 7367e5c37..91bdcba93 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 bfe9c7776..6c7b7d5b5 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 b4cda0fad..9c58dc71a 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 71687dfa7..67d11edce 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 44e0f224e..e4da827f2 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 bd5868726..10811493c 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 919243764..eb398fcfb 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 6276d1c1b..0c8621a01 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 3b8dc11f9..9704426dd 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 a7f099e9d..05fc1cb23 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 195566f37..1175c65f0 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 77a58de7b..ff2d6105c 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 5decd142f..0899007b5 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\.