Lint Ruby docs.

2024-11-25 16:33:34 +08:00 · 2024-04-30 11:10:23 +02:00 · 2024-04-30 11:10:23 +02:00 · 480e264d9a
commit 480e264d9a
parent 9b6fb3d4df
74 changed files with 263 additions and 224 deletions
--- a/.github/ISSUE_TEMPLATE.md
+++ b/.github/ISSUE_TEMPLATE.md
@ -1 +1 @@
-# Please fill out one of the templates on: https://github.com/Homebrew/brew/issues/new/choose or we will close it without comment.
+Please fill out one of the templates on https://github.com/Homebrew/brew/issues/new/choose or we will close your issue without comment.
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@ -25,9 +25,22 @@ jobs:
      - name: Install vale
        run: brew install vale

-      - name: Run vale for docs linting
-        working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs
-        run: vale .
+      - name: Lint docs
+        working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}
+        run: |
+          set -euo pipefail
+
+          # Avoid failing on broken symlinks.
+          rm Library/Homebrew/os/mac/pkgconfig/fuse/fuse.pc
+          rm Library/Homebrew/os/mac/pkgconfig/fuse/osxfuse.pc
+
+          # No ignore support (https://github.com/errata-ai/vale/issues/131).
+          rm -r Library/Homebrew/vendor
+
+          vale .
+
+          # Restore removed files.
+          git reset --hard

      - name: Install Ruby
        uses: ruby/setup-ruby@1198b074305f9356bd56dd4b311757cc0dab2f1c # v1.175.1
--- a/.vale.ini
+++ b/.vale.ini
@ -1,4 +1,7 @@
 StylesPath = ./docs/vale-styles

-[*.md]
+[formats]
+rb = md
+
+[*.{md,rb}]
 BasedOnStyles = Homebrew
--- a/Library/Homebrew/abstract_command.rb
+++ b/Library/Homebrew/abstract_command.rb
@ -6,9 +6,10 @@ require "cli/parser"
 module Homebrew
  # Subclass this to implement a `brew` command. This is preferred to declaring a named function in the `Homebrew`
  # module, because:
+  #
  # - Each Command lives in an isolated namespace.
  # - Each Command implements a defined interface.
-  # - `args` is available as an ivar, and thus does not need to be passed as an argument to helper methods.
+  # - `args` is available as an instance method and thus does not need to be passed as an argument to helper methods.
  # - Subclasses no longer need to reference `CLI::Parser` or parse args explicitly.
  #
  # To subclass, implement a `run` method and provide a `cmd_args` block to document the command and its allowed args.
--- a/Library/Homebrew/build_environment.rb
+++ b/Library/Homebrew/build_environment.rb
@ -28,7 +28,7 @@ class BuildEnvironment
  # DSL for specifying build environment settings.
  module DSL
    # Initialise @env for each class which may use this DSL (e.g. each formula subclass).
-    # `env` may never be called, and it needs to be initialised before the class is frozen.
+    # `env` may never be called and it needs to be initialised before the class is frozen.
    def inherited(child)
      super
      child.instance_eval do
--- a/Library/Homebrew/cask/audit.rb
+++ b/Library/Homebrew/cask/audit.rb
@ -685,7 +685,7 @@ module Cask

    sig { void }
    def audit_github_repository_archived
