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

Library/Homebrew/cmd/reinstall.rb

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

Library/Homebrew/cmd/upgrade.rb

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

Library/Homebrew/dependency.rb

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

Library/Homebrew/dev-cmd/contributions.rb

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

Library/Homebrew/extend/kernel.rb

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

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

Library/Homebrew/formula_creator.rb

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

Library/Homebrew/formula_installer.rb

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

Library/Homebrew/install.rb

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

Library/Homebrew/livecheck/strategy/gnome.rb

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

Library/Homebrew/livecheck/strategy/pypi.rb

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

Library/Homebrew/manpages.rb

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

Library/Homebrew/tab.rb

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

Library/Homebrew/tap.rb

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

Library/Homebrew/test/cli/parser_spec.rb

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

Library/Homebrew/test/completions_spec.rb

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

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

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

Library/Homebrew/utils/curl.rb

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

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).