man: Seperate global options into a section

Library/Homebrew/cli_parser.rb

@@ -11,6 +11,15 @@ module Homebrew
         new(&block).parse(args)
       end
 
+      def self.global_options
+        {
+          quiet: [["-q", "--quiet"], :quiet, "Suppress any warnings."],
+          verbose: [["-v", "--verbose"], :verbose, "Make some output more verbose."],
+          debug: [["-d", "--debug"], :debug, "Display any debugging information."],
+          force: [["-f", "--force"], :force, "Override warnings and enable potentially unsafe operations."],
+        }
+      end
+
       def initialize(&block)
         @parser = OptionParser.new
         Homebrew.args = OpenStruct.new
@@ -34,10 +43,6 @@ module Homebrew
         end
       end
 
-      def wrap_option_desc(desc)
-        Formatter.wrap(desc, @desc_line_length).split("\n")
-      end
-
       def switch(*names, description: nil, env: nil, required_for: nil, depends_on: nil)
         global_switch = names.first.is_a?(Symbol)
         names, env, description = common_switch(*names) if global_switch
@@ -119,6 +124,10 @@ module Homebrew
         @parser
       end
 
+      def global_option?(name)
+        Homebrew::CLI::Parser.global_options.has_key?(name.to_sym)
+      end
+
       private
 
       def enable_switch(*names)
@@ -129,19 +138,17 @@ module Homebrew
 
       # These are common/global switches accessible throughout Homebrew
       def common_switch(name)
-        case name
+        Homebrew::CLI::Parser.global_options.fetch(name, name)
-        when :quiet   then [["-q", "--quiet"], :quiet, "Suppress any warnings."]
-        when :verbose then [["-v", "--verbose"], :verbose, "Make some output more verbose."]
-        when :debug   then [["-d", "--debug"], :debug, "Display any debugging information."]
-        when :force   then [["-f", "--force"], :force, "Override warnings and enable potentially unsafe operations."]
-        else name
-        end
       end
 
       def option_passed?(name)
         Homebrew.args.respond_to?(name) || Homebrew.args.respond_to?("#{name}?")
       end
 
+      def wrap_option_desc(desc)
+        Formatter.wrap(desc, @desc_line_length).split("\n")
+      end
+
       def set_constraints(name, depends_on:, required_for:)
         secondary = option_to_name(name)
         unless required_for.nil?

Library/Homebrew/dev-cmd/audit.rb

@@ -55,7 +55,7 @@ module Homebrew
   def audit_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        ### audit [options] [formulae]:
+        `audit` [`options`] [<formulae>]:
 
         Check <formulae> for Homebrew coding style violations. This should be
         run before submitting a new formula.

Library/Homebrew/dev-cmd/bottle.rb

@@ -72,7 +72,7 @@ module Homebrew
   def bottle_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        ### bottle [options] [formulae]:
+        `bottle` [<options>] [<formulae>]:
 
         Generate a bottle (binary package) from a formula installed with
         `--build-bottle`.

Library/Homebrew/dev-cmd/bump-formula-pr.rb

@@ -50,7 +50,7 @@ module Homebrew
   def bump_formula_pr_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        ### bump-formula-pr [options] [formula]:
+        `bump-formula-pr` [<options>] <formula>:
 
         Creates a pull request to update the formula with a new URL or a new tag.
     

Library/Homebrew/dev-cmd/create.rb

@@ -30,7 +30,7 @@ module Homebrew
   def create_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        ### create URL [options]:
+        `create` <URL> [<options>]:
 
         Generate a formula for the downloadable file at <URL> and open it in the editor.
         Homebrew will attempt to automatically derive the formula name

Library/Homebrew/dev-cmd/edit.rb

@@ -13,11 +13,9 @@ module Homebrew
   def edit_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        ### edit:
+        `edit` <formula>:
-          Open all of Homebrew for editing.
+          Open <formula> in the editor. Open all of Homebrew for editing if
-      
+          no <formula> is provided.
-        ### edit [formula]:
-          Open <formula> in the editor.
       EOS
       switch :force
       switch :verbose

Library/Homebrew/dev-cmd/formula.rb

@@ -10,7 +10,7 @@ module Homebrew
   def formula_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        ### formula [formula]:
+        `formula` <formula>:
 
         Display the path where <formula> is located.
       EOS

Library/Homebrew/dev-cmd/irb.rb

