manpages: fix command & option descriptions

Library/Homebrew/cmd/commands.rb

@@ -10,10 +10,10 @@ module Homebrew
       usage_banner <<~EOS
         `commands` [<options>]
 
-        Show a list of built-in and external commands.
+        Show lists of built-in and external commands.
       EOS
       switch "--quiet",
-             description: "List only the names of commands without the header."
+             description: "List only the names of commands without category headers."
       switch "--include-aliases",
              depends_on:  "--quiet",
              description: "Include the aliases of internal commands."

Library/Homebrew/cmd/config.rb

@@ -11,9 +11,8 @@ module Homebrew
       usage_banner <<~EOS
         `config`
 
-        Show Homebrew and system configuration useful for debugging. If you file
+        Show Homebrew and system configuration info useful for debugging. If you file
-        a bug report, you will likely be asked for this information if you do not
+        a bug report, you will be required to provide this information.
-        provide it.
       EOS
       switch :verbose
       switch :debug

Library/Homebrew/cmd/fetch.rb

@@ -12,7 +12,7 @@ module Homebrew
       usage_banner <<~EOS
         `fetch` [<options>] <formula>
 
-        Download the source packages for the given <formula>.
+        Download a bottle (if available) or source packages for <formula>.
         For tarballs, also print SHA-256 checksums.
       EOS
       switch "--HEAD",
@@ -30,9 +30,9 @@ module Homebrew
       switch "--deps",
              description: "Download dependencies for any listed <formula>."
       switch "-s", "--build-from-source",
-             description: "Download the source for rather than a bottle."
+             description: "Download source packages rather than a bottle."
       switch "--build-bottle",
-             description: "Download the source (for eventual bottling) rather than a bottle."
+             description: "Download source packages (for eventual bottling) rather than a bottle."
       switch "--force-bottle",
              description: "Download a bottle if it exists for the current or newest version of macOS, "\
                           "even if it would not be used during installation."

Library/Homebrew/cmd/install.rb

@@ -18,7 +18,7 @@ module Homebrew
       usage_banner <<~EOS
         `install` [<options>] <formula>
 
-        Install <formula>.
+        Install <formula>. Additional options specific to <formula> may be appended to the command.
 
         Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will be run for the
         installed formulae or, every 30 days, for all formulae.
@@ -42,9 +42,9 @@ module Homebrew
              description: "Attempt to compile using provided <compiler>. <compiler> should be the "\
                           "name of the compiler's executable, for instance `gcc-7` for GCC 7. "\
                           "In order to use LLVM's clang, use `llvm_clang`. To specify the "\
-                          "Apple-provided clang, use `clang`. This parameter will only accept "\
+                          "Apple-provided clang, use `clang`. This option will only accept "\
                           "compilers that are provided by Homebrew or bundled with macOS. "\
-                          "Please do not file issues if you encounter errors while using this flag."
+                          "Please do not file issues if you encounter errors while using this option."
       switch "-s", "--build-from-source",
              description: "Compile the specified <formula> from source even if a bottle is provided. "\
                           "Dependencies will still be installed from bottles if they are available."
@@ -52,7 +52,7 @@ module Homebrew
              description: "Install from a bottle if it exists for the current or newest version of "\
                           "macOS, even if it would not normally be used for installation."
       switch "--include-test",
-             description: "Install testing dependencies required to run `brew test`."
+             description: "Install testing dependencies required to run `brew test` <formula>."
       switch "--devel",
              description: "If <formula> defines it, install the development version."
       switch "--HEAD",
@@ -64,7 +64,8 @@ module Homebrew
       switch "--keep-tmp",
              description: "Don't delete the temporary files created during installation."
       switch "--build-bottle",
-             description: "Prepare the formula for eventual bottling during installation."
+             description: "Prepare the formula for eventual bottling during installation, skipping any "\
+                          "post-install steps."
       flag   "--bottle-arch=",
              depends_on:  "--build-bottle",
              description: "Optimise bottles for the given architecture rather than the oldest "\

Library/Homebrew/cmd/leaves.rb

@@ -12,7 +12,7 @@ module Homebrew
       usage_banner <<~EOS
         `leaves`
 
-        Show installed formulae that are not dependencies of another installed formula.
+        List installed formulae that are not dependencies of another installed formula.
       EOS
       switch :debug
     end

Library/Homebrew/cmd/list.rb

@@ -13,6 +13,8 @@ module Homebrew
         `list`, `ls` [<options>] [<formula>]
 
         List all installed formulae.
+
+        If <formula> is provided, summarize the paths within its current keg.
       EOS
       switch "--full-name",
              description: "Print formulae with fully-qualified names. If `--full-name` is not "\

Library/Homebrew/cmd/log.rb

@@ -11,7 +11,8 @@ module Homebrew
       usage_banner <<~EOS
         `log` [<options>] [<formula>]
 
-        Show the `git log` for the given <formula>.
+        Show the `git log` for <formula>, or show the log for the Homebrew repository
+        if no formula is provided.
       EOS
       switch "-p", "-u", "--patch",
              description: "Also output patch from commit."
@@ -20,7 +21,7 @@ module Homebrew
       switch "--oneline",
              description: "Output only one line per commit."
       flag   "-1", "--max-count",
-             description: "Output only one commit."
+             description: "Print only one or a specified number of commits."
     end
   end
 

Library/Homebrew/cmd/outdated.rb

@@ -12,7 +12,7 @@ module Homebrew
       usage_banner <<~EOS
         `outdated` [<options>]
 
-        Show formulae that have an updated version available.
+        List formulae that have an updated version available.
 
         By default, version information is displayed in interactive shells, and
         suppressed otherwise.

Library/Homebrew/cmd/tap-info.rb

@@ -16,7 +16,7 @@ module Homebrew
       switch "--installed",
              description: "Display information on all installed taps."
       flag   "--json",
-             description: "Print a JSON representation of <taps>. Currently the default and only accepted "\
+             description: "Print a JSON representation of <tap>. Currently the default and only accepted "\
                           "value for <version> is `v1`. See the docs for examples of using the JSON "\
                           "output: <https://docs.brew.sh/Querying-Brew>"
       switch :debug

Library/Homebrew/cmd/untap.rb

@@ -10,7 +10,7 @@ module Homebrew
       usage_banner <<~EOS
         `untap` <tap>
 
-        Remove a tapped repository.
+        Remove a tapped formula repository.
       EOS
       switch :debug
     end

Library/Homebrew/cmd/update-reset.sh

@@ -1,6 +1,8 @@
 #:  * `update-reset` [<repository>]
 #:
-#:  Fetches and resets Homebrew and all tap repositories (or any specified <repository>) using `git`(1) to their latest `origin/master`. Note this will destroy all your uncommitted or committed changes.
+#:  Fetch and reset Homebrew and all tap repositories (or any specified <repository>) using `git`(1) to their latest `origin/master`.
+#:
+#:  *Note:* this will destroy all your uncommitted or committed changes.
 
 homebrew-update-reset() {
   local DIR

Library/Homebrew/dev-cmd/bottle.rb

@@ -64,11 +64,11 @@ module Homebrew
              description: "If the formula specifies a rebuild version, attempt to preserve its value in the "\
                           "generated DSL."
       switch "--json",
-             description: "Write bottle information to a JSON file, which can be used as the argument for "\
+             description: "Write bottle information to a JSON file, which can be used as the value for "\
                           "`--merge`."
       switch "--merge",
              description: "Generate an updated bottle block for a formula and optionally merge it into the "\
-                          "formula file. Instead of a formula name, requires a JSON file generated with "\
+                          "formula file. Instead of a formula name, requires the path to a JSON file generated with "\
                           "`brew bottle --json` <formula>."
       switch "--write",
              depends_on:  "--merge",

Library/Homebrew/dev-cmd/linkage.rb

@@ -12,8 +12,8 @@ module Homebrew
       usage_banner <<~EOS
         `linkage` [<options>] [<formula>]
 
-        Check the library links for kegs of installed formulae.
+        Check the library links from the given <formula> kegs. If no <formula> are
-        Raises an error if run on uninstalled formulae.
+        specified, check all kegs. Raises an error if run on uninstalled formulae.
       EOS
       switch "--test",
              description: "Display only missing libraries and exit with a non-zero status if any missing "\

Library/Homebrew/dev-cmd/update-test.rb

@@ -11,7 +11,7 @@ module Homebrew
         `update-test` [<options>]
 
         Run a test of `brew update` with a new repository clone.
-        If no arguments are passed, use `origin/master` as the start commit.
+        If no options are passed, use `origin/master` as the start commit.
       EOS
       switch "--to-tag",
              description: "Set `HOMEBREW_UPDATE_TO_TAG` to test updating between tags."

Library/Homebrew/manpages/brew.1.md.erb

@@ -26,7 +26,7 @@ didn't include with macOS.
 
 For the full command list, see the [COMMANDS](#commands) section.
 
-With `--verbose` or `-v`, many commands print extra debugging information. Note that
+With `--verbose` or `--debug`, many commands print extra debugging information. Note that
 these flags should only appear after a command.
 
 ### `install` <formula>: