Merge pull request #7393 from EricFromCanada/command-fixes

cmd/dev-cmd: various output fixes

Library/Homebrew/cmd/--cellar.rb

@@ -13,7 +13,7 @@ module Homebrew
         Display Homebrew's Cellar path. *Default:* `$(brew --prefix)/Cellar`, or if
         that directory doesn't exist, `$(brew --repository)/Cellar`.
 
-        If <formula> is provided, display the location in the cellar where <formula>
+        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.
       EOS
     end

Library/Homebrew/cmd/--prefix.rb

@@ -13,7 +13,7 @@ module Homebrew
         Display Homebrew's install path. *Default:* `/usr/local` on macOS and
         `/home/linuxbrew/.linuxbrew` on Linux.
 
-        If <formula> is provided, display the location in the cellar where <formula>
+        If <formula> is provided, display the location in the Cellar where <formula>
         is or would be installed.
       EOS
     end

Library/Homebrew/cmd/analytics.rb

@@ -10,12 +10,17 @@ module Homebrew
       usage_banner <<~EOS
         `analytics` [<subcommand>]
 
-        If `on` or `off` is passed, turn Homebrew's analytics on or off respectively.
+        Control Homebrew's anonymous aggregate user behaviour analytics.
-
-        If `state` is passed, display the current anonymous user behaviour analytics state.
         Read more at <https://docs.brew.sh/Analytics>.
 
-        If `regenerate-uuid` is passed, regenerate the UUID used in Homebrew's analytics.
+        `brew analytics` [`state`]:
+        Display the current state of Homebrew's analytics.
+
+        `brew analytics` [`on`|`off`]:
+        Turn Homebrew's analytics on or off respectively.
+
+        `brew analytics regenerate-uuid`:
+        Regenerate the UUID used for Homebrew's analytics.
       EOS
       switch :verbose
       switch :debug
@@ -41,7 +46,7 @@ module Homebrew
     when "regenerate-uuid"
       Utils::Analytics.regenerate_uuid!
     else
-      raise UsageError, "unknown subcommand"
+      raise UsageError, "unknown subcommand: #{args.named.first}"
     end
   end
 end

Library/Homebrew/cmd/log.rb

@@ -29,7 +29,7 @@ module Homebrew
   def log
     log_args.parse
 
-    # As this command is simplifying user run commands then let's just use a
+    # As this command is simplifying user-run commands then let's just use a
     # user path, too.
     ENV["PATH"] = ENV["HOMEBREW_PATH"]
 

Library/Homebrew/cmd/tap.rb

@@ -8,7 +8,7 @@ module Homebrew
   def tap_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        `tap` [<options>] <user>`/`<repo> [<URL>]
+        `tap` [<options>] [<user>`/`<repo>] [<URL>]
 
         Tap a formula repository.
 
@@ -36,8 +36,7 @@ module Homebrew
              description: "Migrate tapped formulae from symlink-based to directory-based structure."
       switch "--list-pinned",
              description: "List all pinned taps."
-      switch :quiet,
+      switch :quiet
-             description: "Suppress any warnings."
       switch :debug
       max_named 2
     end

Library/Homebrew/cmd/unpin.rb

@@ -16,14 +16,13 @@ module Homebrew
       EOS
       switch :verbose
       switch :debug
+      min_named :formula
     end
   end
 
   def unpin
     unpin_args.parse
 
-    raise FormulaUnspecifiedError if args.no_named?
-
     args.resolved_formulae.each do |f|
       if f.pinned?
         f.unpin

Library/Homebrew/dev-cmd/bump-formula-pr.rb

@@ -109,7 +109,7 @@ module Homebrew
   def bump_formula_pr
     bump_formula_pr_args.parse
 
-    # As this command is simplifying user run commands then let's just use a
+    # As this command is simplifying user-run commands then let's just use a
     # user path, too.
     ENV["PATH"] = ENV["HOMEBREW_PATH"]
 

Library/Homebrew/dev-cmd/bump-revision.rb

@@ -22,21 +22,18 @@ module Homebrew
       switch :quiet
       switch :verbose
       switch :debug
-      max_named 1
+      named :formula
     end
   end
 
   def bump_revision
     bump_revision_args.parse
 
-    # As this command is simplifying user run commands then let's just use a
+    # As this command is simplifying user-run commands then let's just use a
     # user path, too.
     ENV["PATH"] = ENV["HOMEBREW_PATH"]
 
-    formulae = args.formulae
+    formula = args.formulae.first
-    raise FormulaUnspecifiedError if formulae.empty?
-
-    formula = formulae.first
     current_revision = formula.revision
 
     if current_revision.zero?

Library/Homebrew/dev-cmd/mirror.rb

@@ -10,7 +10,7 @@ module Homebrew
       usage_banner <<~EOS
         `mirror` <formula>
 
