docs+rubydoc: various grammar/wording fixes

Library/Homebrew/cmd/--repository.rb

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

Library/Homebrew/cmd/install.rb

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

Library/Homebrew/cmd/reinstall.rb

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

Library/Homebrew/cmd/upgrade.rb

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

Library/Homebrew/dependency.rb

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

Library/Homebrew/dev-cmd/contributions.rb

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

Library/Homebrew/env_config.rb

@@ -300,7 +300,7 @@ module Homebrew
       },
       HOMEBREW_NO_INSECURE_REDIRECT:             {
         description: "If set, forbid redirects from secure HTTPS to insecure HTTP." \
-                     "\n\n    *Note:* While ensuring your downloads are fully secure, this is likely to cause " \
+                     "\n\n    *Note:* while ensuring your downloads are fully secure, this is likely to cause " \
                      "from-source SourceForge, some GNU & GNOME-hosted formulae to fail to download.",
         boolean:     true,
       },
@@ -361,7 +361,7 @@ module Homebrew
       },
       HOMEBREW_SSH_CONFIG_PATH:                  {
         description:  "If set, Homebrew will use the given config file instead of `~/.ssh/config` when fetching " \
-                      "`git` repos over `ssh`.",
+                      "Git repositories over SSH.",
         default_text: "`$HOME/.ssh/config`",
       },
       HOMEBREW_SVN:                              {

Library/Homebrew/extend/kernel.rb

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

Library/Homebrew/formula.rb

@@ -85,13 +85,13 @@ 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
@@ -2428,7 +2428,7 @@ class Formula
     hash
   end
 
-  # Returns the bottle information for a formula
+  # Returns the bottle information for a formula.
   def bottle_hash
     bottle_spec = T.must(stable).bottle_specification
     hash = {

Library/Homebrew/formula_creator.rb

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

Library/Homebrew/formula_installer.rb

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

Library/Homebrew/install.rb

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

Library/Homebrew/livecheck/strategy/gnome.rb

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

Library/Homebrew/livecheck/strategy/pypi.rb

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

Library/Homebrew/manpages.rb

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

Library/Homebrew/tab.rb

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

Library/Homebrew/tap.rb

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

Library/Homebrew/test/cli/parser_spec.rb

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

Library/Homebrew/test/completions_spec.rb

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

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

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

Library/Homebrew/utils/curl.rb

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

docs/Acceptable-Casks.md

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

docs/Cask-Cookbook.md

@@ -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

docs/Checksum_Deprecation.md

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

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

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

docs/FAQ.md

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

docs/Formula-Cookbook.md

@@ -268,7 +268,7 @@ end
 
 [`jrnl`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/j/jrnl.rb) is an example of a formula that does this well. The end result means the user doesn't have to use `pip` or Python and can just run `jrnl`.
 
-For Python formulae, running `brew update-python-resources <formula>` will automatically add the necessary [`resource`](https://rubydoc.brew.sh/Formula#resource-class_method) stanzas for the dependencies of your Python application to the formula. Note that `brew update-python-resources` is run automatically by `brew create` if you pass the `--python` flag. If `brew update-python-resources` is unable to determine the correct `resource` stanzas, [homebrew-pypi-poet](https://github.com/tdsmith/homebrew-pypi-poet) is a good third-party alternative that may help.
+For Python formulae, running `brew update-python-resources <formula>` will automatically add the necessary [`resource`](https://rubydoc.brew.sh/Formula#resource-class_method) stanzas for the dependencies of your Python application to the formula. Note that `brew update-python-resources` is run automatically by `brew create` if you pass the `--python` switch. If `brew update-python-resources` is unable to determine the correct `resource` stanzas, [homebrew-pypi-poet](https://github.com/tdsmith/homebrew-pypi-poet) is a good third-party alternative that may help.
 
 ### Install the formula
 

docs/Homebrew-brew-Maintainer-Guide.md

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

docs/Tips-N'-Tricks.md

@@ -67,7 +67,7 @@ export HOMEBREW_INSTALL_BADGE="☕️ 🐸"
 
 ## Migrate a Homebrew installation to a new location
 
-Run `brew bundle dump` and `brew bundle install` record an installation to and install from a `Brewfile`. See `brew bundle --help` for more details.
+Running `brew bundle dump` will record an installation to a `Brewfile` and `brew bundle install` will install from a `Brewfile`. See `brew bundle --help` for more details.
 
 ## Appoint Homebrew Cask to manage a manually-installed app
 

docs/vale-styles/Homebrew/Terms.yml

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