resolves #1894 rename the outline-list category in the theme to list; remap deprecated keys (PR #2039)

9 files changed, 79 insertions, 63 deletions

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index 2373cdf1..7b7fa480 100644
--- a/CHANGELOG.adoc
+++ b/CHANGELOG.adoc
@@ -198,6 +198,7 @@ Compliance::
 * rename Optimizer#generate_file method to Optimizer#optimize_file
 * drop support for deprecated `pdf-style` and `pdf-stylesdir` attributes (#1827)
 * drop use of the undocumented `vertical_spacing` key from the built-in themes
+* rename the `outline-list` category in the theme to `list` and map the `outline-list-` keys to `list-` with warning if found (#1894)
 * remove unneeded _mb functions (e.g., `uppercase_mb`); multibyte support for upcase, downcase, and capitalize is now provided by corelib
 
 Build / Infrastructure::
diff --git a/data/themes/base-theme.yml b/data/themes/base-theme.yml
index fcc82ff7..8d289b2b 100644
--- a/data/themes/base-theme.yml
+++ b/data/themes/base-theme.yml
@@ -53,8 +53,8 @@ title_page_title_top: 40%
 title_page_title_font_size: 18
 title_page_subtitle_font_size: 14
 title_page_authors_margin_top: 12
-outline_list_indent: 30
-outline_list_item_spacing: 6
+list_indent: 30
+list_item_spacing: 6
 description_list_description_indent: 30
 description_list_term_font_style: bold
 description_list_term_spacing: 4
diff --git a/data/themes/default-theme.yml b/data/themes/default-theme.yml
index f55a717e..daf7e119 100644
--- a/data/themes/default-theme.yml
+++ b/data/themes/default-theme.yml
@@ -230,15 +230,15 @@ thematic_break:
   border_width: $base_border_width
   margin_top: $vertical_rhythm * 0.5
   margin_bottom: $vertical_rhythm * 1.5
+list:
+  indent: $horizontal_rhythm * 1.5
+  #marker_font_color: 404040
+  # NOTE list_item_spacing only applies to list items that do not have complex content
+  item_spacing: $vertical_rhythm / 2
 description_list:
   term_font_style: bold
   term_spacing: $vertical_rhythm / 4
   description_indent: $horizontal_rhythm * 1.25
-outline_list:
-  indent: $horizontal_rhythm * 1.5
-  #marker_font_color: 404040
-  # NOTE outline_list_item_spacing applies to list items that do not have complex content
-  item_spacing: $vertical_rhythm / 2
 table:
   background_color: $page_background_color
   border_color: DDDDDD
@@ -260,7 +260,7 @@ toc:
     #levels: 2 3
 footnotes:
   font_size: round($base_font_size * 0.75)
-  item_spacing: $outline_list_item_spacing / 2
+  item_spacing: $list_item_spacing / 2
 header:
   font_size: $base_font_size_small
   line_height: 1
diff --git a/docs/theming-guide.adoc b/docs/theming-guide.adoc
index 3e016548..2f83dd70 100644
--- a/docs/theming-guide.adoc
+++ b/docs/theming-guide.adoc
@@ -108,7 +108,7 @@ heading:
   margin-bottom: $vertical-spacing
 link:
   font-color: #002FA7
-outline-list:
+list:
   indent: $base-font-size * 1.5
 footer:
   height: $base-line-height-length * 2.5
@@ -3971,39 +3971,39 @@ beta:: feature complete and undergoing testing
   description-indent: 15
 |===
 
-[#keys-outline-list]
-=== Outline List
+[#keys-list]
+=== List
 
-The keys in this category control the arrangement and style of outline list items.
+The keys in this category control the arrangement and style of regular (ordered and unordered) lists.
 
 [cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-3+|[#key-prefix-outline-list]*Key Prefix:* <<key-prefix-outline-list,outline-list>>
+3+|[#key-prefix-list]*Key Prefix:* <<key-prefix-list,list>>
 
 |indent
 |<<measurement-units,Measurement>> +
 (default: 30)
-|outline-list:
+|list:
   indent: 40
 
 |item-spacing
 |<<measurement-units,Measurement>> +
 (default: 6)
-|outline-list:
+|list:
   item-spacing: 4
 
 |marker-font-color^[1]^
 |<<colors,Color>> +
 (default: _inherit_)
-|outline-list:
+|list:
   marker-font-color: #3c763d
 
 |text-align^[2]^
 |<<text-alignments,Text alignment>> +
 (default: $base-align)
-|outline-list:
+|list:
   text-align: left
 |===
 
@@ -4037,7 +4037,7 @@ The keys in this category control the arrangement and style of unordered list it
 
 |font-color
 |<<colors,Color>> +
-(default: $outline-list-marker-font-color)
+(default: $list-marker-font-color)
 |ulist:
   marker:
     font-color: #cccccc
diff --git a/lib/asciidoctor/pdf/converter.rb b/lib/asciidoctor/pdf/converter.rb
index 47a06589..ffcbeab0 100644
--- a/lib/asciidoctor/pdf/converter.rb
+++ b/lib/asciidoctor/pdf/converter.rb
@@ -461,8 +461,8 @@ module Asciidoctor
         theme.prose_text_indent ||= 0
         theme.prose_margin_bottom ||= 0
         theme.block_margin_bottom ||= 0
-        theme.outline_list_indent ||= 0
-        theme.outline_list_item_spacing ||= 0
+        theme.list_indent ||= 0
+        theme.list_item_spacing ||= 0
         theme.description_list_term_spacing ||= 0
         theme.description_list_description_indent ||= 0
         theme.image_border_width ||= 0
@@ -1114,7 +1114,7 @@ module Asciidoctor
         last_item = node.items[-1]
         node.items.each do |item|
           allocate_space_for_list_item line_metrics
-          convert_colist_item item, margin_bottom: (item == last_item ? 0 : @theme.outline_list_item_spacing), normalize_line_height: true
+          convert_colist_item item, margin_bottom: (item == last_item ? 0 : @theme.list_item_spacing), normalize_line_height: true
         end
         @list_numerals.pop
         theme_margin :prose, :bottom, (next_enclosed_block node)
@@ -1239,7 +1239,7 @@ module Asciidoctor
               end
             end
             indent @theme.description_list_description_indent do
-              #margin_bottom (desc.simple? ? @theme.outline_list_item_spacing : term_spacing)
+              #margin_bottom (desc.simple? ? @theme.list_item_spacing : term_spacing)
               margin_bottom term_spacing
               traverse_list_item desc, :dlist_desc, normalize_line_height: true, margin_bottom: ((next_enclosed_block desc, descend: true) ? nil : 0)
             end if desc
@@ -1304,7 +1304,7 @@ module Asciidoctor
               end
             end
           else
-            case node.outline_level
+            case node.list_level
             when 1
               bullet_type = :disc
             when 2
@@ -1322,14 +1322,14 @@ module Asciidoctor
       def convert_list node
         # TODO: check if we're within one line of the bottom of the page
         # and advance to the next page if so (similar to logic for section titles)
-        layout_caption node, category: :outline_list, labeled: false if node.title?
+        layout_caption node, category: :list, labeled: false if node.title?
 
         opts = {}
         if (align = resolve_alignment_from_role node.roles)
           opts[:align] = align
         elsif node.style == 'bibliography'
           opts[:align] = :left
-        elsif (align = @theme.outline_list_text_align&.to_sym) # rubocop:disable Lint/DuplicateBranch
+        elsif (align = @theme.list_text_align&.to_sym) # rubocop:disable Lint/DuplicateBranch
           # NOTE: theme setting only affects alignment of list text (not nested blocks)
           opts[:align] = align
         end
@@ -1342,12 +1342,12 @@ module Asciidoctor
           if node.style == 'unstyled'
             # unstyled takes away all indentation
             list_indent = 0
-          elsif (list_indent = @theme.outline_list_indent) > 0
+          elsif (list_indent = @theme.list_indent) > 0
             # no-bullet aligns text with left-hand side of bullet position (as though there's no bullet)
             list_indent = [list_indent - (rendered_width_of_string %(#{node.context == :ulist ? ?\u2022 : '1.'}x)), 0].max
           end
         else
-          list_indent = @theme.outline_list_indent
+          list_indent = @theme.list_indent
         end
         indent list_indent do
           node.items.each do |item|
@@ -1361,7 +1361,7 @@ module Asciidoctor
       def convert_list_item node, list, opts = {}
         # TODO: move this to a draw_bullet (or draw_marker) method
         marker_style = {}
-        marker_style[:font_color] = @theme.outline_list_marker_font_color || @font_color
+        marker_style[:font_color] = @theme.list_marker_font_color || @font_color
         marker_style[:font_family] = font_family
         marker_style[:font_size] = font_size
         marker_style[:line_height] = @theme.base_line_height
@@ -1438,7 +1438,7 @@ module Asciidoctor
           if junction.compound?
             opts.delete :margin_bottom
           elsif next_enclosed_block junction, descend: true
-            opts[:margin_bottom] = @theme.outline_list_item_spacing
+            opts[:margin_bottom] = @theme.list_item_spacing
           end
         end
         traverse_list_item node, list_type, opts
diff --git a/lib/asciidoctor/pdf/ext/asciidoctor/list.rb b/lib/asciidoctor/pdf/ext/asciidoctor/list.rb
index a5dd2058..31feeb0b 100644
--- a/lib/asciidoctor/pdf/ext/asciidoctor/list.rb
+++ b/lib/asciidoctor/pdf/ext/asciidoctor/list.rb
@@ -9,19 +9,19 @@ class Asciidoctor::List
     Asciidoctor::ListItem === @parent
   end unless method_defined? :nested?
 
-  # Get the level of this list within the broader outline list (unordered or ordered) structure.
+  # Get the nesting level of this list within the broader list (unordered or ordered) structure.
   #
-  # This method differs from the level property in that it considers all outline list ancestors.
+  # This method differs from the level property in that it considers only list ancestors.
   # It's important for selecting the marker for an unordered list.
   #
-  # Return the 1-based level of this list within the outline list structure.
-  def outline_level
+  # Return the 1-based level of this list within the list structure.
+  def list_level
     l = 1
     ancestor = self
     # FIXME: does not cross out of AsciiDoc table cell
     while (ancestor = ancestor.parent)
-      l += 1 if Asciidoctor::List === ancestor && ancestor.outline?
+      l += 1 if Asciidoctor::List === ancestor && (ancestor.context == :ulist || ancestor.context == :olist)
     end
     l
-  end unless method_defined? :outline_level
+  end unless method_defined? :list_level
 end
diff --git a/lib/asciidoctor/pdf/theme_loader.rb b/lib/asciidoctor/pdf/theme_loader.rb
index a2cc9e33..05bd4dc8 100644
--- a/lib/asciidoctor/pdf/theme_loader.rb
+++ b/lib/asciidoctor/pdf/theme_loader.rb
@@ -126,6 +126,10 @@ module Asciidoctor
 
       def process_entry key, val, data, normalize_key = false
         key = key.tr '-', '_' if normalize_key && (key.include? '-')
+        if key == 'outline_list'
+          logger.warn 'the outline-list theme category is deprecated; use the list category instead'
+          key = 'list'
+        end
         if key == 'font'
           val.each do |subkey, subval|
             process_entry %(#{key}_#{subkey}), subval, data if subkey == 'catalog' || subkey == 'fallbacks'
@@ -191,27 +195,20 @@ module Asciidoctor
       def expand_vars expr, vars
         return expr unless (idx = expr.index '$')
         if idx == 0 && expr =~ LoneVariableRx
-          if (key = $1).include? '-'
-            key = key.tr '-', '_'
-          end
-          if vars.respond_to? key
-            vars[key]
-          else
-            logger.warn %(unknown variable reference in PDF theme: $#{$1})
-            expr
-          end
+          resolve_var vars, expr, $1
         else
-          expr.gsub VariableRx do
-            if (key = $1).include? '-'
-              key = key.tr '-', '_'
-            end
-            if vars.respond_to? key
-              vars[key]
-            else
-              logger.warn %(unknown variable reference in PDF theme: $#{$1})
-              $&
-            end
-          end
+          expr.gsub(VariableRx) { resolve_var vars, $&, $1 }
+        end
+      end
+
+      def resolve_var vars, ref, var
+        var = var.tr '-', '_' if var.include? '-'
+        if (vars.respond_to? var) ||
+            ((var.start_with? 'outline_list_') && (vars.respond_to? (var = var.slice 8, var.length)))
+          vars[var]
+        else
+          logger.warn %(unknown variable reference in PDF theme: #{ref})
+          ref
         end
       end
 
diff --git a/spec/list_spec.rb b/spec/list_spec.rb
index 1bd83042..3921d5c8 100644
--- a/spec/list_spec.rb
+++ b/spec/list_spec.rb
@@ -62,8 +62,8 @@ describe 'Asciidoctor::PDF::Converter - List' do
       (expect item_spacings.uniq).to eql [21.78]
     end
 
-    it 'should disable indent for list if outline_list_indent is 0' do
-      pdf = to_pdf <<~'EOS', pdf_theme: { outline_list_indent: 0 }, analyze: true
+    it 'should disable indent for list if list_indent is 0' do
+      pdf = to_pdf <<~'EOS', pdf_theme: { list_indent: 0 }, analyze: true
       before
 
       * a
@@ -137,8 +137,8 @@ describe 'Asciidoctor::PDF::Converter - List' do
       (expect indents[0]).to be > left_margin
     end
 
-    it 'should disable indent for no-bullet list if outline_list_indent is 0' do
-      pdf = to_pdf <<~'EOS', pdf_theme: { outline_list_indent: 0 }, analyze: true
+    it 'should disable indent for no-bullet list if list_indent is 0' do
+      pdf = to_pdf <<~'EOS', pdf_theme: { list_indent: 0 }, analyze: true
       before
 
       [no-bullet]
@@ -181,7 +181,7 @@ describe 'Asciidoctor::PDF::Converter - List' do
 
     it 'should not indent list with no marker if list indent is not set or set to 0 in theme' do
       [nil, 0].each do |indent|
-        pdf = to_pdf <<~'EOS', pdf_theme: { outline_list_indent: indent }, analyze: true
+        pdf = to_pdf <<~'EOS', pdf_theme: { list_indent: indent }, analyze: true
         before
 
         [no-bullet]
@@ -228,7 +228,7 @@ describe 'Asciidoctor::PDF::Converter - List' do
     end
 
     it 'should allow theme to change marker color for any list' do
-      pdf_theme = { outline_list_marker_font_color: '00FF00' }
+      pdf_theme = { list_marker_font_color: '00FF00' }
 
       pdf = to_pdf <<~'EOS', pdf_theme: pdf_theme, analyze: true
       * all
@@ -454,7 +454,7 @@ describe 'Asciidoctor::PDF::Converter - List' do
     end
 
     it 'should allow text alignment to be set using theme', visual: true do
-      to_file = to_pdf_file <<~EOS, 'list-text-left-role.pdf', pdf_theme: { outline_list_text_align: 'left' }
+      to_file = to_pdf_file <<~EOS, 'list-text-left-role.pdf', pdf_theme: { list_text_align: 'left' }
       * #{lorem_ipsum '2-sentences-1-paragraph'}
       EOS
       (expect to_file).to visually_match 'list-text-left.pdf'
@@ -1720,7 +1720,7 @@ describe 'Asciidoctor::PDF::Converter - List' do
       (expect first_to_second_spacing).to eql second_to_third_spacing
     end
 
-    it 'should only separate colist and listing or literal block by outline_list_item_spacing value' do
+    it 'should only separate colist and listing or literal block by list_item_spacing value' do
       %w(---- ....).each do |block_delim|
         input = <<~EOS
         #{block_delim}
diff --git a/spec/theme_loader_spec.rb b/spec/theme_loader_spec.rb
index 8f1c245f..1e45c657 100644
--- a/spec/theme_loader_spec.rb
+++ b/spec/theme_loader_spec.rb
@@ -155,6 +155,24 @@ describe Asciidoctor::PDF::ThemeLoader do
       (expect theme.footer_recto_right_content).to eql '2 * 2'
     end
 
+    it 'should remap outline-list category to list category and warn' do
+      (expect do
+        theme_data = YAML.safe_load <<~'EOS'
+        outline-list:
+          item-spacing: 6
+        footnotes:
+          margin-top: $outline-list-item-spacing
+          item-spacing: $outline_list_item_spacing / 2
+        EOS
+        theme = subject.new.load theme_data
+        (expect theme).to be_an OpenStruct
+        (expect theme.outline_list_item_spacing).to be_nil
+        (expect theme.list_item_spacing).to eql 6
+        (expect theme.footnotes_margin_top).to eql 6
+        (expect theme.footnotes_item_spacing).to eql 3
+      end).to log_message severity: :WARN, message: 'the outline-list theme category is deprecated; use the list category instead'
+    end
+
     it 'should expand variables in value of keys that end in _content' do
       theme_data = YAML.safe_load <<~'EOS'
       page: