Rename and fix Formatter:wrap to Formatter.format_help_text

Library/Homebrew/cli/parser.rb

@@ -9,7 +9,7 @@ require "set"
 require "utils/tty"
 
 COMMAND_DESC_WIDTH = 80
-OPTION_DESC_WIDTH = 43
+OPTION_DESC_WIDTH = 45
 HIDDEN_DESC_PLACEHOLDER = "@@HIDDEN@@"
 
 module Homebrew
@@ -351,7 +351,7 @@ module Homebrew
       end
 
       def generate_help_text
-        Formatter.wrap(@parser.to_s, COMMAND_DESC_WIDTH)
+        Formatter.format_help_text(@parser.to_s, width: COMMAND_DESC_WIDTH)
                  .gsub(/\n.*?@@HIDDEN@@.*?(?=\n)/, "")
                  .sub(/^/, "#{Tty.bold}Usage: brew#{Tty.reset} ")
                  .gsub(/`(.*?)`/m, "#{Tty.bold}\\1#{Tty.reset}")
@@ -503,7 +503,7 @@ module Homebrew
       end
 
       def wrap_option_desc(desc)
-        Formatter.wrap(desc, OPTION_DESC_WIDTH).split("\n")
+        Formatter.format_help_text(desc, width: OPTION_DESC_WIDTH).split("\n")
       end
 
       def set_constraints(name, depends_on:, required_for:)

Library/Homebrew/help.rb

@@ -118,7 +118,7 @@ module Homebrew
       help_lines = command_help_lines(path)
       return if help_lines.blank?
 
-      Formatter.wrap(help_lines.join, COMMAND_DESC_WIDTH)
+      Formatter.format_help_text(help_lines.join, width: COMMAND_DESC_WIDTH)
                .sub("@hide_from_man_page ", "")
                .sub(/^\* /, "#{Tty.bold}Usage: brew#{Tty.reset} ")
                .gsub(/`(.*?)`/m, "#{Tty.bold}\\1#{Tty.reset}")

Library/Homebrew/test/formatter_spec.rb

@@ -56,4 +56,59 @@ describe Formatter do
       it { is_expected.to eq("\n") }
     end
   end
+
+  describe "::format_help_text" do
+    it "indents subcommand descriptions" do
+      # The following example help text was carefully crafted to test all five regular expressions in the method.
+      # Also, the text is designed in such a way such that options (e.g. `--foo`) would be wrapped to the
+      # beginning of new lines if normal wrapping was used. This is to test that the method works as expected
+      # and doesn't allow options to start new lines. Be careful when changing the text so these checks aren't lost.
+      text = <<~HELP
+        Usage: brew command [<options>] <formula>...
+
+        This is a test command.
+        Single line breaks are removed, but the entire line is still wrapped at the correct point.
+
+        Paragraphs are preserved but
+        are also wrapped at the right point. Here's some more filler text to get this line to be long enough.
+        Options, for example: --foo, are never placed at the start of a line.
+
+        `brew command` [`state`]:
+        Display the current state of the command.
+
+        `brew command` (`on`|`off`):
+        Turn the command on or off respectively.
+
+          -f, --foo                        This line is wrapped with a hanging indent. --test. The --test option isn't at the start of a line.
+          -b, --bar                        The following option is not left on its own: --baz
+          -h, --help                       Show this message.
+      HELP
+
+      expected = <<~HELP
+        Usage: brew command [<options>] <formula>...
+
+        This is a test command. Single line breaks are removed, but the entire line is
+        still wrapped at the correct point.
+
+        Paragraphs are preserved but are also wrapped at the right point. Here's some
+        more filler text to get this line to be long enough. Options, for
+        example: --foo, are never placed at the start of a line.
+
+        `brew command` [`state`]:
+            Display the current state of the command.
+
+        `brew command` (`on`|`off`):
+            Turn the command on or off respectively.
+
+          -f, --foo                        This line is wrapped with a hanging
+                                           indent. --test. The --test option isn't at
+                                           the start of a line.
+          -b, --bar                        The following option is not left on its
+                                           own: --baz
+          -h, --help                       Show this message.
+      HELP
+
+      expect(described_class.format_help_text(text, width: 80)).to eq expected
+    end
+  end
 end

Library/Homebrew/utils/formatter.rb

@@ -45,15 +45,19 @@ module Formatter
   #    with a hanging indent, without breaking any words that overflow
   # 4. wrap any remaining description lines that need wrapping with the same indent
   # 5. wrap all lines to the given width.
+  #
+  # Note that an option (e.g. `--foo`) may not be at the beginning of a line,
+  # so we always wrap one word before an option.
+  # @see https://github.com/Homebrew/brew/pull/12672
   # @see https://macromates.com/blog/2006/wrapping-text-with-regular-expressions/
-  def wrap(s, width = 172)
+  def format_help_text(s, width: 172)
     desc = OPTION_DESC_WIDTH
     indent = width - desc
     s.gsub(/(?<=\S) *\n(?=\S)/, " ")
      .gsub(/([`>)\]]:) /, "\\1\n    ")
-     .gsub(/^( +-.+  +(?=\S.{#{desc}}))(.{1,#{desc}})( +|$)\n?/, "\\1\\2\n#{" " * indent}")
-     .gsub(/^( {#{indent}}(?=\S.{#{desc}}))(.{1,#{desc}})( +|$)\n?/, "\\1\\2\n#{" " * indent}")
-     .gsub(/(.{1,#{width}})( +|$)\n?/, "\\1\n")
+     .gsub(/^( +-.+  +(?=\S.{#{desc}}))(.{1,#{desc}})( +|$)(?!-)\n?/, "\\1\\2\n#{" " * indent}")
+     .gsub(/^( {#{indent}}(?=\S.{#{desc}}))(.{1,#{desc}})( +|$)(?!-)\n?/, "\\1\\2\n#{" " * indent}")
+     .gsub(/(.{1,#{width}})( +|$)(?!-)\n?/, "\\1\n")
   end
 
   def url(string)

manpages/brew.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW" "1" "December 2021" "Homebrew" "brew"
+.TH "BREW" "1" "January 2022" "Homebrew" "brew"
 .
 .SH "NAME"
 \fBbrew\fR \- The Missing Package Manager for macOS (or Linux)