diff --git a/Library/Homebrew/cmd/--prefix.rb b/Library/Homebrew/cmd/--prefix.rb index 95e21d38d668a..71282fcba3711 100644 --- a/Library/Homebrew/cmd/--prefix.rb +++ b/Library/Homebrew/cmd/--prefix.rb @@ -10,8 +10,8 @@ def self.__prefix_args 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 is provided, display the location where is or would be installed. diff --git a/Library/Homebrew/cmd/--repository.rb b/Library/Homebrew/cmd/--repository.rb index ead618e8f0f82..b42f8d27c3609 100644 --- a/Library/Homebrew/cmd/--repository.rb +++ b/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 `/` are provided, display where tap `/`'s directory is located. EOS diff --git a/Library/Homebrew/cmd/deps.rb b/Library/Homebrew/cmd/deps.rb index 659a0b5980ee3..7d8cbd58294c4 100644 --- a/Library/Homebrew/cmd/deps.rb +++ b/Library/Homebrew/cmd/deps.rb @@ -17,7 +17,12 @@ def self.deps_args 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." diff --git a/Library/Homebrew/cmd/docs.rb b/Library/Homebrew/cmd/docs.rb index b8107aea6620c..2ac9ef42af95c 100644 --- a/Library/Homebrew/cmd/docs.rb +++ b/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 diff --git a/Library/Homebrew/cmd/doctor.rb b/Library/Homebrew/cmd/doctor.rb index cfe47fae8d776..d3677fc6248fe 100644 --- a/Library/Homebrew/cmd/doctor.rb +++ b/Library/Homebrew/cmd/doctor.rb @@ -11,10 +11,11 @@ def self.doctor_args 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 - 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. + 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. EOS switch "--list-checks", description: "List all audit methods, which can be run individually " \ diff --git a/Library/Homebrew/cmd/info.rb b/Library/Homebrew/cmd/info.rb index c85010d6308ce..ca7ac0f28b904 100644 --- a/Library/Homebrew/cmd/info.rb +++ b/Library/Homebrew/cmd/info.rb @@ -25,7 +25,6 @@ def info_args Homebrew::CLI::Parser.new do description <<~EOS Display brief statistics for your Homebrew installation. - If a or is provided, show summary of information about it. EOS switch "--analytics", diff --git a/Library/Homebrew/cmd/install.rb b/Library/Homebrew/cmd/install.rb index a98ef23e9d705..bee541308044c 100644 --- a/Library/Homebrew/cmd/install.rb +++ b/Library/Homebrew/cmd/install.rb @@ -37,7 +37,7 @@ def self.install_args "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 @@ def self.install_args hidden: true, }], [:switch, "--ignore-dependencies", { - description: "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.", + description: "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.", }], [:switch, "--only-dependencies", { description: "Install the dependencies with specified options but do not install the " \ @@ -184,9 +184,9 @@ def self.install 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 diff --git a/Library/Homebrew/cmd/link.rb b/Library/Homebrew/cmd/link.rb index 3b6520e91c828..78e829662d79a 100644 --- a/Library/Homebrew/cmd/link.rb +++ b/Library/Homebrew/cmd/link.rb @@ -12,9 +12,9 @@ module Homebrew def link_args Homebrew::CLI::Parser.new do description <<~EOS - Symlink all of '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 's installed files into Homebrew's prefix. + This is done automatically when you install formulae but can be useful + for manual installations. EOS switch "--overwrite", description: "Delete files that already exist in the prefix while linking." diff --git a/Library/Homebrew/cmd/list.rb b/Library/Homebrew/cmd/list.rb index 3d9b28e662c1e..819af57ceff85 100644 --- a/Library/Homebrew/cmd/list.rb +++ b/Library/Homebrew/cmd/list.rb @@ -14,7 +14,6 @@ def list_args Homebrew::CLI::Parser.new do description <<~EOS List all installed formulae and casks. - If is provided, summarise the paths within its current keg. If is provided, list its artifacts. EOS diff --git a/Library/Homebrew/cmd/nodenv-sync.rb b/Library/Homebrew/cmd/nodenv-sync.rb index 647f2ebf45e8a..8def8e6723264 100755 --- a/Library/Homebrew/cmd/nodenv-sync.rb +++ b/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. diff --git a/Library/Homebrew/cmd/pyenv-sync.rb b/Library/Homebrew/cmd/pyenv-sync.rb index a78f6c8b52db3..b98d07a26acd0 100644 --- a/Library/Homebrew/cmd/pyenv-sync.rb +++ b/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. diff --git a/Library/Homebrew/cmd/rbenv-sync.rb b/Library/Homebrew/cmd/rbenv-sync.rb index d8ba62f5e90ae..5deef1e0368c3 100755 --- a/Library/Homebrew/cmd/rbenv-sync.rb +++ b/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. diff --git a/Library/Homebrew/cmd/readall.rb b/Library/Homebrew/cmd/readall.rb index 44cfccdaca24b..87a88e61d1039 100644 --- a/Library/Homebrew/cmd/readall.rb +++ b/Library/Homebrew/cmd/readall.rb @@ -24,7 +24,7 @@ def readall_args switch "--aliases", description: "Verify any alias symlinks in each tap." switch "--syntax", - description: "Syntax-check all of Homebrew's Ruby files (if no `` is passed)." + description: "Syntax-check all of Homebrew's Ruby files (if no is passed)." switch "--eval-all", description: "Evaluate all available formulae and casks, whether installed or not. " \ "Implied if `HOMEBREW_EVAL_ALL` is set." diff --git a/Library/Homebrew/cmd/reinstall.rb b/Library/Homebrew/cmd/reinstall.rb index 6a88b3eb0ee4a..e1c90faabf800 100644 --- a/Library/Homebrew/cmd/reinstall.rb +++ b/Library/Homebrew/cmd/reinstall.rb @@ -35,7 +35,7 @@ def self.reinstall_args 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", { diff --git a/Library/Homebrew/cmd/tap-info.rb b/Library/Homebrew/cmd/tap-info.rb index 281db2a6c1115..ce1e5255d4be5 100644 --- a/Library/Homebrew/cmd/tap-info.rb +++ b/Library/Homebrew/cmd/tap-info.rb @@ -11,7 +11,6 @@ def tap_info_args Homebrew::CLI::Parser.new do description <<~EOS Show detailed information about one or more s. - If no names are provided, display brief statistics for all installed taps. EOS switch "--installed", diff --git a/Library/Homebrew/cmd/tap.rb b/Library/Homebrew/cmd/tap.rb index d510e964b4618..91897bb5da496 100644 --- a/Library/Homebrew/cmd/tap.rb +++ b/Library/Homebrew/cmd/tap.rb @@ -12,7 +12,6 @@ def tap_args usage_banner "`tap` [] [`/`] []" description <<~EOS Tap a formula repository. - If no arguments are provided, list all installed taps. With unspecified, tap a formula repository from GitHub using HTTPS. diff --git a/Library/Homebrew/cmd/upgrade.rb b/Library/Homebrew/cmd/upgrade.rb index 5480a2ec5a1d3..a50bd8a1c9a6e 100644 --- a/Library/Homebrew/cmd/upgrade.rb +++ b/Library/Homebrew/cmd/upgrade.rb @@ -35,7 +35,7 @@ def upgrade_args "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." [ diff --git a/Library/Homebrew/cmd/uses.rb b/Library/Homebrew/cmd/uses.rb index 67a06f4419cdc..21635d9df2b48 100644 --- a/Library/Homebrew/cmd/uses.rb +++ b/Library/Homebrew/cmd/uses.rb @@ -23,7 +23,7 @@ def self.uses_args of formulae that use . By default, `uses` shows all formulae and casks that specify 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." diff --git a/Library/Homebrew/dependency.rb b/Library/Homebrew/dependency.rb index 03a898406c3c6..9551cded23d95 100644 --- a/Library/Homebrew/dependency.rb +++ b/Library/Homebrew/dependency.rb @@ -230,7 +230,7 @@ def merge_temporality(deps) 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 diff --git a/Library/Homebrew/dev-cmd/contributions.rb b/Library/Homebrew/dev-cmd/contributions.rb index 818d51b46234b..f9babd353b799 100755 --- a/Library/Homebrew/dev-cmd/contributions.rb +++ b/Library/Homebrew/dev-cmd/contributions.rb @@ -20,7 +20,7 @@ def contributions_args Homebrew::CLI::Parser.new do usage_banner "`contributions` [--user=] [<--repositories>`=`] [<--csv>]" description <<~EOS - Contributions to Homebrew repositories. + Summarise contributions to Homebrew repositories. EOS comma_array "--repositories", diff --git a/Library/Homebrew/dev-cmd/generate-cask-api.rb b/Library/Homebrew/dev-cmd/generate-cask-api.rb index 6ad4f38ff63c1..3cf93c86af986 100644 --- a/Library/Homebrew/dev-cmd/generate-cask-api.rb +++ b/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 diff --git a/Library/Homebrew/dev-cmd/generate-formula-api.rb b/Library/Homebrew/dev-cmd/generate-formula-api.rb index 46a6a83a25a68..6bc958082ed12 100644 --- a/Library/Homebrew/dev-cmd/generate-formula-api.rb +++ b/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 diff --git a/Library/Homebrew/dev-cmd/livecheck.rb b/Library/Homebrew/dev-cmd/livecheck.rb index f797dfc820e4d..3725c9838123b 100644 --- a/Library/Homebrew/dev-cmd/livecheck.rb +++ b/Library/Homebrew/dev-cmd/livecheck.rb @@ -14,7 +14,6 @@ def livecheck_args 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`. diff --git a/Library/Homebrew/dev-cmd/release.rb b/Library/Homebrew/dev-cmd/release.rb index bd981a221b65c..923b66d1df08e 100755 --- a/Library/Homebrew/dev-cmd/release.rb +++ b/Library/Homebrew/dev-cmd/release.rb @@ -17,7 +17,7 @@ def release_args 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." diff --git a/Library/Homebrew/env_config.rb b/Library/Homebrew/env_config.rb index 03bb33852890a..b7a0aba96a6de 100644 --- a/Library/Homebrew/env_config.rb +++ b/Library/Homebrew/env_config.rb @@ -300,7 +300,7 @@ module EnvConfig }, 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 EnvConfig boolean: true, }, HOMEBREW_NO_INSTALL_UPGRADE: { - description: "If set, `brew install` will not upgrade if it is installed but " \ + description: "If set, `brew install` will not upgrade if it is installed but " \ "outdated.", boolean: true, }, @@ -333,7 +333,7 @@ module EnvConfig boolean: true, }, HOMEBREW_PIP_INDEX_URL: { - description: "If set, `brew install ` will use this URL to download PyPI package resources.", + description: "If set, `brew install` will use this URL to download PyPI package resources.", default_text: "`https://pypi.org/simple`.", }, HOMEBREW_PRY: { @@ -361,7 +361,7 @@ module EnvConfig }, 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: { diff --git a/Library/Homebrew/extend/kernel.rb b/Library/Homebrew/extend/kernel.rb index 4a50068feb742..34761ffbfdf6b 100644 --- a/Library/Homebrew/extend/kernel.rb +++ b/Library/Homebrew/extend/kernel.rb @@ -292,7 +292,7 @@ def which_editor(silent: false) 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 diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb index fdf2d37ff002d..caffdb1c878fc 100644 --- a/Library/Homebrew/formula.rb +++ b/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 @@ def versioned_formulae 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 @@ def latest_installed_prefix 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 @@ def std_pip_args(prefix: self.prefix, build_isolation: false) # # If `name` is specified as "*", match any shared library of any version. # - # 
-  # 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 @@ def shared_library(name, version = nil)
   # Optionally specify a `source` or `target` depending on the location
   # of the file containing the RPATH command and where its target is located.
   #
