Merge pull request #15986 from EricFromCanada/docs-assorted-improvements

Docs: assorted refinements for output
Homebrew · Sep 11, 2023 · 4e0ec25 · 4e0ec25
2 parents bd1caa4 + c493b5e
commit 4e0ec25
Show file tree

Hide file tree

Showing 58 changed files with 291 additions and 309 deletions.
diff --git a/Library/Homebrew/cmd/--prefix.rb b/Library/Homebrew/cmd/--prefix.rb
@@ -10,8 +10,8 @@ def self.__prefix_args
       description <<~EOS
         Display Homebrew's install path. *Default:*
 
-          - macOS Intel: `#{HOMEBREW_DEFAULT_PREFIX}`
           - macOS ARM: `#{HOMEBREW_MACOS_ARM_DEFAULT_PREFIX}`
+          - macOS Intel: `#{HOMEBREW_DEFAULT_PREFIX}`
           - Linux: `#{HOMEBREW_LINUX_DEFAULT_PREFIX}`
 
         If <formula> is provided, display the location where <formula> is or would be installed.

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

diff --git a/Library/Homebrew/cmd/deps.rb b/Library/Homebrew/cmd/deps.rb
@@ -17,7 +17,12 @@ def self.deps_args
         show the intersection of dependencies for each formula. By default, `deps`
         shows all required and recommended dependencies.
 
-        Note: `--missing` and `--skip-recommended` have precedence over `--include-*`.
+        If any version of each formula argument is installed and no other options
+        are passed, this command displays their actual runtime dependencies (similar
+        to `brew linkage`), which may differ from the current versons' stated
+        dependencies if the installed versions are outdated.
+
+        *Note:* `--missing` and `--skip-recommended` have precedence over `--include-*`.
       EOS
       switch "-n", "--topological",
              description: "Sort dependencies in topological order."

diff --git a/Library/Homebrew/cmd/docs.rb b/Library/Homebrew/cmd/docs.rb
@@ -10,7 +10,7 @@ module Homebrew
   def docs_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
-        Open Homebrew's online documentation (#{HOMEBREW_DOCS_WWW}) in a browser.
+        Open Homebrew's online documentation at <#{HOMEBREW_DOCS_WWW}> in a browser.
       EOS
     end
   end

diff --git a/Library/Homebrew/cmd/doctor.rb b/Library/Homebrew/cmd/doctor.rb
@@ -11,10 +11,11 @@ def self.doctor_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
         Check your system for potential problems. Will exit with a non-zero status
-        if any potential problems are found. Please note that these warnings are just
-        used to help the Homebrew maintainers with debugging if you file an issue. If
-        everything you use Homebrew for is working fine: please don't worry or file
-        an issue; just ignore this.
+        if any potential problems are found.
+
+        Please note that these warnings are just used to help the Homebrew maintainers
+        with debugging if you file an issue. If everything you use Homebrew for
+        is working fine: please don't worry or file an issue; just ignore this.
       EOS
       switch "--list-checks",
              description: "List all audit methods, which can be run individually " \

diff --git a/Library/Homebrew/cmd/info.rb b/Library/Homebrew/cmd/info.rb
@@ -25,7 +25,6 @@ def info_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
         Display brief statistics for your Homebrew installation.
-
         If a <formula> or <cask> is provided, show summary of information about it.
       EOS
       switch "--analytics",

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

diff --git a/Library/Homebrew/cmd/link.rb b/Library/Homebrew/cmd/link.rb
@@ -12,9 +12,9 @@ module Homebrew
   def link_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
-        Symlink all of <formula>'s installed files into Homebrew's prefix. This
-        is done automatically when you install formulae but can be useful for DIY
-        installations.
+        Symlink all of <formula>'s installed files into Homebrew's prefix.
+        This is done automatically when you install formulae but can be useful
+        for manual installations.
       EOS
       switch "--overwrite",
              description: "Delete files that already exist in the prefix while linking."

diff --git a/Library/Homebrew/cmd/list.rb b/Library/Homebrew/cmd/list.rb
@@ -14,7 +14,6 @@ def list_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
         List all installed formulae and casks.
