cmd: updates for command descriptions

Library/Homebrew/cmd/--env.rb

@@ -11,7 +11,7 @@ module Homebrew
   def __env_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        `--env` [<options>]
+        `--env` [<options>] [<formula>]
 
         Summarise Homebrew's build environment as a plain list.
 

Library/Homebrew/cmd/cat.rb

@@ -18,8 +18,8 @@ module Homebrew
   def cat
     cat_args.parse
     # do not "fix" this to support multiple arguments, the output would be
-    # unparsable, if the user wants to cat multiple formula they can call
-    # brew cat multiple times.
+    # unparsable; if the user wants to cat multiple formula they can call
+    # `brew cat` multiple times.
     formulae = Homebrew.args.formulae
     raise FormulaUnspecifiedError if formulae.empty?
     raise "`brew cat` doesn't support multiple arguments" if args.remaining.size > 1

Library/Homebrew/cmd/cleanup.rb

@@ -21,7 +21,7 @@ module Homebrew
              description: "Show what would be removed, but do not actually remove anything."
       switch "-s",
              description: "Scrub the cache, including downloads for even the latest versions. "\
-                          "Note downloads for any installed formula or cask will still not be deleted. "\
+                          "Note downloads for any installed formulae or casks will still not be deleted. "\
                           "If you want to delete those too: `rm -rf \"$(brew --cache)\"`"
       switch "--prune-prefix",
              description: "Only prune the symlinks and directories from the prefix and remove no other files."

Library/Homebrew/cmd/doctor.rb

@@ -18,7 +18,8 @@ module Homebrew
         an issue; just ignore this.
       EOS
       switch "--list-checks",
-             description: "List all audit methods."
+             description: "List all audit methods, which can be run individually "\
+                          "if provided as arguments."
       switch "-D", "--audit-debug",
              description: "Enable debugging and profiling of audit methods."
       switch :verbose

Library/Homebrew/cmd/outdated.rb

@@ -10,7 +10,7 @@ module Homebrew
   def outdated_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        `outdated` [<options>]
+        `outdated` [<options>] [<formula>]
 
         List installed formulae that have an updated version available. By default, version
         information is displayed in interactive shells, and suppressed otherwise.

Library/Homebrew/cmd/readall.rb

@@ -14,7 +14,7 @@ module Homebrew
         Import all formulae from the specified <tap>, or from all installed taps if none is provided.
         This can be useful for debugging issues across all formulae when making
         significant changes to `formula.rb`, testing the performance of loading
-        all formulae or to determine if any current formulae have Ruby issues.
+        all formulae or checking if any current formulae have Ruby issues.
       EOS
       switch "--aliases",
              description: "Verify any alias symlinks in each tap."

docs/Manpage.md

@@ -67,7 +67,7 @@ this for the given formulae and casks.
 * `-n`, `--dry-run`:
   Show what would be removed, but do not actually remove anything.
 * `-s`:
-  Scrub the cache, including downloads for even the latest versions. Note downloads for any installed formula or cask will still not be deleted. If you want to delete those too: `rm -rf "$(brew --cache)"`
+  Scrub the cache, including downloads for even the latest versions. Note downloads for any installed formulae or casks will still not be deleted. If you want to delete those too: `rm -rf "$(brew --cache)"`
 * `--prune-prefix`:
   Only prune the symlinks and directories from the prefix and remove no other files.
 
@@ -157,7 +157,7 @@ everything you use Homebrew for is working fine: please don't worry or file an
 issue; just ignore this.
 
 * `--list-checks`:
-  List all audit methods.
+  List all audit methods, which can be run individually if provided as arguments.
 * `-D`, `--audit-debug`:
   Enable debugging and profiling of audit methods.
 
@@ -355,7 +355,7 @@ Show install options specific to *`formula`*.
 * `--all`:
   Show options for all available formulae.
 
-### `outdated` [*`options`*]
+### `outdated` [*`options`*] [*`formula`*]
 
 List installed formulae that have an updated version available. By default,
 version information is displayed in interactive shells, and suppressed
