From eb16624c5fab35a6ec6c5655ba6cf83ca3785d78 Mon Sep 17 00:00:00 2001
From: EricFromCanada <enk3@outlook.com>
Date: Wed, 11 Nov 2020 16:12:38 -0500
Subject: [PATCH] manpage: reformat lists of subcommands & env vars

Modify parser.rb to add a colon between each term and the line break, which `ronn` converts into a definition list.
The <br> that follows ensures each term description is on a new line in the manpage output, and also replaces the
double trailing space for generating the hard return that follows each term in the HTML output.
Also modify man.rb to print environment variables with list markup matching the cask commands, and then drop
trailing colons from both lists of terms (cask commands, env vars) and non-list terms (analytics, bundle, services;
a <br> is added here because it would prevent the term description from being indented in the manpage output).
https://docs.brew.sh/Manpage#cask-command-options-cask
---
 Library/Homebrew/cask/cmd.rb    | 1 -
 Library/Homebrew/cli/parser.rb  | 2 +-
 Library/Homebrew/dev-cmd/man.rb | 6 ++++--
 3 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/Library/Homebrew/cask/cmd.rb b/Library/Homebrew/cask/cmd.rb
index c5dc653c5f..cee4589519 100644
--- a/Library/Homebrew/cask/cmd.rb
+++ b/Library/Homebrew/cask/cmd.rb
@@ -78,7 +78,6 @@ module Cask
 
         Commands:
         #{command_lines.join}
-
         See also: `man brew`
       EOS
     end
diff --git a/Library/Homebrew/cli/parser.rb b/Library/Homebrew/cli/parser.rb
index a758d4ece9..433bf8fdbf 100644
--- a/Library/Homebrew/cli/parser.rb
+++ b/Library/Homebrew/cli/parser.rb
@@ -176,7 +176,7 @@ module Homebrew
 
       def usage_banner_text
         @parser.banner
-               .gsub(/^  - (`[^`]+`)\s+/, "\n- \\1  \n  ") # Format `cask` subcommands as MarkDown list.
+               .gsub(/^  - (`[^`]+`)\s+/, "\n- \\1:\n  <br>") # Format `cask` subcommands as Markdown list.
       end
 
       def comma_array(name, description: nil)
diff --git a/Library/Homebrew/dev-cmd/man.rb b/Library/Homebrew/dev-cmd/man.rb
index 6a3e27c372..24fe0e0ff7 100644
--- a/Library/Homebrew/dev-cmd/man.rb
+++ b/Library/Homebrew/dev-cmd/man.rb
@@ -135,6 +135,8 @@ module Homebrew
       when "--markdown"
         ronn_output = 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 = ronn_output.gsub(%r{<code>(.*?)</code>}, "\\fB\\1\\fR")
                                  .gsub(%r{<var>(.*?)</var>}, "\\fI\\1\\fR")
@@ -234,10 +236,10 @@ module Homebrew
   sig { returns(String) }
   def env_vars_manpage
     lines = Homebrew::EnvConfig::ENVS.flat_map do |env, hash|
-      entry = "  * `#{env}`:\n    #{hash[:description]}\n"
+      entry = "- `#{env}`:\n  <br>#{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