Merge pull request #16868 from Homebrew/no-more-ronn

Replace ronn with Kramdown's converter

.gitignore

@@ -82,16 +82,15 @@
 **/vendor/bundle/ruby/*/gems/erubi-*/
 **/vendor/bundle/ruby/*/gems/hana-*/
 **/vendor/bundle/ruby/*/gems/highline-*/
-**/vendor/bundle/ruby/*/gems/hpricot-*/
 **/vendor/bundle/ruby/*/gems/jaro_winkler-*/
 **/vendor/bundle/ruby/*/gems/json-*/
 **/vendor/bundle/ruby/*/gems/json_schemer-*/
+**/vendor/bundle/ruby/*/gems/kramdown-*/
 **/vendor/bundle/ruby/*/gems/language_server-protocol-*/
 **/vendor/bundle/ruby/*/gems/method_source-*/
 **/vendor/bundle/ruby/*/gems/mini_portile2-*/
 **/vendor/bundle/ruby/*/gems/minitest-*/
 **/vendor/bundle/ruby/*/gems/msgpack-*/
-**/vendor/bundle/ruby/*/gems/mustache-*/
 **/vendor/bundle/ruby/*/gems/netrc-*/
 **/vendor/bundle/ruby/*/gems/ntlm-http-*/
 **/vendor/bundle/ruby/*/gems/parallel-*/
@@ -106,10 +105,8 @@
 **/vendor/bundle/ruby/*/gems/racc-*/
 **/vendor/bundle/ruby/*/gems/rainbow-*/
 **/vendor/bundle/ruby/*/gems/rbi-*/
-**/vendor/bundle/ruby/*/gems/rdiscount-*/
 **/vendor/bundle/ruby/*/gems/regexp_parser-*/
 **/vendor/bundle/ruby/*/gems/rexml-*/
-**/vendor/bundle/ruby/*/gems/ronn-*/
 **/vendor/bundle/ruby/*/gems/rspec-*/
 **/vendor/bundle/ruby/*/gems/rspec-core-*/
 **/vendor/bundle/ruby/*/gems/rspec-expectations-*/

Library/Homebrew/Gemfile

@@ -28,7 +28,7 @@ group :livecheck, optional: true do
   gem "ruby-progressbar", require: false
 end
 group :man, optional: true do
-  gem "ronn", require: false
+  gem "kramdown", require: false
 end
 group :pr_upload, optional: true do
   gem "json_schemer", require: false

Library/Homebrew/Gemfile.lock

@@ -18,17 +18,17 @@ GEM
     erubi (1.12.0)
     hana (1.3.7)
     highline (2.0.3)
-    hpricot (0.8.6)
     json (2.7.1)
     json_schemer (2.1.1)
       hana (~> 1.3)
       regexp_parser (~> 2.0)
       simpleidn (~> 0.2)
+    kramdown (2.4.0)
+      rexml
     language_server-protocol (3.17.0.3)
     method_source (1.0.0)
     minitest (5.22.2)
     msgpack (1.7.2)
-    mustache (1.1.1)
     netrc (0.11.0)
     parallel (1.24.0)
     parallel_tests (4.5.2)
@@ -55,13 +55,8 @@ GEM
     rbi (0.1.9)
       prism (>= 0.18.0, < 0.25)
       sorbet-runtime (>= 0.5.9204)
-    rdiscount (2.2.7.3)
     regexp_parser (2.9.0)
     rexml (3.2.6)
-    ronn (0.7.3)
-      hpricot (>= 0.8.2)
-      mustache (>= 0.7.0)
-      rdiscount (>= 1.5.8)
     rspec (3.13.0)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -177,6 +172,7 @@ DEPENDENCIES
   bootsnap
   byebug
   json_schemer
+  kramdown
   method_source
   minitest
   parallel_tests
@@ -185,7 +181,6 @@ DEPENDENCIES
   plist
   pry
   rexml
-  ronn
   rspec
   rspec-github
   rspec-its

Library/Homebrew/dev-cmd/pr-publish.rb

@@ -23,7 +23,7 @@ def pr_publish_args
              description: "Branch to use the workflow from (default: `master`)."
       flag   "--message=",
              depends_on:  "--autosquash",