-
         If <formula> is provided, summarise the paths within its current keg.
         If <cask> is provided, list its artifacts.
       EOS

diff --git a/Library/Homebrew/cmd/nodenv-sync.rb b/Library/Homebrew/cmd/nodenv-sync.rb
@@ -11,7 +11,7 @@ module Homebrew
   def nodenv_sync_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
-        Create symlinks for Homebrew's installed NodeJS versions in ~/.nodenv/versions.
+        Create symlinks for Homebrew's installed NodeJS versions in `~/.nodenv/versions`.
 
         Note that older version symlinks will also be created so e.g. NodeJS 19.1.0 will
         also be symlinked to 19.0.0.

diff --git a/Library/Homebrew/cmd/pyenv-sync.rb b/Library/Homebrew/cmd/pyenv-sync.rb
@@ -11,7 +11,7 @@ module Homebrew
   def pyenv_sync_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
-        Create symlinks for Homebrew's installed Python versions in ~/.pyenv/versions.
+        Create symlinks for Homebrew's installed Python versions in `~/.pyenv/versions`.
 
         Note that older patch version symlinks will be created and linked to the minor
         version so e.g. Python 3.11.0 will also be symlinked to 3.11.3.

diff --git a/Library/Homebrew/cmd/rbenv-sync.rb b/Library/Homebrew/cmd/rbenv-sync.rb
@@ -11,7 +11,7 @@ module Homebrew
   def rbenv_sync_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
-        Create symlinks for Homebrew's installed Ruby versions in ~/.rbenv/versions.
+        Create symlinks for Homebrew's installed Ruby versions in `~/.rbenv/versions`.
 
         Note that older version symlinks will also be created so e.g. Ruby 3.2.1 will
         also be symlinked to 3.2.0.

diff --git a/Library/Homebrew/cmd/readall.rb b/Library/Homebrew/cmd/readall.rb
@@ -24,7 +24,7 @@ def readall_args
       switch "--aliases",
              description: "Verify any alias symlinks in each tap."
       switch "--syntax",
-             description: "Syntax-check all of Homebrew's Ruby files (if no `<tap>` is passed)."
+             description: "Syntax-check all of Homebrew's Ruby files (if no <tap> is passed)."
       switch "--eval-all",
              description: "Evaluate all available formulae and casks, whether installed or not. " \
                           "Implied if `HOMEBREW_EVAL_ALL` is set."

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

diff --git a/Library/Homebrew/cmd/tap-info.rb b/Library/Homebrew/cmd/tap-info.rb
@@ -11,7 +11,6 @@ def tap_info_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
         Show detailed information about one or more <tap>s.
-
         If no <tap> names are provided, display brief statistics for all installed taps.
       EOS
       switch "--installed",

diff --git a/Library/Homebrew/cmd/tap.rb b/Library/Homebrew/cmd/tap.rb
@@ -12,7 +12,6 @@ def tap_args
       usage_banner "`tap` [<options>] [<user>`/`<repo>] [<URL>]"
       description <<~EOS
         Tap a formula repository.
-
         If no arguments are provided, list all installed taps.
 
         With <URL> unspecified, tap a formula repository from GitHub using HTTPS.

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

diff --git a/Library/Homebrew/cmd/uses.rb b/Library/Homebrew/cmd/uses.rb
@@ -23,7 +23,7 @@ def self.uses_args
         of formulae that use <formula>. By default, `uses` shows all formulae and casks that
         specify <formula> as a required or recommended dependency for their stable builds.
 
-        Note: `--missing` and `--skip-recommended` have precedence over `--include-*`.
+        *Note:* `--missing` and `--skip-recommended` have precedence over `--include-*`.
       EOS
       switch "--recursive",
              description: "Resolve more than one level of dependencies."

diff --git a/Library/Homebrew/dependency.rb b/Library/Homebrew/dependency.rb
@@ -230,7 +230,7 @@ def merge_temporality(deps)
   end
 end
 
-# A dependency that marked as "installed" on macOS
+# A dependency that's marked as "installed" on macOS
 class UsesFromMacOSDependency < Dependency
   attr_reader :bounds
 