-  # 
-  # rpath #=> "@loader_path/../lib"
+  # 
rpath #=> "@loader_path/../lib"
   # rpath(target: frameworks) #=> "@loader_path/../Frameworks"
   # rpath(source: libexec/"bin") #=> "@loader_path/../../lib"
   # 

@@ -1808,64 +1806,62 @@ def extract_macho_slice_from(file, arch = Hardware::CPU.arch)
   # 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] 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].
-  # Defaults to plainly passing the shell.
+  #  to the `executable`. Takes either a String representing a prefix, or one of `[:flag, :arg, :none, :click]`.
+  #  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
-  #    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
+  # @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",
-  #                                                     "completions", "--shell=bash")
+  #   # translates to
+  #   (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" },
-  #                                                     bin/"foo")
+  #   # translates to
+  #   (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",
-  #                                                     "completions", "--selected-shell=bash")
+  #   # translates to
+  #   (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 @@ def to_hash_with_variations
     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 @@ def fails_with(compiler, &block)
     # 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
diff --git a/Library/Homebrew/formula_creator.rb b/Library/Homebrew/formula_creator.rb
index d5e8dc92c6296..05679630e2c00 100644
--- a/Library/Homebrew/formula_creator.rb
+++ b/Library/Homebrew/formula_creator.rb
@@ -60,7 +60,7 @@ def generate!
       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
