Fix minor issues in command help text formatting

- Inconsistent or unneeded indentation
- Missing or superfluous empty lines
- Missing or wrongly formatted arguments in command summary
- Missing punctuation

10 files changed, 61 insertions, 56 deletions

diff --git a/Library/Homebrew/cmd/audit.rb b/Library/Homebrew/cmd/audit.rb
index 464b9c020..0845faeb3 100644
--- a/Library/Homebrew/cmd/audit.rb
+++ b/Library/Homebrew/cmd/audit.rb
@@ -9,11 +9,11 @@
 #:
 #:    If `--online` is passed, additional slower checks that require a network
 #:    connection are run.
-#
+#:
 #:    If `--new-formula` is passed, various additional checks are run that check
 #:    if a new formula is eligable for Homebrew. This should be used when creating
 #:    new formulae and implies `--strict` and `--online`.
-#
+#:
 #:    If `--display-cop-names` is passed, the RuboCop cop name for each violation
 #:    is included in the output.
 #:
diff --git a/Library/Homebrew/cmd/gist-logs.rb b/Library/Homebrew/cmd/gist-logs.rb
index bcb15cd14..2c60129d1 100644
--- a/Library/Homebrew/cmd/gist-logs.rb
+++ b/Library/Homebrew/cmd/gist-logs.rb
@@ -1,13 +1,13 @@
 #:  * `gist-logs` [`--new-issue`|`-n`] <formula>:
-#:     Upload logs for a failed build of <formula> to a new Gist.
+#:    Upload logs for a failed build of <formula> to a new Gist.
 #:
-#:     <formula> is usually the name of the formula to install, but it can be specified
-#:     in several different ways. See [SPECIFYING FORMULAE][].
+#:    <formula> is usually the name of the formula to install, but it can be specified
+#:    in several different ways. See [SPECIFYING FORMULAE][].
 #:
-#:     If `--new-issue` is passed, automatically create a new issue in the appropriate
-#:     GitHub repository as well as creating the Gist.
+#:    If `--new-issue` is passed, automatically create a new issue in the appropriate
+#:    GitHub repository as well as creating the Gist.
 #:
-#:     If no logs are found, an error message is presented.
+#:    If no logs are found, an error message is presented.
 
 require "formula"
 require "system_config"
diff --git a/Library/Homebrew/cmd/list.rb b/Library/Homebrew/cmd/list.rb
index eefad0ac9..80576033a 100644
--- a/Library/Homebrew/cmd/list.rb
+++ b/Library/Homebrew/cmd/list.rb
@@ -1,8 +1,7 @@
 #:  * `list`, `ls` [`--full-name`]:
-#:    List all installed formulae. If `--full-name` is passed, print formulae with
-#:    fully-qualified names.
-#:    If `--full-name` is not passed any other options (e.g. `-t`) are passed to
-#:    `ls` which produces the actual output.
+#:    List all installed formulae. If `--full-name` is passed, print formulae
+#:    with fully-qualified names. If `--full-name` is not passed, any other
+#:    options (e.g. `-t`) are passed to `ls` which produces the actual output.
 #:
 #:  * `list`, `ls` `--unbrewed`:
 #:    List all files in the Homebrew prefix not installed by Homebrew.
diff --git a/Library/Homebrew/cmd/log.rb b/Library/Homebrew/cmd/log.rb
index e2dd08d7c..a07107170 100644
--- a/Library/Homebrew/cmd/log.rb
+++ b/Library/Homebrew/cmd/log.rb
@@ -1,4 +1,4 @@
-#:  * `log` [`git-log-options`] <formula> ...:
+#:  * `log` [<git-log-options>] <formula> ...:
 #:    Show the git log for the given formulae. Options that `git-log`(1)
 #:    recognizes can be passed before the formula list.
 
diff --git a/Library/Homebrew/cmd/missing.rb b/Library/Homebrew/cmd/missing.rb
index 41ad4f16d..181530562 100644
--- a/Library/Homebrew/cmd/missing.rb
+++ b/Library/Homebrew/cmd/missing.rb
@@ -1,7 +1,6 @@
 #:  * `missing` [<formulae>]:
