cmd+dev-cmd: fixes for output formatting

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.

Library/Homebrew/cmd/deps.rb

@@ -22,7 +22,7 @@ def self.deps_args
         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-*`.
+        *Note:* `--missing` and `--skip-recommended` have precedence over `--include-*`.
       EOS
       switch "-n", "--topological",
              description: "Sort dependencies in topological order."

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

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.

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.

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.

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

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

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

Library/Homebrew/env_config.rb

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

completions/fish/brew.fish

@@ -250,15 +250,15 @@ __fish_brew_complete_arg '--prefix' -l verbose -d 'Make some output more verbose
 __fish_brew_complete_arg '--prefix' -a '(__fish_brew_suggest_formulae_all)'
 
 
-__fish_brew_complete_cmd '--repo' 'Display where Homebrew\'s git repository is located'
+__fish_brew_complete_cmd '--repo' 'Display where Homebrew\'s Git repository is located'
 __fish_brew_complete_arg '--repo' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg '--repo' -l help -d 'Show this message'
 __fish_brew_complete_arg '--repo' -l quiet -d 'Make some output more quiet'
 __fish_brew_complete_arg '--repo' -l verbose -d 'Make some output more verbose'
 __fish_brew_complete_arg '--repo' -a '(__fish_brew_suggest_taps_installed)'
 
 
-__fish_brew_complete_cmd '--repository' 'Display where Homebrew\'s git repository is located'
+__fish_brew_complete_cmd '--repository' 'Display where Homebrew\'s Git repository is located'
 __fish_brew_complete_arg '--repository' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg '--repository' -l help -d 'Show this message'
 __fish_brew_complete_arg '--repository' -l quiet -d 'Make some output more quiet'
@@ -528,7 +528,7 @@ __fish_brew_complete_arg 'config' -l quiet -d 'Make some output more quiet'
 __fish_brew_complete_arg 'config' -l verbose -d 'Make some output more verbose'
 
 
-__fish_brew_complete_cmd 'contributions' 'Contributions to Homebrew repositories'
+__fish_brew_complete_cmd 'contributions' 'Summarise contributions to Homebrew repositories'
 __fish_brew_complete_arg 'contributions' -l csv -d 'Print a CSV of contributions across repositories over the time period'
 __fish_brew_complete_arg 'contributions' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'contributions' -l from -d 'Date (ISO-8601 format) to start searching contributions. Omitting this flag searches the last year'
@@ -644,7 +644,7 @@ __fish_brew_complete_arg 'dispatch-build-bottle' -l workflow -d 'Dispatch specif
 __fish_brew_complete_arg 'dispatch-build-bottle' -a '(__fish_brew_suggest_formulae_all)'
 
 
-__fish_brew_complete_cmd 'docs' 'Open Homebrew\'s online documentation (https://docs.brew.sh) in a browser'
+__fish_brew_complete_cmd 'docs' 'Open Homebrew\'s online documentation at https://docs.brew.sh in a browser'
 __fish_brew_complete_arg 'docs' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'docs' -l help -d 'Show this message'
 __fish_brew_complete_arg 'docs' -l quiet -d 'Make some output more quiet'
@@ -736,15 +736,15 @@ __fish_brew_complete_arg 'formula' -l verbose -d 'Make some output more verbose'
 __fish_brew_complete_arg 'formula' -a '(__fish_brew_suggest_formulae_all)'
 
 
-__fish_brew_complete_cmd 'generate-cask-api' 'Generates Cask API data files for formulae.brew.sh'
+__fish_brew_complete_cmd 'generate-cask-api' 'Generate `homebrew/cask` API data files for https://formulae.brew.sh'
 __fish_brew_complete_arg 'generate-cask-api' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'generate-cask-api' -l dry-run -d 'Generate API data without writing it to files'
 __fish_brew_complete_arg 'generate-cask-api' -l help -d 'Show this message'
 __fish_brew_complete_arg 'generate-cask-api' -l quiet -d 'Make some output more quiet'
 __fish_brew_complete_arg 'generate-cask-api' -l verbose -d 'Make some output more verbose'
 
 
-__fish_brew_complete_cmd 'generate-formula-api' 'Generates Formula API data files for formulae.brew.sh'
+__fish_brew_complete_cmd 'generate-formula-api' 'Generate `homebrew/core` API data files for https://formulae.brew.sh'
 __fish_brew_complete_arg 'generate-formula-api' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'generate-formula-api' -l dry-run -d 'Generate API data without writing it to files'
 __fish_brew_complete_arg 'generate-formula-api' -l help -d 'Show this message'
@@ -835,7 +835,7 @@ __fish_brew_complete_arg 'instal' -l force-bottle -d 'Install from a bottle if i
 __fish_brew_complete_arg 'instal' -l formula -d 'Treat all named arguments as formulae'
 __fish_brew_complete_arg 'instal' -l git -d 'Create a Git repository, useful for creating patches to the software'
 __fish_brew_complete_arg 'instal' -l help -d 'Show this message'
-__fish_brew_complete_arg 'instal' -l ignore-dependencies -d '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'
+__fish_brew_complete_arg 'instal' -l ignore-dependencies -d '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'
 __fish_brew_complete_arg 'instal' -l include-test -d 'Install testing dependencies required to run `brew test` formula'
 __fish_brew_complete_arg 'instal' -l input-methoddir -d 'Target location for Input Methods (default: `~/Library/Input Methods`)'
 __fish_brew_complete_arg 'instal' -l interactive -d 'Download and patch formula, then open a shell. This allows the user to run `./configure --help` and otherwise determine how to turn the software package into a Homebrew package'
@@ -857,7 +857,7 @@ __fish_brew_complete_arg 'instal' -l screen-saverdir -d 'Target location for Scr
 __fish_brew_complete_arg 'instal' -l servicedir -d 'Target location for Services (default: `~/Library/Services`)'
 __fish_brew_complete_arg 'instal' -l skip-cask-deps -d 'Skip installing cask dependencies'
 __fish_brew_complete_arg 'instal' -l skip-post-install -d 'Install but skip any post-install steps'
-__fish_brew_complete_arg 'instal' -l verbose -d 'Print the verification and postinstall steps'
+__fish_brew_complete_arg 'instal' -l verbose -d 'Print the verification and post-install steps'
 __fish_brew_complete_arg 'instal' -l vst-plugindir -d 'Target location for VST Plugins (default: `~/Library/Audio/Plug-Ins/VST`)'
 __fish_brew_complete_arg 'instal' -l vst3-plugindir -d 'Target location for VST3 Plugins (default: `~/Library/Audio/Plug-Ins/VST3`)'
 __fish_brew_complete_arg 'instal' -l zap -d 'For use with `brew reinstall --cask`. Remove all files associated with a cask. *May remove files which are shared between applications.*'
@@ -889,7 +889,7 @@ __fish_brew_complete_arg 'install' -l force-bottle -d 'Install from a bottle if
 __fish_brew_complete_arg 'install' -l formula -d 'Treat all named arguments as formulae'
 __fish_brew_complete_arg 'install' -l git -d 'Create a Git repository, useful for creating patches to the software'
 __fish_brew_complete_arg 'install' -l help -d 'Show this message'
-__fish_brew_complete_arg 'install' -l ignore-dependencies -d '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'
+__fish_brew_complete_arg 'install' -l ignore-dependencies -d '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'
 __fish_brew_complete_arg 'install' -l include-test -d 'Install testing dependencies required to run `brew test` formula'
 __fish_brew_complete_arg 'install' -l input-methoddir -d 'Target location for Input Methods (default: `~/Library/Input Methods`)'
 __fish_brew_complete_arg 'install' -l interactive -d 'Download and patch formula, then open a shell. This allows the user to run `./configure --help` and otherwise determine how to turn the software package into a Homebrew package'
@@ -911,7 +911,7 @@ __fish_brew_complete_arg 'install' -l screen-saverdir -d 'Target location for Sc
 __fish_brew_complete_arg 'install' -l servicedir -d 'Target location for Services (default: `~/Library/Services`)'
 __fish_brew_complete_arg 'install' -l skip-cask-deps -d 'Skip installing cask dependencies'
 __fish_brew_complete_arg 'install' -l skip-post-install -d 'Install but skip any post-install steps'
-__fish_brew_complete_arg 'install' -l verbose -d 'Print the verification and postinstall steps'
+__fish_brew_complete_arg 'install' -l verbose -d 'Print the verification and post-install steps'
 __fish_brew_complete_arg 'install' -l vst-plugindir -d 'Target location for VST Plugins (default: `~/Library/Audio/Plug-Ins/VST`)'
 __fish_brew_complete_arg 'install' -l vst3-plugindir -d 'Target location for VST3 Plugins (default: `~/Library/Audio/Plug-Ins/VST3`)'
 __fish_brew_complete_arg 'install' -l zap -d 'For use with `brew reinstall --cask`. Remove all files associated with a cask. *May remove files which are shared between applications.*'
@@ -1093,7 +1093,7 @@ __fish_brew_complete_arg 'missing' -l verbose -d 'Make some output more verbose'
 __fish_brew_complete_arg 'missing' -a '(__fish_brew_suggest_formulae_all)'
 
 
-__fish_brew_complete_cmd 'nodenv-sync' 'Create symlinks for Homebrew\'s installed NodeJS versions in ~/.nodenv/versions'
+__fish_brew_complete_cmd 'nodenv-sync' 'Create symlinks for Homebrew\'s installed NodeJS versions in `~/.nodenv/versions`'
 __fish_brew_complete_arg 'nodenv-sync' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'nodenv-sync' -l help -d 'Show this message'
 __fish_brew_complete_arg 'nodenv-sync' -l quiet -d 'Make some output more quiet'
@@ -1239,14 +1239,14 @@ __fish_brew_complete_arg 'prof' -l verbose -d 'Make some output more verbose'
 __fish_brew_complete_arg 'prof' -a '(__fish_brew_suggest_commands)'
 
 
-__fish_brew_complete_cmd 'pyenv-sync' 'Create symlinks for Homebrew\'s installed Python versions in ~/.pyenv/versions'
+__fish_brew_complete_cmd 'pyenv-sync' 'Create symlinks for Homebrew\'s installed Python versions in `~/.pyenv/versions`'
 __fish_brew_complete_arg 'pyenv-sync' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'pyenv-sync' -l help -d 'Show this message'
 __fish_brew_complete_arg 'pyenv-sync' -l quiet -d 'Make some output more quiet'
 __fish_brew_complete_arg 'pyenv-sync' -l verbose -d 'Make some output more verbose'
 
 
-__fish_brew_complete_cmd 'rbenv-sync' 'Create symlinks for Homebrew\'s installed Ruby versions in ~/.rbenv/versions'
+__fish_brew_complete_cmd 'rbenv-sync' 'Create symlinks for Homebrew\'s installed Ruby versions in `~/.rbenv/versions`'
 __fish_brew_complete_arg 'rbenv-sync' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'rbenv-sync' -l help -d 'Show this message'
 __fish_brew_complete_arg 'rbenv-sync' -l quiet -d 'Make some output more quiet'
@@ -1262,7 +1262,7 @@ __fish_brew_complete_arg 'readall' -l help -d 'Show this message'
 __fish_brew_complete_arg 'readall' -l no-simulate -d 'Don\'t simulate other system configurations when checking formulae and casks'
 __fish_brew_complete_arg 'readall' -l os -d 'Read using the given operating system. (Pass `all` to simulate all operating systems.)'
 __fish_brew_complete_arg 'readall' -l quiet -d 'Make some output more quiet'
-__fish_brew_complete_arg 'readall' -l syntax -d 'Syntax-check all of Homebrew\'s Ruby files (if no `tap` is passed)'
+__fish_brew_complete_arg 'readall' -l syntax -d 'Syntax-check all of Homebrew\'s Ruby files (if no tap is passed)'
 __fish_brew_complete_arg 'readall' -l verbose -d 'Make some output more verbose'
 __fish_brew_complete_arg 'readall' -a '(__fish_brew_suggest_taps_installed)'
 
@@ -1302,7 +1302,7 @@ __fish_brew_complete_arg 'reinstall' -l require-sha -d 'Require all casks to hav
 __fish_brew_complete_arg 'reinstall' -l screen-saverdir -d 'Target location for Screen Savers (default: `~/Library/Screen Savers`)'
 __fish_brew_complete_arg 'reinstall' -l servicedir -d 'Target location for Services (default: `~/Library/Services`)'
 __fish_brew_complete_arg 'reinstall' -l skip-cask-deps -d 'Skip installing cask dependencies'
-__fish_brew_complete_arg 'reinstall' -l verbose -d 'Print the verification and postinstall steps'
+__fish_brew_complete_arg 'reinstall' -l verbose -d 'Print the verification and post-install steps'
 __fish_brew_complete_arg 'reinstall' -l vst-plugindir -d 'Target location for VST Plugins (default: `~/Library/Audio/Plug-Ins/VST`)'
 __fish_brew_complete_arg 'reinstall' -l vst3-plugindir -d 'Target location for VST3 Plugins (default: `~/Library/Audio/Plug-Ins/VST3`)'
 __fish_brew_complete_arg 'reinstall' -l zap -d 'For use with `brew reinstall --cask`. Remove all files associated with a cask. *May remove files which are shared between applications.*'
@@ -1687,7 +1687,7 @@ __fish_brew_complete_arg 'upgrade' -l require-sha -d 'Require all casks to have
 __fish_brew_complete_arg 'upgrade' -l screen-saverdir -d 'Target location for Screen Savers (default: `~/Library/Screen Savers`)'
 __fish_brew_complete_arg 'upgrade' -l servicedir -d 'Target location for Services (default: `~/Library/Services`)'
 __fish_brew_complete_arg 'upgrade' -l skip-cask-deps -d 'Skip installing cask dependencies'
-__fish_brew_complete_arg 'upgrade' -l verbose -d 'Print the verification and postinstall steps'
+__fish_brew_complete_arg 'upgrade' -l verbose -d 'Print the verification and post-install steps'
 __fish_brew_complete_arg 'upgrade' -l vst-plugindir -d 'Target location for VST Plugins (default: `~/Library/Audio/Plug-Ins/VST`)'
 __fish_brew_complete_arg 'upgrade' -l vst3-plugindir -d 'Target location for VST3 Plugins (default: `~/Library/Audio/Plug-Ins/VST3`)'
 __fish_brew_complete_arg 'upgrade; and not __fish_seen_argument -l cask -l casks' -a '(__fish_brew_suggest_formulae_outdated)'