diff --git a/Library/Homebrew/dev-cmd/contributions.rb b/Library/Homebrew/dev-cmd/contributions.rb
@@ -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",

diff --git a/Library/Homebrew/dev-cmd/generate-cask-api.rb b/Library/Homebrew/dev-cmd/generate-cask-api.rb
@@ -12,8 +12,7 @@ module Homebrew
   def generate_cask_api_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
-        Generates Cask API data files for formulae.brew.sh.
-
+        Generate `homebrew/cask` API data files for <#{HOMEBREW_API_WWW}>.
         The generated files are written to the current directory.
       EOS
 

diff --git a/Library/Homebrew/dev-cmd/generate-formula-api.rb b/Library/Homebrew/dev-cmd/generate-formula-api.rb
@@ -11,8 +11,7 @@ module Homebrew
   def generate_formula_api_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
-        Generates Formula API data files for formulae.brew.sh.
-
+        Generate `homebrew/core` API data files for <#{HOMEBREW_API_WWW}>.
         The generated files are written to the current directory.
       EOS
 

diff --git a/Library/Homebrew/dev-cmd/livecheck.rb b/Library/Homebrew/dev-cmd/livecheck.rb
@@ -14,7 +14,6 @@ def livecheck_args
     Homebrew::CLI::Parser.new do
       description <<~EOS
         Check for newer versions of formulae and/or casks from upstream.
-
         If no formula or cask argument is passed, the list of formulae and
         casks to check is taken from `HOMEBREW_LIVECHECK_WATCHLIST` or
         `~/.homebrew/livecheck_watchlist.txt`.

diff --git a/Library/Homebrew/dev-cmd/release.rb b/Library/Homebrew/dev-cmd/release.rb
@@ -17,7 +17,7 @@ def release_args
         The command will fail if the previous major or minor release was made less than
         one month ago.
 
-        Requires write access to the Homebrew/brew repository.
+        *Note:* Requires write access to the Homebrew/brew repository.
       EOS
       switch "--major",
              description: "Create a major release."

diff --git a/Library/Homebrew/env_config.rb b/Library/Homebrew/env_config.rb
@@ -300,7 +300,7 @@ module EnvConfig
       },
       HOMEBREW_NO_INSECURE_REDIRECT:             {
         description: "If set, forbid redirects from secure HTTPS to insecure HTTP." \
-                     "\n\n    *Note:* While ensuring your downloads are fully secure, this is likely to cause " \
+                     "\n\n    *Note:* while ensuring your downloads are fully secure, this is likely to cause " \
                      "from-source SourceForge, some GNU & GNOME-hosted formulae to fail to download.",
         boolean:     true,
       },
@@ -317,7 +317,7 @@ module EnvConfig
         boolean:     true,
       },
       HOMEBREW_NO_INSTALL_UPGRADE:               {
-        description: "If set, `brew install` <formula/cask> will not upgrade <formula/cask> if it is installed but " \
+        description: "If set, `brew install` <formula|cask> will not upgrade <formula|cask> if it is installed but " \
                      "outdated.",
         boolean:     true,
       },
@@ -333,7 +333,7 @@ module EnvConfig
         boolean:     true,
       },
       HOMEBREW_PIP_INDEX_URL:                    {
-        description:  "If set, `brew install <formula>` will use this URL to download PyPI package resources.",
+        description:  "If set, `brew install` <formula> will use this URL to download PyPI package resources.",
         default_text: "`https://pypi.org/simple`.",
       },
       HOMEBREW_PRY:                              {
@@ -361,7 +361,7 @@ module EnvConfig
       },
       HOMEBREW_SSH_CONFIG_PATH:                  {
         description:  "If set, Homebrew will use the given config file instead of `~/.ssh/config` when fetching " \
-                      "`git` repos over `ssh`.",
+                      "Git repositories over SSH.",
         default_text: "`$HOME/.ssh/config`",
       },
       HOMEBREW_SVN:                              {

diff --git a/Library/Homebrew/extend/kernel.rb b/Library/Homebrew/extend/kernel.rb
@@ -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