-#:    Check the given <formulae> for missing dependencies.
-#:
-#:    If no <formulae> are given, check all installed brews.
+#:    Check the given <formulae> for missing dependencies. If no <formulae> are
+#:    given, check all installed brews.
 
 require "formula"
 require "tab"
diff --git a/Library/Homebrew/cmd/reinstall.rb b/Library/Homebrew/cmd/reinstall.rb
index a7bbef32d..e98e906f6 100644
--- a/Library/Homebrew/cmd/reinstall.rb
+++ b/Library/Homebrew/cmd/reinstall.rb
@@ -1,5 +1,5 @@
 #:  * `reinstall` <formula>:
-#:    Uninstall then install <formula>
+#:    Uninstall and then install <formula>.
 
 require "formula_installer"
 require "development_tools"
diff --git a/Library/Homebrew/cmd/update.sh b/Library/Homebrew/cmd/update.sh
index ba43fd6d1..dbd1a4de8 100644
--- a/Library/Homebrew/cmd/update.sh
+++ b/Library/Homebrew/cmd/update.sh
@@ -1,11 +1,12 @@
-#:  * `update` [`--merge`]:
+#:  * `update` [`--merge`] [`--force`]:
 #:    Fetch the newest version of Homebrew and all formulae from GitHub using
-#:     `git`(1).
+#:    `git`(1).
 #:
 #:    If `--merge` is specified then `git merge` is used to include updates
-#:      (rather than `git rebase`).
+#:    (rather than `git rebase`).
+#:
 #:    If `--force` is specified then always do a slower, full update check even
-#:      if unnecessary.
+#:    if unnecessary.
 
 # Hide shellcheck complaint:
 # shellcheck source=/dev/null
diff --git a/Library/Homebrew/dev-cmd/bump-formula-pr.rb b/Library/Homebrew/dev-cmd/bump-formula-pr.rb
index bd27a569c..d875e42ac 100644
--- a/Library/Homebrew/dev-cmd/bump-formula-pr.rb
+++ b/Library/Homebrew/dev-cmd/bump-formula-pr.rb
@@ -1,6 +1,5 @@
 #:  * `bump-formula-pr` [`--devel`] [`--dry-run`] `--url=`<url> `--sha256=`<sha-256> <formula>:
 #:  * `bump-formula-pr` [`--devel`] [`--dry-run`] `--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
diff --git a/share/doc/homebrew/brew.1.html b/share/doc/homebrew/brew.1.html
index 07fa7c525..2f4de5906 100644
--- a/share/doc/homebrew/brew.1.html
+++ b/share/doc/homebrew/brew.1.html
@@ -48,11 +48,13 @@ run before submitting a new formula.</p>
 style checks.</p>
 
 <p>If <code>--online</code> is passed, additional slower checks that require a network
-connection are run.
-If <code>--new-formula</code> is passed, various additional checks are run that check
+connection are run.</p>
+
+<p>If <code>--new-formula</code> is passed, various additional checks are run that check
 if a new formula is eligable for Homebrew. This should be used when creating
-new formulae and implies <code>--strict</code> and <code>--online</code>.
-If <code>--display-cop-names</code> is passed, the RuboCop cop name for each violation
+new formulae and implies <code>--strict</code> and <code>--online</code>.</p>
+
+<p>If <code>--display-cop-names</code> is passed, the RuboCop cop name for each violation
 is included in the output.</p>
 
 <p>If <code>--display-filename</code> is passed, every line of output is prefixed with the
@@ -168,15 +170,15 @@ bottle.</p>
 
 <p>If <code>--force-bottle</code> is passed, download a bottle if it exists for the current
 version of OS X, even if it would not be used during installation.</p></dd>
