Replace ronn with Kramdown's converter

[Bo98]

ronn is old and hasn't been updated in 14 years. The same applies to some of its dependencies and some of those dependencies are now breaking and will never be fixed as they have been made EOL.

ronn-ng does exist, and does a good job at carrying on where ronn left off. It however has a dependency on Nokogiri which we went through great measures to get rid of before and Nokogiri does have problems when paired with our Bundler standalone file which only supports one platform/arch at a time. I feel like we can do better than ronn flow anyway, because we had various hacks on top of it already.

The flow has always been a bit weird:

• Manpages: ronn markdown -> HTML -> roff
• Docs: ronn markdown -> HTML -> plain markdown -> HTML again

Our docs website uses Kramdown and it turns out Kramdown itself has a manpage converter. So we can instead do:

• Manpages: Kramdown -> roff
• Docs: Kramdown -> Kramdown -> HTML (double Kramdown is a technicality from how we don't generate HTML in the generate-man-completions itself)

It is also Ruby code rather than something we shell out to which means we have more control over it. Previously we had a ton of horrible looking gsub hacks:

brew/Library/Homebrew/manpages.rb

Lines 98 to 106 in cd1f040

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

Customisability is also useful in order to maintain compatibility with what we have. We customise Kramdown by subclassing:

• A parser that is just a Kramdown parser + support for ronn's variable syntax. This is necessary for backwards compatibility with existing syntax used in command documentation. And it looks a ton cleaner that way anyway over any alternatives.
• Two output converters (Kramdown and roff) that largely just defers to upstream, but has minor tweaks to support the variable syntax we added and make the output more like what we had before.

Because we're using Kramdown, we can also now use features like definition lists which make the output between the manpage and the docs site much more consistent with each other. Previously we used bullet point lists and relied on ronn doing weirdness where it sometimes interpreted a bullet point list like a definition list without it actually being one (clever, though we want to fix the issue at source anyway).

The end result should be that:

• The manpage looks almost identical to how it did before, except it has better support for hyperlinks and is slightly more consistent in how it uses definition lists.
• The doc webpage is now signficantly more aligned with how the manpage looks, i.e less bullet points and more indents.

Fixes #16861

[Bo98]

Another benefit: our docs linter seems to now actually work on the Manpage.md whereas before it seemed to not pick up things.

[EricFromCanada]

This is a huge improvement for readability. Looks great.

Is there any way for the URLs at the very end of the man page to be displayed in the roff output as they are in the HTML?

[Bo98]

Is there any way for the URLs at the very end of the man page to be displayed in the roff output as they are in the HTML?

By this do you mean the formatting of hyperlinks themselves? Right now this is using the groff syntax of:

.UR https://github\.com/Homebrew/brew/issues
.UE

(UR = URI start, UE = URI end)

which macOS man viewer automatically renders as being surrounded by <>.

I think it displays in bold instead in mdoc mode (I don't know why it's different), though that requires various other syntax changes which Kramdown doesn't have a built-in converter for, though we could have a custom one if desired (though a lot more code).

[MikeMcQuaid]

Thanks again @Bo98!