-      # Deprecated/disabled casks may have an archived repo.
+      # Deprecated/disabled casks may have an archived repository.
      return if cask.discontinued? || cask.deprecated? || cask.disabled?

      user, repo = get_repo_data(%r{https?://github\.com/([^/]+)/([^/]+)/?.*}) if online?
@ -699,7 +699,7 @@ module Cask

    sig { void }
    def audit_gitlab_repository_archived
-      # Deprecated/disabled casks may have an archived repo.
+      # Deprecated/disabled casks may have an archived repository.
      return if cask.discontinued? || cask.deprecated? || cask.disabled?

      user, repo = get_repo_data(%r{https?://gitlab\.com/([^/]+)/([^/]+)/?.*}) if online?
--- a/Library/Homebrew/cleaner.rb
+++ b/Library/Homebrew/cleaner.rb
@ -25,27 +25,28 @@ class Cleaner
  def clean
    ObserverPathnameExtension.reset_counts!

-    # Many formulae include 'lib/charset.alias', but it is not strictly needed
-    # and will conflict if more than one formula provides it
+    # Many formulae include `lib/charset.alias`, but it is not strictly needed
+    # and will conflict if more than one formula provides it.
    observe_file_removal @formula.lib/"charset.alias"

    [@formula.bin, @formula.sbin, @formula.lib].each { |dir| clean_dir(dir) if dir.exist? }

-    # Get rid of any info 'dir' files, so they don't conflict at the link stage
+    # Get rid of any info `dir` files, so they don't conflict at the link stage.
    #
-    # The 'dir' files come in at least 3 locations:
+    # The `dir` files come in at least 3 locations:
    #
-    # 1. 'info/dir'
-    # 2. 'info/#{name}/dir'
-    # 3. 'info/#{arch}/dir'
+    # 1. `info/dir`
+    # 2. `info/#{name}/dir`
+    # 3. `info/#{arch}/dir`
    #
-    # Of these 3 only 'info/#{name}/dir' is safe to keep since the rest will
+    # Of these 3 only `info/#{name}/dir` is safe to keep since the rest will
    # conflict with other formulae because they use a shared location.
    #
-    # See [cleaner: recursively delete info `dir`s by gromgit · Pull Request
-    # #11597][1], [emacs 28.1 bottle does not contain `dir` file · Issue
-    # #100190][2], and [Keep `info/#{f.name}/dir` files in cleaner by
-    # timvisher][3] for more info.
+    # See
+    # [cleaner: recursively delete info `dir`s][1],
+    # [emacs 28.1 bottle does not contain `dir` file][2] and
+    # [Keep `info/#{f.name}/dir` files in cleaner][3]
+    # for more info.
    #
    # [1]: https://github.com/Homebrew/brew/pull/11597
    # [2]: https://github.com/Homebrew/homebrew-core/issues/100190
@ -114,15 +115,15 @@ class Cleaner
  # created as part of installing any Perl module.
  PERL_BASENAMES = Set.new(%w[perllocal.pod .packlist]).freeze

-  # Clean a top-level (bin, sbin, lib) directory, recursively, by fixing file
+  # Clean a top-level (`bin`, `sbin`, `lib`) directory, recursively, by fixing file
  # permissions and removing .la files, unless the files (or parent
  # directories) are protected by skip_clean.
  #
-  # bin and sbin should not have any subdirectories; if either do that is
-  # caught as an audit warning
+  # `bin` and `sbin` should not have any subdirectories; if either do that is
+  # caught as an audit warning.
  #
-  # lib may have a large directory tree (see Erlang for instance), and
-  # clean_dir applies cleaning rules to the entire tree
+  # `lib` may have a large directory tree (see Erlang for instance) and
+  # clean_dir applies cleaning rules to the entire tree.
  sig { params(directory: Pathname).void }
  def clean_dir(directory)
    directory.find do |path|
@ -137,7 +138,7 @@ class Cleaner
      elsif path.symlink?
        # Skip it.
      else
-        # Set permissions for executables and non-executables
+        # Set permissions for executables and non-executables.
        perms = if executable_path?(path)
          0555
        else
--- a/Library/Homebrew/cleanup.rb
+++ b/Library/Homebrew/cleanup.rb
@ -376,7 +376,7 @@ module Homebrew
    def cache_files
      files = cache.directory? ? cache.children : []
      cask_files = (cache/"Cask").directory? ? (cache/"Cask").children : []
-      api_source_files = (cache/"api-source").glob("*/*/*/*/*") # org/repo/git_head/type/file.rb
+      api_source_files = (cache/"api-source").glob("*/*/*/*/*") # `<org>/<repo>/<git_head>/<type>/<token>.rb`
      gh_actions_artifacts = (cache/"gh-actions-artifact").directory? ? (cache/"gh-actions-artifact").children : []

      files.map { |path| { path:, type: nil } } +
@ -571,8 +571,8 @@ module Homebrew
      HOMEBREW_PREFIX.glob("lib/python*/site-packages").each do |site_packages|
        site_packages.each_child do |child|
          next unless child.directory?
-          # TODO: Work out a sensible way to clean up pip's, setuptools', and wheel's
-          #       {dist,site}-info directories. Alternatively, consider always removing
+          # TODO: Work out a sensible way to clean up `pip`'s, `setuptools`' and `wheel`'s
+          #       `{dist,site}-info` directories. Alternatively, consider always removing
          #       all `-info` directories, because we may not be making use of them.
          next if child.basename.to_s.end_with?("-info")

--- a/Library/Homebrew/cmd/--prefix.rb
+++ b/Library/Homebrew/cmd/--prefix.rb
@ -95,7 +95,7 @@ module Homebrew
        dirs  = HOMEBREW_PREFIX.subdirs.map { |dir| dir.basename.to_s }
        dirs -= %w[Library Cellar Caskroom .git]

-        # Exclude cache, logs, and repository, if they are located under the prefix.
+        # Exclude cache, logs and repository, if they are located under the prefix.
        [HOMEBREW_CACHE, HOMEBREW_LOGS, HOMEBREW_REPOSITORY].each do |dir|
          dirs.delete dir.relative_path_from(HOMEBREW_PREFIX).to_s
        end
--- a/Library/Homebrew/cmd/outdated.rb
+++ b/Library/Homebrew/cmd/outdated.rb
@ -13,7 +13,7 @@ module Homebrew
      cmd_args do
        description <<~EOS
          List installed casks and formulae that have an updated version available. By default, version
-          information is displayed in interactive shells, and suppressed otherwise.
+          information is displayed in interactive shells and suppressed otherwise.
        EOS
        switch "-q", "--quiet",
               description: "List only the names of outdated kegs (takes precedence over `--verbose`)."
--- a/Library/Homebrew/dependencies_helpers.rb
+++ b/Library/Homebrew/dependencies_helpers.rb
@ -33,7 +33,7 @@ module DependenciesHelpers
      end

      # If a tap isn't installed, we can't find the dependencies of one of
-      # its formulae, and an exception will be thrown if we try.
+      # its formulae and an exception will be thrown if we try.
      Dependency.keep_but_prune_recursive_deps if klass == Dependency && dep.tap && !dep.tap.installed?
    end
  end
--- a/Library/Homebrew/dependency_collector.rb
+++ b/Library/Homebrew/dependency_collector.rb
@ -7,13 +7,13 @@ require "requirement"
 require "requirements"
 require "extend/cachable"

-## A dependency is a formula that another formula needs to install.
-## A requirement is something other than a formula that another formula
-## needs to be present. This includes external language modules,
-## command-line tools in the path, or any arbitrary predicate.
-##
-## The `depends_on` method in the formula DSL is used to declare
-## dependencies and requirements.
+# A dependency is a formula that another formula needs to install.
+# A requirement is something other than a formula that another formula
+# needs to be present. This includes external language modules,
+# command-line tools in the path, or any arbitrary predicate.
+#
+# The `depends_on` method in the formula DSL is used to declare
+# dependencies and requirements.

 # This class is used by `depends_on` in the formula DSL to turn dependency
 # specifications into the proper kinds of dependencies and requirements.
--- a/Library/Homebrew/dev-cmd/pr-pull.rb
+++ b/Library/Homebrew/dev-cmd/pr-pull.rb
@ -15,7 +15,7 @@ module Homebrew

      cmd_args do
        description <<~EOS
-          Download and publish bottles, and apply the bottle commit from a
+          Download and publish bottles and apply the bottle commit from a
          pull request with artifacts generated by GitHub Actions.
          Requires write access to the repository.
        EOS
@ -187,7 +187,7 @@ module Homebrew
        end
      end

-      # Separates a commit message into subject, body, and trailers.
+      # Separates a commit message into subject, body and trailers.
      def separate_commit_message(message)
        subject = message.lines.first.strip

@ -337,7 +337,7 @@ module Homebrew
        new_package = package_file.read
        bump_subject = determine_bump_subject(old_package, new_package, package_file, reason:)

-        # Commit with the new subject, body, and trailers.
+        # Commit with the new subject, body and trailers.
        safe_system("git", "-C", git_repo.pathname, "commit", "--quiet",
                    "-m", bump_subject, "-m", messages.join("\n"), "-m", trailers.join("\n"),
                    "--author", original_author, "--date", original_date, "--", file)
--- a/Library/Homebrew/dev-cmd/tap-new.rb
+++ b/Library/Homebrew/dev-cmd/tap-new.rb
@ -46,6 +46,8 @@ module Homebrew

        (tap.path/"Formula").mkpath

+        # FIXME: https://github.com/errata-ai/vale/issues/818
+        # <!-- vale off -->
        readme = <<~MARKDOWN
          # #{titleized_user} #{titleized_repo}

@ -59,6 +61,7 @@ module Homebrew

          `brew help`, `man brew` or check [Homebrew's documentation](https://docs.brew.sh).
        MARKDOWN
+        # <!-- vale on -->
        write_path(tap, "README.md", readme)

        actions_main = <<~YAML
--- a/Library/Homebrew/dev-cmd/tests.rb
+++ b/Library/Homebrew/dev-cmd/tests.rb
@ -22,13 +22,13 @@ module Homebrew
               description: "Include tests that use the GitHub API and tests that use any of the taps for " \
                            "official external commands."
        switch "--debug",
-               description: "Enable debugging using ruby/debug, or surface the standard `odebug` output."
+               description: "Enable debugging using `ruby/debug`, or surface the standard `odebug` output."
        switch "--changed",
               description: "Only runs tests on files that were changed from the master branch."
        switch "--fail-fast",
               description: "Exit early on the first failing test."
        flag   "--only=",
-               description: "Run only <test_script>`_spec.rb`. Appending `:`<line_number> will start at a " \
+               description: "Run only `<test_script>_spec.rb`. Appending `:<line_number>` will start at a " \
                            "specific line."
        flag   "--profile=",
               description: "Run the test suite serially to find the <n> slowest tests."
@ -145,7 +145,10 @@ module Homebrew
          end

          # Workaround for:
+          #
+          # ```
          # ruby: no -r allowed while running setuid (SecurityError)
+          # ```
          Process::UID.change_privilege(Process.euid) if Process.euid != Process.uid

          if parallel
--- a/Library/Homebrew/dev-cmd/update-test.rb
+++ b/Library/Homebrew/dev-cmd/update-test.rb
@ -116,7 +116,7 @@ module Homebrew
          # update ENV["PATH"]
          ENV["PATH"] = PATH.new(ENV.fetch("PATH")).prepend(curdir/"bin").to_s

-          # run brew help to install portable-ruby (if needed)
+          # Run `brew help` to install `portable-ruby` (if needed).
          quiet_system "brew", "help"

          # run brew update
--- a/Library/Homebrew/diagnostic.rb
+++ b/Library/Homebrew/diagnostic.rb
@ -221,7 +221,7 @@ module Homebrew
        __check_stray_files "/usr/local/lib", "*.dylib", allow_list, <<~EOS
          Unbrewed dylibs were found in /usr/local/lib.
          If you didn't put them there on purpose they could cause problems when
-          building Homebrew formulae, and may need to be deleted.
+          building Homebrew formulae and may need to be deleted.

          Unexpected dylibs:
        EOS
@ -246,7 +246,7 @@ module Homebrew
        __check_stray_files "/usr/local/lib", "*.a", allow_list, <<~EOS
          Unbrewed static libraries were found in /usr/local/lib.
          If you didn't put them there on purpose they could cause problems when
-          building Homebrew formulae, and may need to be deleted.
+          building Homebrew formulae and may need to be deleted.

          Unexpected static libraries:
        EOS
@ -266,7 +266,7 @@ module Homebrew
        __check_stray_files "/usr/local/lib/pkgconfig", "*.pc", allow_list, <<~EOS
          Unbrewed '.pc' files were found in /usr/local/lib/pkgconfig.
          If you didn't put them there on purpose they could cause problems when
-          building Homebrew formulae, and may need to be deleted.
+          building Homebrew formulae and may need to be deleted.

          Unexpected '.pc' files:
        EOS
@ -287,7 +287,7 @@ module Homebrew
        __check_stray_files "/usr/local/lib", "*.la", allow_list, <<~EOS
          Unbrewed '.la' files were found in /usr/local/lib.
          If you didn't put them there on purpose they could cause problems when
-          building Homebrew formulae, and may need to be deleted.
+          building Homebrew formulae and may need to be deleted.

          Unexpected '.la' files:
        EOS
@ -306,7 +306,7 @@ module Homebrew
        __check_stray_files "/usr/local/include", "**/*.h", allow_list, <<~EOS
          Unbrewed header files were found in /usr/local/include.
          If you didn't put them there on purpose they could cause problems when
-          building Homebrew formulae, and may need to be deleted.
+          building Homebrew formulae and may need to be deleted.

          Unexpected header files:
        EOS
@ -491,7 +491,7 @@ module Homebrew

        <<~EOS
          Git could not be found in your PATH.
-          Homebrew uses Git for several internal functions, and some formulae use Git
+          Homebrew uses Git for several internal functions and some formulae use Git
          checkouts instead of stable tarballs. You may want to install Git:
            brew install git
        EOS
--- a/Library/Homebrew/download_strategy.rb
+++ b/Library/Homebrew/download_strategy.rb
@ -931,8 +931,8 @@ class GitDownloadStrategy < VCSDownloadStrategy

    args << "--no-checkout" << "--filter=blob:none" if partial_clone_sparse_checkout?

-    args << "--config" << "advice.detachedHead=false" # silences detached head warning
-    args << "--config" << "core.fsmonitor=false" # prevent fsmonitor from watching this repo
+    args << "--config" << "advice.detachedHead=false" # Silences “detached head” warning.
+    args << "--config" << "core.fsmonitor=false" # Prevent `fsmonitor` from watching this repository.
    args << @url << cached_location.to_s
  end

--- a/Library/Homebrew/extend/ENV.rb
+++ b/Library/Homebrew/extend/ENV.rb
@ -17,10 +17,16 @@ module Kernel
  private :superenv?
 end

+# <!-- vale off -->
 # @!parse
-#  # ENV is not actually a class, but this makes `YARD` happy
-#  # @see https://rubydoc.info/stdlib/core/ENV ENV core documentation
-#  class ENV; end
+#   # `ENV` is not actually a class, but this makes YARD happy
+#   # @see https://rubydoc.info/stdlib/core/ENV
+#   #   <code>ENV</code> core documentation
+#   # @see Superenv
+#   # @see Stdenv
+#   class ENV; end
+# <!-- vale on -->
+
 module EnvActivation
  sig { params(env: T.nilable(String)).void }
  def activate_extensions!(env: nil)
--- a/Library/Homebrew/extend/os/linux/install.rb
+++ b/Library/Homebrew/extend/os/linux/install.rb
@ -4,7 +4,7 @@
 module Homebrew
  module Install
    # This is a list of known paths to the host dynamic linker on Linux if
-    # the host glibc is new enough.  The symlink_ld_so method will fail if
+    # the host glibc is new enough. The symlink_ld_so method will fail if
    # the host linker cannot be found in this list.
    DYNAMIC_LINKERS = %w[
      /lib64/ld-linux-x86-64.so.2
@ -19,7 +19,7 @@ module Homebrew
    private_constant :DYNAMIC_LINKERS

    # We link GCC runtime libraries that are not specifically used for Fortran,
-    # which are linked by the GCC formula.  We only use the versioned shared libraries
+    # which are linked by the GCC formula. We only use the versioned shared libraries
    # as the other shared and static libraries are only used at build time where
    # GCC can find its own libraries.
    GCC_RUNTIME_LIBS = %w[
--- a/Library/Homebrew/extend/os/mac/diagnostic.rb
+++ b/Library/Homebrew/extend/os/mac/diagnostic.rb
@ -340,7 +340,7 @@ module Homebrew
        else
          inject_file_list @found, <<~EOS
            libiconv files detected at a system prefix other than /usr.
-            Homebrew doesn't provide a libiconv formula, and expects to link against
+            Homebrew doesn't provide a libiconv formula and expects to link against
            the system version in /usr. libiconv in other prefixes can cause
            compile or link failure, especially if compiled with improper
            architectures. macOS itself never installs anything to /usr/local so
--- a/Library/Homebrew/extend/os/mac/formula_cellar_checks.rb
+++ b/Library/Homebrew/extend/os/mac/formula_cellar_checks.rb
@ -112,7 +112,7 @@ module FormulaCellarChecks

    <<~EOS
      Libraries were compiled with a flat namespace.
-      This can cause linker errors due to name collisions, and
+      This can cause linker errors due to name collisions and
      is often due to a bug in detecting the macOS version.
        #{flat_namespace_files * "\n  "}
    EOS
--- a/Library/Homebrew/fetch.rb
+++ b/Library/Homebrew/fetch.rb
@ -20,7 +20,7 @@ module Homebrew
      if os.present?
        return true
      elsif ENV["HOMEBREW_TEST_GENERIC_OS"].present?
-        # `:generic` bottles don't exist, and `--os` flag is not specified.
+        # `:generic` bottles don't exist and `--os` flag is not specified.
        return false
      end
      return true if arch.present?
--- a/Library/Homebrew/formula_assertions.rb
+++ b/Library/Homebrew/formula_assertions.rb
@ -16,7 +16,8 @@ module Homebrew
      @assertions ||= 0
    end

-    # Returns the output of running cmd, and asserts the exit status.
+    # Returns the output of running cmd and asserts the exit status.
+    #
    # @api public
    def shell_output(cmd, result = 0)
      ohai cmd
@ -28,8 +29,9 @@ module Homebrew
      raise
    end

-    # Returns the output of running the cmd with the optional input, and
+    # Returns the output of running the cmd with the optional input and
    # optionally asserts the exit status.
+    #
    # @api public
    def pipe_output(cmd, input = nil, result = nil)
      ohai cmd
--- a/Library/Homebrew/formula_creator.rb
+++ b/Library/Homebrew/formula_creator.rb
@ -99,6 +99,8 @@ module Homebrew

    sig { returns(String) }
    def template
+      # FIXME: https://github.com/errata-ai/vale/issues/818
+      # <!-- vale off -->
      <<~ERB
        # Documentation: https://docs.brew.sh/Formula-Cookbook
        #                https://rubydoc.brew.sh/Formula
@ -183,14 +185,14 @@ module Homebrew
            ENV.prepend_create_path "PERL5LIB", libexec/"lib/perl5"
            ENV.prepend_path "PERL5LIB", libexec/"lib"

-            # Stage additional dependency (Makefile.PL style)
+            # Stage additional dependency (`Makefile.PL` style).
            # resource("").stage do
            #   system "perl", "Makefile.PL", "INSTALL_BASE=\#{libexec}"
            #   system "make"
            #   system "make", "install"
            # end

-            # Stage additional dependency (Build.PL style)
+            # Stage additional dependency (`Build.PL` style).
            # resource("").stage do
            #   system "perl", "Build.PL", "--install_base", libexec
            #   system "./Build"
@ -231,6 +233,7 @@ module Homebrew
          end
        end
      ERB
+      # <!-- vale on -->
    end
  end
 end
--- a/Library/Homebrew/formulary.rb
+++ b/Library/Homebrew/formulary.rb
@ -537,19 +537,19 @@ module Formulary
  class FormulaLoader
    include Context

-    # The formula's name
+    # The formula's name.
    sig { returns(String) }
    attr_reader :name

-    # The formula's ruby file's path or filename
+    # The formula file's path.
    sig { returns(Pathname) }
    attr_reader :path

-    # The name used to install the formula
+    # The name used to install the formula.
    sig { returns(T.nilable(Pathname)) }
    attr_reader :alias_path

-    # The formula's tap (nil if it should be implicitly determined)
+    # The formula's tap (`nil` if it should be implicitly determined).
    sig { returns(T.nilable(Tap)) }
    attr_reader :tap

@ -1019,8 +1019,8 @@ module Formulary
  # Return a {Formula} instance for the given rack.
  #
  # @param spec when nil, will auto resolve the formula's spec.
-  # @param :alias_path will be used if the formula is found not to be
-  #   installed, and discarded if it is installed because the `alias_path` used
+  # @param alias_path will be used if the formula is found not to be
+  #   installed and discarded if it is installed because the `alias_path` used
  #   to install the formula will be set instead.
  sig {
    params(
--- a/Library/Homebrew/github_packages.rb
+++ b/Library/Homebrew/github_packages.rb
@ -94,12 +94,12 @@ class GitHubPackages
  end

  def self.repo_without_prefix(repo)
-    # remove redundant repo prefix for a shorter name
+    # Remove redundant repository prefix for a shorter name.
    repo.delete_prefix("homebrew-")
  end

  def self.root_url(org, repo, prefix = URL_PREFIX)
-    # docker/skopeo insist on lowercase org ("repository name")
+    # `docker`/`skopeo` insist on lowercase organisation (“repository name”).
    org = org.downcase

    "#{prefix}#{org}/#{repo_without_prefix(repo)}"
@ -115,9 +115,9 @@ class GitHubPackages
  end

  def self.image_formula_name(formula_name)
-    # invalid docker name characters
-    # / makes sense because we already use it to separate repo/formula
-    # x makes sense because we already use it in Formulary
+    # Invalid docker name characters:
+    # - `/` makes sense because we already use it to separate repository/formula.
+    # - `x` makes sense because we already use it in `Formulary`.
    formula_name.tr("@", "/")
                .tr("+", "x")
  end
@ -231,9 +231,9 @@ class GitHubPackages
      inspect_args << "--creds=#{user}:#{token}"
      inspect_result = system_command(skopeo, print_stderr: false, args: inspect_args)

-      # Order here is important
+      # Order here is important.
      if !inspect_result.status.success? && !inspect_result.stderr.match?(/(name|manifest) unknown/)
-        # We got an error, and it was not about the tag or package being unknown.
+        # We got an error and it was not about the tag or package being unknown.
        if warn_on_error
          opoo "#{image_uri} inspection returned an error, skipping upload!\n#{inspect_result.stderr}"
          return
@ -241,11 +241,11 @@ class GitHubPackages
          odie "#{image_uri} inspection returned an error!\n#{inspect_result.stderr}"
        end
      elsif keep_old
-        # If the tag doesn't exist, ignore --keep-old.
+        # If the tag doesn't exist, ignore `--keep-old`.
        keep_old = false unless inspect_result.status.success?
        # Otherwise, do nothing - the tag already existing is expected behaviour for --keep-old.
      elsif inspect_result.status.success?
-        # The tag already exists, and we are not passing --keep-old.
+        # The tag already exists and we are not passing `--keep-old`.
        if warn_on_error
          opoo "#{image_uri} already exists, skipping upload!"
          return
--- a/Library/Homebrew/keg.rb
+++ b/Library/Homebrew/keg.rb
@ -552,8 +552,8 @@ class Keg

    src = dst.resolved_path

-    # src itself may be a symlink, so check lstat to ensure we are dealing with
-    # a directory, and not a symlink pointing at a directory (which needs to be
+    # `src` itself may be a symlink, so check lstat to ensure we are dealing with
+    # a directory and not a symlink pointing to a directory (which needs to be
    # treated as a file). In other words, we only want to resolve one symlink.

    begin
--- a/Library/Homebrew/language/python.rb
+++ b/Library/Homebrew/language/python.rb
@ -144,7 +144,7 @@ module Language

    # Mixin module for {Formula} adding virtualenv support features.
    module Virtualenv
-      # Instantiates, creates, and yields a {Virtualenv} object for use from
+      # Instantiates, creates and yields a {Virtualenv} object for use from
      # {Formula#install}, which provides helper methods for instantiating and
      # installing packages into a Python virtualenv.
      #
@ -211,7 +211,7 @@ module Language

      # Helper method for the common case of installing a Python application.
      # Creates a virtualenv in `libexec`, installs all `resource`s defined
-      # on the formula, and then installs the formula. An options hash may be
+      # on the formula and then installs the formula. An options hash may be
      # passed (e.g. `:using => "python"`) to override the default, guessed
      # formula preference for python or python@x.y, or to resolve an ambiguous
      # case where it's not clear whether python or python@x.y should be the
--- a/Library/Homebrew/livecheck/strategy/git.rb
+++ b/Library/Homebrew/livecheck/strategy/git.rb
@ -13,7 +13,7 @@ module Homebrew
      # Livecheck has historically prioritized the {Git} strategy over others
      # and this behavior was continued when the priority setup was created.
      # This is partly related to Livecheck checking formula URLs in order of
-      # `head`, `stable`, and then `homepage`. The higher priority here may
+      # `head`, `stable` and then `homepage`. The higher priority here may
      # be removed (or altered) in the future if we reevaluate this particular
      # behavior.
      #
--- a/Library/Homebrew/livecheck/strategy/json.rb
+++ b/Library/Homebrew/livecheck/strategy/json.rb
@ -4,7 +4,7 @@
 module Homebrew
  module Livecheck
    module Strategy
-      # The {Json} strategy fetches content at a URL, parses it as JSON, and
+      # The {Json} strategy fetches content at a URL, parses it as JSON and
      # provides the parsed data to a `strategy` block. If a regex is present
      # in the `livecheck` block, it should be passed as the second argument to
      # the `strategy` block.
--- a/Library/Homebrew/livecheck/strategy/xml.rb
+++ b/Library/Homebrew/livecheck/strategy/xml.rb
@ -5,7 +5,7 @@ module Homebrew
  module Livecheck
    module Strategy
      # The {Xml} strategy fetches content at a URL, parses it as XML using
-      # `REXML`, and provides the `REXML::Document` to a `strategy` block.
+      # `REXML` and provides the `REXML::Document` to a `strategy` block.
      # If a regex is present in the `livecheck` block, it should be passed
      # as the second argument to the `strategy` block.
      #
--- a/Library/Homebrew/livecheck/strategy/yaml.rb
+++ b/Library/Homebrew/livecheck/strategy/yaml.rb
@ -4,7 +4,7 @@
 module Homebrew
  module Livecheck
    module Strategy
-      # The {Yaml} strategy fetches content at a URL, parses it as YAML, and
+      # The {Yaml} strategy fetches content at a URL, parses it as YAML and
      # provides the parsed data to a `strategy` block. If a regex is present
      # in the `livecheck` block, it should be passed as the second argument to
      # the `strategy` block.
--- a/Library/Homebrew/manpages.rb
+++ b/Library/Homebrew/manpages.rb
@ -142,7 +142,7 @@ module Homebrew

    sig { returns(String) }
    def self.global_cask_options_manpage
-      lines = ["These options are applicable to the `install`, `reinstall`, and `upgrade` " \
+      lines = ["These options are applicable to the `install`, `reinstall` and `upgrade` " \
               "subcommands with the `--cask` switch.\n"]
      lines += Homebrew::CLI::Parser.global_cask_options.map do |_, long, kwargs|
        generate_option_doc(nil, long.chomp("="), kwargs.fetch(:description))
--- a/Library/Homebrew/mktemp.rb
+++ b/Library/Homebrew/mktemp.rb
@ -1,7 +1,7 @@
 # typed: true
 # frozen_string_literal: true

-# Performs {Formula#mktemp}'s functionality, and tracks the results.
+# Performs {Formula#mktemp}'s functionality and tracks the results.
 # Each instance is only intended to be used once.
 class Mktemp
  include FileUtils
--- a/Library/Homebrew/os/mac/sdk.rb
+++ b/Library/Homebrew/os/mac/sdk.rb
@ -173,8 +173,8 @@ module OS
      # using that.
      # As of Xcode 10, the Unix-style headers are installed via a
      # separate package, so we can't rely on their being present.
-      # This will only look up SDKs on Xcode 10 or newer, and still
-      # return nil SDKs for Xcode 9 and older.
+      # This will only look up SDKs on Xcode 10 or newer and still
+      # return `nil` SDKs for Xcode 9 and older.
      sig { override.returns(String) }
      def sdk_prefix
        @sdk_prefix ||= if CLT.provides_sdk?
--- a/Library/Homebrew/resource.rb
+++ b/Library/Homebrew/resource.rb
@ -170,8 +170,8 @@ class Resource < Downloadable
  end

  # Whether a livecheck specification is defined or not.
-  # It returns true when a livecheck block is present in the {Resource} and
-  # false otherwise, and is used by livecheck.
+  # It returns true when a `livecheck` block is present in the {Resource} and
+  # false otherwise and is used by livecheck.
  def livecheckable?
    @livecheckable == true
  end
--- a/Library/Homebrew/rubocops/cask/array_alphabetization.rb
+++ b/Library/Homebrew/rubocops/cask/array_alphabetization.rb
@ -44,7 +44,7 @@ module RuboCop
          end

          # Separate the lines into those that should be sorted and those that should not
-          # ie. skip the opening and closing brackets of the array
+          # i.e. skip the opening and closing brackets of the array.
          to_sort, to_keep = combined_source.partition { |line| !line.include?("[") && !line.include?("]") }

          # Sort the lines that should be sorted
--- a/Library/Homebrew/rubocops/cask/url.rb
+++ b/Library/Homebrew/rubocops/cask/url.rb
@ -44,7 +44,7 @@ module RuboCop

            # Skip if the URL and the verified value are the same.
            next if value_node.source == url_stanza.source.gsub(%r{^"https?://}, "\"")
-            # Skip if the URL has two path components, eg: `https://github.com/google/fonts.git`.
+            # Skip if the URL has two path components, e.g. `https://github.com/google/fonts.git`.
            next if url_stanza.source.gsub(%r{^"https?://}, "\"").count("/") == 2
            # Skip if the verified value ends with a slash.
            next if value_node.str_content.end_with?("/")
--- a/Library/Homebrew/rubocops/compact_blank.rb
+++ b/Library/Homebrew/rubocops/compact_blank.rb
@ -13,7 +13,7 @@ module RuboCop
      #       `[[1, 2], [3, nil]].compact_blank` are not compatible. The same is true for `blank?`.
      #       This will work fine when the receiver is a hash object.
      #
-      #       And `compact_blank!` has different implementations for `Array`, `Hash`, and
+      #       And `compact_blank!` has different implementations for `Array`, `Hash` and
      #       `ActionController::Parameters`.
      #       `Array#compact_blank!`, `Hash#compact_blank!` are equivalent to `delete_if(&:blank?)`.
      #       `ActionController::Parameters#compact_blank!` is equivalent to `reject!(&:blank?)`.
--- a/Library/Homebrew/rubocops/homepage.rb
+++ b/Library/Homebrew/rubocops/homepage.rb
@ -69,8 +69,8 @@ module RuboCop
          #
          # Compact the above into this list as we're able to remove detailed notations, etc over time.
          when
-               # Check for http:// GitHub homepage URLs, https:// is preferred.
-               # NOTE: Only check homepages that are repo pages, not *.github.com hosts.
+               # Check for `http://` GitHub homepage URLs, `https://` is preferred.
+               # NOTE: Only check homepages that are repository pages, not `*.github.com` hosts.
               %r{^http://github\.com/},
               %r{^http://[^/]*\.github\.io/},

--- a/Library/Homebrew/rubocops/urls.rb
+++ b/Library/Homebrew/rubocops/urls.rb
@ -127,7 +127,7 @@ module RuboCop
          # SourceForge url patterns
          sourceforge_patterns = %r{^https?://.*\b(sourceforge|sf)\.(com|net)}
          audit_urls(urls, sourceforge_patterns) do |_, url|
-            # Skip if the URL looks like a SVN repo
+            # Skip if the URL looks like a SVN repository.
            next if url.include? "/svnroot/"
            next if url.include? "svn.sourceforge"
            next if url.include? "/p/"
@ -183,19 +183,19 @@ module RuboCop
            problem "Please use https:// for #{url}"
          end

-          # Check for git:// GitHub repo URLs, https:// is preferred.
+          # Check for `git://` GitHub repository URLs, https:// is preferred.
          git_gh_pattern = %r{^git://[^/]*github\.com/}
          audit_urls(urls, git_gh_pattern) do |_, url|
            problem "Please use https:// for #{url}"
          end

-          # Check for git:// Gitorious repo URLs, https:// is preferred.
+          # Check for `git://` Gitorious repository URLs, https:// is preferred.
          git_gitorious_pattern = %r{^git://[^/]*gitorious\.org/}
          audit_urls(urls, git_gitorious_pattern) do |_, url|
            problem "Please use https:// for #{url}"
          end

-          # Check for http:// GitHub repo URLs, https:// is preferred.
+          # Check for `http://` GitHub repository URLs, https:// is preferred.
          gh_pattern = %r{^http://github\.com/.*\.git$}
          audit_urls(urls, gh_pattern) do |_, url|
            problem "Please use https:// for #{url}"
--- a/Library/Homebrew/software_spec.rb
+++ b/Library/Homebrew/software_spec.rb
@ -621,11 +621,11 @@ class BottleSpecification
  def checksums
    tags = collector.tags.sort_by do |tag|
      version = tag.to_macos_version
-      # Give arm64 bottles a higher priority so they are first
-      priority = (tag.arch == :arm64) ? "2" : "1"
+      # Give `arm64` bottles a higher priority so they are first.
+      priority = (tag.arch == :arm64) ? 2 : 1
      "#{priority}.#{version}_#{tag}"
    rescue MacOSVersion::Error
-      # Sort non-MacOS tags below MacOS tags.
+      # Sort non-macOS tags below macOS tags.
      "0.#{tag}"
    end
    tags.reverse.map do |tag|
--- a/Library/Homebrew/startup/config.rb
+++ b/Library/Homebrew/startup/config.rb
@ -12,7 +12,7 @@ HOMEBREW_PREFIX = Pathname(ENV.fetch("HOMEBREW_PREFIX")).freeze
 # Where `.git` is found
 HOMEBREW_REPOSITORY = Pathname(ENV.fetch("HOMEBREW_REPOSITORY")).freeze

-# Where we store most of Homebrew, taps, and various metadata
+# Where we store most of Homebrew, taps and various metadata
 HOMEBREW_LIBRARY = Pathname(ENV.fetch("HOMEBREW_LIBRARY")).freeze

 # Where shim scripts for various build and SCM tools are stored
@ -39,7 +39,7 @@ HOMEBREW_CACHE = Pathname(ENV.fetch("HOMEBREW_CACHE")).freeze
 # Where formulae installed via URL are cached
 HOMEBREW_CACHE_FORMULA = (HOMEBREW_CACHE/"Formula").freeze

-# Where build, postinstall, and test logs of formulae are written to
+# Where build, postinstall and test logs of formulae are written to
 HOMEBREW_LOGS = Pathname(ENV.fetch("HOMEBREW_LOGS")).expand_path.freeze

 # Path to the list of Homebrew maintainers as a JSON file
--- a/Library/Homebrew/tap.rb
+++ b/Library/Homebrew/tap.rb
@ -448,9 +448,9 @@ class Tap
    args << "--origin=origin"
    args << "-q" if quiet

-    # Override user-set default template
+    # Override user-set default template.
    args << "--template="
-    # prevent fsmonitor from watching this repo
+    # Prevent `fsmonitor` from watching this repository.
    args << "--config" << "core.fsmonitor=false"

    begin
--- a/Library/Homebrew/test/cask/artifact/abstract_artifact_spec.rb
+++ b/Library/Homebrew/test/cask/artifact/abstract_artifact_spec.rb
@ -4,7 +4,7 @@ RSpec.describe Cask::Artifact::AbstractArtifact, :cask do
  describe ".read_script_arguments" do
    let(:stanza) { :installer }

-    it "accepts a string, and uses it as the executable" do
+    it "accepts a string and uses it as the executable" do
      arguments = "something"

      expect(described_class.read_script_arguments(arguments, stanza)).to eq(["something", {}])
--- a/Library/Homebrew/test/cask/dsl_spec.rb
+++ b/Library/Homebrew/test/cask/dsl_spec.rb
@ -5,7 +5,7 @@ RSpec.describe Cask::DSL, :cask do
  let(:token) { "basic-cask" }

  describe "stanzas" do
-    it "lets you set url, homepage, and version" do
+    it "lets you set url, homepage and version" do
      expect(cask.url.to_s).to eq("https://brew.sh/TestCask-1.2.3.dmg")
      expect(cask.homepage).to eq("https://brew.sh/")
      expect(cask.version.to_s).to eq("1.2.3")
--- a/Library/Homebrew/test/language/python/virtualenv_spec.rb
+++ b/Library/Homebrew/test/language/python/virtualenv_spec.rb
@ -140,7 +140,7 @@ RSpec.describe Language::Python::Virtualenv, :needs_python do
      end.to raise_error(ArgumentError)
    end

-    it "installs resources in correct order when combining `without`, `start_with`, and `end_with" do
+    it "installs resources in correct order when combining `without`, `start_with` and `end_with" do
      expect(f).to receive(:virtualenv_create).and_return(venv)
      expect(venv).to receive(:pip_install).with([r_d, r_c, r_b])
      expect(venv).to receive(:pip_install_and_link).with(buildpath, { link_manpages: false })
--- a/Library/Homebrew/test/livecheck/strategy/extract_plist_spec.rb
+++ b/Library/Homebrew/test/livecheck/strategy/extract_plist_spec.rb
@ -72,7 +72,7 @@ RSpec.describe Homebrew::Livecheck::Strategy::ExtractPlist do
      ).to eq(versions)
    end

-    it "returns an array of version strings when given Items, a regex, and a block" do
+    it "returns an array of version strings when given `Item`s, a regex and a block" do
      # Returning a string from block
      expect(
        extract_plist.versions_from_items(multipart_items, multipart_regex) do |items, regex|
--- a/Library/Homebrew/test/livecheck/strategy/sparkle_spec.rb
+++ b/Library/Homebrew/test/livecheck/strategy/sparkle_spec.rb
@ -395,7 +395,7 @@ RSpec.describe Homebrew::Livecheck::Strategy::Sparkle do
      ).to eq([items[:v121].nice_version])
    end

-    it "returns an array of version strings when given content, a regex, and a block" do
+    it "returns an array of version strings when given content, a regex and a block" do
      # Returning a string from the block
      expect(
        sparkle.versions_from_content(xml[:appcast], title_regex) do |item, regex|
--- a/Library/Homebrew/test/os/linux/dependency_collector_spec.rb
+++ b/Library/Homebrew/test/os/linux/dependency_collector_spec.rb
@ -10,7 +10,7 @@ RSpec.describe DependencyCollector do
  describe "#add" do
    resource = Resource.new

-    context "when xz, unzip, and bzip2 are not available" do
+    context "when xz, unzip and bzip2 are not available" do
      it "creates a resource dependency from a '.xz' URL" do
        resource.url("https://brew.sh/foo.xz")
        allow_any_instance_of(Object).to receive(:which).with("xz")
@ -30,7 +30,7 @@ RSpec.describe DependencyCollector do
      end
    end

-    context "when xz, zip, and bzip2 are available" do
+    context "when xz, zip and bzip2 are available" do
      it "does not create a resource dependency from a '.xz' URL" do
        resource.url("https://brew.sh/foo.xz")
        allow_any_instance_of(Object).to receive(:which).with("xz").and_return(Pathname.new("foo"))
--- a/Library/Homebrew/test/rubocops/caveats_spec.rb
+++ b/Library/Homebrew/test/rubocops/caveats_spec.rb
@ -13,7 +13,7 @@ RSpec.describe RuboCop::Cop::FormulaAudit::Caveats do
          url "https://brew.sh/foo-1.0.tgz"
           def caveats
            "setuid"
-            ^^^^^^^^ FormulaAudit/Caveats: Don't recommend setuid in the caveats, suggest sudo instead.
+            ^^^^^^^^ FormulaAudit/Caveats: Don't recommend `setuid` in the caveats, suggest `sudo` instead.
          end
        end
      RUBY
--- a/Library/Homebrew/test/spec_helper.rb
+++ b/Library/Homebrew/test/spec_helper.rb
@ -102,7 +102,7 @@ RSpec.configure do |config|
  end
  config.mock_with :rspec do |mocks|
    # Prevents you from mocking or stubbing a method that does not exist on
-    # a real object. This is generally recommended, and will default to
+    # a real object. This is generally recommended and will default to
    # `true` in RSpec 4.
    mocks.verify_partial_doubles = true
  end
--- a/Library/Homebrew/test/utils/gzip_spec.rb
+++ b/Library/Homebrew/test/utils/gzip_spec.rb
@ -6,7 +6,7 @@ RSpec.describe Utils::Gzip do
  include FileUtils

  describe "compress_with_options" do
-    it "uses the explicitly specified mtime, orig_name, and output path when passed" do
+    it "uses the explicitly specified mtime, orig_name and output path when passed" do
      mktmpdir do |path|
        mtime = Time.at(12345).utc
        orig_name = "someotherfile"
--- a/Library/Homebrew/test/utils/pypi_spec.rb
+++ b/Library/Homebrew/test/utils/pypi_spec.rb
@ -141,7 +141,7 @@ RSpec.describe PyPI do
        expect(package_with_version.pypi_info(new_version: "5.29.0")).to eq expected_result
      end

-      it "gets pypi info from a package name, extras, and version" do
+      it "gets pypi info from a package name, extras and version" do
        expected_result = ["snakemake", old_pypi_package_url, old_package_checksum, "5.28.0"]
        expect(package_with_extra_and_version.pypi_info).to eq expected_result
      end
--- a/Library/Homebrew/utils/curl.rb
+++ b/Library/Homebrew/utils/curl.rb
@ -333,7 +333,7 @@ module Utils
        # GitHub does not authorize access to the web UI using token
        #
        # Strategy:
-        # If the `:homepage` 404s, it's a GitHub link, and we have a token then
+        # If the `:homepage` 404s, it's a GitHub link and we have a token then
        # check the API (which does use tokens) for the repository
        repo_details = url.match(%r{https?://github\.com/(?<user>[^/]+)/(?<repo>[^/]+)/?.*})
        check_github_api = url_type == SharedAudits::URL_TYPE_HOMEPAGE &&
@ -483,7 +483,7 @@ module Utils

    # Separates the output text from `curl` into an array of HTTP responses and
    # the final response body (i.e. content). Response hashes contain the
-    # `:status_code`, `:status_text`, and `:headers`.
+    # `:status_code`, `:status_text` and `:headers`.
    # @param output [String] The output text from `curl` containing HTTP
    #   responses, body content, or both.
    # @param max_iterations [Integer] The maximum number of iterations for the
--- a/Library/Homebrew/utils/gems.rb
+++ b/Library/Homebrew/utils/gems.rb
@ -231,7 +231,7 @@ module Homebrew
    invalid_groups = groups - valid_gem_groups
    raise ArgumentError, "Invalid gem groups: #{invalid_groups.join(", ")}" unless invalid_groups.empty?

-    # tests should not modify the state of the repo
+    # Tests should not modify the state of the repository.
    if ENV["HOMEBREW_TESTS"]
      setup_gem_environment!
      return
--- a/Library/Homebrew/utils/pypi.rb
+++ b/Library/Homebrew/utils/pypi.rb
@ -49,7 +49,7 @@ module PyPI
      @is_pypi_url || !@is_url
    end

-    # Get name, URL, SHA-256 checksum, and latest version for a given package.
+    # Get name, URL, SHA-256 checksum and latest version for a given package.
    # This only works for packages from PyPI or from a PyPI URL; packages
    # derived from non-PyPI URLs will produce `nil` here.
    sig { params(new_version: T.nilable(T.any(String, Version))).returns(T.nilable(T::Array[String])) }
--- a/Library/Homebrew/utils/shell.rb
+++ b/Library/Homebrew/utils/shell.rb
@ -110,26 +110,26 @@ module Utils

    sig { params(str: String).returns(String) }
    def csh_quote(str)
-      # ruby's implementation of shell_escape
+      # Ruby's implementation of `shell_escape`.
      str = str.to_s
      return "''" if str.empty?

      str = str.dup
-      # anything that isn't a known safe character is padded
+      # Anything that isn't a known safe character is padded.
      str.gsub!(UNSAFE_SHELL_CHAR, "\\\\" + "\\1") # rubocop:disable Style/StringConcatenation
-      # newlines have to be specially quoted in csh
+      # Newlines have to be specially quoted in `csh`.
      str.gsub!("\n", "'\\\n'")
      str
    end

    sig { params(str: String).returns(String) }
    def sh_quote(str)
-      # ruby's implementation of shell_escape
+      # Ruby's implementation of `shell_escape`.
      str = str.to_s
      return "''" if str.empty?

      str = str.dup
-      # anything that isn't a known safe character is padded
+      # Anything that isn't a known safe character is padded.
      str.gsub!(UNSAFE_SHELL_CHAR, "\\\\" + "\\1") # rubocop:disable Style/StringConcatenation
      str.gsub!("\n", "'\n'")
      str
--- a/Library/Homebrew/version.rb
+++ b/Library/Homebrew/version.rb
@ -382,115 +382,115 @@ class Version

  VERSION_PARSERS = [
    # date-based versioning
-    # e.g. 2023-09-28.tar.gz
-    # e.g. ltopers-v2017-04-14.tar.gz
+    # e.g. `2023-09-28.tar.gz`
+    # e.g. `ltopers-v2017-04-14.tar.gz`
    StemParser.new(/(?:^|[._-]?)v?(\d{4}-\d{2}-\d{2})/),

    # GitHub tarballs
-    # e.g. https://github.com/foo/bar/tarball/v1.2.3
-    # e.g. https://github.com/sam-github/libnet/tarball/libnet-1.1.4
-    # e.g. https://github.com/isaacs/npm/tarball/v0.2.5-1
-    # e.g. https://github.com/petdance/ack/tarball/1.93_02
+    # e.g. `https://github.com/foo/bar/tarball/v1.2.3`
+    # e.g. `https://github.com/sam-github/libnet/tarball/libnet-1.1.4`
+    # e.g. `https://github.com/isaacs/npm/tarball/v0.2.5-1`
+    # e.g. `https://github.com/petdance/ack/tarball/1.93_02`
    UrlParser.new(%r{github\.com/.+/(?:zip|tar)ball/(?:v|\w+-)?((?:\d+[._-])+\d*)$}),

-    # e.g. https://github.com/erlang/otp/tarball/OTP_R15B01 (erlang style)
+    # e.g. `https://github.com/erlang/otp/tarball/OTP_R15B01 (erlang style)`
    UrlParser.new(/[_-]([Rr]\d+[AaBb]\d*(?:-\d+)?)/),

-    # e.g. boost_1_39_0
+    # e.g. `boost_1_39_0`
    StemParser.new(/((?:\d+_)+\d+)$/) { |s| s.tr("_", ".") },

-    # e.g. foobar-4.5.1-1
-    # e.g. unrtf_0.20.4-1
-    # e.g. ruby-1.9.1-p243
+    # e.g. `foobar-4.5.1-1`
+    # e.g. `unrtf_0.20.4-1`
+    # e.g. `ruby-1.9.1-p243`
    StemParser.new(/[_-](#{NUMERIC_WITH_DOTS}-(?:p|P|rc|RC)?\d+)#{CONTENT_SUFFIX}?$/),

    # Hyphenated versions without software-name prefix (e.g. brew-)
-    # e.g. v0.0.8-12.tar.gz
-    # e.g. 3.3.04-1.tar.gz
-    # e.g. v2.1-20210510.tar.gz
-    # e.g. 2020.11.11-3.tar.gz
-    # e.g. v3.6.6-0.2
+    # e.g. `v0.0.8-12.tar.gz`
+    # e.g. `3.3.04-1.tar.gz`
+    # e.g. `v2.1-20210510.tar.gz`
+    # e.g. `2020.11.11-3.tar.gz`
+    # e.g. `v3.6.6-0.2`
    StemParser.new(/^v?(#{NUMERIC_WITH_DOTS}(?:-#{NUMERIC_WITH_OPTIONAL_DOTS})+)/),

    # URL with no extension
-    # e.g. https://waf.io/waf-1.8.12
-    # e.g. https://codeload.github.com/gsamokovarov/jump/tar.gz/v0.7.1
+    # e.g. `https://waf.io/waf-1.8.12`
+    # e.g. `https://codeload.github.com/gsamokovarov/jump/tar.gz/v0.7.1`
    UrlParser.new(/[-v](#{NUMERIC_WITH_OPTIONAL_DOTS})$/),

-    # e.g. lame-398-1
+    # e.g. `lame-398-1`
    StemParser.new(/-(\d+-\d+)/),

-    # e.g. foobar-4.5.1
+    # e.g. `foobar-4.5.1`
    StemParser.new(/-(#{NUMERIC_WITH_OPTIONAL_DOTS})$/),

-    # e.g. foobar-4.5.1.post1
+    # e.g. `foobar-4.5.1.post1`
    StemParser.new(/-(#{NUMERIC_WITH_OPTIONAL_DOTS}(.post\d+)?)$/),

-    # e.g. foobar-4.5.1b
+    # e.g. `foobar-4.5.1b`
    StemParser.new(/-(#{NUMERIC_WITH_OPTIONAL_DOTS}(?:[abc]|rc|RC)\d*)$/),

-    # e.g. foobar-4.5.0-alpha5, foobar-4.5.0-beta1, or foobar-4.50-beta
+    # e.g. `foobar-4.5.0-alpha5, foobar-4.5.0-beta1, or foobar-4.50-beta`
    StemParser.new(/-(#{NUMERIC_WITH_OPTIONAL_DOTS}-(?:alpha|beta|rc)\d*)$/),

-    # e.g. https://ftpmirror.gnu.org/libidn/libidn-1.29-win64.zip
-    # e.g. https://ftpmirror.gnu.org/libmicrohttpd/libmicrohttpd-0.9.17-w32.zip
+    # e.g. `https://ftpmirror.gnu.org/libidn/libidn-1.29-win64.zip`
+    # e.g. `https://ftpmirror.gnu.org/libmicrohttpd/libmicrohttpd-0.9.17-w32.zip`
    StemParser.new(/-(#{MINOR_OR_PATCH})-w(?:in)?(?:32|64)$/),

    # Opam packages
-    # e.g. https://opam.ocaml.org/archives/sha.1.9+opam.tar.gz
-    # e.g. https://opam.ocaml.org/archives/lablgtk.2.18.3+opam.tar.gz
-    # e.g. https://opam.ocaml.org/archives/easy-format.1.0.2+opam.tar.gz
+    # e.g. `https://opam.ocaml.org/archives/sha.1.9+opam.tar.gz`
+    # e.g. `https://opam.ocaml.org/archives/lablgtk.2.18.3+opam.tar.gz`
+    # e.g. `https://opam.ocaml.org/archives/easy-format.1.0.2+opam.tar.gz`
    StemParser.new(/\.(#{MINOR_OR_PATCH})\+opam$/),

-    # e.g. https://ftpmirror.gnu.org/mtools/mtools-4.0.18-1.i686.rpm
-    # e.g. https://ftpmirror.gnu.org/autogen/autogen-5.5.7-5.i386.rpm
-    # e.g. https://ftpmirror.gnu.org/libtasn1/libtasn1-2.8-x86.zip
-    # e.g. https://ftpmirror.gnu.org/libtasn1/libtasn1-2.8-x64.zip
-    # e.g. https://ftpmirror.gnu.org/mtools/mtools_4.0.18_i386.deb
+    # e.g. `https://ftpmirror.gnu.org/mtools/mtools-4.0.18-1.i686.rpm`
+    # e.g. `https://ftpmirror.gnu.org/autogen/autogen-5.5.7-5.i386.rpm`
+    # e.g. `https://ftpmirror.gnu.org/libtasn1/libtasn1-2.8-x86.zip`
+    # e.g. `https://ftpmirror.gnu.org/libtasn1/libtasn1-2.8-x64.zip`
+    # e.g. `https://ftpmirror.gnu.org/mtools/mtools_4.0.18_i386.deb`
    StemParser.new(/[_-](#{MINOR_OR_PATCH}(?:-\d+)?)[._-](?:i[36]86|x86|x64(?:[_-](?:32|64))?)$/),

-    # e.g. https://registry.npmjs.org/@angular/cli/-/cli-1.3.0-beta.1.tgz
-    # e.g. https://github.com/dlang/dmd/archive/v2.074.0-beta1.tar.gz
-    # e.g. https://github.com/dlang/dmd/archive/v2.074.0-rc1.tar.gz
-    # e.g. https://github.com/premake/premake-core/releases/download/v5.0.0-alpha10/premake-5.0.0-alpha10-src.zip
+    # e.g. `https://registry.npmjs.org/@angular/cli/-/cli-1.3.0-beta.1.tgz`
+    # e.g. `https://github.com/dlang/dmd/archive/v2.074.0-beta1.tar.gz`
+    # e.g. `https://github.com/dlang/dmd/archive/v2.074.0-rc1.tar.gz`
+    # e.g. `https://github.com/premake/premake-core/releases/download/v5.0.0-alpha10/premake-5.0.0-alpha10-src.zip`
    StemParser.new(/[-.vV]?(#{NUMERIC_WITH_DOTS}#{PRERELEASE_SUFFIX})/),

-    # e.g. foobar4.5.1
+    # e.g. `foobar4.5.1`
    StemParser.new(/(#{NUMERIC_WITH_OPTIONAL_DOTS})$/),

-    # e.g. foobar-4.5.0-bin
+    # e.g. `foobar-4.5.0-bin`
    StemParser.new(/[-vV](#{NUMERIC_WITH_DOTS}[abc]?)#{CONTENT_SUFFIX}$/),

    # dash version style
-    # e.g. http://www.antlr.org/download/antlr-3.4-complete.jar
-    # e.g. https://cdn.nuxeo.com/nuxeo-9.2/nuxeo-server-9.2-tomcat.zip
-    # e.g. https://search.maven.org/remotecontent?filepath=com/facebook/presto/presto-cli/0.181/presto-cli-0.181-executable.jar
-    # e.g. https://search.maven.org/remotecontent?filepath=org/fusesource/fuse-extra/fusemq-apollo-mqtt/1.3/fusemq-apollo-mqtt-1.3-uber.jar
-    # e.g. https://search.maven.org/remotecontent?filepath=org/apache/orc/orc-tools/1.2.3/orc-tools-1.2.3-uber.jar
+    # e.g. `http://www.antlr.org/download/antlr-3.4-complete.jar`
+    # e.g. `https://cdn.nuxeo.com/nuxeo-9.2/nuxeo-server-9.2-tomcat.zip`
+    # e.g. `https://search.maven.org/remotecontent?filepath=com/facebook/presto/presto-cli/0.181/presto-cli-0.181-executable.jar`
+    # e.g. `https://search.maven.org/remotecontent?filepath=org/fusesource/fuse-extra/fusemq-apollo-mqtt/1.3/fusemq-apollo-mqtt-1.3-uber.jar`
+    # e.g. `https://search.maven.org/remotecontent?filepath=org/apache/orc/orc-tools/1.2.3/orc-tools-1.2.3-uber.jar`
    StemParser.new(/-(#{NUMERIC_WITH_DOTS})-/),

-    # e.g. dash_0.5.5.1.orig.tar.gz (Debian style)
+    # e.g. `dash_0.5.5.1.orig.tar.gz (Debian style)`
    StemParser.new(/_(#{NUMERIC_WITH_DOTS}[abc]?)\.orig$/),

-    # e.g. https://www.openssl.org/source/openssl-0.9.8s.tar.gz
+    # e.g. `https://www.openssl.org/source/openssl-0.9.8s.tar.gz`
    StemParser.new(/-v?(\d[^-]+)/),

-    # e.g. astyle_1.23_macosx.tar.gz
+    # e.g. `astyle_1.23_macosx.tar.gz`
    StemParser.new(/_v?(\d[^_]+)/),

-    # e.g. http://mirrors.jenkins-ci.org/war/1.486/jenkins.war
-    # e.g. https://github.com/foo/bar/releases/download/0.10.11/bar.phar
-    # e.g. https://github.com/clojure/clojurescript/releases/download/r1.9.293/cljs.jar
-    # e.g. https://github.com/fibjs/fibjs/releases/download/v0.6.1/fullsrc.zip
-    # e.g. https://wwwlehre.dhbw-stuttgart.de/~sschulz/WORK/E_DOWNLOAD/V_1.9/E.tgz
-    # e.g. https://github.com/JustArchi/ArchiSteamFarm/releases/download/2.3.2.0/ASF.zip
-    # e.g. https://people.gnome.org/~newren/eg/download/1.7.5.2/eg
+    # e.g. `http://mirrors.jenkins-ci.org/war/1.486/jenkins.war`
+    # e.g. `https://github.com/foo/bar/releases/download/0.10.11/bar.phar`
+    # e.g. `https://github.com/clojure/clojurescript/releases/download/r1.9.293/cljs.jar`
+    # e.g. `https://github.com/fibjs/fibjs/releases/download/v0.6.1/fullsrc.zip`
+    # e.g. `https://wwwlehre.dhbw-stuttgart.de/~sschulz/WORK/E_DOWNLOAD/V_1.9/E.tgz`
+    # e.g. `https://github.com/JustArchi/ArchiSteamFarm/releases/download/2.3.2.0/ASF.zip`
+    # e.g. `https://people.gnome.org/~newren/eg/download/1.7.5.2/eg`
    UrlParser.new(%r{/(?:[rvV]_?)?(\d+\.\d+(?:\.\d+){,2})}),

-    # e.g. https://www.ijg.org/files/jpegsrc.v8d.tar.gz
+    # e.g. `https://www.ijg.org/files/jpegsrc.v8d.tar.gz`
    StemParser.new(/\.v(\d+[a-z]?)/),

-    # e.g. https://secure.php.net/get/php-7.1.10.tar.bz2/from/this/mirror
+    # e.g. `https://secure.php.net/get/php-7.1.10.tar.bz2/from/this/mirror`
    UrlParser.new(/[-.vV]?(#{NUMERIC_WITH_DOTS}#{PRERELEASE_SUFFIX}?)/),
  ].freeze
  private_constant :VERSION_PARSERS
--- a/Library/Homebrew/warnings.rb
+++ b/Library/Homebrew/warnings.rb
@ -9,7 +9,10 @@ module Warnings
    parser_syntax: [
      %r{warning: parser/current is loading parser/ruby\d+, which recognizes},
      /warning: \d+\.\d+\.\d+-compliant syntax, but you are running \d+\.\d+\.\d+\./,
+      # FIXME: https://github.com/errata-ai/vale/issues/818
+      # <!-- vale off -->
      %r{warning: please see https://github\.com/whitequark/parser#compatibility-with-ruby-mri\.},
+      # <!-- vale on -->
    ],
  }.freeze

--- a/completions/fish/brew.fish
+++ b/completions/fish/brew.fish
@ -1196,7 +1196,7 @@ __fish_brew_complete_arg 'pr-publish' -l verbose -d 'Make some output more verbo
 __fish_brew_complete_arg 'pr-publish' -l workflow -d 'Target workflow filename (default: `publish-commit-bottles.yml`)'


-__fish_brew_complete_cmd 'pr-pull' 'Download and publish bottles, and apply the bottle commit from a pull request with artifacts generated by GitHub Actions'
+__fish_brew_complete_cmd 'pr-pull' 'Download and publish bottles and apply the bottle commit from a pull request with artifacts generated by GitHub Actions'
 __fish_brew_complete_arg 'pr-pull' -l artifact-pattern -d 'Download artifacts with the specified pattern (default: `bottles{,_*}`)'
 __fish_brew_complete_arg 'pr-pull' -l autosquash -d 'Automatically reformat and reword commits in the pull request to our preferred format'
 __fish_brew_complete_arg 'pr-pull' -l branch-okay -d 'Do not warn if pulling to a branch besides the repository default (useful for testing)'
@ -1482,12 +1482,12 @@ __fish_brew_complete_arg 'test' -a '(__fish_brew_suggest_formulae_installed)'
 __fish_brew_complete_cmd 'tests' 'Run Homebrew\'s unit and integration tests'
 __fish_brew_complete_arg 'tests' -l changed -d 'Only runs tests on files that were changed from the master branch'
 __fish_brew_complete_arg 'tests' -l coverage -d 'Generate code coverage reports'
-__fish_brew_complete_arg 'tests' -l debug -d 'Enable debugging using ruby/debug, or surface the standard `odebug` output'
+__fish_brew_complete_arg 'tests' -l debug -d 'Enable debugging using `ruby/debug`, or surface the standard `odebug` output'
 __fish_brew_complete_arg 'tests' -l fail-fast -d 'Exit early on the first failing test'
 __fish_brew_complete_arg 'tests' -l generic -d 'Run only OS-agnostic tests'
 __fish_brew_complete_arg 'tests' -l help -d 'Show this message'
 __fish_brew_complete_arg 'tests' -l online -d 'Include tests that use the GitHub API and tests that use any of the taps for official external commands'
-__fish_brew_complete_arg 'tests' -l only -d 'Run only test_script`_spec.rb`. Appending `:`line_number will start at a specific line'
+__fish_brew_complete_arg 'tests' -l only -d 'Run only `test_script_spec.rb`. Appending `:line_number` will start at a specific line'
 __fish_brew_complete_arg 'tests' -l profile -d 'Run the test suite serially to find the n slowest tests'
 __fish_brew_complete_arg 'tests' -l quiet -d 'Make some output more quiet'
 __fish_brew_complete_arg 'tests' -l seed -d 'Randomise tests with the specified value instead of a random seed'
--- a/completions/zsh/_brew
+++ b/completions/zsh/_brew
@ -195,7 +195,7 @@ __brew_internal_commands() {
    'postinstall:Rerun the post-install steps for formula'
    'pr-automerge:Find pull requests that can be automatically merged using `brew pr-publish`'
    'pr-publish:Publish bottles for a pull request with GitHub Actions'
-    'pr-pull:Download and publish bottles, and apply the bottle commit from a pull request with artifacts generated by GitHub Actions'
+    '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`'
@ -1835,12 +1835,12 @@ _brew_tests() {
  _arguments \
    '(--only)--changed[Only runs tests on files that were changed from the master branch]' \
    '--coverage[Generate code coverage reports]' \
-    '--debug[Enable debugging using ruby/debug, or surface the standard `odebug` output]' \
+    '--debug[Enable debugging using `ruby/debug`, or surface the standard `odebug` output]' \
    '--fail-fast[Exit early on the first failing test]' \
    '--generic[Run only OS-agnostic tests]' \
    '--help[Show this message]' \
    '--online[Include tests that use the GitHub API and tests that use any of the taps for official external commands]' \
-    '(--changed)--only[Run only test_script`_spec.rb`. Appending `:`line_number will start at a specific line]' \
+    '(--changed)--only[Run only `test_script_spec.rb`. Appending `:line_number` will start at a specific line]' \
    '--profile[Run the test suite serially to find the n slowest tests]' \
    '--quiet[Make some output more quiet]' \
    '--seed[Randomise tests with the specified value instead of a random seed]' \
--- a/docs/External-Commands.md
+++ b/docs/External-Commands.md
@ -24,7 +24,7 @@ The command may `Kernel.exit` with a status code if it needs to; if it doesn't e

 ### Other executable scripts

-An executable script for a command named `extcmd` should be named `brew-extcmd`. The script itself can use any suitable shebang (`#!`) line, so an external script can be written in Bash, Ruby, or even Python. Unlike the ruby commands this file must not end with a language-specific suffix (`.sh`, or `.py`). This file will be run via `exec` with some Homebrew variables set as environment variables, and passed any additional command-line arguments.
+An executable script for a command named `extcmd` should be named `brew-extcmd`. The script itself can use any suitable shebang (`#!`) line, so an external script can be written in Bash, Ruby, or even Python. Unlike the Ruby commands this file must not end with a language-specific suffix (`.sh`, or `.py`). This file will be run via `exec` with some Homebrew variables set as environment variables, and passed any additional command-line arguments.

 | variable               | description |
 | ---------------------- | ----------- |
--- a/docs/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@ -1175,7 +1175,7 @@ brew search --fink foo

 `superenv` is our "super environment" that isolates builds by removing `/usr/local/bin` and all user `PATH`s that are not essential for the build. It does this because user `PATH`s are often full of stuff that breaks builds. `superenv` also removes bad flags from the commands passed to `clang`/`gcc` and injects others (for example all [`keg_only`](https://rubydoc.brew.sh/Formula#keg_only-class_method) dependencies are added to the `-I` and `-L` flags).

-If in your local Homebrew build of your new formula, you see `Operation not permitted` errors, this will be because your new formula tried to write to the disk outside of your sandbox area. This is enforced on MacOS by `sandbox-exec`.
+If in your local Homebrew build of your new formula, you see `Operation not permitted` errors, this will be because your new formula tried to write to the disk outside of your sandbox area. This is enforced on macOS by `sandbox-exec`.

 ### Fortran

--- a/docs/How-To-Organize-AGM.md
+++ b/docs/How-To-Organize-AGM.md
@ -87,7 +87,7 @@ using this quick command:_

 **When:** Week 1 of YEAR :date: `2024-01-01`

-* [ ] PLC: Solicit changes to [Homebrew Governance](Homebrew-Governance.md) in the form of PRs on the `homebrew-governance-private` repo.
+* [ ] PLC: Solicit changes to [Homebrew Governance](Homebrew-Governance.md) in the form of PRs on the `homebrew-governance-private` repository.

 ### Three weeks prior

--- a/docs/Manpage.md
+++ b/docs/Manpage.md
@ -879,7 +879,7 @@ Show install options specific to *`formula`*.
 ### `outdated` \[*`options`*\] \[*`formula`*\|*`cask`* ...\]

 List installed casks and formulae that have an updated version available. By
-default, version information is displayed in interactive shells, and suppressed
+default, version information is displayed in interactive shells and suppressed
 otherwise.

 `-q`, `--quiet`
@ -2379,7 +2379,7 @@ the repository.

 ### `pr-pull` \[*`options`*\] *`pull_request`* \[...\]

-Download and publish bottles, and apply the bottle commit from a pull request
+Download and publish bottles and apply the bottle commit from a pull request
 with artifacts generated by GitHub Actions. Requires write access to the
 repository.

@ -2681,7 +2681,7 @@ Run Homebrew's unit and integration tests.

 `--debug`

-: Enable debugging using ruby/debug, or surface the standard `odebug` output.
+: Enable debugging using `ruby/debug`, or surface the standard `odebug` output.

 `--changed`

@ -2693,8 +2693,8 @@ Run Homebrew's unit and integration tests.

 `--only`

-: Run only *`test_script`*`_spec.rb`. Appending `:`*`line_number`* will start at
-  a specific line.
+: Run only `<test_script>_spec.rb`. Appending `:<line_number>` will start at a
+  specific line.

 `--profile`

@ -2874,7 +2874,7 @@ Install and commit Homebrew's vendored gems.

 ## GLOBAL CASK OPTIONS

-These options are applicable to the `install`, `reinstall`, and `upgrade`
+These options are applicable to the `install`, `reinstall` and `upgrade`
 subcommands with the `--cask` switch.

 `--appdir`
--- a/docs/Taps.md
+++ b/docs/Taps.md
@ -16,23 +16,18 @@ but the command isn't limited to any one location.
  petere/postgresql
  ```

-<!-- vale Homebrew.Terms = OFF -->
-<!-- The `terms` lint suggests changing "repo" to "repository". But we need the abbreviation in the tap syntax and URL example. -->
-
-* `brew tap <user/repo>` makes a clone of the repository at
-  _https://github.com/\<user>/homebrew-\<repo>_ into `$(brew --repository)/Library/Taps`.
+* `brew tap <user>/<repo>` makes a clone of the repository at
+  `https://github.com/<user>/homebrew-<repo>` into `$(brew --repository)/Library/Taps`.
  After that, `brew` will be able to work with those formulae as if they were in Homebrew's
  [homebrew/core](https://github.com/Homebrew/homebrew-core) canonical repository.
  You can install and uninstall them with `brew [un]install`, and the formulae are
  automatically updated when you run `brew update`. (See below for details
  about how `brew tap` handles the names of repositories.)

-<!-- vale Homebrew.Terms = ON -->
-
-* `brew tap <user/repo> <URL>` makes a clone of the repository at _URL_.
+* `brew tap <user>/<repo> <URL>` makes a clone of the repository at _URL_.
  Unlike the one-argument version, _URL_ is not assumed to be GitHub, and it
  doesn't have to be HTTP. Any location and any protocol that Git can handle is
-  fine, although non-GitHub taps require running `brew tap --force-auto-update <user/repo>`
+  fine, although non-GitHub taps require running `brew tap --force-auto-update <user>/<repo>`
  to enable automatic updating.

 * `brew tap --repair` migrates tapped formulae from a symlink-based to
--- a/docs/governance/2021-agm-minutes.md
+++ b/docs/governance/2021-agm-minutes.md
@ -45,7 +45,7 @@
 - 12:40–12:45 Michka Popoff - Merging the cores <https://github.com/Homebrew/brew/issues/7028>
 - 12:45–12:50 Michka Popoff - Linux CI for homebrew-core <https://github.com/Homebrew/brew/issues/10597>
 - 12:50–13:55 Misty De Meo - Running Homebrew on Apple Silicon
- 12:55–13:00 Shaun Jackman - Speeding up install times / Git repo size <https://github.com/Homebrew/install/issues/523>
+- 12:55–13:00 Shaun Jackman - Speeding up install times/Git repository size <https://github.com/Homebrew/install/issues/523>
 - 13:10 Meeting adjourned

 ## Resolutions
--- a/docs/vale-styles/Homebrew/Abbreviations.yml
+++ b/docs/vale-styles/Homebrew/Abbreviations.yml
@ -1,6 +1,6 @@
 ---
 extends: substitution
-message: Use '%s'
+message: Use '%s' instead of '%s'.
 ignorecase: false
 link: "https://github.com/Homebrew/brew/blob/HEAD/docs/Prose-Style-Guidelines.md#style-and-usage"
 level: error
@ -10,3 +10,9 @@ swap:
  '\bie\b': i.e.
  'e\.g\.,': e.g.
  'i\.e\.,': i.e.
+  '(?<!^\{.*|\.|<)\borg\b': organisation
+  '(?<!^\{.*)\borgs\b': organisations
+  '(?<!^\{.*|<|\{#)\brepo\b': repository # FIXME: https://github.com/errata-ai/vale/issues/818
+  '(?<!^\{.*)\brepos\b': repositories
+  '\bivar\b': instance variable
+  '\bivars\b': instance variables
--- a/docs/vale-styles/Homebrew/Spacing.yml
+++ b/docs/vale-styles/Homebrew/Spacing.yml
@ -5,5 +5,5 @@ link: "https://github.com/Homebrew/brew/blob/HEAD/docs/Prose-Style-Guidelines.md
 level: error
 nonword: true
 tokens:
-  - "[a-z][.?!][A-Z]"
-  - "[.?!] {2,}[A-Z]"
+  - '(?<!^\{.*)[a-z][.?!][A-Z]' # FIXME: https://github.com/errata-ai/vale/issues/818
+  - '[.?!] {2,}[A-Z]'
--- a/docs/vale-styles/Homebrew/Terms.yml
+++ b/docs/vale-styles/Homebrew/Terms.yml
@ -6,7 +6,7 @@ level: error
 scope: paragraph

 swap:
-  "(?<!How to Open a Homebrew )Pull Request": pull request
-  repo: repository
-  repos: repositories
+  '(?<!How to Open a Homebrew )Pull Request': pull request
  Rubocop: RuboCop
+  '(?<!^\{.*)MacOS': macOS # FIXME: https://github.com/errata-ai/vale/issues/818
+  '(?<!^\{.*|^!/.*)ruby': Ruby # FIXME: https://github.com/errata-ai/vale/issues/818
--- a/manpages/README.md
+++ b/manpages/README.md
@ -1,3 +1,3 @@
-# Manual pages
+# Manual Pages

 This directory contains the generated Homebrew man pages from the `brew generate-man-completions` command. This command creates the output from the `CLI::Parser` definitions in files, sections extracted from the repository's `README.md` and `brew.1.md.erb`.
--- a/manpages/brew.1
+++ b/manpages/brew.1
@ -550,7 +550,7 @@ Evaluate all available formulae and casks, whether installed or not, to show the
 \fB\-\-command\fP
 Show options for the specified \fIcommand\fP\&\.
 .SS "\fBoutdated\fP \fR[\fIoptions\fP] \fR[\fIformula\fP|\fIcask\fP \.\.\.]"
-List installed casks and formulae that have an updated version available\. By default, version information is displayed in interactive shells, and suppressed otherwise\.
+List installed casks and formulae that have an updated version available\. By default, version information is displayed in interactive shells and suppressed otherwise\.
 .TP
 \fB\-q\fP, \fB\-\-quiet\fP
 List only the names of outdated kegs (takes precedence over \fB\-\-verbose\fP)\.
@ -1514,7 +1514,7 @@ Target tap repository (default: \fBhomebrew/core\fP)\.
 \fB\-\-workflow\fP
 Target workflow filename (default: \fBpublish\-commit\-bottles\.yml\fP)\.
 .SS "\fBpr\-pull\fP \fR[\fIoptions\fP] \fIpull_request\fP \fR[\.\.\.]"
-Download and publish bottles, and apply the bottle commit from a pull request with artifacts generated by GitHub Actions\. Requires write access to the repository\.
+Download and publish bottles and apply the bottle commit from a pull request with artifacts generated by GitHub Actions\. Requires write access to the repository\.
 .TP
 \fB\-\-no\-upload\fP
 Download the bottles but don\[u2019]t upload them\.
@ -1708,7 +1708,7 @@ Run only OS\-agnostic tests\.
 Include tests that use the GitHub API and tests that use any of the taps for official external commands\.
 .TP
 \fB\-\-debug\fP
-Enable debugging using ruby/debug, or surface the standard \fBodebug\fP output\.
+Enable debugging using \fBruby/debug\fP, or surface the standard \fBodebug\fP output\.
 .TP
 \fB\-\-changed\fP
 Only runs tests on files that were changed from the master branch\.
@ -1717,7 +1717,7 @@ Only runs tests on files that were changed from the master branch\.
 Exit early on the first failing test\.
 .TP
 \fB\-\-only\fP
-Run only \fItest_script\fP\fB_spec\.rb\fP\&\. Appending \fB:\fP\fIline_number\fP will start at a specific line\.
+Run only \fB<test_script>_spec\.rb\fP\&\. Appending \fB:<line_number>\fP will start at a specific line\.
 .TP
 \fB\-\-profile\fP
 Run the test suite serially to find the \fIn\fP slowest tests\.
@ -1836,7 +1836,7 @@ Update the specified list of vendored gems to the latest version\.
 \fB\-\-no\-commit\fP
 Do not generate a new commit upon completion\.
 .SH "GLOBAL CASK OPTIONS"
-These options are applicable to the \fBinstall\fP, \fBreinstall\fP, and \fBupgrade\fP subcommands with the \fB\-\-cask\fP switch\.
+These options are applicable to the \fBinstall\fP, \fBreinstall\fP and \fBupgrade\fP subcommands with the \fB\-\-cask\fP switch\.
 .TP
 \fB\-\-appdir\fP
 Target location for Applications (default: \fB/Applications\fP)\.