docs & audits: text output improvements

Library/Homebrew/cask/auditor.rb

@@ -50,7 +50,8 @@ def audit
       if !language && language_blocks
         sample_languages = if language_blocks.length > LANGUAGE_BLOCK_LIMIT && !@audit_new_cask
           sample_keys = language_blocks.keys.sample(LANGUAGE_BLOCK_LIMIT)
-          ohai "Auditing a sample of available languages: #{sample_keys.map { |lang| lang[0].to_s }.to_sentence}"
+          ohai "Auditing a sample of available languages for #{cask}: " \
+               "#{sample_keys.map { |lang| lang[0].to_s }.to_sentence}"
           language_blocks.select { |k| sample_keys.include?(k) }
         else
           language_blocks

Library/Homebrew/cask/cask.rb

@@ -27,7 +27,7 @@ class Cask
     # @api private
     def self.all(eval_all: false)
       if !eval_all && !Homebrew::EnvConfig.eval_all?
-        raise ArgumentError, "Cask::Cask#all cannot be used without --eval-all or HOMEBREW_EVAL_ALL"
+        raise ArgumentError, "Cask::Cask#all cannot be used without `--eval-all` or HOMEBREW_EVAL_ALL"
       end
 
       # Load core casks from tokens so they load from the API when the core cask is not tapped.

Library/Homebrew/cmd/install.rb

