resolves asciidoctor#1722 add callout-list category to theme for cont…

…rolling font properties and item spacing of callout lists (PR asciidoctor#2047)

CHANGELOG.adoc

@@ -80,6 +80,7 @@ Enhancements::
 * add support for character references that contain both uppercase and lowercase hexadecimal characters (#1990) (*@etiwnad*)
 * log error and skip table instead of raising error if cell content cannot fit into column width of table (#2009)
 * extract `arrange_section` method to compute whether section title should be advanced to next page (#2023)
+* introduce `callout-list` category in theme to control font properties and item spacing of callout lists (#1722)
 
 Bug Fixes::
 

docs/theming-guide.adoc

@@ -4090,6 +4090,83 @@ The keys in this category control the arrangement and style of unordered list it
 
 1. <type> is one of disc, square, circle, checked, unchecked
 
+[#keys-callout-list]
+=== Callout List
+
+The keys in this category control the arrangement and style of callout lists (i.e., colists).
+
+NOTE: The <<keys-callout-numbers>> category controls the appearance of the list markers (i.e., conums) in a callout list.
+If you change the font-size setting on the callout list, then you likely need to change the font-size setting on the conum category as well.
+
+[cols="3,4,5a"]
+|===
+|Key |Value Type |Example
+
+3+|[#key-prefix-callout-list]*Key Prefix:* <<key-prefix-callout-list,callout-list>>
+
+|item-spacing
+|<<measurement-units,Measurement>> +
+(default: $list-item-spacing)
+|[source,yaml]
+callout-list:
+  item-spacing: 3
+
+|font-color
+|<<colors,Color>> +
+(default: _inherit_)
+|[source,yaml]
+callout-list:
+  font-color: #555555
+
+|font-family
+|<<fonts,Font family name>> +
+(default: _inherit_)
+|[source,yaml]
+callout-list:
+  font-family: M+ 1p
+
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|[source,yaml]
+callout-list:
+  font-kerning: none
+
+|font-size
+|<<values,Number>> +
+(default: _inherit_)
+|[source,yaml]
+callout-list:
+  font-size: 9
+
+|font-style
+|<<font-styles,Font style>> +
+(default: _inherit_)
+|[source,yaml]
+callout-list:
+  font-style: italic
+
+|text-transform
+|<<text-transforms,Text transform>> +
+(default: _inherit_)
+|[source,yaml]
+callout-list:
+  text-transform: lowercase
+
+|line-height
+|<<values,Number>> +
+(default: _inherit_)
+|[source,yaml]
+callout-list:
+  line-height: 1
+
+|text-align
+|<<text-alignments,Text alignment>> +
+(default: $list-text-align)
+|callout-list:
+  text-align: left
+|===
+
 [#keys-table]
 === Table
 

lib/asciidoctor/pdf/converter.rb

@@ -1110,17 +1110,19 @@ def convert_colist node
         margin_top @theme.code_callout_list_margin_top if !at_page_top? && ([:listing, :literal].include? node.parent.blocks[(node.parent.blocks.index node) - 1].context)
         add_dest_for_block node if node.id
         @list_numerals << 1
-        line_metrics = theme_font(:conum) { calc_line_metrics @base_line_height }
         last_item = node.items[-1]
         item_spacing = @theme.callout_list_item_spacing || @theme.list_item_spacing
         item_opts = { margin_bottom: item_spacing, normalize_line_height: true }
         if (item_align = (resolve_alignment_from_role node.roles) || @theme.list_text_align&.to_sym)
           item_opts[:align] = item_align
         end
-        node.items.each do |item|
-          allocate_space_for_list_item line_metrics
-          item_opts[:margin_bottom] = 0 if item == last_item
-          convert_colist_item item, item_opts
+        theme_font :callout_list do
+          line_metrics = theme_font(:conum) { calc_line_metrics @base_line_height }
+          node.items.each do |item|
+            allocate_space_for_list_item line_metrics
+            item_opts[:margin_bottom] = 0 if item == last_item
+            convert_colist_item item, item_opts
+          end
         end
         @list_numerals.pop
         theme_margin :prose, :bottom, (next_enclosed_block node)

spec/list_spec.rb

@@ -1771,6 +1771,38 @@
       (expect gap).to be < 14
     end
 
+    it 'should allow theme to control font properties and item spacing of callout list' do
+      pdf_theme = {
+        callout_list_font_size: 9,
+        callout_list_font_color: '555555',
+        callout_list_item_spacing: 3,
+        conum_font_size: nil,
+      }
+
+      pdf = to_pdf <<~'EOS', pdf_theme: pdf_theme, analyze: true
+      ----
+      site:
+        url: https://docs.example.org # <1>
+        robots: allow # <2>
+      ----
+      <1> The base URL where the site is published.
+      <2> Allow search engines to crawl the site.
+      EOS
+
+      conum_1_text = pdf.find_text ?\u2460
+      (expect conum_1_text).to have_size 2
+      (expect conum_1_text[0][:font_size]).to eql 11
+      (expect conum_1_text[1][:font_size]).to eql 9
+      (expect conum_1_text[1][:font_color]).to eql 'B12146'
+      colist_1_text = pdf.find_unique_text %r/^The base URL/
+      (expect colist_1_text[:font_size]).to eql 9
+      (expect colist_1_text[:font_color]).to eql '555555'
+      colist_2_text = pdf.find_unique_text %r/^Allow search engines/
+      (expect colist_2_text[:font_size]).to eql 9
+      (expect colist_2_text[:font_color]).to eql '555555'
+      (expect colist_1_text[:y] - colist_2_text[:y]).to (be_within 1).of 16
+    end
+
     it 'should not move cursor if callout list appears at top of page' do
       pdf = to_pdf <<~EOS, analyze: true
       key-value pair