-<dt><code>gist-logs</code> [<code>--new-issue</code>|<code>-n</code>] <var>formula</var></dt><dd><p> Upload logs for a failed build of <var>formula</var> to a new Gist.</p>
+<dt><code>gist-logs</code> [<code>--new-issue</code>|<code>-n</code>] <var>formula</var></dt><dd><p>Upload logs for a failed build of <var>formula</var> to a new Gist.</p>
 
-<p> <var>formula</var> is usually the name of the formula to install, but it can be specified
- in several different ways. See <a href="#SPECIFYING-FORMULAE" title="SPECIFYING FORMULAE" data-bare-link="true">SPECIFYING FORMULAE</a>.</p>
+<p><var>formula</var> is usually the name of the formula to install, but it can be specified
+in several different ways. See <a href="#SPECIFYING-FORMULAE" title="SPECIFYING FORMULAE" data-bare-link="true">SPECIFYING FORMULAE</a>.</p>
 
-<p> If <code>--new-issue</code> is passed, automatically create a new issue in the appropriate
- GitHub repository as well as creating the Gist.</p>
+<p>If <code>--new-issue</code> is passed, automatically create a new issue in the appropriate
+GitHub repository as well as creating the Gist.</p>
 
-<p> If no logs are found, an error message is presented.</p></dd>
+<p>If no logs are found, an error message is presented.</p></dd>
 <dt class="flush"><code>home</code></dt><dd><p>Open Homebrew's own homepage in a browser.</p></dd>
 <dt><code>home</code> <var>formula</var></dt><dd><p>Open <var>formula</var>'s homepage in a browser.</p></dd>
 <dt><code>info</code> <var>formula</var></dt><dd><p>Display information about <var>formula</var>.</p></dd>
@@ -263,10 +265,9 @@ into <code>/Applications</code>, allowing for easier access.</p>
 
 <p>If provided, <code>--local</code> will symlink them into the user's <code>~/Applications</code>
 directory instead of the system directory.</p></dd>
-<dt><code>list</code>, <code>ls</code> [<code>--full-name</code>]</dt><dd><p>List all installed formulae. If <code>--full-name</code> is passed, print formulae with
-fully-qualified names.
-If <code>--full-name</code> is not passed any other options (e.g. <code>-t</code>) are passed to
-<code>ls</code> which produces the actual output.</p></dd>
+<dt><code>list</code>, <code>ls</code> [<code>--full-name</code>]</dt><dd><p>List all installed formulae. If <code>--full-name</code> is passed, print formulae
+with fully-qualified names. If <code>--full-name</code> is not passed, any other
+options (e.g. <code>-t</code>) are passed to <code>ls</code> which produces the actual output.</p></dd>
 <dt><code>list</code>, <code>ls</code> <code>--unbrewed</code></dt><dd><p>List all files in the Homebrew prefix not installed by Homebrew.</p></dd>
 <dt><code>list</code>, <code>ls</code> [<code>--versions</code> [<code>--multiple</code>]] [<code>--pinned</code>] [<var>formulae</var>]</dt><dd><p>List the installed files for <var>formulae</var>. Combined with <code>--verbose</code>, recursively
 list the contents of all subdirectories in each <var>formula</var>'s keg.</p>
@@ -278,16 +279,15 @@ only show formulae with multiple versions installed.</p>
 <p>If <code>--pinned</code> is passed, show the versions of pinned formulae, or only the
 specified (pinned) formulae if <var>formulae</var> are given.
 See also <code>pin</code>, <code>unpin</code>.</p></dd>
-<dt><code>log</code> [<code>git-log-options</code>] <var>formula</var> ...</dt><dd><p>Show the git log for the given formulae. Options that <code>git-log</code>(1)
+<dt><code>log</code> [<var>git-log-options</var>] <var>formula</var> ...</dt><dd><p>Show the git log for the given formulae. Options that <code>git-log</code>(1)
 recognizes can be passed before the formula list.</p></dd>
 <dt><code>migrate</code> [<code>--force</code>] <var>formulae</var></dt><dd><p>Migrate renamed packages to new name, where <var>formulae</var> are old names of
 packages.</p>
 
 <p>If <code>--force</code> is passed, then treat installed <var>formulae</var> and passed <var>formulae</var>
 like if they are from same taps and migrate them anyway.</p></dd>