-             description: "Message to include when autosquashing revision bumps, deletions, and rebuilds."
+             description: "Message to include when autosquashing revision bumps, deletions and rebuilds."
       flag   "--tap=",
              description: "Target tap repository (default: `homebrew/core`)."
       flag   "--workflow=",

Library/Homebrew/dev-cmd/pr-pull.rb

@@ -51,7 +51,7 @@ def self.pr_pull_args
              description: "Specify a committer name and email in `git`'s standard author format."
       flag   "--message=",
              depends_on:  "--autosquash",
-             description: "Message to include when autosquashing revision bumps, deletions, and rebuilds."
+             description: "Message to include when autosquashing revision bumps, deletions and rebuilds."
       flag   "--artifact=",
              description: "Download artifacts with the specified name (default: `bottles`)."
       flag   "--tap=",

Library/Homebrew/manpages.rb

@@ -3,6 +3,10 @@
 
 require "cli/parser"
 require "erb"
+require "kramdown"
+require "manpages/parser/ronn"
+require "manpages/converter/kramdown"
+require "manpages/converter/roff"
 
 SOURCE_PATH = (HOMEBREW_LIBRARY_PATH/"manpages").freeze
 TARGET_MAN_PATH = (HOMEBREW_REPOSITORY/"manpages").freeze
@@ -31,8 +35,16 @@ def self.regenerate_man_pages(quiet:)
       Homebrew.install_bundler_gems!(groups: ["man"])
 
       markup = build_man_page(quiet:)
-      convert_man_page(markup, TARGET_DOC_PATH/"Manpage.md")
-      convert_man_page(markup, TARGET_MAN_PATH/"brew.1")
+      root, warnings = Parser::Ronn.parse(markup)
+      $stderr.puts(warnings)
+
+      roff, warnings = Converter::Kramdown.convert(root)
+      $stderr.puts(warnings)
+      File.write(TARGET_DOC_PATH/"Manpage.md", roff)
+
+      roff, warnings = Converter::Roff.convert(root)
+      $stderr.puts(warnings)
+      File.write(TARGET_MAN_PATH/"brew.1", roff)
     end
 
     def self.build_man_page(quiet:)
@@ -65,59 +77,6 @@ def self.sort_key_for_path(path)
       path.basename.to_s.sub(/\.(rb|sh)$/, "").sub(/^--/, "~~")
     end
 
