Merge pull request #15986 from EricFromCanada/docs-assorted-improvements

Docs: assorted refinements for output

Library/Homebrew/cmd/--prefix.rb

@@ -10,8 +10,8 @@ module Homebrew
       description <<~EOS
         Display Homebrew's install path. *Default:*
 
-          - macOS Intel: `#{HOMEBREW_DEFAULT_PREFIX}`
           - macOS ARM: `#{HOMEBREW_MACOS_ARM_DEFAULT_PREFIX}`
+          - macOS Intel: `#{HOMEBREW_DEFAULT_PREFIX}`
           - Linux: `#{HOMEBREW_LINUX_DEFAULT_PREFIX}`
 
         If <formula> is provided, display the location where <formula> is or would be installed.

Library/Homebrew/cmd/--repository.rb

@@ -10,7 +10,7 @@ module Homebrew
   def __repository_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
-        Display where Homebrew's git repository is located.
+        Display where Homebrew's Git repository is located.
 
         If <user>`/`<repo> are provided, display where tap <user>`/`<repo>'s directory is located.
       EOS

Library/Homebrew/cmd/deps.rb

@@ -17,7 +17,12 @@ module Homebrew
         show the intersection of dependencies for each formula. By default, `deps`
         shows all required and recommended dependencies.
 
-        Note: `--missing` and `--skip-recommended` have precedence over `--include-*`.
+        If any version of each formula argument is installed and no other options
+        are passed, this command displays their actual runtime dependencies (similar
+        to `brew linkage`), which may differ from the current versons' stated
+        dependencies if the installed versions are outdated.
+
+        *Note:* `--missing` and `--skip-recommended` have precedence over `--include-*`.
       EOS
       switch "-n", "--topological",
              description: "Sort dependencies in topological order."

Library/Homebrew/cmd/docs.rb

@@ -10,7 +10,7 @@ module Homebrew
   def docs_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
-        Open Homebrew's online documentation (#{HOMEBREW_DOCS_WWW}) in a browser.
+        Open Homebrew's online documentation at <#{HOMEBREW_DOCS_WWW}> in a browser.
       EOS
     end
   end

Library/Homebrew/cmd/doctor.rb

@@ -11,10 +11,11 @@ module Homebrew
     Homebrew::CLI::Parser.new do
       description <<~EOS
         Check your system for potential problems. Will exit with a non-zero status
-        if any potential problems are found. Please note that these warnings are just
+        if any potential problems are found.
-        used to help the Homebrew maintainers with debugging if you file an issue. If
+
-        everything you use Homebrew for is working fine: please don't worry or file
+        Please note that these warnings are just used to help the Homebrew maintainers
-        an issue; just ignore this.
+        with debugging if you file an issue. If everything you use Homebrew for
+        is working fine: please don't worry or file an issue; just ignore this.
       EOS
       switch "--list-checks",
              description: "List all audit methods, which can be run individually " \

Library/Homebrew/cmd/info.rb

@@ -25,7 +25,6 @@ module Homebrew
     Homebrew::CLI::Parser.new do
       description <<~EOS
         Display brief statistics for your Homebrew installation.
-
         If a <formula> or <cask> is provided, show summary of information about it.
       EOS
       switch "--analytics",

Library/Homebrew/cmd/install.rb

@@ -37,7 +37,7 @@ module Homebrew
                           "non-migrated versions. When installing casks, overwrite existing files " \
                           "(binaries and symlinks are excluded, unless originally from the same cask)."
       switch "-v", "--verbose",