@@ -25,7 +25,7 @@ module Homebrew
   def irb_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        ### irb [options]:
+        `irb` [<options>]:
 
         Enter the interactive Homebrew Ruby shell.
       EOS

Library/Homebrew/dev-cmd/linkage.rb

@@ -22,7 +22,7 @@ module Homebrew
   def linkage_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        ### linkage [options] [formula]:
+        `linkage` [<options>] <formula>:
 
         Checks the library links of an installed formula.
 

Library/Homebrew/dev-cmd/man.rb

@@ -36,7 +36,7 @@ module Homebrew
   def man_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        ### man [options]:
+        `man` [<options>]:
 
         Generate Homebrew's manpages.
       EOS
@@ -93,6 +93,7 @@ module Homebrew
     variables[:commands] = path_glob_commands("#{HOMEBREW_LIBRARY_PATH}/cmd/*.{rb,sh}")
 
     variables[:developer_commands] = generate_cmd_manpages("#{HOMEBREW_LIBRARY_PATH}/dev-cmd/*.{rb,sh}")
+    variables[:global_options] = global_options_manpage_lines
     readme = HOMEBREW_REPOSITORY/"README.md"
     variables[:lead_maintainer] =
       readme.read[/(Homebrew's lead maintainer .*\.)/, 1]
@@ -180,7 +181,7 @@ module Homebrew
     cmd_paths.each do |cmd_path|
       begin
         cmd_parser = Homebrew.send(cmd_arg_parser(cmd_path))
-        man_page_lines << generate_cmd_manpage_lines(cmd_parser).join
+        man_page_lines << cmd_manpage_lines(cmd_parser).join
       rescue NoMethodError
         man_page_lines << path_glob_commands(cmd_path.to_s)[0]
       end
@@ -192,9 +193,19 @@ module Homebrew
     "#{cmd_path.basename.to_s.gsub('.rb', '').gsub('-', '_')}_args".to_sym
   end
 
-  def generate_cmd_manpage_lines(cmd_parser)
+  def cmd_manpage_lines(cmd_parser)
-    lines = [cmd_parser.usage_banner_text]
+    lines = ["#{format_usage_banner(cmd_parser.usage_banner_text)}"]
     lines += cmd_parser.processed_options.map do |short, long, _, desc|
+      next if !long.nil? && cmd_parser.global_option?(cmd_parser.option_to_name(long))
+      generate_option_doc(short, long, desc)
+    end
+    lines
+  end
+
+  def global_options_manpage_lines
+    lines = ["These options are applicable across all sub-commands.\n"]
+    lines += Homebrew::CLI::Parser.global_options.values.map do |names, _, desc|
+      short, long = names
       generate_option_doc(short, long, desc)
     end
     lines
@@ -211,4 +222,12 @@ module Homebrew
   def format_long_opt(opt)
     "`#{opt}`"
   end
+
+  def format_usage_banner(usage_banner)
+    synopsis, *remaining_lines = usage_banner.split('\n')
+    synopsis = synopsis.sub(/^/, "###")
+                 .gsub(/`/, "")
+                 .gsub(/<(.*?)>/, "\\1")
+    [synopsis, *remaining_lines].join("\n")
+  end
 end

Library/Homebrew/dev-cmd/mirror.rb

@@ -10,9 +10,9 @@ module Homebrew
   def mirror_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        ### mirror [formulae]:
+        `mirror` <formulae>:
          
-         Reuploads the stable URL for a formula to Bintray to use it as a mirror.
+        Reuploads the stable URL for a formula to Bintray to use it as a mirror.
       EOS
       switch :debug
       switch :verbose

Library/Homebrew/dev-cmd/prof.rb

@@ -1,4 +1,4 @@
-#:  ### prof [ruby options]:
+#:  * `prof` [ruby options]:
 #:    Run Homebrew with the Ruby profiler.
 #:    For example:
 #       brew prof readall

Library/Homebrew/dev-cmd/pull.rb

@@ -75,7 +75,7 @@ module Homebrew
   def pull_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        ### pull [options] [formula]:
+        pull [options] [formula]:
 
         Gets a patch from a GitHub commit or pull request and applies it to Homebrew.
         Optionally, installs the formulae changed by the patch.

Library/Homebrew/dev-cmd/release-notes.rb

@@ -13,7 +13,7 @@ module Homebrew
   def release_notes_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        ### release-notes [previous_tag] [end_ref]:
+        `release-notes` [<previous_tag>] [<end_ref>]:
 
         Output the merged pull requests on Homebrew/brew between two Git refs.
         If no <previous_tag> is provided it defaults to the latest tag.

Library/Homebrew/dev-cmd/tap-new.rb

@@ -18,7 +18,7 @@ module Homebrew
   def tap_new_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        ### tap-new [user]/[repo]:
+        `tap-new` <user>/<repo>:
          
         Generate the template files for a new tap.
       EOS

Library/Homebrew/dev-cmd/test.rb

@@ -1,4 +1,4 @@
-#:  ### test [--devel|--HEAD] [--debug] [--keep-tmp] [formula]:
+#:  * test [--devel|--HEAD] [--debug] [--keep-tmp] [formula]:
 #:    Most formulae provide a test method. `brew test` <formula> runs this
 #:    test method. There is no standard output or return code, but it should
 #:    generally indicate to the user if something is wrong with the installed

Library/Homebrew/dev-cmd/tests.rb

@@ -24,7 +24,7 @@ module Homebrew
   def tests_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        ### tests [options] [formula]:
+        `tests` [<options>] <formula>:
 
         Run Homebrew's unit and integration tests. If provided,
         `--only=`<test_script> runs only <test_script>_spec.rb, and `--seed`

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

@@ -22,11 +22,11 @@ module Homebrew
   def update_test_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        ### update-test [options]:
+        `update-test` [options]:
 
-         Runs a test of `brew update` with a new repository clone.
+        Runs a test of `brew update` with a new repository clone.
 
-         If no arguments are passed, use `origin/master` as the start commit.
+        If no arguments are passed, use `origin/master` as the start commit.
       EOS
       switch "--to-tag",
         description: "Set `HOMEBREW_UPDATE_TO_TAG` to test updating between tags."

Library/Homebrew/manpages/brew.1.md.erb

@@ -54,6 +54,10 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
 
 <%= developer_commands.join("\n") %>
 
+## GLOBAL OPTIONS
+
+<%= global_options.join("\n") %>
+
 ## OFFICIAL EXTERNAL COMMANDS
 
   <%= homebrew_bundle.join("\n  ").strip %>

docs/Manpage.md

@@ -663,11 +663,11 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
 
 ## DEVELOPER COMMANDS
 
-### audit [options] [formulae]:
+###audit [options] [formulae]:
 
-Check `formulae` for Homebrew coding style violations. This should be
+Check formulae for Homebrew coding style violations. This should be
 run before submitting a new formula.
-If no `formulae` are provided, all of them are checked.
+If no formulae are provided, all of them are checked.
 
 *  `--strict`:
 Run additional style checks, including Rubocop style checks.
@@ -691,18 +691,14 @@ Passing `--except`=`method` will run only the methods named audit_`method`, `met
 Passing `--only-cops`=`cops` will check for violations of only the listed RuboCop cops. `cops` should be a comma-separated list of cop names.
 *  `--except-cops`:
 Passing `--except-cops`=`cops` will skip checking the listed RuboCop cops violations. `cops` should be a comma-separated list of cop names.
-* `-v`,  `--verbose`:
-Make some output more verbose.
-* `-d`,  `--debug`:
-Display any debugging information.
 
-### bottle [options] [formulae]:
+###bottle [options] [formulae]:
 
 Generate a bottle (binary package) from a formula installed with
-`--build-bottle`.
+--build-bottle.
 If the formula specifies a rebuild version, it will be incremented in the
-generated DSL. Passing `--keep-old` will attempt to keep it at its
+generated DSL. Passing --keep-old will attempt to keep it at its
-original value, while `--no-rebuild` will remove it.
+original value, while --no-rebuild will remove it.
 
 *  `--skip-relocation`:
 Do not check if the bottle can be marked as relocatable.
@@ -724,20 +720,16 @@ When passed with `--write`, a new commit will not generated while writing change
 Write bottle information to a JSON file, which can be used as the argument for `--merge`.
 *  `--root-url`:
 Use the specified `URL` as the root of the bottle's URL instead of Homebrew's default.
-* `-v`,  `--verbose`:
-Make some output more verbose.
-* `-d`,  `--debug`:
-Display any debugging information.
 
-### bump-formula-pr [options] [formula]:
+###bump-formula-pr [options] formula:
 
 Creates a pull request to update the formula with a new URL or a new tag.
 
-If a `URL` is specified, the `sha-256` checksum of the new download must
+If a URL is specified, the sha-256 checksum of the new download must
-also be specified. A best effort to determine the `sha-256` and `formula`
+also be specified. A best effort to determine the sha-256 and formula
 name will be made if either or both values are not supplied by the user.
 
-If a `tag` is specified, the git commit `revision` corresponding to that
+If a tag is specified, the git commit revision corresponding to that
 tag must also be specified.
 
 Note that this command cannot be used to transition a formula from a
@@ -771,22 +763,14 @@ Use the provided `URL` as a mirror URL.
 Use the provided `version` to override the value parsed from the URL or tag. Note that `--version=0` can be used to delete an existing `version` override from a formula if it has become redundant.
 *  `--message`:
 Append provided `message` to the default PR message.
-* `-q`,  `--quiet`:
-Suppress any warnings.
-* `-f`,  `--force`:
-Override warnings and enable potentially unsafe operations.
-* `-v`,  `--verbose`:
-Make some output more verbose.
-* `-d`,  `--debug`:
-Display any debugging information.
 
-### create URL [options]:
+###create URL [options]:
 
-Generate a formula for the downloadable file at `URL` and open it in the editor.
+Generate a formula for the downloadable file at URL and open it in the editor.
 Homebrew will attempt to automatically derive the formula name
-and version, but if it fails, you'll have to make your own template. The `wget`
+and version, but if it fails, you'll have to make your own template. The wget
 formula serves as a simple example. For the complete API have a look at
-<http://www.rubydoc.info/github/Homebrew/brew/master/Formula>.
+http://www.rubydoc.info/github/Homebrew/brew/master/Formula.
 
 *  `--autotools`:
 Create a basic template for an Autotools-style build.
@@ -804,36 +788,18 @@ Set the provided name of the package you are creating.
 Set the provided version of the package you are creating.
 *  `--tap`:
 Takes a tap [`user``/``repo`] as argument and generates the formula in the specified tap.
-* `-f`,  `--force`:
-Override warnings and enable potentially unsafe operations.
-* `-v`,  `--verbose`:
-Make some output more verbose.
-* `-d`,  `--debug`:
-Display any debugging information.
 
-### edit:
+###edit formula:
-  Open all of Homebrew for editing.
+  Open formula in the editor. Open all of Homebrew for editing if
+  no formula is provided.
 
-### edit [formula]:
-  Open `formula` in the editor.
 
-* `-f`,  `--force`:
+###formula formula:
-Override warnings and enable potentially unsafe operations.
-* `-v`,  `--verbose`:
-Make some output more verbose.
-* `-d`,  `--debug`:
-Display any debugging information.
 
-### formula [formula]:
+Display the path where formula is located.
 
-Display the path where `formula` is located.
 
-* `-d`,  `--debug`:
+###irb [options]:
-Display any debugging information.
-* `-v`,  `--verbose`:
-Make some output more verbose.
-
-### irb [options]:
 
 Enter the interactive Homebrew Ruby shell.
 
@@ -842,7 +808,7 @@ Show several examples.
 *  `--pry`:
 Pry will be used instead of irb if `--pry` is passed or HOMEBREW_PRY is set.
 
-### linkage [options] [formula]:
+###linkage [options] formula:
 
 Checks the library links of an installed formula.
 
@@ -855,12 +821,8 @@ Display only missing libraries and exit with a non-zero exit code if any missing
 Print the dylib followed by the binaries which link to it for each library the keg references.
 *  `--cached`:
 Print the cached linkage values stored in HOMEBREW_CACHE, set from a previous `brew linkage` run.
-* `-v`,  `--verbose`:
-Make some output more verbose.
-* `-d`,  `--debug`:
-Display any debugging information.
 
-### man [options]:
+###man [options]:
 
 Generate Homebrew's manpages.
 
@@ -869,25 +831,21 @@ Return a failing status code if changes are detected in the manpage outputs. Thi
 *  `--link`:
 It is now done automatically by `brew update`.
 
-### mirror [formulae]:
+###mirror formulae:
  
- Reuploads the stable URL for a formula to Bintray to use it as a mirror.
+Reuploads the stable URL for a formula to Bintray to use it as a mirror.
 
-* `-d`,  `--debug`:
-Display any debugging information.
-* `-v`,  `--verbose`:
-Make some output more verbose.
 
-  ### prof [ruby options]:
+  * `prof` [ruby options]:
     Run Homebrew with the Ruby profiler.
     For example:
 
-### pull [options] [formula]:
+###pull [options] [formula]:
 
 Gets a patch from a GitHub commit or pull request and applies it to Homebrew.
 Optionally, installs the formulae changed by the patch.
 
-Each `patch-source` may be one of:
+Each patch-source may be one of:
 
   ~ The ID number of a PR (pull request) in the homebrew/core GitHub
     repository
@@ -922,16 +880,12 @@ Do not exit if there's a failure publishing bottles on Bintray.
 Publish at the given Bintray organisation.
 *  `--test-bot-user`:
 Pull the bottle block commit from the specified user on GitHub.
-* `-v`,  `--verbose`:
-Make some output more verbose.
-* `-d`,  `--debug`:
-Display any debugging information.
 
-### release-notes [previous_tag] [end_ref]:
+###release-notes [previous_tag] [end_ref]:
 
 Output the merged pull requests on Homebrew/brew between two Git refs.
-If no `previous_tag` is provided it defaults to the latest tag.
+If no previous_tag is provided it defaults to the latest tag.
-If no `end_ref` is provided it defaults to `origin/master`.
+If no end_ref is provided it defaults to origin/master.
 
 *  `--markdown`:
 Output as a Markdown list.
@@ -940,16 +894,12 @@ Output as a Markdown list.
     Run a Ruby instance with Homebrew's libraries loaded.
     For example:
 
-### tap-new [user]/[repo]:
+###tap-new user/repo:
  
 Generate the template files for a new tap.
 
-* `-d`,  `--debug`:
-Display any debugging information.
-* `-v`,  `--verbose`:
-Make some output more verbose.
 
-  ### test [--devel|--HEAD] [--debug] [--keep-tmp] [formula]:
+  * test [--devel|--HEAD] [--debug] [--keep-tmp] [formula]:
     Most formulae provide a test method. `brew test` `formula` runs this
     test method. There is no standard output or return code, but it should
     generally indicate to the user if something is wrong with the installed
@@ -966,10 +916,10 @@ Make some output more verbose.
 
     Example: `brew install jruby && brew test jruby`
 
-### tests [options] [formula]:
+###tests [options] formula:
 
 Run Homebrew's unit and integration tests. If provided,
-`--only=``test_script` runs only `test_script`_spec.rb, and `--seed`
+--only=test_script runs only test_script_spec.rb, and --seed
 randomizes tests with the provided value instead of a random seed.
 
 *  `--coverage`:
@@ -984,16 +934,12 @@ Include tests that use the GitHub API and tests that use any of the taps for off
 Run only `test_script`_spec.rb
 *  `--seed`:
 Randomizes tests with the provided value instead of a random seed.
-* `-v`,  `--verbose`:
-Make some output more verbose.
-* `-d`,  `--debug`:
-Display any debugging information.
 
-### update-test [options]:
+###update-test [options]:
 
- Runs a test of `brew update` with a new repository clone.
+Runs a test of brew update with a new repository clone.
 
- If no arguments are passed, use `origin/master` as the start commit.
+If no arguments are passed, use origin/master as the start commit.
 
 *  `--to-tag`:
 Set `HOMEBREW_UPDATE_TO_TAG` to test updating between tags.
@@ -1003,11 +949,23 @@ Retain the temporary directory containing the new repository clone.
 Use provided `commit` as the start commit.
 *  `--before`:
 Use the commit at provided `date` as the start commit.
+
+## GLOBAL OPTIONS
+
+These options are applicable across all sub-commands.
+
+* `-q`,  `--quiet`:
+Suppress any warnings.
+
 * `-v`,  `--verbose`:
 Make some output more verbose.
+
 * `-d`,  `--debug`:
 Display any debugging information.
 
+* `-f`,  `--force`:
+Override warnings and enable potentially unsafe operations.
+
 ## OFFICIAL EXTERNAL COMMANDS
 
   * `bundle` `command`:
@@ -1409,6 +1367,7 @@ See our issues on GitHub:
 [ESSENTIAL COMMANDS]: #ESSENTIAL-COMMANDS "ESSENTIAL COMMANDS"
 [COMMANDS]: #COMMANDS "COMMANDS"
 [DEVELOPER COMMANDS]: #DEVELOPER-COMMANDS "DEVELOPER COMMANDS"
+[GLOBAL OPTIONS]: #GLOBAL-OPTIONS "GLOBAL OPTIONS"
 [OFFICIAL EXTERNAL COMMANDS]: #OFFICIAL-EXTERNAL-COMMANDS "OFFICIAL EXTERNAL COMMANDS"
 [CUSTOM EXTERNAL COMMANDS]: #CUSTOM-EXTERNAL-COMMANDS "CUSTOM EXTERNAL COMMANDS"
 [SPECIFYING FORMULAE]: #SPECIFYING-FORMULAE "SPECIFYING FORMULAE"

manpages/brew.1

@@ -622,7 +622,7 @@ If \fB\-\-force\fR (or \fB\-f\fR) is specified then always do a slower, full upd
 .SH "DEVELOPER COMMANDS"
 .
 .SS "audit [options] [formulae]:"
-Check \fIformulae\fR for Homebrew coding style violations\. This should be run before submitting a new formula\. If no \fIformulae\fR are provided, all of them are checked\.
+Check formulae for Homebrew coding style violations\. This should be run before submitting a new formula\. If no formulae are provided, all of them are checked\.
 .
 .TP
 \fB\-\-strict\fR
@@ -668,16 +668,8 @@ Passing \fB\-\-only\-cops\fR=\fIcops\fR will check for violations of only the li
 \fB\-\-except\-cops\fR
 Passing \fB\-\-except\-cops\fR=\fIcops\fR will skip checking the listed RuboCop cops violations\. \fBcops\fR should be a comma\-separated list of cop names\.
 .
-.TP
-\fB\-v\fR, \fB\-\-verbose\fR
-Make some output more verbose\.
-.
-.TP
-\fB\-d\fR, \fB\-\-debug\fR
-Display any debugging information\.
-.
 .SS "bottle [options] [formulae]:"
-Generate a bottle (binary package) from a formula installed with \fB\-\-build\-bottle\fR\. If the formula specifies a rebuild version, it will be incremented in the generated DSL\. Passing \fB\-\-keep\-old\fR will attempt to keep it at its original value, while \fB\-\-no\-rebuild\fR will remove it\.
+Generate a bottle (binary package) from a formula installed with \-\-build\-bottle\. If the formula specifies a rebuild version, it will be incremented in the generated DSL\. Passing \-\-keep\-old will attempt to keep it at its original value, while \-\-no\-rebuild will remove it\.
 .
 .TP
 \fB\-\-skip\-relocation\fR
@@ -719,22 +711,14 @@ Write bottle information to a JSON file, which can be used as the argument for \
 \fB\-\-root\-url\fR
 Use the specified \fIURL\fR as the root of the bottle\'s URL instead of Homebrew\'s default\.
 .
-.TP
+.SS "bump\-formula\-pr [options] formula:"
-\fB\-v\fR, \fB\-\-verbose\fR
-Make some output more verbose\.
-.
-.TP
-\fB\-d\fR, \fB\-\-debug\fR
-Display any debugging information\.
-.
-.SS "bump\-formula\-pr [options] [formula]:"
 Creates a pull request to update the formula with a new URL or a new tag\.
 .
 .P
-If a \fIURL\fR is specified, the \fIsha\-256\fR checksum of the new download must also be specified\. A best effort to determine the \fIsha\-256\fR and \fIformula\fR name will be made if either or both values are not supplied by the user\.
+If a URL is specified, the sha\-256 checksum of the new download must also be specified\. A best effort to determine the sha\-256 and formula name will be made if either or both values are not supplied by the user\.
 .
 .P
-If a \fItag\fR is specified, the git commit \fIrevision\fR corresponding to that tag must also be specified\.
+If a tag is specified, the git commit revision corresponding to that tag must also be specified\.
 .
 .P
 Note that this command cannot be used to transition a formula from a URL\-and\-sha256 style specification into a tag\-and\-revision style specification, nor vice versa\. It must use whichever style specification the preexisting formula already uses\.
@@ -794,24 +778,8 @@ Use the provided \fIversion\fR to override the value parsed from the URL or tag\
 \fB\-\-message\fR
 Append provided \fImessage\fR to the default PR message\.
 .
-.TP
-\fB\-q\fR, \fB\-\-quiet\fR
-Suppress any warnings\.
-.
-.TP
-\fB\-f\fR, \fB\-\-force\fR
-Override warnings and enable potentially unsafe operations\.
-.
-.TP
-\fB\-v\fR, \fB\-\-verbose\fR
-Make some output more verbose\.
-.
-.TP
-\fB\-d\fR, \fB\-\-debug\fR
-Display any debugging information\.
-.
 .SS "create URL [options]:"
-Generate a formula for the downloadable file at \fIURL\fR and open it in the editor\. Homebrew will attempt to automatically derive the formula name and version, but if it fails, you\'ll have to make your own template\. The \fBwget\fR formula serves as a simple example\. For the complete API have a look at \fIhttp://www\.rubydoc\.info/github/Homebrew/brew/master/Formula\fR\.
+Generate a formula for the downloadable file at URL and open it in the editor\. Homebrew will attempt to automatically derive the formula name and version, but if it fails, you\'ll have to make your own template\. The wget formula serves as a simple example\. For the complete API have a look at http://www\.rubydoc\.info/github/Homebrew/brew/master/Formula\.
 .
 .TP
 \fB\-\-autotools\fR
@@ -845,46 +813,11 @@ Set the provided version of the package you are creating\.
 \fB\-\-tap\fR
 Takes a tap [\fIuser\fR\fB/\fR\fIrepo\fR] as argument and generates the formula in the specified tap\.
 .
-.TP
+.SS "edit formula:"
-\fB\-f\fR, \fB\-\-force\fR
+Open formula in the editor\. Open all of Homebrew for editing if no formula is provided\.
-Override warnings and enable potentially unsafe operations\.
 .
-.TP
+.SS "formula formula:"
-\fB\-v\fR, \fB\-\-verbose\fR
+Display the path where formula is located\.
-Make some output more verbose\.
-.
-.TP
-\fB\-d\fR, \fB\-\-debug\fR
-Display any debugging information\.
-.
-.SS "edit:"
-Open all of Homebrew for editing\.
-.
-.SS "edit [formula]:"
-Open \fIformula\fR in the editor\.
-.
-.TP
-\fB\-f\fR, \fB\-\-force\fR
-Override warnings and enable potentially unsafe operations\.
-.
-.TP
-\fB\-v\fR, \fB\-\-verbose\fR
-Make some output more verbose\.
-.
-.TP
-\fB\-d\fR, \fB\-\-debug\fR
-Display any debugging information\.
-.
-.SS "formula [formula]:"
-Display the path where \fIformula\fR is located\.
-.
-.TP
-\fB\-d\fR, \fB\-\-debug\fR
-Display any debugging information\.
-.
-.TP
-\fB\-v\fR, \fB\-\-verbose\fR
-Make some output more verbose\.
 .
 .SS "irb [options]:"
 Enter the interactive Homebrew Ruby shell\.
@@ -897,7 +830,7 @@ Show several examples\.
 \fB\-\-pry\fR
 Pry will be used instead of irb if \fB\-\-pry\fR is passed or HOMEBREW_PRY is set\.
 .
-.SS "linkage [options] [formula]:"
+.SS "linkage [options] formula:"
 Checks the library links of an installed formula\.
 .
 .P
@@ -915,14 +848,6 @@ Print the dylib followed by the binaries which link to it for each library the k
 \fB\-\-cached\fR
 Print the cached linkage values stored in HOMEBREW_CACHE, set from a previous \fBbrew linkage\fR run\.
 .
-.TP
-\fB\-v\fR, \fB\-\-verbose\fR
-Make some output more verbose\.
-.
-.TP
-\fB\-d\fR, \fB\-\-debug\fR
-Display any debugging information\.
-.
 .SS "man [options]:"
 Generate Homebrew\'s manpages\.
 .
@@ -934,27 +859,18 @@ Return a failing status code if changes are detected in the manpage outputs\. Th
 \fB\-\-link\fR
 It is now done automatically by \fBbrew update\fR\.
 .
-.SS "mirror [formulae]:"
+.SS "mirror formulae:"
 Reuploads the stable URL for a formula to Bintray to use it as a mirror\.
 .
 .TP
-\fB\-d\fR, \fB\-\-debug\fR
+\fBprof\fR [ruby options]
-Display any debugging information\.
-.
-.TP
-\fB\-v\fR, \fB\-\-verbose\fR
-Make some output more verbose\.
-.
-.SS "prof [ruby options]:"
-.
-.IP
 Run Homebrew with the Ruby profiler\. For example:
 .
 .SS "pull [options] [formula]:"
 Gets a patch from a GitHub commit or pull request and applies it to Homebrew\. Optionally, installs the formulae changed by the patch\.
 .
 .P
-Each \fIpatch\-source\fR may be one of:
+Each patch\-source may be one of:
 .
 .P
 ~ The ID number of a PR (pull request) in the homebrew/core GitHub repository
@@ -1012,16 +928,8 @@ Publish at the given Bintray organisation\.
 \fB\-\-test\-bot\-user\fR
 Pull the bottle block commit from the specified user on GitHub\.
 .
-.TP
-\fB\-v\fR, \fB\-\-verbose\fR
-Make some output more verbose\.
-.
-.TP
-\fB\-d\fR, \fB\-\-debug\fR
-Display any debugging information\.
-.
 .SS "release\-notes [previous_tag] [end_ref]:"
-Output the merged pull requests on Homebrew/brew between two Git refs\. If no \fIprevious_tag\fR is provided it defaults to the latest tag\. If no \fIend_ref\fR is provided it defaults to \fBorigin/master\fR\.
+Output the merged pull requests on Homebrew/brew between two Git refs\. If no previous_tag is provided it defaults to the latest tag\. If no end_ref is provided it defaults to origin/master\.
 .
 .TP
 \fB\-\-markdown\fR
@@ -1031,20 +939,11 @@ Output as a Markdown list\.
 \fBruby\fR [\fIruby options\fR]
 Run a Ruby instance with Homebrew\'s libraries loaded\. For example:
 .
-.SS "tap\-new [user]/[repo]:"
+.SS "tap\-new user/repo:"
 Generate the template files for a new tap\.
 .
 .TP
-\fB\-d\fR, \fB\-\-debug\fR
+test [\-\-devel|\-\-HEAD] [\-\-debug] [\-\-keep\-tmp] [formula]
-Display any debugging information\.
-.
-.TP
-\fB\-v\fR, \fB\-\-verbose\fR
-Make some output more verbose\.
-.
-.SS "test [\-\-devel|\-\-HEAD] [\-\-debug] [\-\-keep\-tmp] [formula]:"
-.
-.IP
 Most formulae provide a test method\. \fBbrew test\fR \fIformula\fR runs this test method\. There is no standard output or return code, but it should generally indicate to the user if something is wrong with the installed formula\.
 .
 .IP
@@ -1059,8 +958,8 @@ If \fB\-\-keep\-tmp\fR is passed, the temporary files created for the test are n
 .IP
 Example: \fBbrew install jruby && brew test jruby\fR
 .
-.SS "tests [options] [formula]:"
+.SS "tests [options] formula:"
-Run Homebrew\'s unit and integration tests\. If provided, \fB\-\-only=\fR\fItest_script\fR runs only \fItest_script\fR_spec\.rb, and \fB\-\-seed\fR randomizes tests with the provided value instead of a random seed\.
+Run Homebrew\'s unit and integration tests\. If provided, \-\-only=test_script runs only test_script_spec\.rb, and \-\-seed randomizes tests with the provided value instead of a random seed\.
 .
 .TP
 \fB\-\-coverage\fR
@@ -1086,19 +985,11 @@ Run only \fItest_script\fR_spec\.rb
 \fB\-\-seed\fR
 Randomizes tests with the provided value instead of a random seed\.
 .
-.TP
-\fB\-v\fR, \fB\-\-verbose\fR
-Make some output more verbose\.
-.
-.TP
-\fB\-d\fR, \fB\-\-debug\fR
-Display any debugging information\.
-.
 .SS "update\-test [options]:"
-Runs a test of \fBbrew update\fR with a new repository clone\.
+Runs a test of brew update with a new repository clone\.
 .
 .P
-If no arguments are passed, use \fBorigin/master\fR as the start commit\.
+If no arguments are passed, use origin/master as the start commit\.
 .
 .TP
 \fB\-\-to\-tag\fR
@@ -1116,6 +1007,13 @@ Use provided \fIcommit\fR as the start commit\.
 \fB\-\-before\fR
 Use the commit at provided \fIdate\fR as the start commit\.
 .
+.SH "GLOBAL OPTIONS"
+These options are applicable across all sub\-commands\.
+.
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Suppress any warnings\.
+.
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
 Make some output more verbose\.
@@ -1124,6 +1022,10 @@ Make some output more verbose\.
 \fB\-d\fR, \fB\-\-debug\fR
 Display any debugging information\.
 .
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+Override warnings and enable potentially unsafe operations\.
+.
 .SH "OFFICIAL EXTERNAL COMMANDS"
 .
 .TP