-<dt><code>missing</code> [<var>formulae</var>]</dt><dd><p>Check the given <var>formulae</var> for missing dependencies.</p>
-
-<p>If no <var>formulae</var> are given, check all installed brews.</p></dd>
+<dt><code>missing</code> [<var>formulae</var>]</dt><dd><p>Check the given <var>formulae</var> for missing dependencies. If no <var>formulae</var> are
+given, check all installed brews.</p></dd>
 <dt><code>options</code> [<code>--compact</code>] (<code>--all</code>|<code>--installed</code>|<var>formulae</var>)</dt><dd><p>Display install options specific to <var>formulae</var>.</p>
 
 <p>If <code>--compact</code> is passed, show all options on a single line separated by
@@ -322,7 +322,7 @@ created by <code>brew linkapps</code>.</p>
 
 <p>If <code>--dry-run</code> or <code>-n</code> is passed, show what would be removed, but do not
 actually remove anything.</p></dd>
-<dt><code>reinstall</code> <var>formula</var></dt><dd><p>Uninstall then install <var>formula</var></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
@@ -438,13 +438,14 @@ source. This is useful for creating patches for the software.</p></dd>
 <dt><code>unpin</code> <var>formulae</var></dt><dd><p>Unpin <var>formulae</var>, allowing them to be upgraded by <code>brew upgrade</code>. See also
 <code>pin</code>.</p></dd>
 <dt><code>untap</code> <var>tap</var></dt><dd><p>Remove a tapped repository.</p></dd>
-<dt><code>update</code> [<code>--merge</code>]</dt><dd><p>Fetch the newest version of Homebrew and all formulae from GitHub using
- <code>git</code>(1).</p>
+<dt><code>update</code> [<code>--merge</code>] [<code>--force</code>]</dt><dd><p>Fetch the newest version of Homebrew and all formulae from GitHub using
+<code>git</code>(1).</p>
 
 <p>If <code>--merge</code> is specified then <code>git merge</code> is used to include updates
-  (rather than <code>git rebase</code>).
-If <code>--force</code> is specified then always do a slower, full update check even
-  if unnecessary.</p></dd>
+(rather than <code>git rebase</code>).</p>
+
+<p>If <code>--force</code> is specified then always do a slower, full update check even
+if unnecessary.</p></dd>
 <dt><code>upgrade</code> [<var>install-options</var>] [<code>--cleanup</code>] [<code>--fetch-HEAD</code>] [<var>formulae</var>]</dt><dd><p>Upgrade outdated, unpinned brews.</p>
 
 <p>Options for the <code>install</code> command are also valid here.</p>
diff --git a/share/man/man1/brew.1 b/share/man/man1/brew.1
index 15d3a9841..66a4736fd 100644
--- a/share/man/man1/brew.1
+++ b/share/man/man1/brew.1
@@ -66,7 +66,13 @@ If no \fIformulae\fR are provided, all of them are checked\.
 If \fB\-\-strict\fR is passed, additional checks are run, including RuboCop style checks\.
 .
 .IP
-If \fB\-\-online\fR is passed, additional slower checks that require a network connection are run\. If \fB\-\-new\-formula\fR is passed, various additional checks are run that check if a new formula is eligable for Homebrew\. This should be used when creating new formulae and implies \fB\-\-strict\fR and \fB\-\-online\fR\. If \fB\-\-display\-cop\-names\fR is passed, the RuboCop cop name for each violation is included in the output\.
+If \fB\-\-online\fR is passed, additional slower checks that require a network connection are run\.
+.
+.IP
+If \fB\-\-new\-formula\fR is passed, various additional checks are run that check if a new formula is eligable for Homebrew\. This should be used when creating new formulae and implies \fB\-\-strict\fR and \fB\-\-online\fR\.
+.
+.IP
+If \fB\-\-display\-cop\-names\fR is passed, the RuboCop cop name for each violation is included in the output\.
 .
 .IP
 If \fB\-\-display\-filename\fR is passed, every line of output is prefixed with the name of the file or formula being audited, to make the output easy to grep\.