-             description: "Print the verification and postinstall steps."
+             description: "Print the verification and post-install steps."
       switch "-n", "--dry-run",
              description: "Show what would be installed, but do not actually install anything."
       [
@@ -49,9 +49,9 @@ module Homebrew
           hidden:      true,
         }],
         [:switch, "--ignore-dependencies", {
-          description: "An unsupported Homebrew development flag to skip installing any dependencies of any kind. " \
+          description: "An unsupported Homebrew development option to skip installing any dependencies of any " \
-                       "If the dependencies are not already present, the formula will have issues. If you're not " \
+                       "kind. If the dependencies are not already present, the formula will have issues. If you're " \
-                       "developing Homebrew, consider adjusting your PATH rather than using this flag.",
+                       "not developing Homebrew, consider adjusting your PATH rather than using this option.",
         }],
         [:switch, "--only-dependencies", {
           description: "Install the dependencies with specified options but do not install the " \
@@ -184,9 +184,9 @@ module Homebrew
 
     if args.ignore_dependencies?
       opoo <<~EOS
-        #{Tty.bold}`--ignore-dependencies` is an unsupported Homebrew developer flag!#{Tty.reset}
+        #{Tty.bold}`--ignore-dependencies` is an unsupported Homebrew developer option!#{Tty.reset}
         Adjust your PATH to put any preferred versions of applications earlier in the
-        PATH rather than using this unsupported flag!
+        PATH rather than using this unsupported option!
 
       EOS
     end

Library/Homebrew/cmd/link.rb

@@ -12,9 +12,9 @@ module Homebrew
   def link_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
-        Symlink all of <formula>'s installed files into Homebrew's prefix. This
+        Symlink all of <formula>'s installed files into Homebrew's prefix.
-        is done automatically when you install formulae but can be useful for DIY
+        This is done automatically when you install formulae but can be useful
-        installations.
+        for manual installations.
       EOS
       switch "--overwrite",
              description: "Delete files that already exist in the prefix while linking."

Library/Homebrew/cmd/list.rb

@@ -14,7 +14,6 @@ module Homebrew
     Homebrew::CLI::Parser.new do
       description <<~EOS
         List all installed formulae and casks.
-
         If <formula> is provided, summarise the paths within its current keg.
         If <cask> is provided, list its artifacts.
       EOS

Library/Homebrew/cmd/nodenv-sync.rb

@@ -11,7 +11,7 @@ module Homebrew
   def nodenv_sync_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
-        Create symlinks for Homebrew's installed NodeJS versions in ~/.nodenv/versions.
+        Create symlinks for Homebrew's installed NodeJS versions in `~/.nodenv/versions`.
 
         Note that older version symlinks will also be created so e.g. NodeJS 19.1.0 will
         also be symlinked to 19.0.0.

Library/Homebrew/cmd/pyenv-sync.rb

@@ -11,7 +11,7 @@ module Homebrew
   def pyenv_sync_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
-        Create symlinks for Homebrew's installed Python versions in ~/.pyenv/versions.
+        Create symlinks for Homebrew's installed Python versions in `~/.pyenv/versions`.
 
         Note that older patch version symlinks will be created and linked to the minor
         version so e.g. Python 3.11.0 will also be symlinked to 3.11.3.

Library/Homebrew/cmd/rbenv-sync.rb

@@ -11,7 +11,7 @@ module Homebrew
   def rbenv_sync_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
-        Create symlinks for Homebrew's installed Ruby versions in ~/.rbenv/versions.
+        Create symlinks for Homebrew's installed Ruby versions in `~/.rbenv/versions`.
 
         Note that older version symlinks will also be created so e.g. Ruby 3.2.1 will
         also be symlinked to 3.2.0.

Library/Homebrew/cmd/readall.rb

@@ -24,7 +24,7 @@ module Homebrew
       switch "--aliases",
              description: "Verify any alias symlinks in each tap."
       switch "--syntax",
-             description: "Syntax-check all of Homebrew's Ruby files (if no `<tap>` is passed)."
+             description: "Syntax-check all of Homebrew's Ruby files (if no <tap> is passed)."
       switch "--eval-all",
              description: "Evaluate all available formulae and casks, whether installed or not. " \
                           "Implied if `HOMEBREW_EVAL_ALL` is set."

Library/Homebrew/cmd/reinstall.rb

@@ -35,7 +35,7 @@ module Homebrew
              description: "Install without checking for previously installed keg-only or " \
                           "non-migrated versions."
       switch "-v", "--verbose",
-             description: "Print the verification and postinstall steps."
+             description: "Print the verification and post-install steps."
       [
         [:switch, "--formula", "--formulae", { description: "Treat all named arguments as formulae." }],
         [:switch, "-s", "--build-from-source", {

Library/Homebrew/cmd/tap-info.rb

@@ -11,7 +11,6 @@ module Homebrew
     Homebrew::CLI::Parser.new do
       description <<~EOS
         Show detailed information about one or more <tap>s.
-
         If no <tap> names are provided, display brief statistics for all installed taps.
       EOS
       switch "--installed",

Library/Homebrew/cmd/tap.rb

@@ -12,7 +12,6 @@ module Homebrew
       usage_banner "`tap` [<options>] [<user>`/`<repo>] [<URL>]"
       description <<~EOS
         Tap a formula repository.
-
         If no arguments are provided, list all installed taps.
 
         With <URL> unspecified, tap a formula repository from GitHub using HTTPS.

Library/Homebrew/cmd/upgrade.rb

@@ -35,7 +35,7 @@ module Homebrew
                           "non-migrated versions. When installing casks, overwrite existing files " \
                           "(binaries and symlinks are excluded, unless originally from the same cask)."
       switch "-v", "--verbose",
-             description: "Print the verification and postinstall steps."
+             description: "Print the verification and post-install steps."
       switch "-n", "--dry-run",
              description: "Show what would be upgraded, but do not actually upgrade anything."
       [

Library/Homebrew/cmd/uses.rb

@@ -23,7 +23,7 @@ module Homebrew
         of formulae that use <formula>. By default, `uses` shows all formulae and casks that
         specify <formula> as a required or recommended dependency for their stable builds.
 
-        Note: `--missing` and `--skip-recommended` have precedence over `--include-*`.
+        *Note:* `--missing` and `--skip-recommended` have precedence over `--include-*`.
       EOS
       switch "--recursive",
              description: "Resolve more than one level of dependencies."

Library/Homebrew/dependency.rb

@@ -230,7 +230,7 @@ class Dependency
   end
 end
 
-# A dependency that marked as "installed" on macOS
+# A dependency that's marked as "installed" on macOS
 class UsesFromMacOSDependency < Dependency
   attr_reader :bounds
 

Library/Homebrew/dev-cmd/contributions.rb

@@ -20,7 +20,7 @@ module Homebrew
     Homebrew::CLI::Parser.new do
       usage_banner "`contributions` [--user=<email|username>] [<--repositories>`=`] [<--csv>]"
       description <<~EOS
-        Contributions to Homebrew repositories.
+        Summarise contributions to Homebrew repositories.
       EOS
 
       comma_array "--repositories",

Library/Homebrew/dev-cmd/generate-cask-api.rb

@@ -12,8 +12,7 @@ module Homebrew
   def generate_cask_api_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
-        Generates Cask API data files for formulae.brew.sh.
+        Generate `homebrew/cask` API data files for <#{HOMEBREW_API_WWW}>.
-
         The generated files are written to the current directory.
       EOS
 

Library/Homebrew/dev-cmd/generate-formula-api.rb

@@ -11,8 +11,7 @@ module Homebrew
   def generate_formula_api_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
-        Generates Formula API data files for formulae.brew.sh.
+        Generate `homebrew/core` API data files for <#{HOMEBREW_API_WWW}>.
-
         The generated files are written to the current directory.
       EOS
 

Library/Homebrew/dev-cmd/livecheck.rb

@@ -14,7 +14,6 @@ module Homebrew
     Homebrew::CLI::Parser.new do
       description <<~EOS
         Check for newer versions of formulae and/or casks from upstream.
-
         If no formula or cask argument is passed, the list of formulae and
         casks to check is taken from `HOMEBREW_LIVECHECK_WATCHLIST` or
         `~/.homebrew/livecheck_watchlist.txt`.

Library/Homebrew/dev-cmd/release.rb

@@ -17,7 +17,7 @@ module Homebrew
         The command will fail if the previous major or minor release was made less than
         one month ago.
 
-        Requires write access to the Homebrew/brew repository.
+        *Note:* Requires write access to the Homebrew/brew repository.
       EOS
       switch "--major",
              description: "Create a major release."

Library/Homebrew/env_config.rb

@@ -300,7 +300,7 @@ module Homebrew
       },
       HOMEBREW_NO_INSECURE_REDIRECT:             {
         description: "If set, forbid redirects from secure HTTPS to insecure HTTP." \
-                     "\n\n    *Note:* While ensuring your downloads are fully secure, this is likely to cause " \
+                     "\n\n    *Note:* while ensuring your downloads are fully secure, this is likely to cause " \
                      "from-source SourceForge, some GNU & GNOME-hosted formulae to fail to download.",
         boolean:     true,
       },
@@ -317,7 +317,7 @@ module Homebrew
         boolean:     true,
       },
       HOMEBREW_NO_INSTALL_UPGRADE:               {
-        description: "If set, `brew install` <formula/cask> will not upgrade <formula/cask> if it is installed but " \
+        description: "If set, `brew install` <formula|cask> will not upgrade <formula|cask> if it is installed but " \
                      "outdated.",
         boolean:     true,
       },
@@ -333,7 +333,7 @@ module Homebrew
         boolean:     true,
       },
       HOMEBREW_PIP_INDEX_URL:                    {
-        description:  "If set, `brew install <formula>` will use this URL to download PyPI package resources.",
+        description:  "If set, `brew install` <formula> will use this URL to download PyPI package resources.",
         default_text: "`https://pypi.org/simple`.",
       },
       HOMEBREW_PRY:                              {
@@ -361,7 +361,7 @@ module Homebrew
       },
       HOMEBREW_SSH_CONFIG_PATH:                  {
         description:  "If set, Homebrew will use the given config file instead of `~/.ssh/config` when fetching " \
-                      "`git` repos over `ssh`.",
+                      "Git repositories over SSH.",
         default_text: "`$HOME/.ssh/config`",
       },
       HOMEBREW_SVN:                              {

Library/Homebrew/extend/kernel.rb

@@ -292,7 +292,7 @@ module Kernel
     unless silent
       opoo <<~EOS
         Using #{editor} because no editor was set in the environment.
-        This may change in the future, so we recommend setting EDITOR,
+        This may change in the future, so we recommend setting EDITOR
         or HOMEBREW_EDITOR to your preferred text editor.
       EOS
     end

Library/Homebrew/formula.rb

@@ -85,19 +85,19 @@ class Formula
   attr_reader :alias_name
 
   # The fully-qualified name of this {Formula}.
-  # For core formula it's the same as {#name}.
+  # For core formulae it's the same as {#name}.
   # e.g. `homebrew/tap-name/this-formula`
   sig { returns(String) }
   attr_reader :full_name
 
   # The fully-qualified alias referring to this {Formula}.
-  # For core formula it's the same as {#alias_name}.
+  # For core formulae it's the same as {#alias_name}.
   # e.g. `homebrew/tap-name/another-name-for-this-formula`
   sig { returns(T.nilable(String)) }
   attr_reader :full_alias_name
 
   # The full path to this {Formula}.
-  # e.g. `/usr/local/Library/Taps/homebrew/homebrew-core/Formula/this-formula.rb`
+  # e.g. `/usr/local/Library/Taps/homebrew/homebrew-core/Formula/t/this-formula.rb`
   sig { returns(Pathname) }
   attr_reader :path
 
@@ -527,7 +527,7 @@ class Formula
   delegate resource: :active_spec
 
   # An old name for the formula.
-  # @deprecated Use #{#oldnames} instead.
+  # @deprecated Use {#oldnames} instead.
   sig { returns(T.nilable(String)) }
   def oldname
     odeprecated "Formula#oldname", "Formula#oldnames"
@@ -672,7 +672,7 @@ class Formula
   end
 
   # The directory in the cellar that the formula is installed to.
-  # This directory points to {#opt_prefix} if it exists and if #{prefix} is not
+  # This directory points to {#opt_prefix} if it exists and if {#prefix} is not
   # called from within the same formula's {#install} or {#post_install} methods.
   # Otherwise, return the full path to the formula's versioned cellar.
   def prefix(version = pkg_version)
@@ -1718,8 +1718,7 @@ class Formula
   #
   # If `name` is specified as "*", match any shared library of any version.
   #
-  # <pre>
+  # <pre>shared_library("foo")      #=> foo.dylib
-  # shared_library("foo")      #=> foo.dylib
   # shared_library("foo", 1)   #=> foo.1.dylib
   # shared_library("foo", "*") #=> foo.2.dylib, foo.1.dylib, foo.dylib
   # shared_library("*")        #=> foo.dylib, bar.dylib
@@ -1741,8 +1740,7 @@ class Formula
   # Optionally specify a `source` or `target` depending on the location
   # of the file containing the RPATH command and where its target is located.
   #
-  # <pre>
+  # <pre>rpath #=> "@loader_path/../lib"
-  # rpath #=> "@loader_path/../lib"
   # rpath(target: frameworks) #=> "@loader_path/../Frameworks"
   # rpath(source: libexec/"bin") #=> "@loader_path/../../lib"
   # </pre>
@@ -1808,64 +1806,62 @@ class Formula
   # Generate shell completions for a formula for bash, zsh, and fish, using the formula's executable.
   #
   # @param commands [Pathname, String] the path to the executable and any passed subcommand(s)
-  # to use for generating the completion scripts.
+  #  to use for generating the completion scripts.
   # @param base_name [String] the base name of the generated completion script. Defaults to the formula name.
   # @param shells [Array<Symbol>] the shells to generate completion scripts for. Defaults to `[:bash, :zsh, :fish]`.
   # @param shell_parameter_format [String, Symbol] specify how `shells` should each be passed
-  # to the `executable`. Takes either a String representing a prefix, or one of [:flag, :arg, :none, :click].
+  #  to the `executable`. Takes either a String representing a prefix, or one of `[:flag, :arg, :none, :click]`.
-  # Defaults to plainly passing the shell.
+  #  Defaults to plainly passing the shell.
   #
   # @example Using default values for optional arguments
   #   generate_completions_from_executable(bin/"foo", "completions")
-  # translates to
   #
-  # (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions", "bash")
+  #   # translates to
+  #   (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions", "bash")
+  #   (zsh_completion/"_foo").write Utils.safe_popen_read({ "SHELL" => "zsh" }, bin/"foo", "completions", "zsh")
+  #   (fish_completion/"foo.fish").write Utils.safe_popen_read({ "SHELL" => "fish" }, bin/"foo",
+  #                                                            "completions", "fish")
   #
-  # (zsh_completion/"_foo").write Utils.safe_popen_read({ "SHELL" => "zsh" }, bin/"foo", "completions", "zsh")
+  # @example Selecting shells and using a different `base_name`
+  #   generate_completions_from_executable(bin/"foo", "completions", shells: [:bash, :zsh], base_name: "bar")
   #
-  # (fish_completion/"foo.fish").write Utils.safe_popen_read({ "SHELL" => "fish" }, bin/"foo", "completions", "fish")
+  #   # translates to
+  #   (bash_completion/"bar").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions", "bash")
+  #   (zsh_completion/"_bar").write Utils.safe_popen_read({ "SHELL" => "zsh" }, bin/"foo", "completions", "zsh")
   #
-  # @example Selecting shells and using a different base_name
+  # @example Using predefined `shell_parameter_format :flag`
-  #    generate_completions_from_executable(bin/"foo", "completions", shells: [:bash, :zsh], base_name: "bar")
-  # translates to
-  #
-  # (bash_completion/"bar").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions", "bash")
-  #
-  # (zsh_completion/"_bar").write Utils.safe_popen_read({ "SHELL" => "zsh" }, bin/"foo", "completions", "zsh")
-  #
-  # @example Using predefined shell_parameter_format :flag
   #   generate_completions_from_executable(bin/"foo", "completions", shell_parameter_format: :flag, shells: [:bash])
-  # translates to
   #
-  # (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions", "--bash")
+  #   # translates to
+  #   (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions", "--bash")
   #
-  # @example Using predefined shell_parameter_format :arg
+  # @example Using predefined `shell_parameter_format :arg`
   #   generate_completions_from_executable(bin/"foo", "completions", shell_parameter_format: :arg, shells: [:bash])
-  # translates to
   #
-  # (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo",
+  #   # translates to
-  #                                                     "completions", "--shell=bash")
+  #   (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo",
+  #                                                       "completions", "--shell=bash")
   #
-  # @example Using predefined shell_parameter_format :none
+  # @example Using predefined `shell_parameter_format :none`
   #   generate_completions_from_executable(bin/"foo", "completions", shell_parameter_format: :none, shells: [:bash])
-  # translates to
   #
-  # (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions")
+  #   # translates to
+  #   (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions")
   #
-  # @example Using predefined shell_parameter_format :click
+  # @example Using predefined `shell_parameter_format :click`
   #   generate_completions_from_executable(bin/"foo", shell_parameter_format: :click, shells: [:zsh])
-  # translates to
   #
-  # (zsh_completion/"_foo").write Utils.safe_popen_read({ "SHELL" => "zsh", "_FOO_COMPLETE" => "zsh_source" },
+  #   # translates to
-  #                                                     bin/"foo")
+  #   (zsh_completion/"_foo").write Utils.safe_popen_read({ "SHELL" => "zsh", "_FOO_COMPLETE" => "zsh_source" },
+  #                                                       bin/"foo")
   #
-  # @example Using custom shell_parameter_format
+  # @example Using custom `shell_parameter_format`
   #   generate_completions_from_executable(bin/"foo", "completions", shell_parameter_format: "--selected-shell=",
   #                                        shells: [:bash])
-  # translates to
   #
-  # (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo",
+  #   # translates to
-  #                                                     "completions", "--selected-shell=bash")
+  #   (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo",
+  #                                                       "completions", "--selected-shell=bash")
   sig {
     params(commands: T.any(Pathname, String), base_name: String, shells: T::Array[Symbol],
            shell_parameter_format: T.nilable(T.any(Symbol, String))).void
@@ -2432,7 +2428,7 @@ class Formula
     hash
   end
 
-  # Returns the bottle information for a formula
+  # Returns the bottle information for a formula.
   def bottle_hash
     bottle_spec = T.must(stable).bottle_specification
     hash = {
@@ -3451,7 +3447,7 @@ class Formula
     # explicitly use that compiler in a formula's {#install} block,
     # rather than implicitly finding a suitable compiler with `needs`.
     #
-    # @see #fails_with
+    # @see .fails_with
     def needs(*standards)
       specs.each { |spec| spec.needs(*standards) }
     end

Library/Homebrew/formula_creator.rb

@@ -60,7 +60,7 @@ module Homebrew
       raise "#{path} already exists" if path.exist?
 
       if version.nil? || version.null?
-        odie "Version cannot be determined from URL. Explicity set the version with `--set-version` instead."
+        odie "Version cannot be determined from URL. Explicitly set the version with `--set-version` instead."
       elsif fetch?
         unless head?
           r = Resource.new

Library/Homebrew/formula_installer.rb

@@ -685,7 +685,7 @@ on_request: installed_on_request?, options: options)
       # When fetching we don't need to recurse the dependency tree as it's already
       # been done for us in `compute_dependencies` and there's no requirement to
       # fetch in a particular order.
-      # Note, this tree can vary when pouring bottles so we need ot check it then.
+      # Note, this tree can vary when pouring bottles so we need to check it then.
       ignore_deps:                !pour_bottle?,
       installed_as_dependency:    true,
       include_test_formulae:      @include_test_formulae,

Library/Homebrew/global.rb

@@ -36,6 +36,7 @@ HOMEBREW_REQUIRED_RUBY_VERSION = ENV.fetch("HOMEBREW_REQUIRED_RUBY_VERSION").fre
 HOMEBREW_PRODUCT = ENV.fetch("HOMEBREW_PRODUCT").freeze
 HOMEBREW_VERSION = ENV.fetch("HOMEBREW_VERSION").freeze
 HOMEBREW_WWW = "https://brew.sh"
+HOMEBREW_API_WWW = "https://formulae.brew.sh"
 HOMEBREW_DOCS_WWW = "https://docs.brew.sh"
 HOMEBREW_SYSTEM = ENV.fetch("HOMEBREW_SYSTEM").freeze
 HOMEBREW_PROCESSOR = ENV.fetch("HOMEBREW_PROCESSOR").freeze

Library/Homebrew/install.rb

@@ -87,7 +87,7 @@ module Homebrew
           # keg-only install is only possible when no other version is
           # linked to opt, because installing without any warnings can break
           # dependencies. Therefore before performing other checks we need to be
-          # sure --force flag is passed.
+          # sure the --force switch is passed.
           if formula.outdated?
             if !Homebrew::EnvConfig.no_install_upgrade? && !formula.pinned?
               name = formula.name
@@ -113,7 +113,7 @@ module Homebrew
             EOS
           end
         elsif (head && new_head_installed) || prefix_installed
-          # After we're sure that --force flag is passed for linked to opt
+          # After we're sure the --force switch was passed for linking to opt
           # keg-only we need to be sure that the version we're attempting to
           # install is not already installed.
 

Library/Homebrew/livecheck/strategy/gnome.rb

@@ -15,11 +15,11 @@ module Homebrew
       # Before version 40, GNOME used a version scheme where unstable releases
       # were indicated with a minor that's 90+ or odd. The newer version scheme
       # uses trailing alpha/beta/rc text to identify unstable versions
-      # (e.g., `40.alpha`).
+      # (e.g. `40.alpha`).
       #
       # When a regex isn't provided in a `livecheck` block, the strategy uses
       # a default regex that matches versions which don't include trailing text
-      # after the numeric version (e.g., `40.0` instead of `40.alpha`) and it
+      # after the numeric version (e.g. `40.0` instead of `40.alpha`) and it
       # selectively filters out unstable versions below 40 using the rules for
       # the older version scheme.
       #

Library/Homebrew/livecheck/strategy/pypi.rb

@@ -19,7 +19,7 @@ module Homebrew
       class Pypi
         NICE_NAME = "PyPI"
 
-        # The `Regexp` used to extract the package name and suffix (e.g., file
+        # The `Regexp` used to extract the package name and suffix (e.g. file
         # extension) from the URL basename.
         FILENAME_REGEX = /
           (?<package_name>.+)- # The package name followed by a hyphen

Library/Homebrew/manpages.rb

@@ -183,7 +183,7 @@ module Homebrew
     sig { returns(String) }
     def self.global_cask_options_manpage
       lines = ["These options are applicable to the `install`, `reinstall`, and `upgrade` " \
-               "subcommands with the `--cask` flag.\n"]
+               "subcommands with the `--cask` switch.\n"]
       lines += Homebrew::CLI::Parser.global_cask_options.map do |_, long, description:, **|
         generate_option_doc(nil, long.chomp("="), description)
       end

Library/Homebrew/tab.rb

@@ -18,7 +18,7 @@ class Tab
                 :built_on
   attr_writer :used_options, :unused_options, :compiler, :runtime_dependencies, :source_modified_time
 
-  # Instantiates a Tab for a new installation of a formula.
+  # Instantiates a {Tab} for a new installation of a formula.
   def self.create(formula, compiler, stdlib)
     build = formula.build
     runtime_deps = formula.runtime_dependencies(undeclared: false)
@@ -362,7 +362,7 @@ class Tab
     JSON.pretty_generate(attributes, options)
   end
 
-  # a subset of to_json that we care about for bottles
+  # A subset of to_json that we care about for bottles.
   def to_bottle_hash
     attributes = {
       "homebrew_version"     => homebrew_version,

Library/Homebrew/tap.rb

@@ -187,14 +187,14 @@ class Tap
     git_repo.git_repo?
   end
 
-  # git branch for this {Tap}.
+  # Git branch for this {Tap}.
   def git_branch
     raise TapUnavailableError, name unless installed?
 
     git_repo.branch_name
   end
 
-  # git HEAD for this {Tap}.
+  # Git HEAD for this {Tap}.
   def git_head
     raise TapUnavailableError, name unless installed?
 

Library/Homebrew/test/cli/parser_spec.rb

@@ -28,17 +28,17 @@ describe Homebrew::CLI::Parser do
         expect { args.no_positive? }.to raise_error(NoMethodError)
       end
 
-      it "sets the positive name to false if the negative flag is passed" do
+      it "sets the positive name to false if the negative switch is passed" do
         args = parser.parse(["--no-positive"])
         expect(args).not_to be_positive
       end
 
-      it "sets the positive name to true if the positive flag is passed" do
+      it "sets the positive name to true if the positive switch is passed" do
         args = parser.parse(["--positive"])
         expect(args).to be_positive
       end
 
-      it "does not set the positive name if the positive flag is not passed" do
+      it "does not set the positive name if the positive switch is not passed" do
         args = parser.parse([])
         expect(args.positive?).to be_nil
       end
@@ -62,7 +62,7 @@ describe Homebrew::CLI::Parser do
         end.to raise_error(/invalid option/)
       end
 
-      it "sets the negative name to true if the negative flag is passed" do
+      it "sets the negative name to true if the negative switch is passed" do
         args = parser.parse(["--no-positive"])
         expect(args.no_positive?).to be true
       end

Library/Homebrew/test/completions_spec.rb

@@ -222,7 +222,7 @@ describe Homebrew::Completions do
 
       it "will override global options with local descriptions" do
         options = described_class.command_options("upgrade")
-        expect(options["--verbose"]).to eq "Print the verification and postinstall steps."
+        expect(options["--verbose"]).to eq "Print the verification and post-install steps."
       end
     end
 

Library/Homebrew/test/support/lib/startup/config.rb

@@ -9,7 +9,7 @@ TEST_TMPDIR = ENV.fetch("HOMEBREW_TEST_TMPDIR") do |k|
   dir = Dir.mktmpdir("homebrew-tests-", ENV.fetch("HOMEBREW_TEMP"))
   at_exit do
     # Child processes inherit this at_exit handler, but we don't want them
-    # to clean TEST_TMPDIR up prematurely (i.e., when they exit early for a test).
+    # to clean TEST_TMPDIR up prematurely (i.e. when they exit early for a test).
     FileUtils.remove_entry(dir) unless ENV["HOMEBREW_TEST_NO_EXIT_CLEANUP"]
   end
   ENV[k] = dir

Library/Homebrew/utils/curl.rb

@@ -23,7 +23,7 @@ module Utils
     HTTP_RESPONSE_BODY_SEPARATOR = "\r\n\r\n"
 
     # This regex is used to isolate the parts of an HTTP status line, namely
-    # the status code and any following descriptive text (e.g., `Not Found`).
+    # the status code and any following descriptive text (e.g. `Not Found`).
     HTTP_STATUS_LINE_REGEX = %r{^HTTP/.* (?<code>\d+)(?: (?<text>[^\r\n]+))?}.freeze
 
     private_constant :ETAG_VALUE_REGEX, :HTTP_RESPONSE_BODY_SEPARATOR, :HTTP_STATUS_LINE_REGEX
@@ -112,7 +112,7 @@ module Utils
       args << "--connect-timeout" << connect_timeout.round(3) if connect_timeout.present?
       args << "--max-time" << max_time.round(3) if max_time.present?
 
-      # A non-positive integer (e.g., 0) or `nil` will omit this argument
+      # A non-positive integer (e.g. 0) or `nil` will omit this argument
       args << "--retry" << retries if retries&.positive?
 
       args << "--retry-max-time" << retry_max_time.round if retry_max_time.present?

completions/fish/brew.fish

@@ -250,7 +250,7 @@ __fish_brew_complete_arg '--prefix' -l verbose -d 'Make some output more verbose
 __fish_brew_complete_arg '--prefix' -a '(__fish_brew_suggest_formulae_all)'
 
 
-__fish_brew_complete_cmd '--repo' 'Display where Homebrew\'s git repository is located'
+__fish_brew_complete_cmd '--repo' 'Display where Homebrew\'s Git repository is located'
 __fish_brew_complete_arg '--repo' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg '--repo' -l help -d 'Show this message'
 __fish_brew_complete_arg '--repo' -l quiet -d 'Make some output more quiet'
@@ -258,7 +258,7 @@ __fish_brew_complete_arg '--repo' -l verbose -d 'Make some output more verbose'
 __fish_brew_complete_arg '--repo' -a '(__fish_brew_suggest_taps_installed)'
 
 
-__fish_brew_complete_cmd '--repository' 'Display where Homebrew\'s git repository is located'
+__fish_brew_complete_cmd '--repository' 'Display where Homebrew\'s Git repository is located'
 __fish_brew_complete_arg '--repository' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg '--repository' -l help -d 'Show this message'
 __fish_brew_complete_arg '--repository' -l quiet -d 'Make some output more quiet'
@@ -528,7 +528,7 @@ __fish_brew_complete_arg 'config' -l quiet -d 'Make some output more quiet'
 __fish_brew_complete_arg 'config' -l verbose -d 'Make some output more verbose'
 
 
-__fish_brew_complete_cmd 'contributions' 'Contributions to Homebrew repositories'
+__fish_brew_complete_cmd 'contributions' 'Summarise contributions to Homebrew repositories'
 __fish_brew_complete_arg 'contributions' -l csv -d 'Print a CSV of contributions across repositories over the time period'
 __fish_brew_complete_arg 'contributions' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'contributions' -l from -d 'Date (ISO-8601 format) to start searching contributions. Omitting this flag searches the last year'
@@ -644,7 +644,7 @@ __fish_brew_complete_arg 'dispatch-build-bottle' -l workflow -d 'Dispatch specif
 __fish_brew_complete_arg 'dispatch-build-bottle' -a '(__fish_brew_suggest_formulae_all)'
 
 
-__fish_brew_complete_cmd 'docs' 'Open Homebrew\'s online documentation (https://docs.brew.sh) in a browser'
+__fish_brew_complete_cmd 'docs' 'Open Homebrew\'s online documentation at https://docs.brew.sh in a browser'
 __fish_brew_complete_arg 'docs' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'docs' -l help -d 'Show this message'
 __fish_brew_complete_arg 'docs' -l quiet -d 'Make some output more quiet'
@@ -736,7 +736,7 @@ __fish_brew_complete_arg 'formula' -l verbose -d 'Make some output more verbose'
 __fish_brew_complete_arg 'formula' -a '(__fish_brew_suggest_formulae_all)'
 
 
-__fish_brew_complete_cmd 'generate-cask-api' 'Generates Cask API data files for formulae.brew.sh'
+__fish_brew_complete_cmd 'generate-cask-api' 'Generate `homebrew/cask` API data files for https://formulae.brew.sh'
 __fish_brew_complete_arg 'generate-cask-api' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'generate-cask-api' -l dry-run -d 'Generate API data without writing it to files'
 __fish_brew_complete_arg 'generate-cask-api' -l help -d 'Show this message'
@@ -744,7 +744,7 @@ __fish_brew_complete_arg 'generate-cask-api' -l quiet -d 'Make some output more
 __fish_brew_complete_arg 'generate-cask-api' -l verbose -d 'Make some output more verbose'
 
 
-__fish_brew_complete_cmd 'generate-formula-api' 'Generates Formula API data files for formulae.brew.sh'
+__fish_brew_complete_cmd 'generate-formula-api' 'Generate `homebrew/core` API data files for https://formulae.brew.sh'
 __fish_brew_complete_arg 'generate-formula-api' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'generate-formula-api' -l dry-run -d 'Generate API data without writing it to files'
 __fish_brew_complete_arg 'generate-formula-api' -l help -d 'Show this message'
@@ -835,7 +835,7 @@ __fish_brew_complete_arg 'instal' -l force-bottle -d 'Install from a bottle if i
 __fish_brew_complete_arg 'instal' -l formula -d 'Treat all named arguments as formulae'
 __fish_brew_complete_arg 'instal' -l git -d 'Create a Git repository, useful for creating patches to the software'
 __fish_brew_complete_arg 'instal' -l help -d 'Show this message'
-__fish_brew_complete_arg 'instal' -l ignore-dependencies -d 'An unsupported Homebrew development flag to skip installing any dependencies of any kind. If the dependencies are not already present, the formula will have issues. If you\'re not developing Homebrew, consider adjusting your PATH rather than using this flag'
+__fish_brew_complete_arg 'instal' -l ignore-dependencies -d 'An unsupported Homebrew development option to skip installing any dependencies of any kind. If the dependencies are not already present, the formula will have issues. If you\'re not developing Homebrew, consider adjusting your PATH rather than using this option'
 __fish_brew_complete_arg 'instal' -l include-test -d 'Install testing dependencies required to run `brew test` formula'
 __fish_brew_complete_arg 'instal' -l input-methoddir -d 'Target location for Input Methods (default: `~/Library/Input Methods`)'
 __fish_brew_complete_arg 'instal' -l interactive -d 'Download and patch formula, then open a shell. This allows the user to run `./configure --help` and otherwise determine how to turn the software package into a Homebrew package'
@@ -857,7 +857,7 @@ __fish_brew_complete_arg 'instal' -l screen-saverdir -d 'Target location for Scr
 __fish_brew_complete_arg 'instal' -l servicedir -d 'Target location for Services (default: `~/Library/Services`)'
 __fish_brew_complete_arg 'instal' -l skip-cask-deps -d 'Skip installing cask dependencies'
 __fish_brew_complete_arg 'instal' -l skip-post-install -d 'Install but skip any post-install steps'
-__fish_brew_complete_arg 'instal' -l verbose -d 'Print the verification and postinstall steps'
+__fish_brew_complete_arg 'instal' -l verbose -d 'Print the verification and post-install steps'
 __fish_brew_complete_arg 'instal' -l vst-plugindir -d 'Target location for VST Plugins (default: `~/Library/Audio/Plug-Ins/VST`)'
 __fish_brew_complete_arg 'instal' -l vst3-plugindir -d 'Target location for VST3 Plugins (default: `~/Library/Audio/Plug-Ins/VST3`)'
 __fish_brew_complete_arg 'instal' -l zap -d 'For use with `brew reinstall --cask`. Remove all files associated with a cask. *May remove files which are shared between applications.*'
@@ -889,7 +889,7 @@ __fish_brew_complete_arg 'install' -l force-bottle -d 'Install from a bottle if
 __fish_brew_complete_arg 'install' -l formula -d 'Treat all named arguments as formulae'
 __fish_brew_complete_arg 'install' -l git -d 'Create a Git repository, useful for creating patches to the software'
 __fish_brew_complete_arg 'install' -l help -d 'Show this message'
-__fish_brew_complete_arg 'install' -l ignore-dependencies -d 'An unsupported Homebrew development flag to skip installing any dependencies of any kind. If the dependencies are not already present, the formula will have issues. If you\'re not developing Homebrew, consider adjusting your PATH rather than using this flag'
+__fish_brew_complete_arg 'install' -l ignore-dependencies -d 'An unsupported Homebrew development option to skip installing any dependencies of any kind. If the dependencies are not already present, the formula will have issues. If you\'re not developing Homebrew, consider adjusting your PATH rather than using this option'
 __fish_brew_complete_arg 'install' -l include-test -d 'Install testing dependencies required to run `brew test` formula'
 __fish_brew_complete_arg 'install' -l input-methoddir -d 'Target location for Input Methods (default: `~/Library/Input Methods`)'
 __fish_brew_complete_arg 'install' -l interactive -d 'Download and patch formula, then open a shell. This allows the user to run `./configure --help` and otherwise determine how to turn the software package into a Homebrew package'
@@ -911,7 +911,7 @@ __fish_brew_complete_arg 'install' -l screen-saverdir -d 'Target location for Sc
 __fish_brew_complete_arg 'install' -l servicedir -d 'Target location for Services (default: `~/Library/Services`)'
 __fish_brew_complete_arg 'install' -l skip-cask-deps -d 'Skip installing cask dependencies'
 __fish_brew_complete_arg 'install' -l skip-post-install -d 'Install but skip any post-install steps'
-__fish_brew_complete_arg 'install' -l verbose -d 'Print the verification and postinstall steps'
+__fish_brew_complete_arg 'install' -l verbose -d 'Print the verification and post-install steps'
 __fish_brew_complete_arg 'install' -l vst-plugindir -d 'Target location for VST Plugins (default: `~/Library/Audio/Plug-Ins/VST`)'
 __fish_brew_complete_arg 'install' -l vst3-plugindir -d 'Target location for VST3 Plugins (default: `~/Library/Audio/Plug-Ins/VST3`)'
 __fish_brew_complete_arg 'install' -l zap -d 'For use with `brew reinstall --cask`. Remove all files associated with a cask. *May remove files which are shared between applications.*'
@@ -1093,7 +1093,7 @@ __fish_brew_complete_arg 'missing' -l verbose -d 'Make some output more verbose'
 __fish_brew_complete_arg 'missing' -a '(__fish_brew_suggest_formulae_all)'
 
 
-__fish_brew_complete_cmd 'nodenv-sync' 'Create symlinks for Homebrew\'s installed NodeJS versions in ~/.nodenv/versions'
+__fish_brew_complete_cmd 'nodenv-sync' 'Create symlinks for Homebrew\'s installed NodeJS versions in `~/.nodenv/versions`'
 __fish_brew_complete_arg 'nodenv-sync' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'nodenv-sync' -l help -d 'Show this message'
 __fish_brew_complete_arg 'nodenv-sync' -l quiet -d 'Make some output more quiet'
@@ -1239,14 +1239,14 @@ __fish_brew_complete_arg 'prof' -l verbose -d 'Make some output more verbose'
 __fish_brew_complete_arg 'prof' -a '(__fish_brew_suggest_commands)'
 
 
-__fish_brew_complete_cmd 'pyenv-sync' 'Create symlinks for Homebrew\'s installed Python versions in ~/.pyenv/versions'
+__fish_brew_complete_cmd 'pyenv-sync' 'Create symlinks for Homebrew\'s installed Python versions in `~/.pyenv/versions`'
 __fish_brew_complete_arg 'pyenv-sync' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'pyenv-sync' -l help -d 'Show this message'
 __fish_brew_complete_arg 'pyenv-sync' -l quiet -d 'Make some output more quiet'
 __fish_brew_complete_arg 'pyenv-sync' -l verbose -d 'Make some output more verbose'
 
 
-__fish_brew_complete_cmd 'rbenv-sync' 'Create symlinks for Homebrew\'s installed Ruby versions in ~/.rbenv/versions'
+__fish_brew_complete_cmd 'rbenv-sync' 'Create symlinks for Homebrew\'s installed Ruby versions in `~/.rbenv/versions`'
 __fish_brew_complete_arg 'rbenv-sync' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'rbenv-sync' -l help -d 'Show this message'
 __fish_brew_complete_arg 'rbenv-sync' -l quiet -d 'Make some output more quiet'
@@ -1262,7 +1262,7 @@ __fish_brew_complete_arg 'readall' -l help -d 'Show this message'
 __fish_brew_complete_arg 'readall' -l no-simulate -d 'Don\'t simulate other system configurations when checking formulae and casks'
 __fish_brew_complete_arg 'readall' -l os -d 'Read using the given operating system. (Pass `all` to simulate all operating systems.)'
 __fish_brew_complete_arg 'readall' -l quiet -d 'Make some output more quiet'
-__fish_brew_complete_arg 'readall' -l syntax -d 'Syntax-check all of Homebrew\'s Ruby files (if no `tap` is passed)'
+__fish_brew_complete_arg 'readall' -l syntax -d 'Syntax-check all of Homebrew\'s Ruby files (if no tap is passed)'
 __fish_brew_complete_arg 'readall' -l verbose -d 'Make some output more verbose'
 __fish_brew_complete_arg 'readall' -a '(__fish_brew_suggest_taps_installed)'
 
@@ -1302,7 +1302,7 @@ __fish_brew_complete_arg 'reinstall' -l require-sha -d 'Require all casks to hav
 __fish_brew_complete_arg 'reinstall' -l screen-saverdir -d 'Target location for Screen Savers (default: `~/Library/Screen Savers`)'
 __fish_brew_complete_arg 'reinstall' -l servicedir -d 'Target location for Services (default: `~/Library/Services`)'
 __fish_brew_complete_arg 'reinstall' -l skip-cask-deps -d 'Skip installing cask dependencies'
-__fish_brew_complete_arg 'reinstall' -l verbose -d 'Print the verification and postinstall steps'
+__fish_brew_complete_arg 'reinstall' -l verbose -d 'Print the verification and post-install steps'
 __fish_brew_complete_arg 'reinstall' -l vst-plugindir -d 'Target location for VST Plugins (default: `~/Library/Audio/Plug-Ins/VST`)'
 __fish_brew_complete_arg 'reinstall' -l vst3-plugindir -d 'Target location for VST3 Plugins (default: `~/Library/Audio/Plug-Ins/VST3`)'
 __fish_brew_complete_arg 'reinstall' -l zap -d 'For use with `brew reinstall --cask`. Remove all files associated with a cask. *May remove files which are shared between applications.*'
@@ -1687,7 +1687,7 @@ __fish_brew_complete_arg 'upgrade' -l require-sha -d 'Require all casks to have
 __fish_brew_complete_arg 'upgrade' -l screen-saverdir -d 'Target location for Screen Savers (default: `~/Library/Screen Savers`)'
 __fish_brew_complete_arg 'upgrade' -l servicedir -d 'Target location for Services (default: `~/Library/Services`)'
 __fish_brew_complete_arg 'upgrade' -l skip-cask-deps -d 'Skip installing cask dependencies'
-__fish_brew_complete_arg 'upgrade' -l verbose -d 'Print the verification and postinstall steps'
+__fish_brew_complete_arg 'upgrade' -l verbose -d 'Print the verification and post-install steps'
 __fish_brew_complete_arg 'upgrade' -l vst-plugindir -d 'Target location for VST Plugins (default: `~/Library/Audio/Plug-Ins/VST`)'
 __fish_brew_complete_arg 'upgrade' -l vst3-plugindir -d 'Target location for VST3 Plugins (default: `~/Library/Audio/Plug-Ins/VST3`)'
 __fish_brew_complete_arg 'upgrade; and not __fish_seen_argument -l cask -l casks' -a '(__fish_brew_suggest_formulae_outdated)'

completions/zsh/_brew

@@ -137,7 +137,7 @@ __brew_internal_commands() {
     '--cellar:Display Homebrew'\''s Cellar path'
     '--env:Summarise Homebrew'\''s build environment as a plain list'
     '--prefix:Display Homebrew'\''s install path'
-    '--repository:Display where Homebrew'\''s git repository is located'
+    '--repository:Display where Homebrew'\''s Git repository is located'
     '--version:Print the version numbers of Homebrew, Homebrew/homebrew-core and Homebrew/homebrew-cask (if tapped) to standard output'
     'analytics:Control Homebrew'\''s anonymous aggregate user behaviour analytics'
     'audit:Check formula for Homebrew coding style violations'
@@ -155,22 +155,22 @@ __brew_internal_commands() {
     'commands:Show lists of built-in and external commands'
     'completions:Control whether Homebrew automatically links external tap shell completion files'
     'config:Show Homebrew and system configuration info useful for debugging'
-    'contributions:Contributions to Homebrew repositories'
+    'contributions:Summarise contributions to Homebrew repositories'
     'create:Generate a formula or, with `--cask`, a cask for the downloadable file at URL and open it in the editor'
     'deps:Show dependencies for formula'
     'desc:Display formula'\''s name and one-line description'
     'determine-test-runners:Determines the runners used to test formulae or their dependents'
     'developer:Control Homebrew'\''s developer mode'
     'dispatch-build-bottle:Build bottles for these formulae with GitHub Actions'
-    'docs:Open Homebrew'\''s online documentation (https://docs.brew.sh) in a browser'
+    'docs:Open Homebrew'\''s online documentation at https://docs.brew.sh in a browser'
     'doctor:Check your system for potential problems'
     'edit:Open a formula, cask or tap in the editor set by `EDITOR` or `HOMEBREW_EDITOR`, or open the Homebrew repository for editing if no argument is provided'
     'extract:Look through repository history to find the most recent version of formula and create a copy in tap'
     'fetch:Download a bottle (if available) or source packages for formulae and binaries for casks'
     'formula:Display the path where formula is located'
     'formulae:List all locally installable formulae including short names'
-    'generate-cask-api:Generates Cask API data files for formulae.brew.sh'
+    'generate-cask-api:Generate `homebrew/cask` API data files for https://formulae.brew.sh'
-    'generate-formula-api:Generates Formula API data files for formulae.brew.sh'
+    'generate-formula-api:Generate `homebrew/core` API data files for https://formulae.brew.sh'
     'generate-man-completions:Generate Homebrew'\''s manpages and shell completions'
     'gist-logs:Upload logs for a failed build of formula to a new Gist'
     'home:Open a formula or cask'\''s homepage in a browser, or open Homebrew'\''s own homepage if no argument is provided'
@@ -186,7 +186,7 @@ __brew_internal_commands() {
     'log:Show the `git log` for formula or cask, or show the log for the Homebrew repository if no formula or cask is provided'
     'migrate:Migrate renamed packages to new names, where formula are old names of packages'
     'missing:Check the given formula kegs for missing dependencies'
-    'nodenv-sync:Create symlinks for Homebrew'\''s installed NodeJS versions in ~/.nodenv/versions'
+    'nodenv-sync:Create symlinks for Homebrew'\''s installed NodeJS versions in `~/.nodenv/versions`'
     'options:Show install options specific to formula'
     'outdated:List installed casks and formulae that have an updated version available'
     'pin:Pin the specified formula, preventing them from being upgraded when issuing the `brew upgrade` formula command'
@@ -197,8 +197,8 @@ __brew_internal_commands() {
     'pr-pull:Download and publish bottles, and apply the bottle commit from a pull request with artifacts generated by GitHub Actions'
     'pr-upload:Apply the bottle commit and publish bottles to a host'
     'prof:Run Homebrew with a Ruby profiler'
-    'pyenv-sync:Create symlinks for Homebrew'\''s installed Python versions in ~/.pyenv/versions'
+    'pyenv-sync:Create symlinks for Homebrew'\''s installed Python versions in `~/.pyenv/versions`'
-    'rbenv-sync:Create symlinks for Homebrew'\''s installed Ruby versions in ~/.rbenv/versions'
+    'rbenv-sync:Create symlinks for Homebrew'\''s installed Ruby versions in `~/.rbenv/versions`'
     'readall:Import all items from the specified tap, or from all installed taps if none is provided'
     'reinstall:Uninstall and then reinstall a formula or cask using the same options it was originally installed with, plus any appended options specific to a formula'
     'release:Create a new draft Homebrew/brew release with the appropriate version number and release notes'
@@ -1045,7 +1045,7 @@ _brew_instal() {
     '(--cask --build-from-source --build-bottle)--force-bottle[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]' \
     '(--cask)--git[Create a Git repository, useful for creating patches to the software]' \
     '--help[Show this message]' \
-    '(--cask --only-dependencies)--ignore-dependencies[An unsupported Homebrew development flag to skip installing any dependencies of any kind. If the dependencies are not already present, the formula will have issues. If you'\''re not developing Homebrew, consider adjusting your PATH rather than using this flag]' \
+    '(--cask --only-dependencies)--ignore-dependencies[An unsupported Homebrew development option to skip installing any dependencies of any kind. If the dependencies are not already present, the formula will have issues. If you'\''re not developing Homebrew, consider adjusting your PATH rather than using this option]' \
     '(--cask)--include-test[Install testing dependencies required to run `brew test` formula]' \
     '(--formula)--input-methoddir[Target location for Input Methods (default: `~/Library/Input Methods`)]' \
     '(--cask)--interactive[Download and patch formula, then open a shell. This allows the user to run `./configure --help` and otherwise determine how to turn the software package into a Homebrew package]' \
@@ -1067,7 +1067,7 @@ _brew_instal() {
     '(--formula)--servicedir[Target location for Services (default: `~/Library/Services`)]' \
     '(--formula)--skip-cask-deps[Skip installing cask dependencies]' \
     '(--cask)--skip-post-install[Install but skip any post-install steps]' \
-    '--verbose[Print the verification and postinstall steps]' \
+    '--verbose[Print the verification and post-install steps]' \
     '(--formula)--vst-plugindir[Target location for VST Plugins (default: `~/Library/Audio/Plug-Ins/VST`)]' \
     '(--formula)--vst3-plugindir[Target location for VST3 Plugins (default: `~/Library/Audio/Plug-Ins/VST3`)]' \
     '(--formula)--zap[For use with `brew reinstall --cask`. Remove all files associated with a cask. *May remove files which are shared between applications.*]' \
@@ -1103,7 +1103,7 @@ _brew_install() {
     '(--cask --build-from-source --build-bottle)--force-bottle[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]' \
     '(--cask)--git[Create a Git repository, useful for creating patches to the software]' \
     '--help[Show this message]' \
-    '(--cask --only-dependencies)--ignore-dependencies[An unsupported Homebrew development flag to skip installing any dependencies of any kind. If the dependencies are not already present, the formula will have issues. If you'\''re not developing Homebrew, consider adjusting your PATH rather than using this flag]' \
+    '(--cask --only-dependencies)--ignore-dependencies[An unsupported Homebrew development option to skip installing any dependencies of any kind. If the dependencies are not already present, the formula will have issues. If you'\''re not developing Homebrew, consider adjusting your PATH rather than using this option]' \
     '(--cask)--include-test[Install testing dependencies required to run `brew test` formula]' \
     '(--formula)--input-methoddir[Target location for Input Methods (default: `~/Library/Input Methods`)]' \
     '(--cask)--interactive[Download and patch formula, then open a shell. This allows the user to run `./configure --help` and otherwise determine how to turn the software package into a Homebrew package]' \
@@ -1125,7 +1125,7 @@ _brew_install() {
     '(--formula)--servicedir[Target location for Services (default: `~/Library/Services`)]' \
     '(--formula)--skip-cask-deps[Skip installing cask dependencies]' \
     '(--cask)--skip-post-install[Install but skip any post-install steps]' \
-    '--verbose[Print the verification and postinstall steps]' \
+    '--verbose[Print the verification and post-install steps]' \
     '(--formula)--vst-plugindir[Target location for VST Plugins (default: `~/Library/Audio/Plug-Ins/VST`)]' \
     '(--formula)--vst3-plugindir[Target location for VST3 Plugins (default: `~/Library/Audio/Plug-Ins/VST3`)]' \
     '(--formula)--zap[For use with `brew reinstall --cask`. Remove all files associated with a cask. *May remove files which are shared between applications.*]' \
@@ -1559,7 +1559,7 @@ _brew_readall() {
     '--no-simulate[Don'\''t simulate other system configurations when checking formulae and casks]' \
     '--os[Read using the given operating system. (Pass `all` to simulate all operating systems.)]' \
     '--quiet[Make some output more quiet]' \
-    '--syntax[Syntax-check all of Homebrew'\''s Ruby files (if no `tap` is passed)]' \
+    '--syntax[Syntax-check all of Homebrew'\''s Ruby files (if no tap is passed)]' \
     '--verbose[Make some output more verbose]' \
     - tap \
     '*::tap:__brew_any_tap'
@@ -1600,7 +1600,7 @@ _brew_reinstall() {
     '(--formula)--screen-saverdir[Target location for Screen Savers (default: `~/Library/Screen Savers`)]' \
     '(--formula)--servicedir[Target location for Services (default: `~/Library/Services`)]' \
     '(--formula)--skip-cask-deps[Skip installing cask dependencies]' \
-    '--verbose[Print the verification and postinstall steps]' \
+    '--verbose[Print the verification and post-install steps]' \
     '(--formula)--vst-plugindir[Target location for VST Plugins (default: `~/Library/Audio/Plug-Ins/VST`)]' \
     '(--formula)--vst3-plugindir[Target location for VST3 Plugins (default: `~/Library/Audio/Plug-Ins/VST3`)]' \
     '(--formula)--zap[For use with `brew reinstall --cask`. Remove all files associated with a cask. *May remove files which are shared between applications.*]' \
@@ -2074,7 +2074,7 @@ _brew_upgrade() {
     '(--formula)--screen-saverdir[Target location for Screen Savers (default: `~/Library/Screen Savers`)]' \
     '(--formula)--servicedir[Target location for Services (default: `~/Library/Services`)]' \
     '(--formula)--skip-cask-deps[Skip installing cask dependencies]' \
-    '--verbose[Print the verification and postinstall steps]' \
+    '--verbose[Print the verification and post-install steps]' \
     '(--formula)--vst-plugindir[Target location for VST Plugins (default: `~/Library/Audio/Plug-Ins/VST`)]' \
     '(--formula)--vst3-plugindir[Target location for VST3 Plugins (default: `~/Library/Audio/Plug-Ins/VST3`)]' \
     - outdated_formula \

docs/Acceptable-Casks.md

@@ -40,7 +40,7 @@ When an app exists in more than one language or has different regional editions,
 
 ### Trial and Freemium versions
 
-Before submitting a trial, make sure it can be made into a full working version without needing to be redownloaded. If an app provides a trial but the only way to buy the full version is via the Mac App Store, it does not belong in any of the official repos. Freemium versions are fine.
+Before submitting a trial, make sure it can be made into a full working version without needing to be redownloaded. If an app provides a trial but the only way to buy the full version is via the Mac App Store, it does not belong in any of the official repositories. Freemium versions are fine.
 
 ### Forks and apps with conflicting names
 
@@ -95,14 +95,14 @@ However, there is a difference between discoverability (finding new apps you did
 
 ## Rejected Casks
 
-Before submitting a cask to any of our repos, you must read our [documentation on acceptable casks](#finding-a-home-for-your-cask) and perform a (at least quick) search to see if there were any previous attempts to introduce it.
+Before submitting a cask to any of our repositories, you must read our [documentation on acceptable casks](#finding-a-home-for-your-cask) and perform a (at least quick) search to see if there were any previous attempts to introduce it.
 
 Common reasons to reject a cask entirely:
 
 * We have strong reasons to believe including the cask can put the whole project at risk. Happened only once so far, [with Popcorn Time](https://github.com/Homebrew/homebrew-cask/pull/3954).
 * Cask is unreasonably difficult to maintain. Examples have included [Audacity](https://github.com/Homebrew/homebrew-cask/pull/27517) and [older Java development casks](https://github.com/Homebrew/homebrew-cask/issues/57387).
 * App is a trial version, and the only way to acquire the full version is through the Mac App Store.
-  * Similarly (and trickier to spot), the app has moved to the Mac App Store but still provides old versions via direct download. We reject these in all official repos so users don’t get stuck using an old version, wrongly thinking they’re using the most up-to-date one (which, amongst other things, might be a security risk).
+  * Similarly (and trickier to spot), the app has moved to the Mac App Store but still provides old versions via direct download. We reject these in all official repositories so users don’t get stuck using an old version, wrongly thinking they’re using the most up-to-date one (which, amongst other things, might be a security risk).
 * App is both open-source and CLI-only (i.e. it only uses the `binary` artifact). In that case, and [in the spirit of deduplication](https://github.com/Homebrew/homebrew-cask/issues/15603), submit it first to [homebrew/core](https://github.com/Homebrew/homebrew-core) as a formula that builds from source. If it is rejected, you may then try again as a cask (link to the issue from your pull request so we can see the discussion and reasoning for rejection).
 * App is open-source and has a GUI but no compiled versions (or only old ones) are provided. It’s better to have them in [homebrew/core](https://github.com/Homebrew/homebrew-core) so users don’t get perpetually outdated versions. See [`gedit`](https://github.com/Homebrew/homebrew-cask/pull/23360) for example.
 * Cask has been rejected before due to an issue we cannot fix, and the new submission doesn’t fix that. An example would be the [first submission of `soapui`](https://github.com/Homebrew/homebrew-cask/pull/4939), whose installation problems were not fixed in the two [subsequent](https://github.com/Homebrew/homebrew-cask/pull/9969) [submissions](https://github.com/Homebrew/homebrew-cask/pull/10606).

docs/Adding-Software-to-Homebrew.md

@@ -250,19 +250,18 @@ See the [Acceptable Casks documentation](Acceptable-Casks.md#finding-a-home-for-
 
 Hop into your tap and check to make sure your new cask is there:
 
-```bash
+```console
 $ cd "$(brew --repository)"/Library/Taps/homebrew/homebrew-cask
 $ git status
-# On branch master
+On branch master
-# Untracked files:
+Untracked files:
-#   (use "git add <file>..." to include in what will be committed)
+  (use "git add <file>..." to include in what will be committed)
-#
+        Casks/m/my-new-cask.rb
-#       Casks/my-new-cask.rb
 ```
 
 So far, so good. Now make a feature branch `my-new-cask-branch` that you’ll use in your pull request:
 
-```bash
+```console
 $ git checkout -b my-new-cask-branch
 Switched to a new branch 'my-new-cask-branch'
 ```

docs/Cask-Cookbook.md

@@ -19,7 +19,7 @@ end
 * Table of Contents
 {:toc}
 
-## The Cask Language Is Declarative
+## The cask language is declarative
 
 Each cask contains a series of stanzas (or “fields”) which *declare* how the software is to be obtained and installed. In a declarative language, the author does not need to worry about **order**. As long as all the needed fields are present, Homebrew Cask will figure out what needs to be done at install time.
 
@@ -27,7 +27,7 @@ To make maintenance easier, the most-frequently-updated stanzas are usually plac
 
 Exception: `do` blocks such as `postflight` may enclose a block of pure Ruby code. Lines within that block follow a procedural (order-dependent) paradigm.
 
-## Header Line Details
+## Header line details
 
 The first non-comment line in a cask follows the form:
 
@@ -101,7 +101,7 @@ Note that every stanza that has additional parameters (`:symbols` after a `,`) s
 
 ## Stanzas
 
-### Required Stanzas
+### Required stanzas
 
 Each of the following stanzas is required for every cask.
 
@@ -114,7 +114,7 @@ Each of the following stanzas is required for every cask.
 | [`desc`](#stanza-desc)       | no                            | One-line description of the cask. Shown when running `brew info`.
 | `homepage`                   | no                            | Application homepage; used for the `brew home` command.
 
-### At Least One Artifact Stanza Is Also Required
+### At least one artifact stanza is also required
 
 Each cask must declare one or more *artifacts* (i.e. something to install).
 
@@ -143,7 +143,7 @@ Each cask must declare one or more *artifacts* (i.e. something to install).
 | `artifact`                       | yes                           | Relative path to an arbitrary path that should be moved on installation. Must provide an absolute path as a `target`. (Example: [free-gpgmail.rb](https://github.com/Homebrew/homebrew-cask/blob/b3c438d608d9702380edf10d5495e0727cf17108/Casks/f/free-gpgmail.rb#L44)) This is only for unusual cases; the `app` stanza is strongly preferred when moving `.app` bundles.
 | `stage_only`                     | no                            | `true`. Asserts that the cask contains no activatable artifacts.
 
-### Optional Stanzas
+### Optional stanzas
 
 | name                                       | multiple occurrences allowed? | value |
 | ------------------------------------------ | :---------------------------: | ----- |
@@ -178,7 +178,7 @@ by default moves the source to:
 /Applications/Alfred 2.app
 ```
 
-#### Renaming the Target
+#### Renaming the target
 
 You can rename the target which appears in your `/Applications` directory by adding a `target:` key to `app`. Example (from [scala-ide.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/s/scala-ide.rb#L24)):
 
@@ -186,7 +186,7 @@ You can rename the target which appears in your `/Applications` directory by add
 app "eclipse.app", target: "Scala IDE.app"
 ```
 
-#### *target* May Contain an Absolute Path
+#### *target* may contain an absolute path
 
 If `target:` has a leading slash, it is interpreted as an absolute path. The containing directory for the absolute path will be created if it does not already exist. Example (from [sapmachine-jdk.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/s/sapmachine-jdk.rb#L21)):
 
@@ -194,11 +194,11 @@ If `target:` has a leading slash, it is interpreted as an absolute path. The con
 artifact "sapmachine-jdk-#{version}.jdk", target: "/Library/Java/JavaVirtualMachines/sapmachine-jdk-#{version}.jdk"
 ```
 
-#### *target* Works on Most Artifact Types
+#### *target* works on most artifact types
 
 The `target:` key works similarly for most cask artifacts, such as `app`, `binary`, `colorpicker`, `dictionary`, `font`, `input_method`, `internet_plugin`, `keyboard_layout`, `prefpane`, `qlplugin`, `mdimporter`, `screen_saver`, `service`, `suite`, `audio_unit_plugin`, `vst_plugin`, `vst3_plugin`, and `artifact`.
 
-#### *target* Should Only Be Used in Select Cases
+#### *target* should only be used in select cases
 
 Don’t use `target:` for aesthetic reasons, like removing version numbers (`app "Slack #{version}.app", target: "Slack.app"`). Use it when it makes sense functionally and document your reason clearly in the cask, using one of the templates: [for clarity](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/i/imagemin.rb#L10); [for consistency](https://github.com/Homebrew/homebrew-cask/blob/8be96e3658ff7ab66ca40723c3018fc5e35e3735/Casks/x-moto.rb#L16); [to prevent conflicts](https://github.com/Homebrew/homebrew-cask/blob/4472df441468e2aa657005550e2b951c2ef817f4/Casks/t/telegram-desktop.rb#L20); [due to developer suggestion](https://github.com/Homebrew/homebrew-cask/blob/ff3e9c4a6623af44b8a071027e8dcf3f4edfc6d9/Casks/kivy.rb#L12).
 
@@ -243,7 +243,7 @@ Sometimes there are particularities with the installation of a piece of software
 
 To avoid flooding users with too many messages (thus desensitising them to the important ones), `caveats` should be used sparingly and exclusively for installation-related matters. If you’re not sure a `caveat` you find pertinent is installation-related or not, ask a maintainer. As a general rule, if your case isn’t already covered in our comprehensive [`caveats Mini-DSL`](#caveats-mini-dsl), it’s unlikely to be accepted.
 
-#### `caveats` as a String
+#### `caveats` as a string
 
 When `caveats` is a string, it is evaluated at compile time. The following methods are available for interpolation if `caveats` is placed in its customary position at the end of the cask:
 
@@ -261,11 +261,11 @@ Example:
 caveats "Using #{token} may be hazardous to your health."
 ```
 
-#### `caveats` as a Block
+#### `caveats` as a block
 
 When `caveats` is a Ruby block, evaluation is deferred until install time. Within a block you may refer to the `@cask` instance variable, and invoke [any method available on `@cask`](https://rubydoc.brew.sh/Cask/Cask).
 
-#### `caveats` Mini-DSL
+#### `caveats` mini-DSL
 
 There is a mini-DSL available within `caveats` blocks.
 
@@ -346,7 +346,7 @@ depends_on formula: "unar"
 
 #### `depends_on` *macos*
 
-##### Requiring an Exact macOS Release
+##### Requiring an exact macOS release
 
 The value for `depends_on macos:` may be a symbol or an array of symbols, listing the exact compatible macOS releases. The available values for macOS releases are defined in the [MacOSVersion class](https://rubydoc.brew.sh/MacOSVersion.html).
 
@@ -360,7 +360,7 @@ depends_on macos: [
 ]
 ```
 
-##### Setting a Minimum macOS Release
+##### Setting a minimum macOS release
 
 `depends_on macos:` can also accept a string starting with a comparison operator such as `>=`, followed by an macOS release in the form above. The following is a valid expression meaning “at least macOS Big Sur (11.0)”:
 
@@ -391,7 +391,7 @@ depends_on arch: [:x86_64]          # same meaning as above
 depends_on arch: :arm64
 ```
 
-#### `depends_on` Parameters
+#### `depends_on` parameters
 
 | key        | description |
 | ---------- | ----------- |
@@ -469,11 +469,11 @@ depends_on arch: :arm64
 
 The stanzas `preflight`, `postflight`, `uninstall_preflight`, and `uninstall_postflight` define operations to be run before or after installation or uninstallation.
 
-#### Evaluation of Blocks is Always Deferred
+#### Evaluation of blocks is always deferred
 
 The Ruby blocks defined by these stanzas are not evaluated until install time or uninstall time. Within a block you may refer to the `@cask` instance variable, and invoke [any method available on `@cask`](https://rubydoc.brew.sh/Cask/Cask).
 
-#### `*flight` Mini-DSL
+#### `*flight` mini-DSL
 
 There is a mini-DSL available within these blocks.
 
@@ -676,7 +676,7 @@ The `sha256` value is usually calculated by the `shasum` command:
 shasum --algorithm 256 <file>
 ```
 
-#### Special Value `:no_check`
+#### Special value `:no_check`
 
 The special value `sha256 :no_check` is used to turn off SHA checking whenever checksumming is impractical due to the upstream configuration.
 
@@ -700,11 +700,11 @@ The value of `suite` is never an `.app` bundle, but a plain directory.
 
 > If you cannot design a working `uninstall` stanza, please submit your cask anyway. The maintainers can help you write an `uninstall` stanza, just ask!
 
-#### `uninstall pkgutil:` Is The Easiest and Most Useful
+#### `uninstall pkgutil:` is the easiest and most useful
 
 The easiest and most useful `uninstall` directive is [`pkgutil:`](#uninstall-pkgutil). It should cover most use cases.
 
-#### `uninstall` Is Required for Casks That Install using `pkg` or `installer manual:`
+#### `uninstall` is required for casks that install using `pkg` or `installer manual:`
 
 For most casks, uninstall actions are determined automatically, and an explicit `uninstall` stanza is not needed. However, a cask which uses the `pkg` or `installer manual:` stanzas will **not** know how to uninstall correctly unless an `uninstall` stanza is given.
 
@@ -712,11 +712,11 @@ So, while the [cask DSL](#required-stanzas) does not enforce the requirement, it
 
 The `uninstall` stanza is available for non-`pkg` casks, and is useful for a few corner cases. However, the documentation below concerns the typical case of using `uninstall` to define procedures for a `pkg`.
 
-#### There Are Multiple Uninstall Techniques
+#### There are multiple uninstall techniques
 
 Since `pkg` installers can do arbitrary things, different techniques are needed to uninstall in each case. You may need to specify one, or several, of the following key/value pairs as arguments to `uninstall`.
 
-#### Summary of Keys
+#### Summary of keys
 
 * **`early_script:`** (string or hash) - like [`script:`](#uninstall-script), but runs early (for special cases, best avoided)
 * [`launchctl:`](#uninstall-launchctl) (string or array) - IDs of `launchd` jobs to remove
@@ -757,7 +757,7 @@ IDs for the most recently installed packages can be listed using [`list_recent_p
 "$(brew --repository homebrew/cask)/developer/bin/list_pkg_ids_by_regexp" <regular-expression>
 ```
 
-#### List Files Associated With a Package ID
+#### List files associated with a package ID
 
 Once you know the ID for an installed package (see above), you can list all files on your system associated with that package ID using the macOS `pkgutil` command:
 
@@ -879,7 +879,7 @@ To remove user-specific files, use the [`zap` stanza](#stanza-zap).
 
 `trash:` arguments follow the same rules listed above for `delete:`.
 
-#### Working With a `.pkg` File Manually
+#### Working with a `.pkg` file manually
 
 Advanced users may wish to work with a `.pkg` file manually, without having the package installed.
 
@@ -911,11 +911,11 @@ A fully manual method for finding bundle IDs in a package file follows:
 
 ### Stanza: `url`
 
-#### HTTPS URLs are Preferred
+#### HTTPS URLs are preferred
 
 If available, an HTTPS URL is preferred. A plain HTTP URL should only be used in the absence of a secure alternative.
 
-#### Additional `url` Parameters
+#### Additional `url` parameters
 
 When a plain URL string is insufficient to fetch a file, additional information may be provided to the `curl`-based downloader, in the form of key/value pairs appended to `url`:
 
@@ -929,7 +929,7 @@ When a plain URL string is insufficient to fetch a file, additional information
 | `user_agent:`      | string holding the user agent to set for the download request. Can also be set to the symbol `:fake`, which will use a generic browser-like user agent string. We prefer `:fake` when the server does not require a specific user agent.
 | `data:`            | hash of parameters to be set in the POST request (Example: [segger-jlink.rb](https://github.com/Homebrew/homebrew-cask/blob/38ac55614f146d68ae317594f0c119e9acbd7c9e/Casks/s/segger-jlink.rb#L6-L11))
 
-#### When URL and Homepage Domains Differ, Add `verified:`
+#### When URL and homepage domains differ, add `verified:`
 
 When the domains of `url` and `homepage` differ, the discrepancy should be documented with the `verified:` parameter, repeating the smallest possible portion of the URL that uniquely identifies the app or vendor, excluding the protocol. (Example: [shotcut.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/s/shotcut.rb#L5-L6))
 
@@ -937,7 +937,7 @@ This must be added so a user auditing the cask knows the URL was verified by the
 
 The parameter doesn’t mean you should trust the source blindly, but we only approve casks in which users can easily verify its authenticity with basic means, such as checking the official homepage or public repository. Occasionally, slightly more elaborate techniques may be used, such as inspecting a [`livecheck`](#stanza-livecheck) URL we established as official. Cases where such quick verifications aren’t possible (e.g. when the download URL is behind a registration wall) are [treated in a stricter manner](https://docs.brew.sh/Acceptable-Casks#unofficial-vendorless-and-walled-builds).
 
-#### Difficulty Finding a URL
+#### Difficulty finding a URL
 
 Web browsers may obscure the direct `url` download location for a variety of reasons. Homebrew Cask supplies a [`list_url_attributes_on_file`](https://github.com/Homebrew/homebrew-cask/blob/HEAD/developer/bin/list_url_attributes_on_file) script which can read extended file attributes to extract the actual source URL of most files downloaded by a browser on macOS. The script usually emits multiple candidate URLs; you may have to test each of them:
 
@@ -983,13 +983,13 @@ If these formats are not available, and the application is macOS-exclusive (othe
 
     https://sourceforge.net/projects/<project_name>/files/latest/download
 
-#### Some Providers Block Command-line Downloads
+#### Some providers block command-line downloads
 
 Some hosting providers actively block command-line HTTP clients. Such URLs cannot be used in casks.
 
 Other providers may use URLs that change periodically, or even on each visit (example: FossHub). While some cases [could be circumvented](#using-a-block-to-defer-code-execution), they tend to occur when the vendor is actively trying to prevent automated downloads, so we prefer to not add those casks to the main repository.
 
-#### Using a Block to Defer Code Execution
+#### Using a block to defer code execution
 
 Some casks—notably nightlies—have versioned download URLs but are updated so often that they become impractical to keep current with the usual process. For those, we want to dynamically determine `url`.
 
@@ -999,7 +999,7 @@ In theory, one can write arbitrary Ruby code right in the cask definition to fet
 
 However, this typically involves an HTTP round trip to a landing site, which may take a long time. Because of the way Homebrew Cask loads and parses casks, it is not acceptable that such expensive operations be performed directly in the body of a cask definition.
 
-##### Writing the Block
+##### Writing the block
 
 Similar to the `preflight`, `postflight`, `uninstall_preflight`, and `uninstall_postflight` blocks, the `url` stanza offers an optional *block syntax*:
 
@@ -1020,7 +1020,7 @@ You can use the `url` stanza with either a direct argument or a block but not wi
 
 Example of using the block syntax: [vlc-nightly.rb](https://github.com/Homebrew/homebrew-cask-versions/blob/d3b9d0fdcf83f1f87c3ad64a852323a6e687c5f7/Casks/vlc-nightly.rb#L7-L12)
 
-##### Mixing Additional URL Parameters With the Block Syntax
+##### Mixing additional URL parameters with the block syntax
 
 In rare cases, you might need to set URL parameters like `cookies` or `referer` while also using the block syntax.
 
@@ -1058,7 +1058,7 @@ version "1.2.3build4"
 url "https://example.com/#{version.sub(%r{build\d+}, '')}/file-version-#{version}.dmg"
 ```
 
-#### `version` Methods
+#### `version` methods
 
 The examples above can become hard to read, however. Since many of these changes are common, we provide a number of helpers to clearly interpret otherwise obtuse cases:
 
@@ -1081,7 +1081,7 @@ Finally, there is `csv` which returns an array of comma-separated values. `csv`,
 
 #### `version :latest`
 
-The special value `:latest` is used when
+The special value `:latest` is used when:
 
 * `url` does not contain any version information and there is no way to retrieve
   the version using a `livecheck`, or
@@ -1091,7 +1091,7 @@ The special value `:latest` is used when
 
 ### Stanza: `zap`
 
-#### `zap` Purpose
+#### `zap` purpose
 
 The `zap` stanza describes a more complete uninstallation of files associated with a cask. The `zap` procedures will never be performed by default, but only if the user uses `--zap` on `uninstall`:
 
@@ -1114,13 +1114,13 @@ Appending `--force` to the command will allow you to perform these actions even
 brew uninstall --zap --force firefox
 ```
 
-#### `zap` Syntax
+#### `zap` syntax
 
 The form of the `zap` stanza follows the [`uninstall` stanza](#stanza-uninstall). All the same directives are available. The `trash:` key is preferred over `delete:`.
 
 Example: [dropbox.rb](https://github.com/Homebrew/homebrew-cask/blob/974a55ade77bb4edc8bbb80ef72eec83ae0e76c0/Casks/d/dropbox.rb#L30-L68)
 
-#### `zap` Creation
+#### `zap` creation
 
 The simplest method is to use [@nrlquaker's CreateZap](https://github.com/nrlquaker/homebrew-createzap), which can automatically generate the stanza. In a few instances it may fail to pick up anything and manual creation may be required.
 
@@ -1131,7 +1131,7 @@ Manual creation can be facilitated with:
 * An uninstaller tool such as [AppCleaner](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/a/appcleaner.rb).
 * Inspection of the usual paths, i.e. `/Library/{'Application Support',LaunchAgents,LaunchDaemons,Frameworks,Logs,Preferences,PrivilegedHelperTools}` and `~/Library/{'Application Support',Caches,Containers,LaunchAgents,Logs,Preferences,'Saved Application State'}`.
 
-## Conditional Statements
+## Conditional statements
 
 ### Handling different system configurations
 
@@ -1201,11 +1201,11 @@ cask "calibre" do
 
 Such `on_<system>` blocks can be nested and contain other stanzas not listed here. Examples: [calhash.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/c/calhash.rb), [openzfs.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/o/openzfs.rb), [r.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/r/r.rb), [wireshark.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/w/wireshark.rb)
 
-### Switch Between Languages or Regions
+### Switch between languages or regions
 
 If a cask is available in multiple languages, you can use the [`language` stanza](#stanza-language) to switch between languages or regions based on the system locale.
 
-## Arbitrary Ruby Methods
+## Arbitrary Ruby methods
 
 In the exceptional case that the cask DSL is insufficient, it is possible to define arbitrary Ruby variables and methods inside the cask by creating a `Utils` namespace. Example:
 
@@ -1254,9 +1254,9 @@ Software vendors are often inconsistent with their naming. By enforcing strict n
 
 Details of software names and brands will inevitably be lost in the conversion to a minimal token. To capture the vendor’s full name for a distribution, use the [`name`](#stanza-name) within a cask. `name` accepts an unrestricted UTF-8 string.
 
-### Finding the Simplified Name of the Vendor’s Distribution
+### Finding the simplified name of the vendor’s distribution
 
-#### Simplified Names of Apps
+#### Simplified names of apps
 
 * Start with the exact name of the application bundle as it appears on disk, such as `Google Chrome.app`.
 
@@ -1303,17 +1303,17 @@ Details of software names and brands will inevitably be lost in the conversion t
 
 * As a last resort, translate the name of the app bundle into English.
 
-#### Simplified Names of `pkg`-based Installers
+#### Simplified names of `pkg`-based installers
 
 * The Simplified Name of a `pkg` may be more tricky to determine than that of an App. If a `pkg` installs an App, then use that App name with the rules above. If not, just create the best name you can, based on the vendor’s web page.
 
-#### Simplified Names of non-App Software
+#### Simplified names of non-App software
 
 * Currently, rules for generating a token are not well-defined for Preference Panes, QuickLook plugins, and several other types of software installable by Homebrew Cask. Just create the best name you can, based on the filename on disk or the vendor’s web page. Watch out for duplicates.
 
   Non-app tokens should become more standardized in the future.
 
-### Converting the Simplified Name To a Token
+### Converting the simplified name to a token
 
 The token is the primary identifier for a package in this project. It’s the unique string users refer to when operating on the cask.
 
@@ -1331,15 +1331,15 @@ To convert the App’s Simplified Name (above) to a token:
 * Collapse a series of multiple hyphens into one hyphen.
 * Delete a leading or trailing hyphen.
 
-### Cask Filenames
+### Cask filenames
 
 Casks are stored in a Ruby file named after the token, with the file extension `.rb`.
 
-### Cask Headers
+### Cask headers
 
 The token is also given in the header line for each cask.
 
-### Cask Token Examples
+### Cask token examples
 
 These illustrate most of the rules for generating a token:
 
@@ -1351,22 +1351,22 @@ App Name on Disk       | Simplified App Name | Cask Token       | Filename
 `LPK25 Editor.app`     | LPK25 Editor        | lpk25-editor     | `lpk25-editor.rb`
 `Sublime Text 2.app`   | Sublime Text        | sublime-text     | `sublime-text.rb`
 
-#### Tap-Specific Cask Token Examples
+#### Tap-specific cask token examples
 
 Cask taps have naming conventions specific to each tap.
 
 * [Homebrew/cask-versions](https://github.com/Homebrew/homebrew-cask-versions/blob/HEAD/CONTRIBUTING.md#naming-versions-casks)
 * [Homebrew/cask-fonts](https://github.com/Homebrew/homebrew-cask-fonts/blob/HEAD/CONTRIBUTING.md#naming-font-casks)
 
-### Special Affixes
+### Special affixes
 
 A few situations require a prefix or suffix to be added to the token.
 
-#### Token Overlap
+#### Token overlap
 
 When the token for a new cask would otherwise conflict with the token of an already existing cask, the nature of that overlap dictates the token, potentially for both casks. See [Forks and Apps with Conflicting Names](Acceptable-Casks.md#forks-and-apps-with-conflicting-names) for information on how to proceed.
 
-#### Potentially Misleading Name
+#### Potentially misleading name
 
 If the token for a piece of unofficial software that interacts with a popular service would make it look official and the vendor is not authorised to use the name, [a prefix must be added](Acceptable-Casks.md#forks-and-apps-with-conflicting-names) for disambiguation.
 

docs/Checksum_Deprecation.md

@@ -2,7 +2,7 @@
 
 In early 2015 Homebrew started the process of deprecating _SHA1_ for package
 integrity verification. Since then formulae under the Homebrew organisation
-have been migrated to use _SHA256_ for verification; this includes both source
+have been migrated to use _SHA-256_ for verification; this includes both source
 packages and our precompiled packages (bottles).
 
 Homebrew has since stopped supporting _SHA1_ and _MD5_ entirely.
@@ -15,4 +15,4 @@ This is enforced in the same way _MD5_ is, by blocking the installation of that
 individual formula until the checksum is migrated.
 
 This means custom taps, local custom formulae, etc. need to be migrated to use
-_SHA256_ before you can install them.
+_SHA-256_ before you can install them.

docs/Common-Issues-for-Core-Contributors.md

@@ -16,11 +16,11 @@ Follow these steps to fix this issue:
 Alternative instructions using `pr-pull`:
 
 * `git reset --hard <SHA>` in `homebrew/core` to reset to the commit before all the commits created by `brew pr-pull`.
-* `brew pr-pull <options>` to upload the right bottles. Add the `--warn-on-upload-failure` flag if the bottles have been partially uploaded and you're certain that the bottle checksums will match the checksums already present in the `bottle do` block of the formula.
+* `brew pr-pull <options>` to upload the right bottles. Add the `--warn-on-upload-failure` switch if the bottles have been partially uploaded and you're certain that the bottle checksums will match the checksums already present in the `bottle do` block of the formula.
 * `git reset --hard origin/master` to return to the latest commit and discard the commits made by `brew pr-pull`.
 
 ### `ld: internal error: atom not found in symbolIndex(__ZN10SQInstance3GetERK11SQObjectPtrRS0_) for architecture x86_64`
 
 The exact atom may be different.
 
-This can be caused by passing the obsolete `-s` flag to the linker and can be fixed [using `inreplace`](https://github.com/Homebrew/homebrew-core/commit/c4ad981d788b21a406a6efe7748f2922986919a8).
+This can be caused by passing the obsolete `-s` option to the linker and can be fixed [using `inreplace`](https://github.com/Homebrew/homebrew-core/commit/c4ad981d788b21a406a6efe7748f2922986919a8).

docs/Common-Issues.md

@@ -133,7 +133,9 @@ xcode-select --install
 brew upgrade
 ```
 
-## Cask - cURL error
+## Homebrew Cask issues
+
+### Cask - cURL error
 
 First, let's tackle a common problem: do you have a `.curlrc` file? Check with `ls -A ~ | grep .curlrc` (if you get a result, the file exists). Those are a frequent cause of issues of this nature. Before anything else, remove that file and try again. If it now works, do not open an issue. Incompatible `.curlrc` configurations must be fixed on your side.
 
@@ -142,7 +144,7 @@ If, however, you do not have a `.curlrc` or removing it did not work, let’s se
 1. Go to the vendor’s website (`brew home <cask_name>`).
 2. Find the download link for the app and click on it.
 
-### If the download works
+#### If the download works
 
 The cask is outdated. Let’s fix it:
 
@@ -151,7 +153,7 @@ The cask is outdated. Let’s fix it:
 
 Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/HEAD/CONTRIBUTING.md#updating-a-cask). If you get stumped, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and where you’re having trouble.
 
-### If the download does not work
+#### If the download does not work
 
 The issue isn’t in any way related to Homebrew Cask, but with the vendor or your connection.
 
@@ -161,7 +163,7 @@ If you’re sure the issue is not with your connection, contact the app’s vend
 
 **Do not open an issue.**
 
-## Cask - checksum does not match
+### Cask - checksum does not match
 
 First, check if the problem was with your download. Delete the downloaded file (its location will be pointed out in the error message) and try again.
 
@@ -173,7 +175,7 @@ If the problem persists, the cask must be outdated. It’ll likely need a new ve
 
 Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/HEAD/CONTRIBUTING.md#updating-a-cask). If you get stumped, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and where you’re having trouble.
 
-## Cask - permission denied
+### Cask - permission denied
 
 In this case, it’s likely your user account has no admin rights and therefore lacks permissions for writing to `/Applications`, which is the default install location. You can use [`--appdir`](https://github.com/Homebrew/homebrew-cask/blob/HEAD/USAGE.md#options) to choose where to install your applications.
 
@@ -183,7 +185,7 @@ Some app bundles don’t have certain permissions that are necessary for us to m
 
 Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/HEAD/CONTRIBUTING.md#updating-a-cask). If you get stumped, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and where you’re having trouble.
 
-## Cask - source is not there
+### Cask - source is not there
 
 First, you need to identify which artifact is not being handled correctly anymore. It’s explicit in the error message: if it says `It seems the App source…'` then the problem is with the [`app`](https://docs.brew.sh/Cask-Cookbook#stanza-app) stanza. This pattern is the same across [all artifacts](https://docs.brew.sh/Cask-Cookbook#at-least-one-artifact-stanza-is-also-required).
 
@@ -206,7 +208,7 @@ Note that occasionally the app’s name changes completely (from `SomeApp.app` t
 
 Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/HEAD/CONTRIBUTING.md#updating-a-cask). If you get stumped, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and where you’re having trouble.
 
-## Cask - wrong number of arguments
+### Cask - wrong number of arguments
 
 Make sure the issue really lies with your macOS version. To do so, try to install the software manually. If it is incompatible with your macOS version, it will tell you. In that case, there is nothing we can do to help you install the software, but we can add a [`depends_on macos:`](https://docs.brew.sh/Cask-Cookbook#depends_on-macos) stanza to prevent the cask from being installed on incompatible macOS versions.
 

docs/FAQ.md

@@ -198,7 +198,7 @@ In the resulting dialog, click the *Open* button to have macOS permanently allow
 
 <img src="assets/img/docs/gatekeeper-unidentified-open.png" width="532" alt="Gatekeeper unidentified developer open prompt">
 
-Alternatively, you may provide the [`--no-quarantine` flag](https://github.com/Homebrew/homebrew-cask/blob/HEAD/USAGE.md#options) at install time to not add this feature to a specific app.
+Alternatively, you may provide the [`--no-quarantine` switch](https://github.com/Homebrew/homebrew-cask/blob/HEAD/USAGE.md#options) at install time to not add this feature to a specific app.
 
 ## Why aren’t some apps included during `brew upgrade`?
 
@@ -225,7 +225,7 @@ If you still want to force software to be upgraded via Homebrew Cask, you can re
 
     brew upgrade <cask>
 
-Or use the `--greedy` flag:
+Or use the `--greedy` switch:
 
     brew upgrade --greedy
 

docs/Formula-Cookbook.md

@@ -210,7 +210,7 @@ When a version scheme of a formula fails to recognise a new version as newer it
 
 When you already have a lot of formulae installed, it's easy to miss a common dependency. You can double-check which libraries a binary links to with the `otool` command (perhaps you need to use `xcrun otool`):
 
-```sh
+```console
 $ otool -L /usr/local/bin/ldapvi
 /usr/local/bin/ldapvi:
     /usr/local/opt/openssl/lib/libssl.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0)
@@ -268,7 +268,7 @@ end
 
 [`jrnl`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/j/jrnl.rb) is an example of a formula that does this well. The end result means the user doesn't have to use `pip` or Python and can just run `jrnl`.
 
-For Python formulae, running `brew update-python-resources <formula>` will automatically add the necessary [`resource`](https://rubydoc.brew.sh/Formula#resource-class_method) stanzas for the dependencies of your Python application to the formula. Note that `brew update-python-resources` is run automatically by `brew create` if you pass the `--python` flag. If `brew update-python-resources` is unable to determine the correct `resource` stanzas, [homebrew-pypi-poet](https://github.com/tdsmith/homebrew-pypi-poet) is a good third-party alternative that may help.
+For Python formulae, running `brew update-python-resources <formula>` will automatically add the necessary [`resource`](https://rubydoc.brew.sh/Formula#resource-class_method) stanzas for the dependencies of your Python application to the formula. Note that `brew update-python-resources` is run automatically by `brew create` if you pass the `--python` switch. If `brew update-python-resources` is unable to determine the correct `resource` stanzas, [homebrew-pypi-poet](https://github.com/tdsmith/homebrew-pypi-poet) is a good third-party alternative that may help.
 
 ### Install the formula
 

docs/Homebrew-brew-Maintainer-Guide.md

@@ -41,7 +41,7 @@ There are many checks that run on every PR. The following is a quick list of the
 - `CI / vendored gems`: This checks whether there was a change to the vendored gems on Linux that needs to be committed to the PR branch.
 - `CI / test default formula (Linux)`: This runs `brew test-bot` on Linux to ensure it still works as expected.
 - `CI / syntax`: This is run first to check whether the PR passes `brew style` and `brew typecheck`. If this job fails the following jobs will not run.
-- `CI / tap syntax`: This runs `brew style` and `brew audit` on all official taps (note that although this runs on Linux, it does check all cask repos).
+- `CI / tap syntax`: This runs `brew style` and `brew audit` on all official taps (note that although this runs on Linux, it does check all cask repositories).
 - `CI / docker`: This builds and deploys a new Homebrew Docker image to GitHub Packages and Docker Hub.
 - `CI / test everything (macOS)`: This runs several checks on macOS including `brew tests`, `brew update-tests`, `brew test-bot --only-formulae --test-default-formula`, `brew readall` and `brew doctor`.
 - `CI / tests (generic OS)` and `CI / tests (Linux)`: These run `brew tests` with various options on Linux.

docs/How-To-Organize-AGM.md

@@ -130,13 +130,13 @@ using this quick command:_
 
 ## Pre-planning
 
-### Finding a Meeting Venue
+### Finding a meeting venue
 
 In the past, PLC hosted the AGM at the
 [THON Hotel Brussels City Centre](https://www.thonhotels.com/conference/belgium/brussels/thon-hotel-brussels-city-centre/?Persons=20)
 and arranged for a room block checking in the day before FOSDEM and AGM weekend, generally on Friday, and checking out the day after, generally Tuesday when the AGM is Monday.
 
-### Who Qualifies For AGM Travel Assistance
+### Who qualifies for AGM travel assistance
 
 Travel assistance is available for AGM participants who are expected to attend the AGM in-person.
 Those who have employers able to cover all or a part of the costs of attending FOSDEM should exhaust that

docs/Manpage.md

@@ -141,7 +141,12 @@ Show dependencies for *`formula`*. When given multiple formula arguments,
 show the intersection of dependencies for each formula. By default, `deps`
 shows all required and recommended dependencies.
 
-Note: `--missing` and `--skip-recommended` have precedence over `--include-*`.
+If any version of each formula argument is installed and no other options
+are passed, this command displays their actual runtime dependencies (similar
+to `brew linkage`), which may differ from the current versons' stated
+dependencies if the installed versions are outdated.
+
+*Note:* `--missing` and `--skip-recommended` have precedence over `--include-*`.
 
 * `-n`, `--topological`:
   Sort dependencies in topological order.
@@ -214,15 +219,16 @@ branch instead of the latest stable version along with some other behaviour chan
 
 ### `docs`
 
-Open Homebrew's online documentation (https://docs.brew.sh) in a browser.
+Open Homebrew's online documentation at <https://docs.brew.sh> in a browser.
 
 ### `doctor`, `dr` [`--list-checks`] [`--audit-debug`] [*`diagnostic_check`* ...]
 
 Check your system for potential problems. Will exit with a non-zero status
-if any potential problems are found. Please note that these warnings are just
+if any potential problems are found.
-used to help the Homebrew maintainers with debugging if you file an issue. If
+
-everything you use Homebrew for is working fine: please don't worry or file
+Please note that these warnings are just used to help the Homebrew maintainers
-an issue; just ignore this.
+with debugging if you file an issue. If 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, which can be run individually if provided as arguments.
@@ -292,7 +298,6 @@ Homebrew's own homepage if no argument is provided.
 ### `info`, `abv` [*`options`*] [*`formula`*|*`cask`* ...]
 
 Display brief statistics for your Homebrew installation.
-
 If a *`formula`* or *`cask`* is provided, show summary of information about it.
 
 * `--analytics`:
@@ -337,13 +342,13 @@ is already installed but outdated.
 * `-f`, `--force`:
   Install formulae without checking for previously installed keg-only or non-migrated versions. When installing casks, overwrite existing files (binaries and symlinks are excluded, unless originally from the same cask).
 * `-v`, `--verbose`:
-  Print the verification and postinstall steps.
+  Print the verification and post-install steps.
 * `-n`, `--dry-run`:
   Show what would be installed, but do not actually install anything.
 * `--formula`:
   Treat all named arguments as formulae.
 * `--ignore-dependencies`:
-  An unsupported Homebrew development flag to skip installing any dependencies of any kind. If the dependencies are not already present, the formula will have issues. If you're not developing Homebrew, consider adjusting your PATH rather than using this flag.
+  An unsupported Homebrew development option to skip installing any dependencies of any kind. If the dependencies are not already present, the formula will have issues. If you're not developing Homebrew, consider adjusting your PATH rather than using this option.
 * `--only-dependencies`:
   Install the dependencies with specified options but do not install the formula itself.
 * `--cc`:
@@ -402,9 +407,9 @@ List installed formulae that are not dependencies of another installed formula o
 
 ### `link`, `ln` [*`options`*] *`installed_formula`* [...]
 
-Symlink all of *`formula`*'s installed files into Homebrew's prefix. This
+Symlink all of *`formula`*'s installed files into Homebrew's prefix.
-is done automatically when you install formulae but can be useful for DIY
+This is done automatically when you install formulae but can be useful
-installations.
+for manual installations.
 
 * `--overwrite`:
   Delete files that already exist in the prefix while linking.
@@ -418,7 +423,6 @@ installations.
 ### `list`, `ls` [*`options`*] [*`installed_formula`*|*`installed_cask`* ...]
 
 List all installed formulae and casks.
-
 If *`formula`* is provided, summarise the paths within its current keg.
 If *`cask`* is provided, list its artifacts.
 
@@ -488,7 +492,7 @@ to be missing dependencies.
 
 ### `nodenv-sync`
 
-Create symlinks for Homebrew's installed NodeJS versions in ~/.nodenv/versions.
+Create symlinks for Homebrew's installed NodeJS versions in `~/.nodenv/versions`.
 
 Note that older version symlinks will also be created so e.g. NodeJS 19.1.0 will
 also be symlinked to 19.0.0.
@@ -541,14 +545,14 @@ Rerun the post-install steps for *`formula`*.
 
 ### `pyenv-sync`
 
-Create symlinks for Homebrew's installed Python versions in ~/.pyenv/versions.
+Create symlinks for Homebrew's installed Python versions in `~/.pyenv/versions`.
 
 Note that older patch version symlinks will be created and linked to the minor
 version so e.g. Python 3.11.0 will also be symlinked to 3.11.3.
 
 ### `rbenv-sync`
 
-Create symlinks for Homebrew's installed Ruby versions in ~/.rbenv/versions.
+Create symlinks for Homebrew's installed Ruby versions in `~/.rbenv/versions`.
 
 Note that older version symlinks will also be created so e.g. Ruby 3.2.1 will
 also be symlinked to 3.2.0.
@@ -567,7 +571,7 @@ all items or checking if any current formulae/casks have Ruby issues.
 * `--aliases`:
   Verify any alias symlinks in each tap.
 * `--syntax`:
-  Syntax-check all of Homebrew's Ruby files (if no `*`tap`*` is passed).
+  Syntax-check all of Homebrew's Ruby files (if no *`tap`* is passed).
 * `--eval-all`:
   Evaluate all available formulae and casks, whether installed or not. Implied if `HOMEBREW_EVAL_ALL` is set.
 * `--no-simulate`:
@@ -589,7 +593,7 @@ reinstalled formulae or, every 30 days, for all formulae.
 * `-f`, `--force`:
   Install without checking for previously installed keg-only or non-migrated versions.
 * `-v`, `--verbose`:
-  Print the verification and postinstall steps.
+  Print the verification and post-install steps.
 * `--formula`:
   Treat all named arguments as formulae.
 * `-s`, `--build-from-source`:
@@ -671,7 +675,6 @@ The shell can be specified explicitly with a supported shell name parameter. Unk
 ### `tap` [*`options`*] [*`user`*`/`*`repo`*] [*`URL`*]
 
 Tap a formula repository.
-
 If no arguments are provided, list all installed taps.
 
 With *`URL`* unspecified, tap a formula repository from GitHub using HTTPS.
@@ -698,7 +701,6 @@ using protocols other than HTTPS, e.g. SSH, git, HTTP, FTP(S), rsync.
 ### `tap-info` [`--installed`] [`--json`] [*`tap`* ...]
 
 Show detailed information about one or more *`tap`*s.
-
 If no *`tap`* names are provided, display brief statistics for all installed taps.
 
 * `--installed`:
@@ -776,7 +778,7 @@ upgraded formulae or, every 30 days, for all formulae.
 * `-f`, `--force`:
   Install formulae without checking for previously installed keg-only or non-migrated versions. When installing casks, overwrite existing files (binaries and symlinks are excluded, unless originally from the same cask).
 * `-v`, `--verbose`:
-  Print the verification and postinstall steps.
+  Print the verification and post-install steps.
 * `-n`, `--dry-run`:
   Show what would be upgraded, but do not actually upgrade anything.
 * `--formula`:
@@ -821,7 +823,7 @@ of *`formula`*. When given multiple formula arguments, show the intersection
 of formulae that use *`formula`*. By default, `uses` shows all formulae and casks that
 specify *`formula`* as a required or recommended dependency for their stable builds.
 
-Note: `--missing` and `--skip-recommended` have precedence over `--include-*`.
+*Note:* `--missing` and `--skip-recommended` have precedence over `--include-*`.
 
 * `--recursive`:
   Resolve more than one level of dependencies.
@@ -898,8 +900,8 @@ the list is formatted for export to `bash`(1) unless `--plain` is passed.
 
 Display Homebrew's install path. *Default:*
 
-  - macOS Intel: `/usr/local`
   - macOS ARM: `/opt/homebrew`
+  - macOS Intel: `/usr/local`
   - Linux: `/home/linuxbrew/.linuxbrew`
 
 If *`formula`* is provided, display the location where *`formula`* is or would be installed.
@@ -911,7 +913,7 @@ If *`formula`* is provided, display the location where *`formula`* is or would b
 
 ### `--repository`, `--repo` [*`tap`* ...]
 
-Display where Homebrew's git repository is located.
+Display where Homebrew's Git repository is located.
 
 If *`user`*`/`*`repo`* are provided, display where tap *`user`*`/`*`repo`*'s directory is located.
 
@@ -1169,7 +1171,7 @@ Display the path to the file being used when invoking `brew` *`cmd`*.
 
 ### `contributions` [--user=*`email|username`*] [*`--repositories`*`=`] [*`--csv`*]
 
-Contributions to Homebrew repositories.
+Summarise contributions to Homebrew repositories.
 
 * `--repositories`:
   Specify a comma-separated list of repositories to search. Supported repositories: `brew`, `core`, `cask`, `aliases`, `autoupdate`, `bundle`, `command-not-found`, `test-bot`, `services`, `cask-fonts` and `cask-versions`. Omitting this flag, or specifying `--repositories=primary`, searches only the main repositories: brew,core,cask. Specifying `--repositories=all`, searches all repositories. 
@@ -1282,8 +1284,7 @@ Display the path where *`formula`* is located.
 
 ### `generate-cask-api` [`--dry-run`]
 
-Generates Cask API data files for formulae.brew.sh.
+Generate `homebrew/cask` API data files for <https://formulae.brew.sh>.
-
 The generated files are written to the current directory.
 
 * `-n`, `--dry-run`:
@@ -1291,8 +1292,7 @@ The generated files are written to the current directory.
 
 ### `generate-formula-api` [`--dry-run`]
 
-Generates Formula API data files for formulae.brew.sh.
+Generate `homebrew/core` API data files for <https://formulae.brew.sh>.
-
 The generated files are written to the current directory.
 
 * `-n`, `--dry-run`:
@@ -1335,7 +1335,6 @@ provided, check all kegs. Raises an error if run on uninstalled formulae.
 ### `livecheck`, `lc` [*`options`*] [*`formula`*|*`cask`* ...]
 
 Check for newer versions of formulae and/or casks from upstream.
-
 If no formula or cask argument is passed, the list of formulae and
 casks to check is taken from `HOMEBREW_LIVECHECK_WATCHLIST` or
 `~/.homebrew/livecheck_watchlist.txt`.
@@ -1486,7 +1485,7 @@ By default, `brew release` will bump the patch version number. Pass
 The command will fail if the previous major or minor release was made less than
 one month ago.
 
-Requires write access to the Homebrew/brew repository.
+*Note:* Requires write access to the Homebrew/brew repository.
 
 * `--major`:
   Create a major release.
@@ -1698,7 +1697,7 @@ Install and commit Homebrew's vendored gems.
 
 ## GLOBAL CASK OPTIONS
 
-These options are applicable to the `install`, `reinstall`, and `upgrade` subcommands with the `--cask` flag.
+These options are applicable to the `install`, `reinstall`, and `upgrade` subcommands with the `--cask` switch.
 
 * `--appdir`:
   Target location for Applications (default: `/Applications`).
@@ -2306,7 +2305,7 @@ prefix-specific files take precedence over system-wide files (unless
 - `HOMEBREW_NO_INSECURE_REDIRECT`
   <br>If set, forbid redirects from secure HTTPS to insecure HTTP.
 
-    *Note:* While ensuring your downloads are fully secure, this is likely to cause from-source SourceForge, some GNU & GNOME-hosted formulae to fail to download.
+    *Note:* while ensuring your downloads are fully secure, this is likely to cause from-source SourceForge, some GNU & GNOME-hosted formulae to fail to download.
 
 - `HOMEBREW_NO_INSTALL_CLEANUP`
   <br>If set, `brew install`, `brew upgrade` and `brew reinstall` will never automatically cleanup installed/upgraded/reinstalled formulae or all formulae every `HOMEBREW_CLEANUP_PERIODIC_FULL_DAYS` days. Alternatively, `HOMEBREW_NO_CLEANUP_FORMULAE` allows specifying specific formulae to not clean up.
@@ -2315,7 +2314,7 @@ prefix-specific files take precedence over system-wide files (unless
   <br>If set, do not install formulae and casks in homebrew/core and homebrew/cask taps using Homebrew's API and instead use (large, slow) local checkouts of these repositories.
 
 - `HOMEBREW_NO_INSTALL_UPGRADE`
-  <br>If set, `brew install` <formula/cask> will not upgrade <formula/cask> if it is installed but outdated.
+  <br>If set, `brew install` *`formula|cask`* will not upgrade *`formula|cask`* if it is installed but outdated.
 
 - `HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK`
   <br>If set, do not check for broken linkage of dependents or outdated dependents after installing, upgrading or reinstalling formulae. This will result in fewer dependents (and their dependencies) being upgraded or reinstalled but may result in more breakage from running `brew install` *`formula`* or `brew upgrade` *`formula`*.
@@ -2324,7 +2323,7 @@ prefix-specific files take precedence over system-wide files (unless
   <br>If set, `brew update` will not show the list of newly added formulae/casks.
 
 - `HOMEBREW_PIP_INDEX_URL`
-  <br>If set, `brew install *`formula`*` will use this URL to download PyPI package resources.
+  <br>If set, `brew install` *`formula`* will use this URL to download PyPI package resources.
 
   *Default:* `https://pypi.org/simple`.
 
@@ -2344,7 +2343,7 @@ prefix-specific files take precedence over system-wide files (unless
   <br>If set, enable runtime typechecking using Sorbet. Set by default for HOMEBREW_DEVELOPER or when running some developer commands.
 
 - `HOMEBREW_SSH_CONFIG_PATH`
-  <br>If set, Homebrew will use the given config file instead of `~/.ssh/config` when fetching `git` repos over `ssh`.
+  <br>If set, Homebrew will use the given config file instead of `~/.ssh/config` when fetching Git repositories over SSH.
 
   *Default:* `$HOME/.ssh/config`
 

docs/Taps.md

@@ -9,7 +9,7 @@ but the command isn't limited to any one location.
 * `brew tap` without arguments lists all currently tapped repositories. For
   example:
 
-  ```sh
+  ```console
   $ brew tap
   homebrew/cask
   homebrew/core

docs/Tips-N'-Tricks.md

@@ -39,7 +39,7 @@ brew install --only-dependencies <formula>
 
 ## Use the interactive Homebrew shell
 
-```sh
+```console
 $ brew irb
 ==> Interactive Homebrew Shell
 Example commands available with: `brew irb --examples`
@@ -67,7 +67,7 @@ export HOMEBREW_INSTALL_BADGE="☕️ 🐸"
 
 ## Migrate a Homebrew installation to a new location
 
-Run `brew bundle dump` and `brew bundle install` record an installation to and install from a `Brewfile`. See `brew bundle --help` for more details.
+Running `brew bundle dump` will record an installation to a `Brewfile` and `brew bundle install` will install from a `Brewfile`. See `brew bundle --help` for more details.
 
 ## Appoint Homebrew Cask to manage a manually-installed app
 

docs/Typechecking.md

@@ -6,7 +6,7 @@ The [Sorbet Documentation] is a good place to get started if you want to dive de
 
 ## Sorbet in the Homebrew Codebase
 
-### Inline Type Annotations
+### Inline type annotations
 
 The `sig` method is used to annotate method signatures. Here's a simple example:
 
@@ -30,7 +30,7 @@ For more information on how to express more complex types, refer to the official
 - [Nilable Types](https://sorbet.org/docs/nilable-types)
 - [Union Types](https://sorbet.org/docs/union-types)
 
-### Ruby Interface Files (`.rbi`)
+### Ruby interface files (`.rbi`)
 
 [RBI files](https://sorbet.org/docs/rbi) help Sorbet learn about constants, ancestors and methods defined in ways it doesn’t understand natively. We can also create an RBI file to help Sorbet understand dynamic definitions.
 
@@ -38,7 +38,7 @@ Sometimes it is necessary to explicitly include the `Kernel` module in order for
 
 [example]: https://github.com/Homebrew/brew/blob/61b79318ed089b5010501e2cbf163fd8e48e2dfc/Library/Homebrew/global.rbi
 
-### The [`Library/Homebrew/sorbet`] Directory
+### The [`Library/Homebrew/sorbet`] directory
 
 [`Library/Homebrew/sorbet`]: https://github.com/Homebrew/brew/tree/master/Library/Homebrew/sorbet
 

docs/vale-styles/Homebrew/Terms.yml

@@ -8,4 +8,5 @@ scope: paragraph
 swap:
   "(?<!How to Open a Homebrew )Pull Request": pull request
   repo: repository
+  repos: repositories
   Rubocop: RuboCop

manpages/brew.1

@@ -158,7 +158,10 @@ Show Homebrew and system configuration info useful for debugging\. If you file a
 Show dependencies for \fIformula\fR\. When given multiple formula arguments, show the intersection of dependencies for each formula\. By default, \fBdeps\fR shows all required and recommended dependencies\.
 .
 .P
-Note: \fB\-\-missing\fR and \fB\-\-skip\-recommended\fR have precedence over \fB\-\-include\-*\fR\.
+If any version of each formula argument is installed and no other options are passed, this command displays their actual runtime dependencies (similar to \fBbrew linkage\fR), which may differ from the current versons\' stated dependencies if the installed versions are outdated\.
+.
+.P
+\fINote:\fR \fB\-\-missing\fR and \fB\-\-skip\-recommended\fR have precedence over \fB\-\-include\-*\fR\.
 .
 .TP
 \fB\-n\fR, \fB\-\-topological\fR
@@ -275,10 +278,13 @@ Control Homebrew\'s developer mode\. When developer mode is enabled, \fBbrew upd
     Turn Homebrew\'s developer mode on or off respectively\.
 .
 .SS "\fBdocs\fR"
-Open Homebrew\'s online documentation (https://docs\.brew\.sh) in a browser\.
+Open Homebrew\'s online documentation at \fIhttps://docs\.brew\.sh\fR in a browser\.
 .
 .SS "\fBdoctor\fR, \fBdr\fR [\fB\-\-list\-checks\fR] [\fB\-\-audit\-debug\fR] [\fIdiagnostic_check\fR \.\.\.]"
-Check your system for potential problems\. Will exit with a non\-zero status if any potential problems are found\. Please note that these warnings are just used to help the Homebrew maintainers with debugging if you file an issue\. If everything you use Homebrew for is working fine: please don\'t worry or file an issue; just ignore this\.
+Check your system for potential problems\. Will exit with a non\-zero status if any potential problems are found\.
+.
+.P
+Please note that these warnings are just used to help the Homebrew maintainers with debugging if you file an issue\. If everything you use Homebrew for is working fine: please don\'t worry or file an issue; just ignore this\.
 .
 .TP
 \fB\-\-list\-checks\fR
@@ -377,10 +383,7 @@ Treat all named arguments as formulae\.
 Treat all named arguments as casks\.
 .
 .SS "\fBinfo\fR, \fBabv\fR [\fIoptions\fR] [\fIformula\fR|\fIcask\fR \.\.\.]"
-Display brief statistics for your Homebrew installation\.
+Display brief statistics for your Homebrew installation\. If a \fIformula\fR or \fIcask\fR is provided, show summary of information about it\.
-.
-.P
-If a \fIformula\fR or \fIcask\fR is provided, show summary of information about it\.
 .
 .TP
 \fB\-\-analytics\fR
@@ -448,7 +451,7 @@ Install formulae without checking for previously installed keg\-only or non\-mig
 .
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
-Print the verification and postinstall steps\.
+Print the verification and post\-install steps\.
 .
 .TP
 \fB\-n\fR, \fB\-\-dry\-run\fR
@@ -460,7 +463,7 @@ Treat all named arguments as formulae\.
 .
 .TP
 \fB\-\-ignore\-dependencies\fR
-An unsupported Homebrew development flag to skip installing any dependencies of any kind\. If the dependencies are not already present, the formula will have issues\. If you\'re not developing Homebrew, consider adjusting your PATH rather than using this flag\.
+An unsupported Homebrew development option to skip installing any dependencies of any kind\. If the dependencies are not already present, the formula will have issues\. If you\'re not developing Homebrew, consider adjusting your PATH rather than using this option\.
 .
 .TP
 \fB\-\-only\-dependencies\fR
@@ -566,7 +569,7 @@ Only list leaves that were manually installed\.
 Only list leaves that were installed as dependencies\.
 .
 .SS "\fBlink\fR, \fBln\fR [\fIoptions\fR] \fIinstalled_formula\fR [\.\.\.]"
-Symlink all of \fIformula\fR\'s installed files into Homebrew\'s prefix\. This is done automatically when you install formulae but can be useful for DIY installations\.
+Symlink all of \fIformula\fR\'s installed files into Homebrew\'s prefix\. This is done automatically when you install formulae but can be useful for manual installations\.
 .
 .TP
 \fB\-\-overwrite\fR
@@ -585,10 +588,7 @@ Allow keg\-only formulae to be linked\.
 Link the HEAD version of the formula if it is installed\.
 .
 .SS "\fBlist\fR, \fBls\fR [\fIoptions\fR] [\fIinstalled_formula\fR|\fIinstalled_cask\fR \.\.\.]"
-List all installed formulae and casks\.
+List all installed formulae and casks\. If \fIformula\fR is provided, summarise the paths within its current keg\. If \fIcask\fR is provided, list its artifacts\.
-.
-.P
-If \fIformula\fR is provided, summarise the paths within its current keg\. If \fIcask\fR is provided, list its artifacts\.
 .
 .TP
 \fB\-\-formula\fR
@@ -688,7 +688,7 @@ Check the given \fIformula\fR kegs for missing dependencies\. If no \fIformula\f
 Act as if none of the specified \fIhidden\fR are installed\. \fIhidden\fR should be a comma\-separated list of formulae\.
 .
 .SS "\fBnodenv\-sync\fR"
-Create symlinks for Homebrew\'s installed NodeJS versions in ~/\.nodenv/versions\.
+Create symlinks for Homebrew\'s installed NodeJS versions in \fB~/\.nodenv/versions\fR\.
 .
 .P
 Note that older version symlinks will also be created so e\.g\. NodeJS 19\.1\.0 will also be symlinked to 19\.0\.0\.
@@ -758,13 +758,13 @@ Pin the specified \fIformula\fR, preventing them from being upgraded when issuin
 Rerun the post\-install steps for \fIformula\fR\.
 .
 .SS "\fBpyenv\-sync\fR"
-Create symlinks for Homebrew\'s installed Python versions in ~/\.pyenv/versions\.
+Create symlinks for Homebrew\'s installed Python versions in \fB~/\.pyenv/versions\fR\.
 .
 .P
 Note that older patch version symlinks will be created and linked to the minor version so e\.g\. Python 3\.11\.0 will also be symlinked to 3\.11\.3\.
 .
 .SS "\fBrbenv\-sync\fR"
-Create symlinks for Homebrew\'s installed Ruby versions in ~/\.rbenv/versions\.
+Create symlinks for Homebrew\'s installed Ruby versions in \fB~/\.rbenv/versions\fR\.
 .
 .P
 Note that older version symlinks will also be created so e\.g\. Ruby 3\.2\.1 will also be symlinked to 3\.2\.0\.
@@ -786,7 +786,7 @@ Verify any alias symlinks in each tap\.
 .
 .TP
 \fB\-\-syntax\fR
-Syntax\-check all of Homebrew\'s Ruby files (if no \fB<tap>\fR is passed)\.
+Syntax\-check all of Homebrew\'s Ruby files (if no \fItap\fR is passed)\.
 .
 .TP
 \fB\-\-eval\-all\fR
@@ -815,7 +815,7 @@ Install without checking for previously installed keg\-only or non\-migrated ver
 .
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
-Print the verification and postinstall steps\.
+Print the verification and post\-install steps\.
 .
 .TP
 \fB\-\-formula\fR
@@ -950,10 +950,7 @@ The variables \fBHOMEBREW_PREFIX\fR, \fBHOMEBREW_CELLAR\fR and \fBHOMEBREW_REPOS
 The shell can be specified explicitly with a supported shell name parameter\. Unknown shells will output POSIX exports\.
 .
 .SS "\fBtap\fR [\fIoptions\fR] [\fIuser\fR\fB/\fR\fIrepo\fR] [\fIURL\fR]"
-Tap a formula repository\.
+Tap a formula repository\. If no arguments are provided, list all installed taps\.
-.
-.P
-If no arguments are provided, list all installed taps\.
 .
 .P
 With \fIURL\fR unspecified, tap a formula repository from GitHub using HTTPS\. Since so many taps are hosted on GitHub, this command is a shortcut for \fBbrew tap\fR \fIuser\fR\fB/\fR\fIrepo\fR \fBhttps://github\.com/\fR\fIuser\fR\fB/homebrew\-\fR\fIrepo\fR\.
@@ -982,10 +979,7 @@ Evaluate all the formulae, casks and aliases in the new tap to check validity\.
 Force install core taps even under API mode\.
 .
 .SS "\fBtap\-info\fR [\fB\-\-installed\fR] [\fB\-\-json\fR] [\fItap\fR \.\.\.]"
-Show detailed information about one or more \fItap\fRs\.
+Show detailed information about one or more \fItap\fRs\. If no \fItap\fR names are provided, display brief statistics for all installed taps\.
-.
-.P
-If no \fItap\fR names are provided, display brief statistics for all installed taps\.
 .
 .TP
 \fB\-\-installed\fR
@@ -1075,7 +1069,7 @@ Install formulae without checking for previously installed keg\-only or non\-mig
 .
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
-Print the verification and postinstall steps\.
+Print the verification and post\-install steps\.
 .
 .TP
 \fB\-n\fR, \fB\-\-dry\-run\fR
@@ -1153,7 +1147,7 @@ Disable/enable quarantining of downloads (default: enabled)\.
 Show formulae and casks that specify \fIformula\fR as a dependency; that is, show dependents of \fIformula\fR\. When given multiple formula arguments, show the intersection of formulae that use \fIformula\fR\. By default, \fBuses\fR shows all formulae and casks that specify \fIformula\fR as a required or recommended dependency for their stable builds\.
 .
 .P
-Note: \fB\-\-missing\fR and \fB\-\-skip\-recommended\fR have precedence over \fB\-\-include\-*\fR\.
+\fINote:\fR \fB\-\-missing\fR and \fB\-\-skip\-recommended\fR have precedence over \fB\-\-include\-*\fR\.
 .
 .TP
 \fB\-\-recursive\fR
@@ -1263,10 +1257,10 @@ Generate plain output even when piped\.
 Display Homebrew\'s install path\. \fIDefault:\fR
 .
 .IP "\(bu" 4
-macOS Intel: \fB/usr/local\fR
+macOS ARM: \fB/opt/homebrew\fR
 .
 .IP "\(bu" 4
-macOS ARM: \fB/opt/homebrew\fR
+macOS Intel: \fB/usr/local\fR
 .
 .IP "\(bu" 4
 Linux: \fB/home/linuxbrew/\.linuxbrew\fR
@@ -1285,7 +1279,7 @@ List files in Homebrew\'s prefix not installed by Homebrew\.
 Outputs nothing and returns a failing status code if \fIformula\fR is not installed\.
 .
 .SS "\fB\-\-repository\fR, \fB\-\-repo\fR [\fItap\fR \.\.\.]"
-Display where Homebrew\'s git repository is located\.
+Display where Homebrew\'s Git repository is located\.
 .
 .P
 If \fIuser\fR\fB/\fR\fIrepo\fR are provided, display where tap \fIuser\fR\fB/\fR\fIrepo\fR\'s directory is located\.
@@ -1686,7 +1680,7 @@ Treat all named arguments as casks\.
 Display the path to the file being used when invoking \fBbrew\fR \fIcmd\fR\.
 .
 .SS "\fBcontributions\fR [\-\-user=\fIemail|username\fR] [\fI\-\-repositories\fR\fB=\fR] [\fI\-\-csv\fR]"
-Contributions to Homebrew repositories\.
+Summarise contributions to Homebrew repositories\.
 .
 .TP
 \fB\-\-repositories\fR
@@ -1852,20 +1846,14 @@ Overwrite the destination formula if it already exists\.
 Display the path where \fIformula\fR is located\.
 .
 .SS "\fBgenerate\-cask\-api\fR [\fB\-\-dry\-run\fR]"
-Generates Cask API data files for formulae\.brew\.sh\.
+Generate \fBhomebrew/cask\fR API data files for \fIhttps://formulae\.brew\.sh\fR\. The generated files are written to the current directory\.
-.
-.P
-The generated files are written to the current directory\.
 .
 .TP
 \fB\-n\fR, \fB\-\-dry\-run\fR
 Generate API data without writing it to files\.
 .
 .SS "\fBgenerate\-formula\-api\fR [\fB\-\-dry\-run\fR]"
-Generates Formula API data files for formulae\.brew\.sh\.
+Generate \fBhomebrew/core\fR API data files for \fIhttps://formulae\.brew\.sh\fR\. The generated files are written to the current directory\.
-.
-.P
-The generated files are written to the current directory\.
 .
 .TP
 \fB\-n\fR, \fB\-\-dry\-run\fR
@@ -1912,10 +1900,7 @@ For every library that a keg references, print its dylib path followed by the bi
 Print the cached linkage values stored in \fBHOMEBREW_CACHE\fR, set by a previous \fBbrew linkage\fR run\.
 .
 .SS "\fBlivecheck\fR, \fBlc\fR [\fIoptions\fR] [\fIformula\fR|\fIcask\fR \.\.\.]"
-Check for newer versions of formulae and/or casks from upstream\.
+Check for newer versions of formulae and/or casks from upstream\. If no formula or cask argument is passed, the list of formulae and casks to check is taken from \fBHOMEBREW_LIVECHECK_WATCHLIST\fR or \fB~/\.homebrew/livecheck_watchlist\.txt\fR\.
-.
-.P
-If no formula or cask argument is passed, the list of formulae and casks to check is taken from \fBHOMEBREW_LIVECHECK_WATCHLIST\fR or \fB~/\.homebrew/livecheck_watchlist\.txt\fR\.
 .
 .TP
 \fB\-\-full\-name\fR
@@ -2155,7 +2140,7 @@ Create a new draft Homebrew/brew release with the appropriate version number and
 By default, \fBbrew release\fR will bump the patch version number\. Pass \fB\-\-major\fR or \fB\-\-minor\fR to bump the major or minor version numbers, respectively\. The command will fail if the previous major or minor release was made less than one month ago\.
 .
 .P
-Requires write access to the Homebrew/brew repository\.
+\fINote:\fR Requires write access to the Homebrew/brew repository\.
 .
 .TP
 \fB\-\-major\fR
@@ -2443,7 +2428,7 @@ Update the specified list of vendored gems to the latest version\.
 Do not generate a new commit upon completion\.
 .
 .SH "GLOBAL CASK OPTIONS"
-These options are applicable to the \fBinstall\fR, \fBreinstall\fR, and \fBupgrade\fR subcommands with the \fB\-\-cask\fR flag\.
+These options are applicable to the \fBinstall\fR, \fBreinstall\fR, and \fBupgrade\fR subcommands with the \fB\-\-cask\fR switch\.
 .
 .TP
 \fB\-\-appdir\fR
@@ -3395,7 +3380,7 @@ If set, do not use the GitHub API, e\.g\. for searches or fetching relevant issu
 If set, forbid redirects from secure HTTPS to insecure HTTP\.
 .
 .IP
-\fINote:\fR While ensuring your downloads are fully secure, this is likely to cause from\-source SourceForge, some GNU & GNOME\-hosted formulae to fail to download\.
+\fINote:\fR while ensuring your downloads are fully secure, this is likely to cause from\-source SourceForge, some GNU & GNOME\-hosted formulae to fail to download\.
 .
 .TP
 \fBHOMEBREW_NO_INSTALL_CLEANUP\fR
@@ -3413,7 +3398,7 @@ If set, do not install formulae and casks in homebrew/core and homebrew/cask tap
 \fBHOMEBREW_NO_INSTALL_UPGRADE\fR
 .
 .br
-If set, \fBbrew install\fR <formula/cask> will not upgrade <formula/cask> if it is installed but outdated\.
+If set, \fBbrew install\fR \fIformula|cask\fR will not upgrade \fIformula|cask\fR if it is installed but outdated\.
 .
 .TP
 \fBHOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK\fR
@@ -3431,7 +3416,7 @@ If set, \fBbrew update\fR will not show the list of newly added formulae/casks\.
 \fBHOMEBREW_PIP_INDEX_URL\fR
 .
 .br
-If set, \fBbrew install <formula>\fR will use this URL to download PyPI package resources\.
+If set, \fBbrew install\fR \fIformula\fR will use this URL to download PyPI package resources\.
 .
 .IP
 \fIDefault:\fR \fBhttps://pypi\.org/simple\fR\.
@@ -3470,7 +3455,7 @@ If set, enable runtime typechecking using Sorbet\. Set by default for HOMEBREW_D
 \fBHOMEBREW_SSH_CONFIG_PATH\fR
 .
 .br
-If set, Homebrew will use the given config file instead of \fB~/\.ssh/config\fR when fetching \fBgit\fR repos over \fBssh\fR\.
+If set, Homebrew will use the given config file instead of \fB~/\.ssh/config\fR when fetching Git repositories over SSH\.
 .
 .IP
 \fIDefault:\fR \fB$HOME/\.ssh/config\fR