-    def self.convert_man_page(markup, target)
-      manual = target.basename(".1")
-      organisation = "Homebrew"
-
-      # Set the manpage date to the existing one if we're updating.
-      # This avoids the only change being e.g. a new date.
-      date = if target.extname == ".1" && target.exist?
-        /"(\d{1,2})" "([A-Z][a-z]+) (\d{4})" "#{organisation}" "#{manual}"/ =~ target.read
-        Date.parse("#{Regexp.last_match(1)} #{Regexp.last_match(2)} #{Regexp.last_match(3)}")
-      else
-        Date.today
-      end
-      date = date.strftime("%Y-%m-%d")
-
-      shared_args = %W[
-        --pipe
-        --organization=#{organisation}
-        --manual=#{target.basename(".1")}
-        --date=#{date}
-      ]
-
-      format_flag, format_desc = target_path_to_format(target)
-
-      puts "Writing #{format_desc} to #{target}"
-      Utils.popen(["ronn", format_flag] + shared_args, "rb+") do |ronn|
-        ronn.write markup
-        ronn.close_write
-        ronn_output = ronn.read
-        odie "Got no output from ronn!" if ronn_output.blank?
-        ronn_output = case format_flag
-        when "--markdown"
-          ronn_output.gsub(%r{<var>(.*?)</var>}, "*`\\1`*")
-                     .gsub(/\n\n\n+/, "\n\n")
-                     .gsub(/^(- `[^`]+`):/, "\\1") # drop trailing colons from definition lists
-                     .gsub(/(?<=\n\n)([\[`].+):\n/, "\\1\n<br>") # replace colons with <br> on subcommands
-        when "--roff"
-          ronn_output.gsub(%r{<code>(.*?)</code>}, "\\fB\\1\\fR")
-                     .gsub(%r{<var>(.*?)</var>}, "\\fI\\1\\fR")
-                     .gsub(/(^\[?\\fB.+): /, "\\1\n    ")
-        end
-        target.atomic_write ronn_output
-      end
-    end
-
-    def self.target_path_to_format(target)
-      case target.basename
-      when /\.md$/    then ["--markdown", "markdown"]
-      when /\.\d$/    then ["--roff", "man page"]
-      else
-        odie "Failed to infer output format from '#{target.basename}'."
-      end
-    end
-
     def self.generate_cmd_manpages(cmd_paths)
       man_page_lines = []
 
@@ -129,8 +88,10 @@ def self.generate_cmd_manpages(cmd_paths)
 
           cmd_parser_manpage_lines(cmd_parser).join
         else
-          cmd_comment_manpage_lines(cmd_path)
+          cmd_comment_manpage_lines(cmd_path)&.join("\n")
         end
+        # Convert subcommands to definition lists
+        cmd_man_page_lines&.gsub!(/(?<=\n\n)([\\?\[`].+):\n/, "\\1\n\n: ")
 
         man_page_lines << cmd_man_page_lines
       end
@@ -173,8 +134,10 @@ def self.cmd_comment_manpage_lines(cmd_path)
         next if line.match?(/--(debug|help|quiet|verbose) /)
 
         # Format one option or a comma-separated pair of short and long options.
-        lines << line.gsub(/^ +(-+[a-z-]+), (-+[a-z-]+) +/, "* `\\1`, `\\2`:\n  ")
-                     .gsub(/^ +(-+[a-z-]+) +/, "* `\\1`:\n  ")
+        line.gsub!(/^ +(-+[a-z-]+), (-+[a-z-]+) +(.*)$/, "`\\1`, `\\2`\n\n: \\3\n")
+        line.gsub!(/^ +(-+[a-z-]+) +(.*)$/, "`\\1`\n\n: \\2\n")
+
+        lines << line
       end
       lines.last << "\n"
       lines
@@ -202,10 +165,10 @@ def self.global_options_manpage
     sig { returns(String) }
     def self.env_vars_manpage
       lines = Homebrew::EnvConfig::ENVS.flat_map do |env, hash|
-        entry = "- `#{env}`:\n  <br>#{hash[:description]}\n"
+        entry = "`#{env}`\n\n: #{hash[:description]}\n"
         default = hash[:default_text]
         default ||= "`#{hash[:default]}`." if hash[:default]
-        entry += "\n\n  *Default:* #{default}\n" if default
+        entry += "\n\n    *Default:* #{default}\n" if default
 
         entry
       end
@@ -219,13 +182,16 @@ def self.format_opt(opt)
     def self.generate_option_doc(short, long, desc)
       comma = (short && long) ? ", " : ""
       <<~EOS
-        * #{format_opt(short)}#{comma}#{format_opt(long)}:
-          #{desc}
+        #{format_opt(short)}#{comma}#{format_opt(long)}
+
+        : #{desc}
+
       EOS
     end
 
     def self.format_usage_banner(usage_banner)
       usage_banner&.sub(/^(#: *\* )?/, "### ")
+                  &.gsub(/(?<!`)\[([^\[\]]*)\](?!`)/, "\\[\\1\\]") # escape [] character (except those in code spans)
     end
   end
 end

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

@@ -20,7 +20,7 @@ brew(1) -- The Missing Package Manager for macOS (or Linux)
 ## SYNOPSIS
 
 `brew` `--version`<br>
-`brew` <command> [`--verbose`|`-v`] [<options>] [<formula>] ...
+`brew` <command> \[`--verbose`\|`-v`\] \[<options>\] \[<formula>\] ...
 
 ## DESCRIPTION
 
@@ -30,29 +30,53 @@ Linux distribution without requiring `sudo`.
 
 ## TERMINOLOGY
 
-**formula**: Homebrew package definition that builds from upstream sources
+**formula**
 
-**cask**: Homebrew package definition that installs macOS native applications
+: Homebrew package definition that builds from upstream sources
 
-**prefix**: path in which Homebrew is installed, e.g. `/usr/local`
+**cask**
 
-**keg**: installation destination directory of a given **formula** version, e.g. `/usr/local/Cellar/foo/0.1`
+: Homebrew package definition that installs macOS native applications
 
-**rack**: directory containing one or more versioned **kegs**, e.g. `/usr/local/Cellar/foo`
+**prefix**
 
-**keg-only**: a **formula** is *keg-only* if it is not symlinked into Homebrew's prefix
+: path in which Homebrew is installed, e.g. `/usr/local`
 
-**opt prefix**: a symlink to the active version of a **keg**, e.g. `/usr/local/opt/foo`
+**keg**
 
-**Cellar**: directory containing one or more named **racks**, e.g. `/usr/local/Cellar`
+: installation destination directory of a given **formula** version, e.g. `/usr/local/Cellar/foo/0.1`
 
-**Caskroom**: directory containing one or more named **casks**, e.g. `/usr/local/Caskroom`
+**rack**
 
-**external command**: `brew` subcommand defined outside of the Homebrew/brew GitHub repository
+: directory containing one or more versioned **kegs**, e.g. `/usr/local/Cellar/foo`
 
-**tap**: directory (and usually Git repository) of **formulae**, **casks** and/or **external commands**
+**keg-only**
 
-**bottle**: pre-built **keg** poured into a **rack** of the **Cellar** instead of building from upstream sources
+: a **formula** is *keg-only* if it is not symlinked into Homebrew's prefix
+
+**opt prefix**
+
+: a symlink to the active version of a **keg**, e.g. `/usr/local/opt/foo`
+
+**Cellar**
+
+: directory containing one or more named **racks**, e.g. `/usr/local/Cellar`
+
+**Caskroom**
+
+: directory containing one or more named **casks**, e.g. `/usr/local/Caskroom`
+
+**external command**
+
+: `brew` subcommand defined outside of the Homebrew/brew GitHub repository
+
+**tap**
+
+: directory (and usually Git repository) of **formulae**, **casks** and/or **external commands**
+
+**bottle**
+
+: pre-built **keg** poured into a **rack** of the **Cellar** instead of building from upstream sources
 
 ## ESSENTIAL COMMANDS
 
@@ -79,11 +103,11 @@ Uninstall <formula>.
 
 List all installed formulae.
 
-### `search` [<text>|`/`<text>`/`]
+### `search` \[<text>\|`/`<text>`/`\]
 
 Perform a substring search of cask tokens and formula names for <text>. If
-<text> is flanked by slashes, it is interpreted as a regular expression.
-The search for <text> is extended online to `homebrew/core` and `homebrew/cask`.
+<text> is flanked by slashes, it is interpreted as a regular expression. The
+search for <text> is extended online to `homebrew/core` and `homebrew/cask`.
 If no search term is provided, all locally available formulae are listed.
 
 ## COMMANDS
@@ -110,8 +134,8 @@ If no search term is provided, all locally available formulae are listed.
 
 Homebrew, like `git`(1), supports external commands. These are executable
 scripts that reside somewhere in the `PATH`, named `brew-`<cmdname> or
-`brew-`<cmdname>`.rb`, which can be invoked like `brew` <cmdname>. This allows
-you to create your own commands without modifying Homebrew's internals.
+`brew-`<cmdname>`.rb`, which can be invoked like `brew` <cmdname>. This
+allows you to create your own commands without modifying Homebrew's internals.
 
 Instructions for creating your own commands can be found in the docs:
 <https://docs.brew.sh/External-Commands>
@@ -206,11 +230,14 @@ Homebrew API: <https://rubydoc.brew.sh>
 
 See our issues on GitHub:
 
-  * **Homebrew/brew**:
-    <br><https://github.com/Homebrew/brew/issues>
+**Homebrew/brew**
+
+: <https://github.com/Homebrew/brew/issues>
+
+**Homebrew/homebrew-core**
+
+: <https://github.com/Homebrew/homebrew-core/issues>
 
-  * **Homebrew/homebrew-core**:
-    <br><https://github.com/Homebrew/homebrew-core/issues>
+**Homebrew/homebrew-cask**
 
-  * **Homebrew/homebrew-cask**:
-    <br><https://github.com/Homebrew/homebrew-cask/issues>
+: <https://github.com/Homebrew/homebrew-cask/issues>