diff --git a/Library/Homebrew/formula_installer.rb b/Library/Homebrew/formula_installer.rb
index fac502909735a..c6e457045df2d 100644
--- a/Library/Homebrew/formula_installer.rb
+++ b/Library/Homebrew/formula_installer.rb
@@ -685,7 +685,7 @@ def fetch_dependency(dep)
       # 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,
diff --git a/Library/Homebrew/global.rb b/Library/Homebrew/global.rb
index 9c1803157d4d4..38ba85dd1be2c 100644
--- a/Library/Homebrew/global.rb
+++ b/Library/Homebrew/global.rb
@@ -36,6 +36,7 @@
 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
diff --git a/Library/Homebrew/install.rb b/Library/Homebrew/install.rb
index 88d1b7d609399..a2df39fed202a 100644
--- a/Library/Homebrew/install.rb
+++ b/Library/Homebrew/install.rb
@@ -87,7 +87,7 @@ def install_formula?(
           # 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 @@ def install_formula?(
             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.
 
diff --git a/Library/Homebrew/livecheck/strategy/gnome.rb b/Library/Homebrew/livecheck/strategy/gnome.rb
index a6612e620828f..5ef8f27fcd697 100644
--- a/Library/Homebrew/livecheck/strategy/gnome.rb
+++ b/Library/Homebrew/livecheck/strategy/gnome.rb
@@ -15,11 +15,11 @@ module Strategy
       # 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.
       #
diff --git a/Library/Homebrew/livecheck/strategy/pypi.rb b/Library/Homebrew/livecheck/strategy/pypi.rb
index 99d495a20fb30..4be3eb970a650 100644
--- a/Library/Homebrew/livecheck/strategy/pypi.rb
+++ b/Library/Homebrew/livecheck/strategy/pypi.rb
@@ -19,7 +19,7 @@ module Strategy
       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 = /
           (?.+)- # The package name followed by a hyphen
diff --git a/Library/Homebrew/manpages.rb b/Library/Homebrew/manpages.rb
index 8b53c571b42c6..f9572878719b6 100644
--- a/Library/Homebrew/manpages.rb
+++ b/Library/Homebrew/manpages.rb
@@ -183,7 +183,7 @@ def self.cmd_comment_manpage_lines(cmd_path)
     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
diff --git a/Library/Homebrew/tab.rb b/Library/Homebrew/tab.rb
index 7fbddefb65c2c..40866bb215cc5 100644
--- a/Library/Homebrew/tab.rb
+++ b/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 @@ def to_json(options = nil)
     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,
diff --git a/Library/Homebrew/tap.rb b/Library/Homebrew/tap.rb
index a5fc3d85278fa..d850d6052f47c 100644
--- a/Library/Homebrew/tap.rb
+++ b/Library/Homebrew/tap.rb
@@ -187,14 +187,14 @@ def git?
     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?
 
diff --git a/Library/Homebrew/test/cli/parser_spec.rb b/Library/Homebrew/test/cli/parser_spec.rb
index 5e1f20f78490e..7785e3f790f7b 100644
--- a/Library/Homebrew/test/cli/parser_spec.rb
+++ b/Library/Homebrew/test/cli/parser_spec.rb
@@ -28,17 +28,17 @@
         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 @@
         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
diff --git a/Library/Homebrew/test/completions_spec.rb b/Library/Homebrew/test/completions_spec.rb
index ce7b3bdd5bacb..62c03a826a18a 100644
--- a/Library/Homebrew/test/completions_spec.rb
+++ b/Library/Homebrew/test/completions_spec.rb
@@ -222,7 +222,7 @@ def delete_completions_setting(setting: "linkcompletions")
 
       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
 
diff --git a/Library/Homebrew/test/support/lib/startup/config.rb b/Library/Homebrew/test/support/lib/startup/config.rb
index 00f13b2bcebb1..408aea45c9e4c 100644
--- a/Library/Homebrew/test/support/lib/startup/config.rb
+++ b/Library/Homebrew/test/support/lib/startup/config.rb
@@ -9,7 +9,7 @@
   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
diff --git a/Library/Homebrew/utils/curl.rb b/Library/Homebrew/utils/curl.rb
index caf88ba6641e0..7b3aba4b7aba9 100644
--- a/Library/Homebrew/utils/curl.rb
+++ b/Library/Homebrew/utils/curl.rb
@@ -23,7 +23,7 @@ module Curl
     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/.* (?\d+)(?: (?[^\r\n]+))?}.freeze
 
     private_constant :ETAG_VALUE_REGEX, :HTTP_RESPONSE_BODY_SEPARATOR, :HTTP_STATUS_LINE_REGEX