@@ -139,7 +139,7 @@ def self.install_args
         }],
         [:switch, "--adopt", {
           description: "Adopt existing artifacts in the destination that are identical to those being installed. " \
-                       "Cannot be combined with --force.",
+                       "Cannot be combined with `--force`.",
         }],
         [:switch, "--skip-cask-deps", {
           description: "Skip installing cask dependencies.",

Library/Homebrew/cmd/pin.rb

@@ -14,7 +14,7 @@ def pin_args
         Pin the specified <formula>, preventing them from being upgraded when
         issuing the `brew upgrade` <formula> command. See also `unpin`.
 
-        Note: Other packages which depend on newer versions of a pinned formula
+        *Note:* Other packages which depend on newer versions of a pinned formula
         might not install or run correctly.
       EOS
 

Library/Homebrew/cmd/reinstall.rb

@@ -86,7 +86,7 @@ def self.reinstall_args
         }],
         [:switch, "--adopt", {
           description: "Adopt existing artifacts in the destination that are identical to those being installed. " \
-                       "Cannot be combined with --force.",
+                       "Cannot be combined with `--force`.",
         }],
         [:switch, "--skip-cask-deps", {
           description: "Skip installing cask dependencies.",

Library/Homebrew/dev-cmd/bottle.rb

@@ -326,7 +326,7 @@ def self.bottle_formula(formula, args:)
         return ofail "Formula not installed or up-to-date: #{formula.full_name}"
       end
       unless Utils::Bottles.built_as? formula
-        return ofail "Formula was not installed with --build-bottle: #{formula.full_name}"
+        return ofail "Formula was not installed with `--build-bottle`: #{formula.full_name}"
       end
     end
 

Library/Homebrew/env_config.rb

@@ -36,15 +36,15 @@ module EnvConfig
       HOMEBREW_API_AUTO_UPDATE_SECS:             {
         description: "Check Homebrew's API for new formulae or cask data every " \
                      "`HOMEBREW_API_AUTO_UPDATE_SECS` seconds. Alternatively, disable API auto-update " \
-                     "checks entirely with HOMEBREW_NO_AUTO_UPDATE.",
+                     "checks entirely with `HOMEBREW_NO_AUTO_UPDATE`.",
         default:     450,
       },
       HOMEBREW_AUTO_UPDATE_SECS:                 {
         description:  "Run `brew update` once every `HOMEBREW_AUTO_UPDATE_SECS` seconds before some commands, " \
                       "e.g. `brew install`, `brew upgrade` and `brew tap`. Alternatively, " \
                       "disable auto-update entirely with `HOMEBREW_NO_AUTO_UPDATE`.",
-        default_text: "86400 (24 hours), 3600 (1 hour) if a developer command has been run " \
-                      "or 300 (5 minutes) if `HOMEBREW_NO_INSTALL_FROM_API` is set.",
+        default_text: "`86400` (24 hours), `3600` (1 hour) if a developer command has been run " \
+                      "or `300` (5 minutes) if `HOMEBREW_NO_INSTALL_FROM_API` is set.",
       },
       HOMEBREW_AUTOREMOVE:                       {
         description: "If set, calls to `brew cleanup` and `brew uninstall` will automatically " \
@@ -178,7 +178,7 @@ module EnvConfig
       },
       HOMEBREW_EVAL_ALL:                         {
         description: "If set, `brew` commands evaluate all formulae and casks, executing their arbitrary code, by " \
-                     "default without requiring --eval-all. Required to cache formula and cask descriptions.",
+                     "default without requiring `--eval-all`. Required to cache formula and cask descriptions.",
         boolean:     true,
       },
       HOMEBREW_FAIL_LOG_LINES:                   {
@@ -356,7 +356,7 @@ module EnvConfig
       },
       HOMEBREW_SORBET_RUNTIME:                   {
         description: "If set, enable runtime typechecking using Sorbet. " \
-                     "Set by default for HOMEBREW_DEVELOPER or when running some developer commands.",
+                     "Set by default for `HOMEBREW_DEVELOPER` or when running some developer commands.",
         boolean:     true,
       },
       HOMEBREW_SSH_CONFIG_PATH:                  {

Library/Homebrew/exceptions.rb

@@ -436,7 +436,7 @@ def message
       Please `brew unlink #{conflicts.map(&:name) * " "}` before continuing.
 
       Unlinking removes a formula's symlinks from #{HOMEBREW_PREFIX}. You can
-      link the formula again after the install finishes. You can --force this
+      link the formula again after the install finishes. You can `--force` this
       install, but the build may fail or cause obscure side effects in the
       resulting software.
     EOS

Library/Homebrew/formula.rb

@@ -1933,7 +1933,7 @@ def self.full_names
   # @private
   def self.all(eval_all: false)
     if !eval_all && !Homebrew::EnvConfig.eval_all?
-      raise ArgumentError, "Formula#all without --eval-all or HOMEBREW_EVAL_ALL"
+      raise ArgumentError, "Formula#all without `--eval-all` or HOMEBREW_EVAL_ALL"
     end
 
     (core_names + tap_files).map do |name_or_file|

Library/Homebrew/test/dev-cmd/audit_spec.rb

@@ -415,7 +415,7 @@ class Cask < Formula
         EOS
       end
 
-      it "checks online and verifies that a standard license id is in the same exempted license group" \
+      it "checks online and verifies that a standard license id is in the same exempted license group " \
          "as what is indicated on its GitHub repo", :needs_network do
         fa = formula_auditor "cask", <<~RUBY, spdx_license_data: spdx_license_data, online: true, new_formula: true
           class Cask < Formula
@@ -429,7 +429,7 @@ class Cask < Formula
         expect(fa.problems).to be_empty
       end
 
-      it "checks online and verifies that a standard license array is in the same exempted license group" \
+      it "checks online and verifies that a standard license array is in the same exempted license group " \
          "as what is indicated on its GitHub repo", :needs_network do
         fa = formula_auditor "cask", <<~RUBY, spdx_license_data: spdx_license_data, online: true, new_formula: true
           class Cask < Formula

Library/Homebrew/test/software_spec_spec.rb

@@ -210,7 +210,7 @@
         expect(spec.declared_deps.first).to be_use_macos_install
       end
 
-      it "add a macOS dependency if the OS version doesn't meet requirements" do
+      it "adds a macOS dependency if the OS version doesn't meet requirements" do
         spec.uses_from_macos("foo", since: :high_sierra)
 
         expect(spec.declared_deps).not_to be_empty

Library/Homebrew/utils/backtrace.rb

@@ -28,7 +28,7 @@ def self.print_backtrace_message
       return if @print_backtrace_message
 
       opoo "Removed Sorbet lines from backtrace!"
-      puts "Rerun with --verbose to see the original backtrace" unless Homebrew::EnvConfig.no_env_hints?
+      puts "Rerun with `--verbose` to see the original backtrace" unless Homebrew::EnvConfig.no_env_hints?
 
       @print_backtrace_message = true
     end

Library/Homebrew/utils/github.rb

@@ -572,7 +572,7 @@ def self.check_for_duplicate_pull_requests(name, tap_remote_repo, state:, file:,
       These #{state} pull requests may be duplicates:
       #{pull_requests.map { |pr| "#{pr["title"]} #{pr["html_url"]}" }.join("\n")}
     EOS
-    error_message = "Duplicate PRs should not be opened. Use --force to override this error."
+    error_message = "Duplicate PRs should not be opened. Use `--force` to override this error."
     if args.force? && !args.quiet?
       opoo duplicates_message
     elsif !args.force? && args.quiet?

Library/Homebrew/utils/shared_audits.rb

@@ -142,7 +142,7 @@ def bitbucket(user, repo)
     metadata = JSON.parse(out)
     return if metadata.nil?
 
-    return "Uses deprecated mercurial support in Bitbucket" if metadata["scm"] == "hg"
+    return "Uses deprecated Mercurial support in Bitbucket" if metadata["scm"] == "hg"
 
     return "Bitbucket fork (not canonical repository)" unless metadata["parent"].nil?
 

completions/fish/brew.fish

@@ -814,7 +814,7 @@ __fish_brew_complete_arg 'info; and not __fish_seen_argument -l formula -l formu
 
 __fish_brew_complete_cmd 'instal' 'Install a formula or cask'
 __fish_brew_complete_arg 'instal' -l HEAD -d 'If formula defines it, install the HEAD version, aka. main, trunk, unstable, master'
-__fish_brew_complete_arg 'instal' -l adopt -d 'Adopt existing artifacts in the destination that are identical to those being installed. Cannot be combined with --force'
+__fish_brew_complete_arg 'instal' -l adopt -d 'Adopt existing artifacts in the destination that are identical to those being installed. Cannot be combined with `--force`'
 __fish_brew_complete_arg 'instal' -l appdir -d 'Target location for Applications (default: `/Applications`)'
 __fish_brew_complete_arg 'instal' -l audio-unit-plugindir -d 'Target location for Audio Unit Plugins (default: `~/Library/Audio/Plug-Ins/Components`)'
 __fish_brew_complete_arg 'instal' -l binaries -d 'Disable/enable linking of helper executables (default: enabled)'
@@ -868,7 +868,7 @@ __fish_brew_complete_arg 'instal; and not __fish_seen_argument -l formula -l for
 
 __fish_brew_complete_cmd 'install' 'Install a formula or cask'
 __fish_brew_complete_arg 'install' -l HEAD -d 'If formula defines it, install the HEAD version, aka. main, trunk, unstable, master'
-__fish_brew_complete_arg 'install' -l adopt -d 'Adopt existing artifacts in the destination that are identical to those being installed. Cannot be combined with --force'
+__fish_brew_complete_arg 'install' -l adopt -d 'Adopt existing artifacts in the destination that are identical to those being installed. Cannot be combined with `--force`'
 __fish_brew_complete_arg 'install' -l appdir -d 'Target location for Applications (default: `/Applications`)'
 __fish_brew_complete_arg 'install' -l audio-unit-plugindir -d 'Target location for Audio Unit Plugins (default: `~/Library/Audio/Plug-Ins/Components`)'
 __fish_brew_complete_arg 'install' -l binaries -d 'Disable/enable linking of helper executables (default: enabled)'
@@ -1268,7 +1268,7 @@ __fish_brew_complete_arg 'readall' -a '(__fish_brew_suggest_taps_installed)'
 
 
 __fish_brew_complete_cmd 'reinstall' 'Uninstall and then reinstall a formula or cask using the same options it was originally installed with, plus any appended options specific to a formula'
-__fish_brew_complete_arg 'reinstall' -l adopt -d 'Adopt existing artifacts in the destination that are identical to those being installed. Cannot be combined with --force'
+__fish_brew_complete_arg 'reinstall' -l adopt -d 'Adopt existing artifacts in the destination that are identical to those being installed. Cannot be combined with `--force`'
 __fish_brew_complete_arg 'reinstall' -l appdir -d 'Target location for Applications (default: `/Applications`)'
 __fish_brew_complete_arg 'reinstall' -l audio-unit-plugindir -d 'Target location for Audio Unit Plugins (default: `~/Library/Audio/Plug-Ins/Components`)'
 __fish_brew_complete_arg 'reinstall' -l binaries -d 'Disable/enable linking of helper executables (default: enabled)'

completions/zsh/_brew

@@ -1027,7 +1027,7 @@ _brew_info() {
 _brew_instal() {
   _arguments \
     '(--cask)--HEAD[If formula defines it, install the HEAD version, aka. main, trunk, unstable, master]' \
-    '(--formula --force)--adopt[Adopt existing artifacts in the destination that are identical to those being installed. Cannot be combined with --force]' \
+    '(--formula --force)--adopt[Adopt existing artifacts in the destination that are identical to those being installed. Cannot be combined with `--force`]' \
     '(--formula)--appdir[Target location for Applications (default: `/Applications`)]' \
     '(--formula)--audio-unit-plugindir[Target location for Audio Unit Plugins (default: `~/Library/Audio/Plug-Ins/Components`)]' \
     '(--formula)--binaries[Disable/enable linking of helper executables (default: enabled)]' \
@@ -1085,7 +1085,7 @@ _brew_instal() {
 _brew_install() {
   _arguments \
     '(--cask)--HEAD[If formula defines it, install the HEAD version, aka. main, trunk, unstable, master]' \
-    '(--formula --force)--adopt[Adopt existing artifacts in the destination that are identical to those being installed. Cannot be combined with --force]' \
+    '(--formula --force)--adopt[Adopt existing artifacts in the destination that are identical to those being installed. Cannot be combined with `--force`]' \
     '(--formula)--appdir[Target location for Applications (default: `/Applications`)]' \
     '(--formula)--audio-unit-plugindir[Target location for Audio Unit Plugins (default: `~/Library/Audio/Plug-Ins/Components`)]' \
     '(--formula)--binaries[Disable/enable linking of helper executables (default: enabled)]' \
@@ -1569,7 +1569,7 @@ _brew_readall() {
 # brew reinstall
 _brew_reinstall() {
   _arguments \
-    '(--formula)--adopt[Adopt existing artifacts in the destination that are identical to those being installed. Cannot be combined with --force]' \
+    '(--formula)--adopt[Adopt existing artifacts in the destination that are identical to those being installed. Cannot be combined with `--force`]' \
     '(--formula)--appdir[Target location for Applications (default: `/Applications`)]' \
     '(--formula)--audio-unit-plugindir[Target location for Audio Unit Plugins (default: `~/Library/Audio/Plug-Ins/Components`)]' \
     '(--formula)--binaries[Disable/enable linking of helper executables (default: enabled)]' \

docs/Manpage.md

@@ -392,7 +392,7 @@ is already installed but outdated.
 * `--[no-]quarantine`:
   Disable/enable quarantining of downloads (default: enabled).
 * `--adopt`:
-  Adopt existing artifacts in the destination that are identical to those being installed. Cannot be combined with --force.
+  Adopt existing artifacts in the destination that are identical to those being installed. Cannot be combined with `--force`.
 * `--skip-cask-deps`:
   Skip installing cask dependencies.
 * `--zap`:
@@ -541,7 +541,7 @@ information is displayed in interactive shells, and suppressed otherwise.
 Pin the specified *`formula`*, preventing them from being upgraded when
 issuing the `brew upgrade` *`formula`* command. See also `unpin`.
 
-Note: Other packages which depend on newer versions of a pinned formula
+*Note:* Other packages which depend on newer versions of a pinned formula
 might not install or run correctly.
 
 ### `postinstall`, `post_install` *`installed_formula`* [...]
@@ -624,7 +624,7 @@ reinstalled formulae or, every 30 days, for all formulae.
 * `--[no-]quarantine`:
   Disable/enable quarantining of downloads (default: enabled).
 * `--adopt`:
-  Adopt existing artifacts in the destination that are identical to those being installed. Cannot be combined with --force.
+  Adopt existing artifacts in the destination that are identical to those being installed. Cannot be combined with `--force`.
 * `--skip-cask-deps`:
   Skip installing cask dependencies.
 * `--zap`:
@@ -2122,14 +2122,14 @@ command execution e.g. `$(cat file)`.
   <br>Prefix all download URLs, including those for bottles, with this value. For example, `HOMEBREW_ARTIFACT_DOMAIN=http://localhost:8080` will cause a formula with the URL `https://example.com/foo.tar.gz` to instead download from `http://localhost:8080/https://example.com/foo.tar.gz`. Bottle URLs however, have their domain replaced with this prefix. This results in e.g. `https://ghcr.io/v2/homebrew/core/gettext/manifests/0.21` to instead be downloaded from `http://localhost:8080/v2/homebrew/core/gettext/manifests/0.21`
 
 - `HOMEBREW_API_AUTO_UPDATE_SECS`
-  <br>Check Homebrew's API for new formulae or cask data every `HOMEBREW_API_AUTO_UPDATE_SECS` seconds. Alternatively, disable API auto-update checks entirely with HOMEBREW_NO_AUTO_UPDATE.
+  <br>Check Homebrew's API for new formulae or cask data every `HOMEBREW_API_AUTO_UPDATE_SECS` seconds. Alternatively, disable API auto-update checks entirely with `HOMEBREW_NO_AUTO_UPDATE`.
 
   *Default:* `450`.
 
 - `HOMEBREW_AUTO_UPDATE_SECS`
   <br>Run `brew update` once every `HOMEBREW_AUTO_UPDATE_SECS` seconds before some commands, e.g. `brew install`, `brew upgrade` and `brew tap`. Alternatively, disable auto-update entirely with `HOMEBREW_NO_AUTO_UPDATE`.
 
-  *Default:* 86400 (24 hours), 3600 (1 hour) if a developer command has been run or 300 (5 minutes) if `HOMEBREW_NO_INSTALL_FROM_API` is set.
+  *Default:* `86400` (24 hours), `3600` (1 hour) if a developer command has been run or `300` (5 minutes) if `HOMEBREW_NO_INSTALL_FROM_API` is set.
 
 - `HOMEBREW_AUTOREMOVE`
   <br>If set, calls to `brew cleanup` and `brew uninstall` will automatically remove unused formula dependents and if `HOMEBREW_NO_INSTALL_CLEANUP` is not set, `brew cleanup` will start running `brew autoremove` periodically.
@@ -2240,7 +2240,7 @@ command execution e.g. `$(cat file)`.
   *Default:* `$EDITOR` or `$VISUAL`.
 
 - `HOMEBREW_EVAL_ALL`
-  <br>If set, `brew` commands evaluate all formulae and casks, executing their arbitrary code, by default without requiring --eval-all. Required to cache formula and cask descriptions.
+  <br>If set, `brew` commands evaluate all formulae and casks, executing their arbitrary code, by default without requiring `--eval-all`. Required to cache formula and cask descriptions.
 
 - `HOMEBREW_FAIL_LOG_LINES`
   <br>Output this many lines of output on formula `system` failures.
@@ -2368,7 +2368,7 @@ command execution e.g. `$(cat file)`.
   <br>If set along with `HOMEBREW_DEVELOPER`, do not use bottles from older versions of macOS. This is useful in development on new macOS versions.
 
 - `HOMEBREW_SORBET_RUNTIME`
-  <br>If set, enable runtime typechecking using Sorbet. Set by default for HOMEBREW_DEVELOPER or when running some developer commands.
+  <br>If set, enable runtime typechecking using Sorbet. Set by default for `HOMEBREW_DEVELOPER` or when running some developer commands.
 
 - `HOMEBREW_SSH_CONFIG_PATH`
   <br>If set, Homebrew will use the given config file instead of `~/.ssh/config` when fetching Git repositories over SSH.