Better man page formatting

Library/Homebrew/cli_parser.rb

@@ -5,6 +5,8 @@ require "set"
 module Homebrew
   module CLI
     class Parser
+      attr_reader :processed_options
+
       def self.parse(args = ARGV, &block)
         new(&block).parse(args)
       end
@@ -16,32 +18,31 @@ module Homebrew
         Homebrew.args.instance_eval { undef tap }
         @constraints = []
         @conflicts = []
+        @processed_options = []
+        @desc_line_length = 48
         instance_eval(&block)
         post_initialize
       end
 
       def post_initialize
         @parser.on_tail("-h", "--help", "Show this message") do
-          puts @parser
+          puts @parser.to_s.sub(/^/, "#{Tty.bold}Usage: brew#{Tty.reset} ")
-          xyz = @parser.summarize([], 8, 44, " "*8).map do |r|
+                      .gsub(/`(.*?)`/, "#{Tty.bold}\\1#{Tty.reset}")
-            if r.match?(/^\s{12}\S/)
+                      .gsub(%r{<([^\s]+?://[^\s]+?)>}) { |url| Formatter.url(url) }
-              "\n" + r.gsub(" "*12, " "*8)
+                      .gsub(/<(.*?)>/, "#{Tty.underline}\\1#{Tty.reset}")
-            elsif r.start_with?(" "*17)
-              r.gsub(" "*17, " "*11)
-            else
-              "\n" + r
         end
       end
-          puts xyz
+
-          exit
+      def wrap_option_desc(desc)
-        end
+        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
         description = option_to_description(*names) if description.nil?
-        @parser.on(*names, *description.split("\n")) do
+        process_option(*names, description)
+        @parser.on(*names, *wrap_option_desc(description)) do
           enable_switch(*names)
         end
 
@@ -52,13 +53,18 @@ module Homebrew
         enable_switch(*names) if !env.nil? && !ENV["HOMEBREW_#{env.to_s.upcase}"].nil?
       end
 
-      def banner(text)
+      def usage_banner(text)
         @parser.banner = text
       end
 
+      def usage_banner_text
+        @parser.banner
+      end
+
       def comma_array(name, description: nil)
         description = option_to_description(name) if description.nil?
-        @parser.on(name, OptionParser::REQUIRED_ARGUMENT, Array, *description.split("\n")) do |list|
+        process_option(name, description)
+        @parser.on(name, OptionParser::REQUIRED_ARGUMENT, Array, *wrap_option_desc(description)) do |list|
           Homebrew.args[option_to_name(name)] = list
         end
       end
@@ -71,7 +77,8 @@ module Homebrew
           required = OptionParser::OPTIONAL_ARGUMENT
         end
         description = option_to_description(name) if description.nil?
-        @parser.on(name, *description.split("\n"), required) do |option_value|
+        process_option(name, description)
+        @parser.on(name, *wrap_option_desc(description), required) do |option_value|
           Homebrew.args[option_to_name(name)] = option_value
         end
 
@@ -122,10 +129,10 @@ module Homebrew
       # These are common/global switches accessible throughout Homebrew
       def common_switch(name)
         case name
-        when :quiet   then [["-q", "--quiet"], :quiet, "Suppress warnings."]
+        when :quiet   then [["-q", "--quiet"], :quiet, "Suppress any warnings."]
-        when :verbose then [["-v", "--verbose"], :verbose, "Verbose mode."]
+        when :verbose then [["-v", "--verbose"], :verbose, "Make some output more verbose."]
-        when :debug   then [["-d", "--debug"], :debug, "Display debug info."]
+        when :debug   then [["-d", "--debug"], :debug, "Display any debugging information."]
-        when :force   then [["-f", "--force"], :force, "Override any warnings/validations."]
+        when :force   then [["-f", "--force"], :force, "Override warnings and enable potentially unsafe operations."]
         else name
         end
       end
@@ -187,6 +194,11 @@ module Homebrew
         check_conflicts
         check_constraints
       end
+
+      def process_option(*args)
+        option, = @parser.make_switch(args)
+        @processed_options << [option.short.first, option.long.first, option.arg, option.desc.first]
+      end
     end
 
     class OptionConstraintError < RuntimeError

Library/Homebrew/dev-cmd/audit.rb

@@ -54,8 +54,8 @@ module Homebrew
 
   def audit_args
     Homebrew::CLI::Parser.new do
-      banner <<~EOS
+      usage_banner <<~EOS
-        Usage: brew audit [options] [<formulae>]
+        `audit` [<options>] [<formulae>]:
 
         Check <formulae> for Homebrew coding style violations. This should be
         run before submitting a new formula.
@@ -63,17 +63,37 @@ module Homebrew
         If no <formulae> are provided, all of them are checked.
 
       EOS
-      switch      "--strict", description: "Run additional style checks, including Rubocop style checks."
+      switch      "--strict",            description: "Run additional style checks, "\
-      switch      "--online", description: "Run additional slower style checks that require a\nnetwork connection."
+                                                      "including Rubocop style checks."
-      switch      "--new-formula", description: "Run various additional style checks to determine if a new formula \nis eligible for Homebrew. This should be used when creating \nnew formula and implies --strict and --online."
+      switch      "--online",            description: "Run additional slower style checks "\
-      switch      "--fix", description: "Fix style violations automatically using\nRuboCop's auto-correct feature."
+                                                      "that require a network connection."
-      switch      "--display-cop-names", description: "Include the RuboCop cop name for each violation\nin the output."
+      switch      "--new-formula",       description: "Run various additional style checks "\
-      switch      "--display-filename", description: "Prefix everyline of output with name of the file or\nformula being audited, to make output easy to grep."
+                                                      "to determine if a new formula is eligible "\
+                                                      "for Homebrew. This should be used when "\
+                                                      "creating new formula and implies "\
+                                                      "`--strict` and `--online`."
+      switch      "--fix",               description: "Fix style violations automatically using "\
+                                                      "RuboCop's auto-correct feature."
+      switch      "--display-cop-names", description: "Include the RuboCop cop name for each "\
+                                                      "violation in the output."
+      switch      "--display-filename",  description: "Prefix everyline of output with name of "\
+                                                      "the file or formula being audited, to "\
+                                                      "make output easy to grep."
       switch      "-D", "--audit-debug", description: "Activates debugging and profiling"
-      comma_array "--only", description: "Passing --only=method will run only the methods named audit_method,\n`method` should be a comma-separated list."
+      comma_array "--only",              description: "Passing `--only`=<method> will run only the"\
-      comma_array "--except", description: "Passing --except=method will run only the methods named audit_method,\n`method` should be a comma-separated list."
+                                                      "methods named audit_method, `method` should "\
-      comma_array "--only-cops", description: "Passing --only-cops=cops will check for violations of only the listed\nRuboCop cops. `cops` should be a comma-separated list of cop names."
+                                                      "be a comma-separated list."
-      comma_array "--except-cops", description: "Passing --except-cops=cops will skip checking the listed\nRuboCop cops violations. `cops` should be a comma-separated list of cop names."
+      comma_array "--except",            description: "Passing `--except`=<method> will run only the "\
+                                                      "methods named audit_method, `method` should "\
+                                                      "be a comma-separated list."
+      comma_array "--only-cops",         description: "Passing `--only-cops`=<cops> will check for "\
+                                                      "violations of only the listed RuboCop cops."\
+                                                      "`cops` should be a comma-separated list of "\
+                                                      "cop names."
+      comma_array "--except-cops",       description: "Passing `--except-cops`=<cops> will "\
+                                                      "skip checking the listed RuboCop cops "\
+                                                      "violations. `cops` should be a "\
+                                                      "comma-separated list of cop names."
       switch      :verbose
       switch      :debug
     end

Library/Homebrew/dev-cmd/man.rb

@@ -69,7 +69,7 @@ module Homebrew
     variables = OpenStruct.new
 
     variables[:commands] = path_glob_commands("#{HOMEBREW_LIBRARY_PATH}/cmd/*.{rb,sh}")
-    variables[:developer_commands] = [Homebrew.send(:audit_args).summary] + path_glob_commands("#{HOMEBREW_LIBRARY_PATH}/dev-cmd/*.{rb,sh}")
+    variables[:developer_commands] = generate_cmd_manpage(Homebrew.send(:audit_args)) + path_glob_commands("#{HOMEBREW_LIBRARY_PATH}/dev-cmd/*.{rb,sh}")
     readme = HOMEBREW_REPOSITORY/"README.md"
     variables[:lead_maintainer] =
       readme.read[/(Homebrew's lead maintainer .*\.)/, 1]
@@ -150,4 +150,24 @@ module Homebrew
       odie "Failed to infer output format from '#{target.basename}'."
     end
   end
+
+  def generate_cmd_manpage(cmd_parser)
+    lines = [cmd_parser.usage_banner_text]
+    lines += cmd_parser.processed_options.map do |short, long, _, desc|
+      generate_option_doc(short, long, desc)
+    end
+    lines
+  end
+
+  def generate_option_doc(short, long, desc)
+    "* #{format_short_opt(short)} #{format_long_opt(long)}:" + "\n" + desc + "\n"
+  end
+
+  def format_short_opt(opt)
+    "`#{opt}`, " unless opt.nil?
+  end
+
+  def format_long_opt(opt)
+    "`#{opt}`".ljust(30)
+  end
 end

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

@@ -15,6 +15,7 @@ module Homebrew
       switch "--markdown"
     end
   end
+
   def release_notes
     release_notes_args.parse
 

Library/Homebrew/dev-cmd/tests.rb

@@ -33,6 +33,7 @@ module Homebrew
       flag   "--seed="
     end
   end
+
   def tests
     tests_args.parse
 

Library/Homebrew/utils/formatter.rb

@@ -31,6 +31,10 @@ module Formatter
     label(label, string, :red)
   end
 
+  def wrap(s, width = 172)
+    s.gsub(/(.{1,#{width}})(\s+|\Z)/, "\\1\n")
+  end
+
   def url(string)
     "#{Tty.underline}#{string}#{Tty.no_underline}"
   end

docs/Manpage.md

@@ -663,37 +663,52 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
 
 ## DEVELOPER COMMANDS
 
-Usage: brew audit [options] [`formulae`]
+`audit` [`options`] [`formulae`]:
 
 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.
 
-        --strict                     Run additional style checks, including Rubocop style checks.
+
-        --online                     Run additional slower style checks that require a
+*  `--strict`                    :
-                                     network connection.
+Run additional style checks, including Rubocop style checks.
-        --new-formula                Run various additional style checks to determine if a new formula 
+
-                                     is eligible for Homebrew. This should be used when creating 
+*  `--online`                    :
-                                     new formula and implies --strict and --online.
+Run additional slower style checks that require a network connection.
-        --fix                        Fix style violations automatically using
+
-                                     RuboCop's auto-correct feature.
+*  `--new-formula`               :
-        --display-cop-names          Include the RuboCop cop name for each violation
+Run various additional style checks to determine if a new formula is eligible for Homebrew. This should be used when creating new formula and implies `--strict` and `--online`.
-                                     in the output.
+
-        --display-filename           Prefix everyline of output with name of the file or
+*  `--fix`                       :
-                                     formula being audited, to make output easy to grep.
+Fix style violations automatically using RuboCop's auto-correct feature.
-    -D, --audit-debug                Activates debugging and profiling
+
-        --only                       Passing --only=method will run only the methods named audit_method,
+*  `--display-cop-names`         :
-                                     `method` should be a comma-separated list.
+Include the RuboCop cop name for each violation in the output.
-        --except                     Passing --except=method will run only the methods named audit_method,
+
-                                     `method` should be a comma-separated list.
+*  `--display-filename`          :
-        --only-cops                  Passing --only-cops=cops will check for violations of only the listed
+Prefix everyline of output with name of the file or formula being audited, to make output easy to grep.
-                                     RuboCop cops. `cops` should be a comma-separated list of cop names.
+
-        --except-cops                Passing --except-cops=cops will skip checking the listed
+* `-D`,  `--audit-debug`               :
-                                     RuboCop cops violations. `cops` should be a comma-separated list of cop names.
+Activates debugging and profiling
-    -v, --verbose                    Verbose mode.
+
-    -d, --debug                      Display debug info.
+*  `--only`                      :
-    -h, --help                       Show this message
+Passing `--only`=`method` will run only themethods named audit_method, `method` should be a comma-separated list.
+
+*  `--except`                    :
+Passing `--except`=`method` will run only the methods named audit_method, `method` should be a comma-separated list.
+
+*  `--only-cops`                 :
+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.
 
   * `audit` [`--strict`] [`--fix`] [`--online`] [`--new-formula`] [`--display-cop-names`] [`--display-filename`] [`--only=``method`|`--except=``method`] [`--only-cops=``cops`|`--except-cops=``cops`] [`formulae`]:
     Check `formulae` for Homebrew coding style violations. This should be

manpages/brew.1

@@ -601,7 +601,7 @@ If the command\'s output is sent through a pipe and no shell is specified, the l
 .IP "" 0
 .
 .SH "DEVELOPER COMMANDS"
-Usage: brew audit [options] [\fIformulae\fR]
+\fBaudit\fR [\fIoptions\fR] [\fIformulae\fR]:
 .
 .P
 Check \fIformulae\fR for Homebrew coding style violations\. This should be run before submitting a new formula\.
@@ -609,38 +609,57 @@ Check \fIformulae\fR for Homebrew coding style violations\. This should be run b
 .P
 If no \fIformulae\fR are provided, all of them are checked\.
 .
-.IP "" 4
+.TP
+\fB\-\-strict\fR
+Run additional style checks, including Rubocop style checks\.
 .
-.nf
+.TP
-
+\fB\-\-online\fR
-    \-\-strict                     Run additional style checks, including Rubocop style checks\.
+Run additional slower style checks that require a network connection\.
-    \-\-online                     Run additional slower style checks that require a
-                                 network connection\.
-    \-\-new\-formula                Run various additional style checks to determine if a new formula
-                                 is eligible for Homebrew\. This should be used when creating
-                                 new formula and implies \-\-strict and \-\-online\.
-    \-\-fix                        Fix style violations automatically using
-                                 RuboCop\'s auto\-correct feature\.
-    \-\-display\-cop\-names          Include the RuboCop cop name for each violation
-                                 in the output\.
-    \-\-display\-filename           Prefix everyline of output with name of the file or
-                                 formula being audited, to make output easy to grep\.
-\-D, \-\-audit\-debug                Activates debugging and profiling
-    \-\-only                       Passing \-\-only=method will run only the methods named audit_method,
-                                 `method` should be a comma\-separated list\.
-    \-\-except                     Passing \-\-except=method will run only the methods named audit_method,
-                                 `method` should be a comma\-separated list\.
-    \-\-only\-cops                  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                    Verbose mode\.
-\-d, \-\-debug                      Display debug info\.
-\-h, \-\-help                       Show this message
 .
-.fi
+.TP
+\fB\-\-new\-formula\fR
+Run various additional style checks to determine if a new formula is eligible for Homebrew\. This should be used when creating new formula and implies \fB\-\-strict\fR and \fB\-\-online\fR\.
 .
-.IP "" 0
+.TP
+\fB\-\-fix\fR
+Fix style violations automatically using RuboCop\'s auto\-correct feature\.
+.
+.TP
+\fB\-\-display\-cop\-names\fR
+Include the RuboCop cop name for each violation in the output\.
+.
+.TP
+\fB\-\-display\-filename\fR
+Prefix everyline of output with name of the file or formula being audited, to make output easy to grep\.
+.
+.TP
+\fB\-D\fR, \fB\-\-audit\-debug\fR
+Activates debugging and profiling
+.
+.TP
+\fB\-\-only\fR
+Passing \fB\-\-only\fR=\fImethod\fR will run only themethods named audit_method, \fBmethod\fR should be a comma\-separated list\.
+.
+.TP
+\fB\-\-except\fR
+Passing \fB\-\-except\fR=\fImethod\fR will run only the methods named audit_method, \fBmethod\fR should be a comma\-separated list\.
+.
+.TP
+\fB\-\-only\-cops\fR
+Passing \fB\-\-only\-cops\fR=\fIcops\fR will check for violations of only the listed RuboCop cops\.\fBcops\fR should be a comma\-separated list of cop names\.
+.
+.TP
+\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\.
 .
 .TP
 \fBaudit\fR [\fB\-\-strict\fR] [\fB\-\-fix\fR] [\fB\-\-online\fR] [\fB\-\-new\-formula\fR] [\fB\-\-display\-cop\-names\fR] [\fB\-\-display\-filename\fR] [\fB\-\-only=\fR\fImethod\fR|\fB\-\-except=\fR\fImethod\fR] [\fB\-\-only\-cops=\fR\fIcops\fR|\fB\-\-except\-cops=\fR\fIcops\fR] [\fIformulae\fR]
@@ -945,6 +964,7 @@ If \fB\-\-to\-tag\fR is passed, set \fBHOMEBREW_UPDATE_TO_TAG\fR to test updatin
 .
 .IP
 If \fB\-\-keep\-tmp\fR is passed, retain the temporary directory containing the new repository clone\.
+
 .
 .SH "OFFICIAL EXTERNAL COMMANDS"
 .