-        Reuploads the stable URL for a formula to Bintray to use it as a mirror.
+        Reupload the stable URL of a formula to Bintray for use as a mirror.
       EOS
       switch :verbose
       switch :debug

Library/Homebrew/dev-cmd/pr-automerge.rb

@@ -11,20 +11,21 @@ module Homebrew
       usage_banner <<~EOS
         `pr-automerge` [<options>]
 
-        Finds pull requests that can be automatically merged using `brew pr-publish`.
+        Find pull requests that can be automatically merged using `brew pr-publish`.
       EOS
-      flag "--tap=",
+      flag   "--tap=",
-           description: "Target repository tap (default: `homebrew/core`)"
+             description: "Target tap repository (default: `homebrew/core`)."
-      flag "--with-label=",
+      flag   "--with-label=",
-           description: "Pull requests must have this label (default: `ready to merge`)"
+             description: "Pull requests must have this label (default: `ready to merge`)."
       comma_array "--without-labels=",
-                  description: "Pull requests must not have these labels (default: `do not merge`, `new formula`)"
+                  description: "Pull requests must not have these labels (default: `do not merge`, `new formula`)."
       switch "--publish",
              description: "Run `brew pr-publish` on matching pull requests."
       switch "--ignore-failures",
              description: "Include pull requests that have failing status checks."
-      switch :debug
       switch :verbose
+      switch :debug
+      max_named 0
     end
   end
 
@@ -57,8 +58,7 @@ module Homebrew
     if args.publish?
       safe_system "#{HOMEBREW_PREFIX}/bin/brew", "pr-publish", *pr_urls
     else
-      ohai "Now run:"
+      ohai "Now run:", "  brew pr-publish \\\n    #{pr_urls.join " \\\n    "}"
-      puts "  brew pr-publish \\\n    #{pr_urls.join " \\\n    "}"
     end
   end
 end

Library/Homebrew/dev-cmd/pr-publish.rb

@@ -11,10 +11,11 @@ module Homebrew
       usage_banner <<~EOS
         `pr-publish` [<options>] <pull_request> [<pull_request> ...]
 
-        Publishes bottles for a pull request with GitHub Actions.
+        Publish bottles for a pull request with GitHub Actions.
-        Requires write access to the repository.
+        Requires write access to the `homebrew/core` repository.
       EOS
       switch :verbose
+      min_named 1
     end
   end
 
@@ -23,8 +24,6 @@ module Homebrew
 
     ENV["HOMEBREW_FORCE_HOMEBREW_ON_LINUX"] = "1" unless OS.mac?
 
-    odie "You need to specify at least one pull request number!" if Homebrew.args.named.empty?
-
     args.named.uniq.each do |arg|
       arg = "#{CoreTap.instance.default_remote}/pull/#{arg}" if arg.to_i.positive?
       url_match = arg.match HOMEBREW_PULL_OR_COMMIT_URL_REGEX

Library/Homebrew/dev-cmd/pr-pull.rb

@@ -15,32 +15,32 @@ module Homebrew
         `pr-pull` [<options>] <pull_request> [<pull_request> ...]
 
         Download and publish bottles, and apply the bottle commit from a
-        pull request with artifacts generated from GitHub Actions.
+        pull request with artifacts generated by GitHub Actions.
         Requires write access to the repository.
       EOS
       switch "--no-publish",
-             description: "Download the bottles, apply the bottle commit, and "\
+             description: "Download the bottles, apply the bottle commit and "\
                           "upload the bottles to Bintray, but don't publish them."
       switch "--no-upload",
              description: "Download the bottles and apply the bottle commit, "\
                           "but don't upload to Bintray."
-      switch "--dry-run", "-n",
+      switch "-n", "--dry-run",
              description: "Print what would be done rather than doing it."
       switch "--clean",
              description: "Do not amend the commits from pull requests."
       switch "--branch-okay",
              description: "Do not warn if pulling to a branch besides master (useful for testing)."
       switch "--resolve",
-             description: "When a patch fails to apply, leave in progress and allow user to resolve, instead "\
+             description: "When a patch fails to apply, leave in progress and allow user to resolve, "\
-                          "of aborting."
+                          "instead of aborting."
-      flag "--workflow=",
+      flag   "--workflow=",
-           description: "Retrieve artifacts from the specified workflow (default: tests.yml)."
+             description: "Retrieve artifacts from the specified workflow (default: tests.yml)."
-      flag "--artifact=",
+      flag   "--artifact=",
-           description: "Download artifacts with the specified name (default: bottles)."
+             description: "Download artifacts with the specified name (default: bottles)."
-      flag "--bintray-org=",
+      flag   "--bintray-org=",
-           description: "Upload to the specified Bintray organisation (default: homebrew)."
+             description: "Upload to the specified Bintray organisation (default: homebrew)."
-      flag "--tap=",
+      flag   "--tap=",
-           description: "Target repository tap (default: homebrew/core)."
+             description: "Target tap repository (default: homebrew/core)."
       switch :verbose
       switch :debug
       min_named 1