@@ -112,7 +112,7 @@ def curl_args(
       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?
diff --git a/completions/fish/brew.fish b/completions/fish/brew.fish
index 9cc48bb54c944..1e0a314ef4ec7 100644
--- a/completions/fish/brew.fish
+++ b/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)'
diff --git a/completions/zsh/_brew b/completions/zsh/_brew
index c93c27f7031ab..70092ca845d9e 100644
--- a/completions/zsh/_brew
+++ b/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-formula-api:Generates Formula API data files for formulae.brew.sh'
+    'generate-cask-api:Generate `homebrew/cask` API data files for https://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'
-    'rbenv-sync:Create symlinks for Homebrew'\''s installed Ruby versions in ~/.rbenv/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`'
     '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 \
diff --git a/docs/Acceptable-Casks.md b/docs/Acceptable-Casks.md
index aac8230a56afe..7f854d13fbe83 100644
--- a/docs/Acceptable-Casks.md
+++ b/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).
diff --git a/docs/Adding-Software-to-Homebrew.md b/docs/Adding-Software-to-Homebrew.md
index 8fe5a8072c816..d57f0e2b97835 100644
--- a/docs/Adding-Software-to-Homebrew.md
+++ b/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
-# Untracked files:
-#   (use "git add ..." to include in what will be committed)
-#
-#       Casks/my-new-cask.rb
+On branch master
+Untracked files:
+  (use "git add ..." to include in what will be committed)
+        Casks/m/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'
 ```
