From 7d849449b5b01582f376a349879be50de00bbb7f Mon Sep 17 00:00:00 2001
From: nick evans <nick@rubinick.dev>
Date: Fri, 15 Nov 2024 09:16:54 -0500
Subject: [PATCH 1/4] Use the original `label` description list style

As a default for all description lists, the original "label" style is
more readable.

This is slightly different from the original `label` dl though:
* slightly increased left margin for `dd` (to 1em)
* removed right margin on `dd`
* removed `dt` bottom margin and `dd` top margin, to reduce the gap
  between the term and its description (to only the standard line-height
  gap).
---
 lib/rdoc/generator/template/darkfish/css/rdoc.css | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/lib/rdoc/generator/template/darkfish/css/rdoc.css b/lib/rdoc/generator/template/darkfish/css/rdoc.css
index 82c1e4baf6..8d495e3767 100644
--- a/lib/rdoc/generator/template/darkfish/css/rdoc.css
+++ b/lib/rdoc/generator/template/darkfish/css/rdoc.css
@@ -469,14 +469,15 @@ main dl {
 }
 
 main dt {
-  margin-bottom: 0.5em;
-  margin-right: 1em;
-  float: left;
   font-weight: bold;
 }
 
 main dd {
-  margin: 0 1em 1em 0.5em;
+  margin: 0 0 1em 1em;
+}
+
+main dd p:first-child {
+  margin-top: 0;
 }
 
 /* Headers within Main */

From 8232b7f2b90d8b1c0c97641a00b46b5776a985d9 Mon Sep 17 00:00:00 2001
From: nick evans <nick@rubinick.dev>
Date: Fri, 15 Nov 2024 12:53:04 -0500
Subject: [PATCH 2/4] Add closing tags for description list terms

Without the closing tags, the dt elements contain whitespace after the
text.  This normally isn't a big deal, but does mess some things up,
e.g: using `::after` with `content: ", "` in stylesheets.
---
 lib/rdoc/markup/to_html.rb            |  2 +-
 test/rdoc/test_rdoc_markup_to_html.rb | 12 ++++++------
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/lib/rdoc/markup/to_html.rb b/lib/rdoc/markup/to_html.rb
index 91cadf9d16..dd37bf9eb3 100644
--- a/lib/rdoc/markup/to_html.rb
+++ b/lib/rdoc/markup/to_html.rb
@@ -407,7 +407,7 @@ def list_item_start(list_item, list_type)
       "<li>"
     when :LABEL, :NOTE then
       Array(list_item.label).map do |label|
-        "<dt>#{to_html label}\n"
+        "<dt>#{to_html label}</dt>\n"
       end.join << "<dd>"
     else
       raise RDoc::Error, "Invalid list type: #{list_type.inspect}"
diff --git a/test/rdoc/test_rdoc_markup_to_html.rb b/test/rdoc/test_rdoc_markup_to_html.rb
index e3affa533c..225598a651 100644
--- a/test/rdoc/test_rdoc_markup_to_html.rb
+++ b/test/rdoc/test_rdoc_markup_to_html.rb
@@ -146,7 +146,7 @@ def accept_list_item_start_bullet
   end
 
   def accept_list_item_start_label
-    assert_equal "<dl class=\"rdoc-list label-list\"><dt>cat\n<dd>", @to.res.join
+    assert_equal "<dl class=\"rdoc-list label-list\"><dt>cat</dt>\n<dd>", @to.res.join
   end
 
   def accept_list_item_start_lalpha
@@ -154,13 +154,13 @@ def accept_list_item_start_lalpha
   end
 
   def accept_list_item_start_note
-    assert_equal "<dl class=\"rdoc-list note-list\"><dt>cat\n<dd>",
+    assert_equal "<dl class=\"rdoc-list note-list\"><dt>cat</dt>\n<dd>",
                  @to.res.join
   end
 
   def accept_list_item_start_note_2
     expected = <<-EXPECTED
-<dl class="rdoc-list note-list"><dt><code>teletype</code>
+<dl class="rdoc-list note-list"><dt><code>teletype</code></dt>
 <dd>
 <p>teletype description</p>
 </dd></dl>
@@ -171,7 +171,7 @@ def accept_list_item_start_note_2
 
   def accept_list_item_start_note_multi_description
     expected = <<-EXPECTED
-<dl class="rdoc-list note-list"><dt>label
+<dl class="rdoc-list note-list"><dt>label</dt>
 <dd>
 <p>description one</p>
 </dd><dd>
@@ -184,8 +184,8 @@ def accept_list_item_start_note_multi_description
 
   def accept_list_item_start_note_multi_label
     expected = <<-EXPECTED
-<dl class="rdoc-list note-list"><dt>one
-<dt>two
+<dl class="rdoc-list note-list"><dt>one</dt>
+<dt>two</dt>
 <dd>
 <p>two headers</p>
 </dd></dl>

From 24797bb86761d79df22c57d8d5ea872ed17ec60d Mon Sep 17 00:00:00 2001
From: nick evans <nick@rubinick.dev>
Date: Fri, 15 Nov 2024 17:27:59 -0500
Subject: [PATCH 3/4] Restore float:left style for note lists

Unlike the original note list styles, this version sets the line-height
for all `dt` elements to be the same as the `p` elements contained
inside the `dd`, so that the second line has the same indentation as all
subsequent lines.
---
 lib/rdoc/generator/template/darkfish/css/rdoc.css | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/lib/rdoc/generator/template/darkfish/css/rdoc.css b/lib/rdoc/generator/template/darkfish/css/rdoc.css
index 8d495e3767..c97129a90b 100644
--- a/lib/rdoc/generator/template/darkfish/css/rdoc.css
+++ b/lib/rdoc/generator/template/darkfish/css/rdoc.css
@@ -469,9 +469,15 @@ main dl {
 }
 
 main dt {
+  line-height: 1.5; /* matches `main p` */
   font-weight: bold;
 }
 
+main dl.note-list dt {
+  margin-right: 1em;
+  float: left;
+}
+
 main dd {
   margin: 0 0 1em 1em;
 }

From 4e56713a7634e19ddefd0d70c7ea8b2d4a659dc4 Mon Sep 17 00:00:00 2001
From: nick evans <nick@rubinick.dev>
Date: Fri, 15 Nov 2024 17:30:17 -0500
Subject: [PATCH 4/4] Add commas between note list terms

---
 lib/rdoc/generator/template/darkfish/css/rdoc.css | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/lib/rdoc/generator/template/darkfish/css/rdoc.css b/lib/rdoc/generator/template/darkfish/css/rdoc.css
index c97129a90b..69b1d08577 100644
--- a/lib/rdoc/generator/template/darkfish/css/rdoc.css
+++ b/lib/rdoc/generator/template/darkfish/css/rdoc.css
@@ -478,6 +478,15 @@ main dl.note-list dt {
   float: left;
 }
 
+main dl.note-list dt:has(+ dt) {
+  margin-right: 0.25em;
+}
+
+main dl.note-list dt:has(+ dt)::after {
+  content: ', ';
+  font-weight: normal;
+}
+
 main dd {
   margin: 0 0 1em 1em;
 }