@@ -384,7 +384,7 @@ Rerun the post-install steps for *`formula`*.
 Import all formulae from the specified *`tap`*, or from all installed taps if none
 is provided. This can be useful for debugging issues across all formulae when
 making significant changes to `formula.rb`, testing the performance of loading
-all formulae or to determine if any current formulae have Ruby issues.
+all formulae or checking if any current formulae have Ruby issues.
 
 * `--aliases`:
   Verify any alias symlinks in each tap.
@@ -644,7 +644,7 @@ directory doesn't exist, `$(brew --repository)/Cellar`.
 If *`formula`* is provided, display the location in the cellar where *`formula`*
 would be installed, without any sort of versioned directory as the last path.
 
-### `--env` [*`options`*]
+### `--env` [*`options`*] [*`formula`*]
 
 Summarise Homebrew's build environment as a plain list.
 

manpages/brew-cask.1

 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW\-CASK" "1" "November 2019" "Homebrew" "brew-cask"
+.TH "BREW\-CASK" "1" "December 2019" "Homebrew" "brew-cask"
 .
 .SH "NAME"
 \fBbrew\-cask\fR \- a friendly binary installer for macOS

manpages/brew.1

 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW" "1" "November 2019" "Homebrew" "brew"
+.TH "BREW" "1" "December 2019" "Homebrew" "brew"
 .
 .SH "NAME"
 \fBbrew\fR \- The missing package manager for macOS
@@ -63,7 +63,7 @@ Show what would be removed, but do not actually remove anything\.
 .
 .TP
 \fB\-s\fR
-Scrub the cache, including downloads for even the latest versions\. Note downloads for any installed formula or cask will still not be deleted\. If you want to delete those too: \fBrm \-rf "$(brew \-\-cache)"\fR
+Scrub the cache, including downloads for even the latest versions\. Note downloads for any installed formulae or casks will still not be deleted\. If you want to delete those too: \fBrm \-rf "$(brew \-\-cache)"\fR
 .
 .TP
 \fB\-\-prune\-prefix\fR
@@ -176,7 +176,7 @@ Check your system for potential problems\. Will exit with a non\-zero status if
 .
 .TP
 \fB\-\-list\-checks\fR
-List all audit methods\.
+List all audit methods, which can be run individually if provided as arguments\.
 .
 .TP
 \fB\-D\fR, \fB\-\-audit\-debug\fR
@@ -467,7 +467,7 @@ Show options for formulae that are currently installed\.
 \fB\-\-all\fR
 Show options for all available formulae\.
 .
-.SS "\fBoutdated\fR [\fIoptions\fR]"
+.SS "\fBoutdated\fR [\fIoptions\fR] [\fIformula\fR]"
 List installed formulae that have an updated version available\. By default, version information is displayed in interactive shells, and suppressed otherwise\.
 .
 .TP
@@ -493,7 +493,7 @@ Pin the specified \fIformula\fR, preventing them from being upgraded when issuin
 Rerun the post\-install steps for \fIformula\fR\.
 .
 .SS "\fBreadall\fR [\fIoptions\fR] [\fItap\fR]"
-Import all formulae from the specified \fItap\fR, or from all installed taps if none is provided\. This can be useful for debugging issues across all formulae when making significant changes to \fBformula\.rb\fR, testing the performance of loading all formulae or to determine if any current formulae have Ruby issues\.
+Import all formulae from the specified \fItap\fR, or from all installed taps if none is provided\. This can be useful for debugging issues across all formulae when making significant changes to \fBformula\.rb\fR, testing the performance of loading all formulae or checking if any current formulae have Ruby issues\.
 .
 .TP
 \fB\-\-aliases\fR
@@ -812,7 +812,7 @@ Display Homebrew\'s Cellar path\. \fIDefault:\fR \fB$(brew \-\-prefix)/Cellar\fR
 .P
 If \fIformula\fR is provided, display the location in the cellar where \fIformula\fR would be installed, without any sort of versioned directory as the last path\.
 .
-.SS "\fB\-\-env\fR [\fIoptions\fR]"
+.SS "\fB\-\-env\fR [\fIoptions\fR] [\fIformula\fR]"
 Summarise Homebrew\'s build environment as a plain list\.
 .
 .P