Library/Homebrew/dev-cmd/prof.rb

@@ -12,6 +12,7 @@ module Homebrew
 
         Run Homebrew with the Ruby profiler, e.g. `brew prof readall`.
       EOS
+      min_named 1
     end
   end
 

Library/Homebrew/dev-cmd/pull.rb

@@ -22,8 +22,8 @@ module Homebrew
         Get a patch from a GitHub commit or pull request and apply it to Homebrew.
         Optionally, publish updated bottles for any formulae changed by the patch.
 
-        Each <patch> may be the number of a pull request in `homebrew/core`, the URL of any pull request
+        Each <patch> may be the number of a pull request in `homebrew/core`
-        or commit on GitHub.
+        or the URL of any pull request or commit on GitHub.
       EOS
       switch "--bump",
              description: "For one-formula PRs, automatically reword commit message to our preferred format."

Library/Homebrew/dev-cmd/unpack.rb

@@ -26,6 +26,7 @@ module Homebrew
       switch :verbose
       switch :debug
       conflicts "--git", "--patch"
+      min_named :formula
     end
   end
 
@@ -33,7 +34,6 @@ module Homebrew
     unpack_args.parse
 
     formulae = args.formulae
-    raise FormulaUnspecifiedError if formulae.empty?
 
     if dir = args.destdir
       unpack_dir = Pathname.new(dir).expand_path

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

@@ -65,7 +65,7 @@ If no search term is provided, all locally available formulae are listed.
 
 ## OFFICIAL EXTERNAL COMMANDS
 
-### `cask` <subcommand>:
+### `cask` <subcommand>
 
 Install macOS applications distributed as binaries. See `brew-cask`(1).
 

Library/Homebrew/test/cask/cmd/upgrade_spec.rb

@@ -167,33 +167,6 @@ describe Cask::Cmd::Upgrade, :cask do
         expect(local_transmission.versions).to include("2.60")
         expect(local_transmission.versions).not_to include("2.61")
       end
-
-      it 'would update "auto_updates" and "latest" Casks when their tokens are provided in the command line' do
-        local_caffeine = Cask::CaskLoader.load("local-caffeine")
-        local_caffeine_path = Cask::Config.global.appdir.join("Caffeine.app")
-        auto_updates = Cask::CaskLoader.load("auto-updates")
-        auto_updates_path = Cask::Config.global.appdir.join("MyFancyApp.app")
-
-        expect(local_caffeine).to be_installed
-        expect(local_caffeine_path).to be_a_directory
-        expect(local_caffeine.versions).to include("1.2.2")
-
-        expect(auto_updates).to be_installed
-        expect(auto_updates_path).to be_a_directory
-        expect(auto_updates.versions).to include("2.57")
-
-        described_class.run("--dry-run", "local-caffeine", "auto-updates")
-
-        expect(local_caffeine).to be_installed
-        expect(local_caffeine_path).to be_a_directory
-        expect(local_caffeine.versions).to include("1.2.2")
-        expect(local_caffeine.versions).not_to include("1.2.3")
-
-        expect(auto_updates).to be_installed
-        expect(auto_updates_path).to be_a_directory
-        expect(auto_updates.versions).to include("2.57")
-        expect(auto_updates.versions).not_to include("2.61")
-      end
     end
 
     describe "with --greedy it checks additional Casks" do

Library/Homebrew/utils/formatter.rb

@@ -36,15 +36,17 @@ module Formatter
   # Wraps text to fit within a given number of columns using regular expressions that:
   #
   # 1. convert hard-wrapped paragraphs to a single line
-  # 2. find any option descriptions longer than a pre-set length and wrap between words
+  # 2. add line break and indent to subcommand descriptions
+  # 3. find any option descriptions longer than a pre-set length and wrap between words
   #    with a hanging indent, without breaking any words that overflow
-  # 3. wrap any remaining description lines that need wrapping with the same indent
+  # 4. wrap any remaining description lines that need wrapping with the same indent
-  # 4. wrap all lines to the given width.
+  # 5. wrap all lines to the given width.
   # @see https://macromates.com/blog/2006/wrapping-text-with-regular-expressions/
   def wrap(s, width = 172)
     desc = OPTION_DESC_WIDTH
     indent = width - desc
     s.gsub(/(?<=\S) *\n(?=\S)/, " ")