@@ -344,7 +350,7 @@ If provided, \fB\-\-local\fR will symlink them into the user\'s \fB~/Application
 .
 .TP
 \fBlist\fR, \fBls\fR [\fB\-\-full\-name\fR]
-List all installed formulae\. If \fB\-\-full\-name\fR is passed, print formulae with fully\-qualified names\. If \fB\-\-full\-name\fR is not passed any other options (e\.g\. \fB\-t\fR) are passed to \fBls\fR which produces the actual output\.
+List all installed formulae\. If \fB\-\-full\-name\fR is passed, print formulae with fully\-qualified names\. If \fB\-\-full\-name\fR is not passed, any other options (e\.g\. \fB\-t\fR) are passed to \fBls\fR which produces the actual output\.
 .
 .TP
 \fBlist\fR, \fBls\fR \fB\-\-unbrewed\fR
@@ -361,7 +367,7 @@ If \fB\-\-versions\fR is passed, show the version number for installed formulae,
 If \fB\-\-pinned\fR is passed, show the versions of pinned formulae, or only the specified (pinned) formulae if \fIformulae\fR are given\. See also \fBpin\fR, \fBunpin\fR\.
 .
 .TP
-\fBlog\fR [\fBgit\-log\-options\fR] \fIformula\fR \.\.\.
+\fBlog\fR [\fIgit\-log\-options\fR] \fIformula\fR \.\.\.
 Show the git log for the given formulae\. Options that \fBgit\-log\fR(1) recognizes can be passed before the formula list\.
 .
 .TP
@@ -373,10 +379,7 @@ If \fB\-\-force\fR is passed, then treat installed \fIformulae\fR and passed \fI
 .
 .TP
 \fBmissing\fR [\fIformulae\fR]
-Check the given \fIformulae\fR for missing dependencies\.
-.
-.IP
-If no \fIformulae\fR are given, check all installed brews\.
+Check the given \fIformulae\fR for missing dependencies\. If no \fIformulae\fR are given, check all installed brews\.
 .
 .TP
 \fBoptions\fR [\fB\-\-compact\fR] (\fB\-\-all\fR|\fB\-\-installed\fR|\fIformulae\fR)
@@ -423,7 +426,7 @@ If \fB\-\-dry\-run\fR or \fB\-n\fR is passed, show what would be removed, but do
 .
 .TP
 \fBreinstall\fR \fIformula\fR
-Uninstall then install \fIformula\fR
+Uninstall and then install \fIformula\fR\.
 .
 .TP
 \fBsearch\fR, \fB\-S\fR
@@ -593,11 +596,14 @@ Unpin \fIformulae\fR, allowing them to be upgraded by \fBbrew upgrade\fR\. See a
 Remove a tapped repository\.
 .
 .TP
-\fBupdate\fR [\fB\-\-merge\fR]
+\fBupdate\fR [\fB\-\-merge\fR] [\fB\-\-force\fR]
 Fetch the newest version of Homebrew and all formulae from GitHub using \fBgit\fR(1)\.
 .
 .IP
-If \fB\-\-merge\fR is specified then \fBgit merge\fR is used to include updates (rather than \fBgit rebase\fR)\. If \fB\-\-force\fR is specified then always do a slower, full update check even if unnecessary\.
+If \fB\-\-merge\fR is specified then \fBgit merge\fR is used to include updates (rather than \fBgit rebase\fR)\.
+.
+.IP
+If \fB\-\-force\fR is specified then always do a slower, full update check even if unnecessary\.
 .
 .TP
 \fBupgrade\fR [\fIinstall\-options\fR] [\fB\-\-cleanup\fR] [\fB\-\-fetch\-HEAD\fR] [\fIformulae\fR]