diff --git a/docs/Cask-Cookbook.md b/docs/Cask-Cookbook.md
index 9b8898b0cef25..cfc71eb82cf71 100644
--- a/docs/Cask-Cookbook.md
+++ b/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 
 ```
 
-#### 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" 
 ```
 
-#### 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//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_` 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.
 
diff --git a/docs/Checksum_Deprecation.md b/docs/Checksum_Deprecation.md
index 633a6d6498aed..b758dd51ed8f2 100644
--- a/docs/Checksum_Deprecation.md
+++ b/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.
diff --git a/docs/Common-Issues-for-Core-Contributors.md b/docs/Common-Issues-for-Core-Contributors.md
index 44b909e4fea22..f6ceb5143fd2b 100644
--- a/docs/Common-Issues-for-Core-Contributors.md
+++ b/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 ` in `homebrew/core` to reset to the commit before all the commits created by `brew pr-pull`.
-* `brew pr-pull ` 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 ` 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).
diff --git a/docs/Common-Issues.md b/docs/Common-Issues.md
index d32ee88d67a44..d81f02cd69643 100644
--- a/docs/Common-Issues.md
+++ b/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 `).
 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.
 
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 386664fbfaf6b..9685963fd9933 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -198,7 +198,7 @@ In the resulting dialog, click the *Open* button to have macOS permanently allow
 
 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 
 
-Or use the `--greedy` flag:
+Or use the `--greedy` switch:
 
     brew upgrade --greedy
 
diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index a9860a495f296..45cd6b5c7e334 100644
--- a/docs/Formula-Cookbook.md
+++ b/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 ` 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 ` 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
 
diff --git a/docs/Homebrew-brew-Maintainer-Guide.md b/docs/Homebrew-brew-Maintainer-Guide.md
index b185d5e68335f..f8e3baa02dd1c 100644
--- a/docs/Homebrew-brew-Maintainer-Guide.md
+++ b/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.
diff --git a/docs/How-To-Organize-AGM.md b/docs/How-To-Organize-AGM.md
index a59ba159254b6..9930d41635708 100644
--- a/docs/How-To-Organize-AGM.md
+++ b/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
diff --git a/docs/Manpage.md b/docs/Manpage.md
index c43429d78656c..ec2a9d17cf9c1 100644
--- a/docs/Manpage.md
+++ b/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  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
-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.
+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.
 
 * `--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