+     .gsub(/([`>)\]]:) /, "\\1\n    ")
      .gsub(/^( +-.+  +(?=\S.{#{desc}}))(.{1,#{desc}})( +|$)\n?/, "\\1\\2\n" + " " * indent)
      .gsub(/^( {#{indent}}(?=\S.{#{desc}}))(.{1,#{desc}})( +|$)\n?/, "\\1\\2\n" + " " * indent)
      .gsub(/(.{1,#{width}})( +|$)\n?/, "\\1\n")

docs/Manpage.md

@@ -44,13 +44,17 @@ If no search term is provided, all locally available formulae are listed.
 
 ### `analytics` [*`subcommand`*]
 
-If `on` or `off` is passed, turn Homebrew's analytics on or off respectively.
+Control Homebrew's anonymous aggregate user behaviour analytics. Read more at
+<https://docs.brew.sh/Analytics>.
 
-If `state` is passed, display the current anonymous user behaviour analytics
+`brew analytics` [`state`]:
-state. Read more at <https://docs.brew.sh/Analytics>.
+    Display the current state of Homebrew's analytics.
 
-If `regenerate-uuid` is passed, regenerate the UUID used in Homebrew's
+`brew analytics` [`on`|`off`]:
-analytics.
+    Turn Homebrew's analytics on or off respectively.
+
+`brew analytics regenerate-uuid`:
+    Regenerate the UUID used for Homebrew's analytics.
 
 ### `cleanup` [*`options`*] [*`formula`*|*`cask`*]
 
@@ -437,7 +441,7 @@ Consider adding evaluation of this command's output to your dotfiles (e.g. `~/.p
 Symlink all of the specified *`version`* of *`formula`*'s installation into
 Homebrew's prefix.
 
-### `tap` [*`options`*] *`user`*`/`*`repo`* [*`URL`*]
+### `tap` [*`options`*] [*`user`*`/`*`repo`*] [*`URL`*]
 
 Tap a formula repository.
 
@@ -588,7 +592,7 @@ If *`formula`* is provided, display the file or directory used to cache *`formul
 Display Homebrew's Cellar path. *Default:* `$(brew --prefix)/Cellar`, or if that
 directory doesn't exist, `$(brew --repository)/Cellar`.
 
-If *`formula`* is provided, display the location in the cellar where *`formula`*
+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`*] [*`formula`*]
@@ -608,7 +612,7 @@ list is formatted for export to `bash`(1) unless `--plain` is passed.
 Display Homebrew's install path. *Default:* `/usr/local` on macOS and
 `/home/linuxbrew/.linuxbrew` on Linux.
 
-If *`formula`* is provided, display the location in the cellar where *`formula`* is
+If *`formula`* is provided, display the location in the Cellar where *`formula`* is
 or would be installed.
 
 ### `--repository`, `--repo` [*`user`*`/`*`repo`*]
@@ -848,14 +852,14 @@ Generate Homebrew's manpages.
 
 ### `pr-automerge` [*`options`*]
 
-Finds pull requests that can be automatically merged using `brew pr-publish`.
+Find pull requests that can be automatically merged using `brew pr-publish`.
 
 * `--tap`:
-  Target repository tap (default: `homebrew/core`)
+  Target tap repository (default: `homebrew/core`).
 * `--with-label`:
-  Pull requests must have this label (default: `ready to merge`)
+  Pull requests must have this label (default: `ready to merge`).
 * `--without-labels`:
-  Pull requests must not have these labels (default: `do not merge`, `new formula`)
+  Pull requests must not have these labels (default: `do not merge`, `new formula`).
 * `--publish`:
   Run `brew pr-publish` on matching pull requests.
 * `--ignore-failures`:
@@ -863,17 +867,17 @@ Finds pull requests that can be automatically merged using `brew pr-publish`.
 
 ### `pr-publish` [*`options`*] *`pull_request`* [*`pull_request`* ...]
 
-Publishes bottles for a pull request with GitHub Actions. Requires write access
+Publish bottles for a pull request with GitHub Actions. Requires write access to
-to the repository.
+the `homebrew/core` repository.
 
 ### `pr-pull` [*`options`*] *`pull_request`* [*`pull_request`* ...]
 
 Download and publish bottles, and apply the bottle commit from a pull request
-with artifacts generated from GitHub Actions. Requires write access to the
+with artifacts generated by GitHub Actions. Requires write access to the
 repository.
 
 * `--no-publish`:
-  Download the bottles, apply the bottle commit, and upload the bottles to Bintray, but don't publish them.
+  Download the bottles, apply the bottle commit and upload the bottles to Bintray, but don't publish them.
 * `--no-upload`:
   Download the bottles and apply the bottle commit, but don't upload to Bintray.
 * `-n`, `--dry-run`:
@@ -891,7 +895,7 @@ repository.
 * `--bintray-org`:
   Upload to the specified Bintray organisation (default: homebrew).
 * `--tap`:
-  Target repository tap (default: homebrew/core).
+  Target tap repository (default: homebrew/core).
 
 ### `prof` *`command`*
 
@@ -902,8 +906,8 @@ Run Homebrew with the Ruby profiler, e.g. `brew prof readall`.
 Get a patch from a GitHub commit or pull request and apply it to Homebrew.
 Optionally, publish updated bottles for any formulae changed by the patch.
 
-Each *`patch`* may be the number of a pull request in `homebrew/core`, the URL of
+Each *`patch`* may be the number of a pull request in `homebrew/core` or the URL
-any pull request or commit on GitHub.
+of any pull request or commit on GitHub.
 
 * `--bump`:
   For one-formula PRs, automatically reword commit message to our preferred format.
@@ -1049,52 +1053,46 @@ These options are applicable across multiple subcommands.
 
 ## OFFICIAL EXTERNAL COMMANDS
 
-### `cask` *`subcommand`*:
+### `cask` *`subcommand`*
 
 Install macOS applications distributed as binaries. See `brew-cask`(1).
 
 **Homebrew/homebrew-cask**: <https://github.com/Homebrew/homebrew-cask>
 
-### `bundle` *`subcommand`*
+### `bundle` [*`subcommand`*]
 
 Bundler for non-Ruby dependencies from Homebrew, Homebrew Cask, Mac App Store
 and Whalebrew.
 
-`brew bundle` [`install`]
+`brew bundle` [`install`]:
+    Install or upgrade all dependencies in a `Brewfile`.
 
-Install or upgrade all dependencies in a `Brewfile`.
+`brew bundle dump`:
+    Write all installed casks/formulae/images/taps into a `Brewfile`.
 
-`brew bundle dump`
+`brew bundle cleanup`:
+    Uninstall all dependencies not listed in a `Brewfile`.
 
-Write all installed casks/formulae/images/taps into a `Brewfile`.
+`brew bundle check`:
+    Check if all dependencies are installed in a `Brewfile`.
 
-`brew bundle cleanup`
+`brew bundle exec` *`command`*:
+    Run an external command in an isolated build environment.
 
-Uninstall all dependencies not listed in a `Brewfile`.
+`brew bundle list`:
-
+    List all dependencies present in a `Brewfile`. By default, only Homebrew
-`brew bundle check`
-
-Check if all dependencies are installed in a `Brewfile`.
-
-`brew bundle exec` *`command`*
-
-Run an external command in an isolated build environment.
-
-`brew bundle list`
-
-List all dependencies present in a Brewfile. By default, only Homebrew
 dependencies are listed.
 
 * `--file`:
-  Read the `Brewfile` from this file. Use `--file=-` to pipe to stdin/stdout.
+  Read the `Brewfile` from this location. Use `--file=-` to pipe to stdin/stdout.
 * `--global`:
   Read the `Brewfile` from `~/.Brewfile`.
 * `-v`, `--verbose`:
-  `install` output is printed from commands as they are run. `check` prints all missing dependencies.
+  `install` prints output from commands as they are run. `check` lists all missing dependencies.
 * `--no-upgrade`:
   `install` won't run `brew upgrade` on outdated dependencies. Note they may still be upgraded by `brew install` if needed.
 * `-f`, `--force`:
-  `dump` overwrites an existing `Brewfile`. `cleanup` actually perform the cleanup operations.
+  `dump` overwrites an existing `Brewfile`. `cleanup` actually performs its cleanup operations.
 * `--no-lock`:
   `install` won't output a `Brewfile.lock.json`.
 * `--all`:
@@ -1110,39 +1108,39 @@ dependencies are listed.
 * `--whalebrew`:
   `list` Whalebrew dependencies.
 * `--describe`:
-  `dump` a description comment above each line, unless the dependency does not have a description.
+  `dump` adds a description comment above each line, unless the dependency does not have a description.
 * `--no-restart`:
   `dump` does not add `restart_service` to formula lines.
 * `--zap`:
   `cleanup` casks using the `zap` command instead of `uninstall`.
 
-### `services` *`subcommand`*
+### `services` [*`subcommand`*]
 
 Manage background services with macOS' `launchctl`(1) daemon manager.
 
 If `sudo` is passed, operate on `/Library/LaunchDaemons` (started at boot).
 Otherwise, operate on `~/Library/LaunchAgents` (started at login).
 
-[`sudo`] `brew services` [`list`]
+[`sudo`] `brew services` [`list`]:
-  List all running services for the current user (or root).
+    List all running services for the current user (or root).
 
-[`sudo`] `brew services run` (*`formula`*|`--all`)
+[`sudo`] `brew services run` (*`formula`*|`--all`):
-  Run the service *`formula`* without registering to launch at login (or boot).
+    Run the service *`formula`* without registering to launch at login (or boot).
 
-[`sudo`] `brew services start` (*`formula`*|`--all`)
+[`sudo`] `brew services start` (*`formula`*|`--all`):
-  Start the service *`formula`* immediately and register it to launch at login (or
+    Start the service *`formula`* immediately and register it to launch at login
-boot).
+(or boot).
 
-[`sudo`] `brew services stop` (*`formula`*|`--all`)
+[`sudo`] `brew services stop` (*`formula`*|`--all`):
-  Stop the service *`formula`* immediately and unregister it from launching at
+    Stop the service *`formula`* immediately and unregister it from launching at
 login (or boot).
 
-[`sudo`] `brew services restart` (*`formula`*|`--all`)
+[`sudo`] `brew services restart` (*`formula`*|`--all`):
-  Stop (if necessary) and start the service *`formula`* immediately and register
+    Stop (if necessary) and start the service *`formula`* immediately and register
 it to launch at login (or boot).
 
-[`sudo`] `brew services cleanup`
+[`sudo`] `brew services cleanup`:
-  Remove all unused services.
+    Remove all unused services.
 
 * `--all`:
   Run *`subcommand`* on all services.

manpages/brew.1

@@ -39,13 +39,19 @@ Perform a substring search of cask tokens and formula names for \fItext\fR\. If
 .SH "COMMANDS"
 .
 .SS "\fBanalytics\fR [\fIsubcommand\fR]"
-If \fBon\fR or \fBoff\fR is passed, turn Homebrew\'s analytics on or off respectively\.
+Control Homebrew\'s anonymous aggregate user behaviour analytics\. Read more at \fIhttps://docs\.brew\.sh/Analytics\fR\.
 .
 .P
-If \fBstate\fR is passed, display the current anonymous user behaviour analytics state\. Read more at \fIhttps://docs\.brew\.sh/Analytics\fR\.
+\fBbrew analytics\fR [\fBstate\fR]
+    Display the current state of Homebrew\'s analytics\.
 .
 .P
-If \fBregenerate\-uuid\fR is passed, regenerate the UUID used in Homebrew\'s analytics\.
+\fBbrew analytics\fR [\fBon\fR|\fBoff\fR]
+    Turn Homebrew\'s analytics on or off respectively\.
+.
+.P
+\fBbrew analytics regenerate\-uuid\fR
+    Regenerate the UUID used for Homebrew\'s analytics\.
 .
 .SS "\fBcleanup\fR [\fIoptions\fR] [\fIformula\fR|\fIcask\fR]"
 Remove stale lock files and outdated downloads for all formulae and casks, and remove old versions of installed formulae\. If arguments are specified, only do this for the given formulae and casks\.
@@ -575,7 +581,7 @@ The variables \fBHOMEBREW_PREFIX\fR, \fBHOMEBREW_CELLAR\fR and \fBHOMEBREW_REPOS
 .SS "\fBswitch\fR \fIformula\fR \fIversion\fR"
 Symlink all of the specified \fIversion\fR of \fIformula\fR\'s installation into Homebrew\'s prefix\.
 .
-.SS "\fBtap\fR [\fIoptions\fR] \fIuser\fR\fB/\fR\fIrepo\fR [\fIURL\fR]"
+.SS "\fBtap\fR [\fIoptions\fR] [\fIuser\fR\fB/\fR\fIrepo\fR] [\fIURL\fR]"
 Tap a formula repository\.
 .
 .P
@@ -761,7 +767,7 @@ Show the cache file used when pouring a bottle\.
 Display Homebrew\'s Cellar path\. \fIDefault:\fR \fB$(brew \-\-prefix)/Cellar\fR, or if that directory doesn\'t exist, \fB$(brew \-\-repository)/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\.
+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] [\fIformula\fR]"
 Summarise Homebrew\'s build environment as a plain list\.
@@ -781,7 +787,7 @@ Generate plain output even when piped\.
 Display Homebrew\'s install path\. \fIDefault:\fR \fB/usr/local\fR on macOS and \fB/home/linuxbrew/\.linuxbrew\fR on Linux\.
 .
 .P
-If \fIformula\fR is provided, display the location in the cellar where \fIformula\fR is or would be installed\.
+If \fIformula\fR is provided, display the location in the Cellar where \fIformula\fR is or would be installed\.
 .
 .SS "\fB\-\-repository\fR, \fB\-\-repo\fR [\fIuser\fR\fB/\fR\fIrepo\fR]"
 Display where Homebrew\'s \fB\.git\fR directory is located\.
@@ -1089,19 +1095,19 @@ Return a failing status code if changes are detected in the manpage outputs\. Th
 This is now done automatically by \fBbrew update\fR\.
 .
 .SS "\fBpr\-automerge\fR [\fIoptions\fR]"
-Finds pull requests that can be automatically merged using \fBbrew pr\-publish\fR\.
+Find pull requests that can be automatically merged using \fBbrew pr\-publish\fR\.
 .
 .TP
 \fB\-\-tap\fR
-Target repository tap (default: \fBhomebrew/core\fR)
+Target tap repository (default: \fBhomebrew/core\fR)\.
 .
 .TP
 \fB\-\-with\-label\fR
-Pull requests must have this label (default: \fBready to merge\fR)
+Pull requests must have this label (default: \fBready to merge\fR)\.
 .
 .TP
 \fB\-\-without\-labels\fR
-Pull requests must not have these labels (default: \fBdo not merge\fR, \fBnew formula\fR)
+Pull requests must not have these labels (default: \fBdo not merge\fR, \fBnew formula\fR)\.
 .
 .TP
 \fB\-\-publish\fR
@@ -1112,14 +1118,14 @@ Run \fBbrew pr\-publish\fR on matching pull requests\.
 Include pull requests that have failing status checks\.
 .
 .SS "\fBpr\-publish\fR [\fIoptions\fR] \fIpull_request\fR [\fIpull_request\fR \.\.\.]"
-Publishes bottles for a pull request with GitHub Actions\. Requires write access to the repository\.
+Publish bottles for a pull request with GitHub Actions\. Requires write access to the \fBhomebrew/core\fR repository\.
 .
 .SS "\fBpr\-pull\fR [\fIoptions\fR] \fIpull_request\fR [\fIpull_request\fR \.\.\.]"
-Download and publish bottles, and apply the bottle commit from a pull request with artifacts generated from GitHub Actions\. Requires write access to the repository\.
+Download and publish bottles, and apply the bottle commit from a pull request with artifacts generated by GitHub Actions\. Requires write access to the repository\.
 .
 .TP
 \fB\-\-no\-publish\fR
-Download the bottles, apply the bottle commit, and upload the bottles to Bintray, but don\'t publish them\.
+Download the bottles, apply the bottle commit and upload the bottles to Bintray, but don\'t publish them\.
 .
 .TP
 \fB\-\-no\-upload\fR
@@ -1155,7 +1161,7 @@ Upload to the specified Bintray organisation (default: homebrew)\.
 .
 .TP
 \fB\-\-tap\fR
-Target repository tap (default: homebrew/core)\.
+Target tap repository (default: homebrew/core)\.
 .
 .SS "\fBprof\fR \fIcommand\fR"
 Run Homebrew with the Ruby profiler, e\.g\. \fBbrew prof readall\fR\.
@@ -1164,7 +1170,7 @@ Run Homebrew with the Ruby profiler, e\.g\. \fBbrew prof readall\fR\.
 Get a patch from a GitHub commit or pull request and apply it to Homebrew\. Optionally, publish updated bottles for any formulae changed by the patch\.
 .
 .P
-Each \fIpatch\fR may be the number of a pull request in \fBhomebrew/core\fR, the URL of any pull request or commit on GitHub\.
+Each \fIpatch\fR may be the number of a pull request in \fBhomebrew/core\fR or the URL of any pull request or commit on GitHub\.
 .
 .TP
 \fB\-\-bump\fR
@@ -1343,55 +1349,43 @@ Override warnings and enable potentially unsafe operations\.
 .
 .SH "OFFICIAL EXTERNAL COMMANDS"
 .
-.SS "\fBcask\fR \fIsubcommand\fR:"
+.SS "\fBcask\fR \fIsubcommand\fR"
 Install macOS applications distributed as binaries\. See \fBbrew\-cask\fR(1)\.
 .
 .P
 \fBHomebrew/homebrew\-cask\fR
     \fIhttps://github\.com/Homebrew/homebrew\-cask\fR
 .
-.SS "\fBbundle\fR \fIsubcommand\fR"
+.SS "\fBbundle\fR [\fIsubcommand\fR]"
 Bundler for non\-Ruby dependencies from Homebrew, Homebrew Cask, Mac App Store and Whalebrew\.
 .
 .P
 \fBbrew bundle\fR [\fBinstall\fR]
-.
+    Install or upgrade all dependencies in a \fBBrewfile\fR\.
-.P
-Install or upgrade all dependencies in a \fBBrewfile\fR\.
 .
 .P
 \fBbrew bundle dump\fR
-.
+    Write all installed casks/formulae/images/taps into a \fBBrewfile\fR\.
-.P
-Write all installed casks/formulae/images/taps into a \fBBrewfile\fR\.
 .
 .P
 \fBbrew bundle cleanup\fR
-.
+    Uninstall all dependencies not listed in a \fBBrewfile\fR\.
-.P
-Uninstall all dependencies not listed in a \fBBrewfile\fR\.
 .
 .P
 \fBbrew bundle check\fR
-.
+    Check if all dependencies are installed in a \fBBrewfile\fR\.
-.P
-Check if all dependencies are installed in a \fBBrewfile\fR\.
 .
 .P
 \fBbrew bundle exec\fR \fIcommand\fR
-.
+    Run an external command in an isolated build environment\.
-.P
-Run an external command in an isolated build environment\.
 .
 .P
 \fBbrew bundle list\fR
-.
+    List all dependencies present in a \fBBrewfile\fR\. By default, only Homebrew dependencies are listed\.
-.P
-List all dependencies present in a Brewfile\. By default, only Homebrew dependencies are listed\.
 .
 .TP
 \fB\-\-file\fR
-Read the \fBBrewfile\fR from this file\. Use \fB\-\-file=\-\fR to pipe to stdin/stdout\.
+Read the \fBBrewfile\fR from this location\. Use \fB\-\-file=\-\fR to pipe to stdin/stdout\.
 .
 .TP
 \fB\-\-global\fR
@@ -1399,7 +1393,7 @@ Read the \fBBrewfile\fR from \fB~/\.Brewfile\fR\.
 .
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
-\fBinstall\fR output is printed from commands as they are run\. \fBcheck\fR prints all missing dependencies\.
+\fBinstall\fR prints output from commands as they are run\. \fBcheck\fR lists all missing dependencies\.
 .
 .TP
 \fB\-\-no\-upgrade\fR
@@ -1407,7 +1401,7 @@ Read the \fBBrewfile\fR from \fB~/\.Brewfile\fR\.
 .
 .TP
 \fB\-f\fR, \fB\-\-force\fR
-\fBdump\fR overwrites an existing \fBBrewfile\fR\. \fBcleanup\fR actually perform the cleanup operations\.
+\fBdump\fR overwrites an existing \fBBrewfile\fR\. \fBcleanup\fR actually performs its cleanup operations\.
 .
 .TP
 \fB\-\-no\-lock\fR
@@ -1439,7 +1433,7 @@ Read the \fBBrewfile\fR from \fB~/\.Brewfile\fR\.
 .
 .TP
 \fB\-\-describe\fR
-\fBdump\fR a description comment above each line, unless the dependency does not have a description\.
+\fBdump\fR adds a description comment above each line, unless the dependency does not have a description\.
 .
 .TP
 \fB\-\-no\-restart\fR
@@ -1449,29 +1443,35 @@ Read the \fBBrewfile\fR from \fB~/\.Brewfile\fR\.
 \fB\-\-zap\fR
 \fBcleanup\fR casks using the \fBzap\fR command instead of \fBuninstall\fR\.
 .
-.SS "\fBservices\fR \fIsubcommand\fR"
+.SS "\fBservices\fR [\fIsubcommand\fR]"
 Manage background services with macOS\' \fBlaunchctl\fR(1) daemon manager\.
 .
 .P
 If \fBsudo\fR is passed, operate on \fB/Library/LaunchDaemons\fR (started at boot)\. Otherwise, operate on \fB~/Library/LaunchAgents\fR (started at login)\.
 .
 .P
-[\fBsudo\fR] \fBbrew services\fR [\fBlist\fR] List all running services for the current user (or root)\.
+[\fBsudo\fR] \fBbrew services\fR [\fBlist\fR]
+    List all running services for the current user (or root)\.
 .
 .P
-[\fBsudo\fR] \fBbrew services run\fR (\fIformula\fR|\fB\-\-all\fR) Run the service \fIformula\fR without registering to launch at login (or boot)\.
+[\fBsudo\fR] \fBbrew services run\fR (\fIformula\fR|\fB\-\-all\fR)
+    Run the service \fIformula\fR without registering to launch at login (or boot)\.
 .
 .P
-[\fBsudo\fR] \fBbrew services start\fR (\fIformula\fR|\fB\-\-all\fR) Start the service \fIformula\fR immediately and register it to launch at login (or boot)\.
+[\fBsudo\fR] \fBbrew services start\fR (\fIformula\fR|\fB\-\-all\fR)
+    Start the service \fIformula\fR immediately and register it to launch at login (or boot)\.
 .
 .P
-[\fBsudo\fR] \fBbrew services stop\fR (\fIformula\fR|\fB\-\-all\fR) Stop the service \fIformula\fR immediately and unregister it from launching at login (or boot)\.
+[\fBsudo\fR] \fBbrew services stop\fR (\fIformula\fR|\fB\-\-all\fR)
+    Stop the service \fIformula\fR immediately and unregister it from launching at login (or boot)\.
 .
 .P
-[\fBsudo\fR] \fBbrew services restart\fR (\fIformula\fR|\fB\-\-all\fR) Stop (if necessary) and start the service \fIformula\fR immediately and register it to launch at login (or boot)\.
+[\fBsudo\fR] \fBbrew services restart\fR (\fIformula\fR|\fB\-\-all\fR)
+    Stop (if necessary) and start the service \fIformula\fR immediately and register it to launch at login (or boot)\.
 .
 .P
-[\fBsudo\fR] \fBbrew services cleanup\fR Remove all unused services\.
+[\fBsudo\fR] \fBbrew services cleanup\fR
+    Remove all unused services\.
 .
 .TP
 \fB\-\-all\fR