-is done automatically when you install formulae but can be useful for DIY
-installations.
+Symlink all of *`formula`*'s installed files into Homebrew's prefix.
+This is done automatically when you install formulae but can be useful
+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 .
 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 .
 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`
   
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`
   
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
   
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`
-  
If set, `brew install`  will not upgrade  if it is installed but outdated.
+  
If set, `brew install` *`formula|cask`* will not upgrade *`formula|cask`* if it is installed but outdated.
 
 - `HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK`
   
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
   
If set, `brew update` will not show the list of newly added formulae/casks.
 
 - `HOMEBREW_PIP_INDEX_URL`
-  
If set, `brew install *`formula`*` will use this URL to download PyPI package resources.
+  
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
   
If set, enable runtime typechecking using Sorbet. Set by default for HOMEBREW_DEVELOPER or when running some developer commands.
 
 - `HOMEBREW_SSH_CONFIG_PATH`
-  
If set, Homebrew will use the given config file instead of `~/.ssh/config` when fetching `git` repos over `ssh`.
+  
If set, Homebrew will use the given config file instead of `~/.ssh/config` when fetching Git repositories over SSH.
 
   *Default:* `$HOME/.ssh/config`
 
diff --git a/docs/Taps.md b/docs/Taps.md
index c4f5db1c38c32..74d2637b7fc75 100644
--- a/docs/Taps.md
+++ b/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
diff --git a/docs/Tips-N'-Tricks.md b/docs/Tips-N'-Tricks.md
index 0e4cd4af3b1e8..d13f571e78103 100644
--- a/docs/Tips-N'-Tricks.md
+++ b/docs/Tips-N'-Tricks.md
@@ -39,7 +39,7 @@ brew install --only-dependencies 
 
 ## 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
 
diff --git a/docs/Typechecking.md b/docs/Typechecking.md
index f11dce7ef5125..d77689d615902 100644
--- a/docs/Typechecking.md
+++ b/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
 
diff --git a/docs/vale-styles/Homebrew/Terms.yml b/docs/vale-styles/Homebrew/Terms.yml
index c6486537b46d8..915388cd2a76a 100644
--- a/docs/vale-styles/Homebrew/Terms.yml
+++ b/docs/vale-styles/Homebrew/Terms.yml
@@ -8,4 +8,5 @@ scope: paragraph
 swap:
   "(?\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\.
-.
-.P
-If no arguments are provided, list all installed taps\.
+Tap a formula repository\. 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\.
-.
-.P
-If no \fItap\fR names are provided, display brief statistics for all installed taps\.
+Show detailed information about one or more \fItap\fRs\. 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\.
-.
-.P
-The generated files are written to the current directory\.
+Generate \fBhomebrew/cask\fR API data files for \fIhttps://formulae\.brew\.sh\fR\. 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\.
-.
-.P
-The generated files are written to the current directory\.
+Generate \fBhomebrew/core\fR API data files for \fIhttps://formulae\.brew\.sh\fR\. 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\.
-.
-.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\.
+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\.
 .
 .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  will not upgrade  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 \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