asciidoctor-pdf 2.0.0.alpha.2 → 2.0.0.beta.2

data/lib/asciidoctor/pdf/converter.rb

@@ -52,6 +52,7 @@ module Asciidoctor
       TextAlignmentRoles = %w(text-justify text-left text-center text-right)
       TextDecorationStyleTable = { 'underline' => :underline, 'line-through' => :strikethrough }
       FontKerningTable = { 'normal' => true, 'none' => false }
+      BlockFloatNames = %w(left right)
       BlockAlignmentNames = %w(left center right)
       (AlignmentTable = { '<' => :left, '=' => :center, '>' => :right }).default = :left
       ColumnPositions = [:left, :center, :right]
@@ -139,6 +140,7 @@ module Asciidoctor
           # NOTE: enabling data-uri forces Asciidoctor Diagram to produce absolute image paths
           doc.attributes['data-uri'] = (doc.instance_variable_get :@attribute_overrides)['data-uri'] = ''
         end
+        @label = :primary
         @initial_instance_variables = [:@initial_instance_variables] + instance_variables
       end
 
@@ -168,7 +170,7 @@ module Asciidoctor
           if (bottom_gutter = @bottom_gutters[-1][node])
             prose_opts[:bottom_gutter] = bottom_gutter
           end
-          inscribe_prose string, prose_opts
+          ink_prose string, prose_opts
         end
       ensure
         node.document.instance_variable_set :@converter, prev_converter if prev_converter
@@ -181,8 +183,9 @@ module Asciidoctor
       def convert_document doc
         doc.promote_preface_block
         init_pdf doc
-        # set default value for outline, pagenums, and show-link-uri if not otherwise set
+        # set default value for outline, outline-title, and pagenums attributes if not otherwise set
         doc.attributes['outline'] = '' unless (doc.attribute_locked? 'outline') || ((doc.instance_variable_get :@attributes_modified).include? 'outline')
+        doc.attributes['outline-title'] = '' unless (doc.attribute_locked? 'outline-title') || ((doc.instance_variable_get :@attributes_modified).include? 'outline-title')
         doc.attributes['pagenums'] = '' unless (doc.attribute_locked? 'pagenums') || ((doc.instance_variable_get :@attributes_modified).include? 'pagenums')
         #assign_missing_section_ids doc
 
@@ -190,22 +193,22 @@ module Asciidoctor
 
         marked_page_number = page_number
         # NOTE: a new page will already be started (page_number = 2) if the front cover image is a PDF
-        inscribe_cover_page doc, :front
+        ink_cover_page doc, :front
         has_front_cover = page_number > marked_page_number
-        has_title_page = inscribe_title_page doc if (title_page_on = doc.doctype == 'book' || (doc.attr? 'title-page'))
+        has_title_page = ink_title_page doc if (title_page_on = doc.doctype == 'book' || (doc.attr? 'title-page'))
 
         @page_margin_by_side[:cover] = @page_margin_by_side[:recto] if @media == 'prepress' && page_number == 0
 
         start_new_page unless page&.empty? # rubocop:disable Lint/SafeNavigationWithEmpty
 
         # NOTE: the base font must be set before any content is written to the main or scratch document
-        # this method is called inside inscribe_title_page if the title page is active
+        # this method is called inside ink_title_page if the title page is active
         font @theme.base_font_family, size: @root_font_size, style: @theme.base_font_style unless has_title_page
 
         unless title_page_on
           body_start_page_number = page_number
           theme_font :heading, level: 1 do
-            inscribe_general_heading doc, doc.doctitle, align: (@theme.heading_h1_text_align&.to_sym || :center), level: 1, role: :doctitle
+            ink_general_heading doc, doc.doctitle, align: (@theme.heading_h1_text_align&.to_sym || :center), level: 1, role: :doctitle
           end if doc.header? && !doc.notitle
         end
 
@@ -216,7 +219,7 @@ module Asciidoctor
           if (insert_toc = (doc.attr? 'toc') && !((toc_placement = doc.attr 'toc-placement') == 'macro' || toc_placement == 'preamble') && doc.sections?)
             start_new_page if @ppbook && verso_page?
             add_dest_for_block doc, id: 'toc', y: (at_page_top? ? page_height : nil)
-            allocate_toc doc, toc_num_levels, cursor, title_page_on
+            @toc_extent = allocate_toc doc, toc_num_levels, cursor, title_page_on
           else
             @toc_extent = nil
           end
@@ -301,26 +304,26 @@ module Asciidoctor
           traverse doc
 
           # NOTE: for a book, these are leftover footnotes; for an article this is everything
-          outdent_section { inscribe_footnotes doc }
+          outdent_section { ink_footnotes doc }
 
-          if @toc_extent
+          if (toc_extent = @toc_extent)
             if title_page_on && !insert_toc
-              num_front_matter_pages[0] = @toc_extent.to.page if @theme.running_content_start_at == 'after-toc'
-              num_front_matter_pages[1] = @toc_extent.to.page if @theme.page_numbering_start_at == 'after-toc'
+              num_front_matter_pages[0] = toc_extent.to.page if @theme.running_content_start_at == 'after-toc'
+              num_front_matter_pages[1] = toc_extent.to.page if @theme.page_numbering_start_at == 'after-toc'
             end
-            toc_page_nums = inscribe_toc doc, toc_num_levels, @toc_extent.from.page, @toc_extent.from.cursor, num_front_matter_pages[1]
+            toc_page_nums = ink_toc doc, toc_num_levels, toc_extent.from.page, toc_extent.from.cursor, num_front_matter_pages[1]
           else
             toc_page_nums = []
           end
 
           # NOTE: delete orphaned page (a page was created but there was no additional content)
           # QUESTION: should we delete page if document is empty? (leaving no pages?)
-          delete_page if page_count > 1 && page.empty?
+          delete_current_page if page_count > 1 && page.empty?
         end
 
         unless page_count < body_start_page_number
-          inscribe_running_content :header, doc, num_front_matter_pages, body_start_page_number unless doc.noheader || @theme.header_height.to_f == 0 # rubocop:disable Lint/FloatComparison
-          inscribe_running_content :footer, doc, num_front_matter_pages, body_start_page_number unless doc.nofooter || @theme.footer_height.to_f == 0 # rubocop:disable Lint/FloatComparison
+          ink_running_content :header, doc, num_front_matter_pages, body_start_page_number unless doc.noheader || @theme.header_height.to_f == 0 # rubocop:disable Lint/FloatComparison
+          ink_running_content :footer, doc, num_front_matter_pages, body_start_page_number unless doc.nofooter || @theme.footer_height.to_f == 0 # rubocop:disable Lint/FloatComparison
         end
 
         add_outline doc, (doc.attr 'outlinelevels', toc_num_levels), toc_page_nums, num_front_matter_pages[1], has_front_cover
@@ -337,7 +340,7 @@ module Asciidoctor
         catalog.data[:ViewerPreferences] = { DisplayDocTitle: true }
 
         stamp_foreground_image doc, has_front_cover
-        inscribe_cover_page doc, :back
+        ink_cover_page doc, :back
         add_dest_for_top doc
         nil
       end
@@ -461,7 +464,6 @@ module Asciidoctor
       end
 
       def prepare_theme theme
-        theme.base_border_width || 0
         theme.base_font_color ||= '000000'
         theme.base_font_size ||= 12
         theme.base_font_style = theme.base_font_style&.to_sym || :normal
@@ -478,12 +480,16 @@ module Asciidoctor
         theme.list_item_spacing ||= 0
         theme.description_list_term_spacing ||= 0
         theme.description_list_description_indent ||= 0
+        theme.table_border_color ||= (theme.base_border_color || '000000')
+        theme.table_border_width ||= 0.5
+        theme.thematic_break_border_color ||= (theme.base_border_color || '000000')
         theme.image_border_width ||= 0
         theme.code_linenum_font_color ||= '999999'
         theme.callout_list_margin_top_after_code ||= 0
         theme.role_unresolved_font_color ||= 'FF0000'
-        theme.index_columns ||= 2
         theme.footnotes_item_spacing ||= 0
+        theme.index_columns ||= 2
+        theme.index_column_gap ||= theme.base_font_size
         theme.kbd_separator ||= '+'
         theme.title_page_authors_delimiter ||= ', '
         theme.title_page_revision_delimiter ||= ', '
@@ -661,24 +667,24 @@ module Asciidoctor
           title, _, subtitle = title.rpartition sep
           title = %(#{title}\n<em class="subtitle">#{subtitle}</em>)
         end
-        hlevel = sect.level + 1
+        hlevel = sect.level.next
         align = (@theme[%(heading_h#{hlevel}_text_align)] || @theme.heading_text_align || @base_text_align).to_sym
         chapterlike = !(part = sectname == 'part') && (sectname == 'chapter' || (sect.document.doctype == 'book' && sect.level == 1))
         hidden = sect.option? 'notitle'
         hopts = { align: align, level: hlevel, part: part, chapterlike: chapterlike, outdent: !(part || chapterlike) }
         if part
           unless @theme.heading_part_break_before == 'auto'
-            start_new = true
+            started_new = true
             start_new_part sect
           end
         elsif chapterlike
           if @theme.heading_chapter_break_before != 'auto' ||
               (@theme.heading_part_break_after == 'always' && sect == sect.parent.sections[0])
-            start_new = true
+            started_new = true
             start_new_chapter sect
           end
         end
-        arrange_section sect, title, hopts unless hidden || start_new || at_page_top?
+        arrange_heading sect, title, hopts unless hidden || started_new || at_page_top? || !sect.blocks?
         # QUESTION: should we store pdf-page-start, pdf-anchor & pdf-destination in internal map?
         sect.set_attr 'pdf-page-start', (start_pgnum = page_number)
         # QUESTION: should we just assign the section this generated id?
@@ -687,11 +693,11 @@ module Asciidoctor
         add_dest_for_block sect, id: sect_anchor, y: (at_page_top? ? page_height : nil)
         theme_font :heading, level: hlevel do
           if part
-            inscribe_part_title sect, title, hopts
+            ink_part_title sect, title, hopts
           elsif chapterlike
-            inscribe_chapter_title sect, title, hopts
+            ink_chapter_title sect, title, hopts
           else
-            inscribe_general_heading sect, title, hopts
+            ink_general_heading sect, title, hopts
           end
         end unless hidden
 
@@ -700,7 +706,7 @@ module Asciidoctor
         else
           traverse sect
         end
-        outdent_section { inscribe_footnotes sect } if chapterlike
+        outdent_section { ink_footnotes sect } if chapterlike
         sect.set_attr 'pdf-page-end', page_number
       end
 
@@ -721,7 +727,7 @@ module Asciidoctor
       end
 
       # QUESTION: if a footnote ref appears in a separate chapter, should the footnote def be duplicated?
-      def inscribe_footnotes node
+      def ink_footnotes node
         return if (fns = (doc = node.document).footnotes - @rendered_footnotes).empty?
         theme_margin :block, :bottom if node.context == :document || node == node.document.blocks[-1]
         theme_margin :footnotes, :top
@@ -730,7 +736,7 @@ module Asciidoctor
             move_down delta
           end
           theme_font :footnotes do
-            (title = doc.attr 'footnotes-title') && (inscribe_caption title, category: :footnotes)
+            (title = doc.attr 'footnotes-title') && (ink_caption title, category: :footnotes)
             item_spacing = @theme.footnotes_item_spacing
             index_offset = @rendered_footnotes.length
             sect_xreftext = node.context == :section && (node.xreftext node.document.attr 'xrefstyle')
@@ -740,7 +746,7 @@ module Asciidoctor
                 fn.singleton_class.send :attr_accessor, :label unless fn.respond_to? :label=
                 fn.label = %(#{label} - #{sect_xreftext})
               end
-              inscribe_prose %(<a id="_footnotedef_#{index}">#{DummyText}</a>[<a anchor="_footnoteref_#{index}">#{label}</a>] #{fn.text}), margin_bottom: item_spacing, hyphenate: true
+              ink_prose %(<a id="_footnotedef_#{index}">#{DummyText}</a>[<a anchor="_footnoteref_#{index}">#{label}</a>] #{fn.text}), margin_bottom: item_spacing, hyphenate: true
             end
             @rendered_footnotes += fns if extent
           end
@@ -749,14 +755,17 @@ module Asciidoctor
       end
 
       def convert_floating_title node
-        add_dest_for_block node if node.id
+        title = node.title
         hlevel = node.level.next
-        unless (align = resolve_alignment_from_role node.roles)
+        unless (align = resolve_text_align_from_role node.roles)
           align = (@theme[%(heading_h#{hlevel}_text_align)] || @theme.heading_text_align || @base_text_align).to_sym
         end
+        hopts = { align: align, level: hlevel, outdent: (parent = node.parent).context == :section }
+        arrange_heading node, title, hopts unless at_page_top? || node == parent.blocks[-1]
+        add_dest_for_block node if node.id
         # QUESTION: should we decouple styles from section titles?
         theme_font :heading, level: hlevel do
-          inscribe_general_heading node, node.title, align: align, level: hlevel, outdent: (node.parent.context == :section)
+          ink_general_heading node, title, hopts
         end
       end
 
@@ -765,7 +774,7 @@ module Asciidoctor
         outdent_section do
           pad_box @theme.abstract_padding do
             theme_font :abstract_title do
-              inscribe_prose node.title, align: (@theme.abstract_title_text_align || @base_text_align).to_sym, margin_top: @theme.heading_margin_top, margin_bottom: @theme.heading_margin_bottom, line_height: (@theme.heading_line_height || @theme.base_line_height)
+              ink_prose node.title, align: (@theme.abstract_title_text_align || @base_text_align).to_sym, margin_top: @theme.heading_margin_top, margin_bottom: @theme.heading_margin_bottom, line_height: (@theme.heading_line_height || @theme.base_line_height)
             end if node.title?
             theme_font :abstract do
               prose_opts = { align: (@theme.abstract_text_align || @base_text_align).to_sym, hyphenate: true }
@@ -774,11 +783,21 @@ module Asciidoctor
               end
               # FIXME: allow theme to control more first line options
               if (line1_font_style = @theme.abstract_first_line_font_style&.to_sym) && line1_font_style != font_style
-                first_line_options = { styles: line1_font_style == :normal ? [] : [font_style, line1_font_style] }
+                case line1_font_style
+                when :normal
+                  first_line_options = { styles: [] }
+                when :normal_italic
+                  first_line_options = { styles: [:italic] }
+                else
+                  first_line_options = { styles: [font_style, line1_font_style] }
+                end
               end
               if (line1_font_color = @theme.abstract_first_line_font_color)
                 (first_line_options ||= {})[:color] = line1_font_color
               end
+              if (line1_text_transform = @theme.abstract_first_line_text_transform)
+                (first_line_options ||= {})[:text_transform] = line1_text_transform
+              end
               prose_opts[:first_line_options] = first_line_options if first_line_options
               # FIXME: make this cleaner!!
               if node.blocks?
@@ -787,7 +806,7 @@ module Asciidoctor
                   if child.context == :paragraph
                     child.document.playback_attributes child.attributes
                     prose_opts[:margin_bottom] = 0 if child == last_block
-                    inscribe_prose child.content, ((align = resolve_alignment_from_role child.roles) ? (prose_opts.merge align: align) : prose_opts.dup)
+                    ink_prose child.content, ((align = resolve_text_align_from_role child.roles) ? (prose_opts.merge align: align) : prose_opts.dup)
                     prose_opts.delete :first_line_options
                     prose_opts.delete :margin_bottom
                   else
@@ -796,10 +815,10 @@ module Asciidoctor
                   end
                 end
               elsif node.content_model != :compound && (string = node.content)
-                if (align = resolve_alignment_from_role node.roles)
+                if (align = resolve_text_align_from_role node.roles)
                   prose_opts[:align] = align
                 end
-                inscribe_prose string, (prose_opts.merge margin_bottom: 0)
+                ink_prose string, (prose_opts.merge margin_bottom: 0)
               end
             end
           end
@@ -820,39 +839,39 @@ module Asciidoctor
 
       def convert_paragraph node
         add_dest_for_block node if node.id
+
         prose_opts = { margin_bottom: 0, hyphenate: true }
-        if (align = resolve_alignment_from_role (roles = node.roles), use_theme: true)
+        if (align = resolve_text_align_from_role (roles = node.roles), query_theme: true, remove_predefined: true)
           prose_opts[:align] = align
-          roles -= TextAlignmentRoles
         end
-
+        role_keys = roles.map {|role| %(role_#{role}).to_sym } unless roles.empty?
         if (text_indent = @theme.prose_text_indent) > 0 ||
             ((text_indent = @theme.prose_text_indent_inner) > 0 &&
             (self_idx = (siblings = node.parent.blocks).index node) > 0 && siblings[self_idx - 1].context == :paragraph)
           prose_opts[:indent_paragraphs] = text_indent
         end
-
-        # 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)
-        inscribe_caption node, labeled: false if node.title?
-
         if (bottom_gutter = @bottom_gutters[-1][node])
           prose_opts[:bottom_gutter] = bottom_gutter
         end
 
-        if roles.empty?
-          inscribe_prose node.content, prose_opts
-        else
-          theme_font_cascade (roles.map {|role| %(role_#{role}).to_sym }) do
-            inscribe_prose node.content, prose_opts
+        block_next = next_enclosed_block node
+
+        insert_margin_bottom = proc do
+          if (margin_inner_val = @theme.prose_margin_inner) && block_next&.context == :paragraph
+            margin_bottom margin_inner_val
+          else
+            theme_margin :prose, :bottom, block_next
           end
         end
 
-        block_next = next_enclosed_block node
-        if (margin_inner_val = @theme.prose_margin_inner) && block_next&.context == :paragraph
-          margin_bottom margin_inner_val
+        if (float_box = (@float_box ||= nil))
+          ink_paragraph_in_float_box node, float_box, prose_opts, role_keys, block_next, insert_margin_bottom
         else
-          theme_margin :prose, :bottom, block_next
+          # 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)
+          ink_caption node, labeled: false if node.title?
+          role_keys ? theme_font_cascade(role_keys) { ink_prose node.content, prose_opts } : (ink_prose node.content, prose_opts)
+          insert_margin_bottom.call
         end
       end
 
@@ -892,20 +911,16 @@ module Asciidoctor
             label_width = label_min_width if label_min_width && label_min_width > label_width
           end
         end
-        unless ::Array === (cpad = @theme.admonition_padding || 0)
-          cpad = ::Array.new 4, cpad
-        end
-        unless ::Array === (lpad = @theme.admonition_label_padding || cpad)
-          lpad = ::Array.new 4, lpad
-        end
+        cpad = expand_padding_value @theme.admonition_padding
+        lpad = (lpad = @theme.admonition_label_padding) ? (expand_padding_value lpad) : cpad
         arrange_block node do |extent|
           add_dest_for_block node if node.id
           theme_fill_and_stroke_block :admonition, extent if extent
           pad_box [0, cpad[1], 0, lpad[3]] do
             if extent
               label_height = extent.single_page_height || cursor
-              if (rule_color = @theme.admonition_column_rule_color) &&
-                  (rule_width = @theme.admonition_column_rule_width || @theme.base_border_width) && rule_width > 0
+              if (rule_width = @theme.admonition_column_rule_width || 0) > 0 &&
+                  (rule_color = @theme.admonition_column_rule_color || @theme.base_border_color)
                 rule_style = @theme.admonition_column_rule_style&.to_sym || :solid
                 float do
                   extent.each_page do |first_page, last_page|
@@ -996,7 +1011,7 @@ module Asciidoctor
                         end
                       end
                       @text_transform = nil # already applied to label
-                      inscribe_prose label_text,
+                      ink_prose label_text,
                         align: label_align,
                         valign: label_valign,
                         line_height: 1,
@@ -1010,7 +1025,7 @@ module Asciidoctor
               end
             end
             pad_box [cpad[0], 0, cpad[2], label_width + lpad[1] + cpad[3]], node do
-              inscribe_caption node, category: :admonition, labeled: false if node.title?
+              ink_caption node, category: :admonition, labeled: false if node.title?
               theme_font :admonition do
                 traverse node
               end
@@ -1044,13 +1059,13 @@ module Asciidoctor
           arrange_block node do
             add_dest_for_block node if id
             tare_first_page_content_stream do
-              node.context == :example ? (inscribe_caption %(\u25bc #{node.title})) : (inscribe_caption node, labeled: false)
+              node.context == :example ? (ink_caption %(\u25bc #{node.title})) : (ink_caption node, labeled: false)
             end if has_title
             traverse node
           end
         else
           add_dest_for_block node if id
-          node.context == :example ? (inscribe_caption %(\u25bc #{node.title})) : (inscribe_caption node, labeled: false) if has_title
+          node.context == :example ? (ink_caption %(\u25bc #{node.title})) : (ink_caption node, labeled: false) if has_title
           traverse node
         end
       end
@@ -1059,7 +1074,7 @@ module Asciidoctor
         category = node.context == :quote ? :quote : :verse
         # NOTE: b_width and b_left_width are mutually exclusive
         if (b_left_width = @theme[%(#{category}_border_left_width)]) && b_left_width > 0
-          b_color = @theme[%(#{category}_border_color)]
+          b_color = @theme[%(#{category}_border_color)] || @theme.base_border_color
         else
           b_left_width = nil
           b_width = nil if (b_width = @theme[%(#{category}_border_width)]) == 0
@@ -1094,7 +1109,7 @@ module Asciidoctor
                 traverse node
               else # :verse
                 content = guard_indentation node.content
-                inscribe_prose content,
+                ink_prose content,
                   normalize: false,
                   align: :left,
                   hyphenate: true,
@@ -1106,7 +1121,7 @@ module Asciidoctor
               margin_bottom @theme.block_margin_bottom
               theme_font %(#{category}_cite) do
                 attribution_parts = citetitle ? [attribution, citetitle] : [attribution]
-                inscribe_prose %(#{EmDash} #{attribution_parts.join ', '}), align: :left, normalize: false, margin_bottom: 0
+                ink_prose %(#{EmDash} #{attribution_parts.join ', '}), align: :left, normalize: false, margin_bottom: 0
               end
             end
           end
@@ -1122,9 +1137,11 @@ module Asciidoctor
           add_dest_for_block node if node.id
           theme_fill_and_stroke_block :sidebar, extent if extent
           pad_box @theme.sidebar_padding, node do
-            theme_font :sidebar_title do
-              # QUESTION: should we allow margins of sidebar title to be customized?
-              inscribe_prose node.title, align: (@theme.sidebar_title_text_align || @theme.heading_text_align || @base_text_align).to_sym, margin_bottom: @theme.heading_margin_bottom, line_height: (@theme.heading_line_height || @theme.base_line_height)
+            tare_first_page_content_stream do
+              theme_font :sidebar_title do
+                # QUESTION: should we allow margins of sidebar title to be customized?
+                ink_prose node.title, align: (@theme.sidebar_title_text_align || @theme.heading_text_align || @base_text_align).to_sym, margin_bottom: @theme.heading_margin_bottom, line_height: (@theme.heading_line_height || @theme.base_line_height)
+              end
             end if node.title?
             theme_font :sidebar do
               traverse node
@@ -1135,13 +1152,15 @@ module Asciidoctor
       end
 
       def convert_colist node
-        margin_top @theme.callout_list_margin_top_after_code if !at_page_top? && ([:listing, :literal].include? node.parent.blocks[(node.parent.blocks.index node) - 1].context)
+        unless at_page_top? || (self_idx = (siblings = node.parent.blocks).index node) == 0 || !([:listing, :literal].include? siblings[self_idx - 1].context)
+          margin_top @theme.callout_list_margin_top_after_code
+        end
         add_dest_for_block node if node.id
         @list_numerals << 1
         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)
+        if (item_align = (resolve_text_align_from_role node.roles) || @theme.list_text_align&.to_sym)
           item_opts[:align] = item_align
         end
         theme_font :callout_list do
@@ -1163,7 +1182,7 @@ module Asciidoctor
           marker_width = rendered_width_of_string %(#{marker = conum_glyph index}x)
           float do
             bounding_box [0, cursor], width: marker_width do
-              inscribe_prose marker, align: :center, inline_format: false, margin: 0
+              ink_prose marker, align: :center, inline_format: false, margin: 0
             end
           end
         end
@@ -1247,7 +1266,7 @@ module Asciidoctor
           max_term_width += (term_padding[1] + term_padding[3])
           term_column_width = [max_term_width, bounds.width * 0.5].min
           table table_data, position: :left, cell_style: { border_width: 0 }, column_widths: [term_column_width] do
-            @pdf.inscribe_table_caption node if node.title?
+            @pdf.ink_table_caption node if node.title?
           end
           theme_margin :prose, :bottom, (next_enclosed_block actual_node) #unless actual_node.nested?
         when 'qanda'
@@ -1257,7 +1276,7 @@ module Asciidoctor
         else
           # 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)
-          inscribe_caption node, category: :description_list, labeled: false if node.title?
+          ink_caption node, category: :description_list, labeled: false if node.title?
 
           term_spacing = @theme.description_list_term_spacing
           term_height = theme_font(:description_list_term) { height_of_typeset_text 'A' }
@@ -1269,8 +1288,8 @@ module Asciidoctor
                 term_font_styles = nil
               end
               terms.each_with_index do |term, idx|
-                # QUESTION: should we pass down styles in other calls to inscribe_prose
-                inscribe_prose term.text, margin_top: (idx > 0 ? term_spacing : 0), margin_bottom: 0, align: :left, normalize_line_height: true, styles: term_font_styles
+                # QUESTION: should we pass down styles in other calls to ink_prose
+                ink_prose term.text, margin_top: (idx > 0 ? term_spacing : 0), margin_bottom: 0, align: :left, normalize_line_height: true, styles: term_font_styles
               end
             end
             indent @theme.description_list_description_indent do
@@ -1357,10 +1376,10 @@ 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)
-        inscribe_caption node, category: :list, labeled: false if node.title?
+        ink_caption node, category: :list, labeled: false if node.title?
 
         opts = {}
-        if (align = resolve_alignment_from_role node.roles)
+        if (align = resolve_text_align_from_role node.roles)
           opts[:align] = align
         elsif node.style == 'bibliography'
           opts[:align] = :left
@@ -1454,7 +1473,7 @@ module Asciidoctor
             float do
               advance_page if @media == 'prepress' && cursor < marker_height
               flow_bounding_box position: start_position, width: marker_width do
-                inscribe_prose marker,
+                ink_prose marker,
                   align: :right,
                   character_spacing: -0.5,
                   color: marker_style[:font_color],
@@ -1482,16 +1501,16 @@ module Asciidoctor
       def traverse_list_item node, list_type, opts = {}
         if list_type == :dlist # qanda
           terms, desc = node
-          terms.each {|term| inscribe_prose %(<em>#{term.text}</em>), (opts.merge margin_bottom: @theme.description_list_term_spacing) }
+          terms.each {|term| ink_prose %(<em>#{term.text}</em>), (opts.merge margin_bottom: @theme.description_list_term_spacing) }
           if desc
-            inscribe_prose desc.text, (opts.merge hyphenate: true) if desc.text?
+            ink_prose desc.text, (opts.merge hyphenate: true) if desc.text?
             traverse desc
           end
         else
           if (primary_text = node.text).nil_or_empty?
-            inscribe_prose DummyText, opts unless node.blocks?
+            ink_prose DummyText, opts unless node.blocks?
           else
-            inscribe_prose primary_text, (opts.merge hyphenate: true)
+            ink_prose primary_text, (opts.merge hyphenate: true)
           end
           traverse node
         end
@@ -1553,22 +1572,29 @@ module Asciidoctor
 
         return on_image_error :missing, node, target, opts unless image_path
 
-        alignment = (alignment = node.attr 'align') ?
-          ((BlockAlignmentNames.include? alignment) ? alignment.to_sym : :left) :
-          (resolve_alignment_from_role node.roles) || @theme.image_align&.to_sym || :left
+        if (float_to = node.attr 'float') && ((BlockFloatNames.include? float_to) ? float_to : (float_to = nil))
+          alignment = float_to.to_sym
+        elsif (alignment = node.attr 'align')
+          alignment = (BlockAlignmentNames.include? alignment) ? alignment.to_sym : :left
+        else
+          alignment = (resolve_text_align_from_role node.roles) || @theme.image_align&.to_sym || :left
+        end
         # TODO: support cover (aka canvas) image layout using "canvas" (or "cover") role
         width = resolve_explicit_width node.attributes, bounds_width: (available_w = bounds.width), support_vw: true, use_fallback: true, constrain_to_bounds: true
         # TODO: add `to_pt page_width` method to ViewportWidth type
         width = (width.to_f / 100) * page_width if ViewportWidth === width
 
+        caption_end = @theme.image_caption_end&.to_sym || :bottom
+        caption_max_width = @theme.image_caption_max_width
+        caption_max_width = 'fit-content' if float_to && !(caption_max_width&.start_with? 'fit-content')
         # NOTE: if width is not set explicitly and max-width is fit-content, caption height may not be accurate
-        caption_h = node.title? ? (inscribe_caption node, category: :image, side: :bottom, block_align: alignment, block_width: width, max_width: @theme.image_caption_max_width, dry_run: true, force_top_margin: true) : 0
+        caption_h = node.title? ? (ink_caption node, category: :image, end: caption_end, block_align: alignment, block_width: width, max_width: caption_max_width, dry_run: true, force_top_margin: caption_end == :bottom) : 0
 
         align_to_page = node.option? 'align-to-page'
         pinned = opts[:pinned]
 
         begin
-          rendered_w = nil
+          rendered_h = rendered_w = nil
           span_page_width_if align_to_page do
             if image_format == 'svg'
               if ::Base64 === image_path
@@ -1598,14 +1624,14 @@ module Asciidoctor
                 end
                 rendered_w = (svg_obj.resize height: (rendered_h = available_h)).output_width if rendered_h > available_h
               end
-              image_y = y
-              image_cursor = cursor
               add_dest_for_block node if node.id
               # NOTE: workaround to fix Prawn not adding fill and stroke commands on page that only has an image;
               # breakage occurs when running content (stamps) are added to page
               update_colors if graphic_state.color_space.empty?
-              # NOTE: cursor advances automatically
-              svg_obj.draw
+              ink_caption node, category: :image, end: :top, block_align: alignment, block_width: rendered_w, max_width: caption_max_width if caption_end == :top && node.title?
+              image_y = y
+              image_cursor = cursor
+              svg_obj.draw # NOTE: cursor advances automatically
               svg_obj.document.warnings.each do |img_warning|
                 log :warn, %(problem encountered in image: #{image_path}; #{img_warning})
               end unless scratch?
@@ -1629,12 +1655,13 @@ module Asciidoctor
                 end
                 rendered_w, rendered_h = image_info.calc_image_dimensions height: available_h if rendered_h > available_h
               end
-              image_y = y
-              image_cursor = cursor
               add_dest_for_block node if node.id
               # NOTE: workaround to fix Prawn not adding fill and stroke commands on page that only has an image;
               # breakage occurs when running content (stamps) are added to page
               update_colors if graphic_state.color_space.empty?
+              ink_caption node, category: :image, end: :top, block_align: alignment, block_width: rendered_w, max_width: caption_max_width if caption_end == :top && node.title?
+              image_y = y
+              image_cursor = cursor
               # NOTE: specify both width and height to avoid recalculation
               embed_image image_obj, image_info, width: rendered_w, height: rendered_h, position: alignment
               draw_image_border image_cursor, rendered_w, rendered_h, alignment unless node.role? && (node.has_role? 'noborder')
@@ -1645,16 +1672,40 @@ module Asciidoctor
               move_down rendered_h if y == image_y
             end
           end
-          inscribe_caption node, category: :image, side: :bottom, block_align: alignment, block_width: rendered_w, max_width: @theme.image_caption_max_width if node.title?
-          theme_margin :block, :bottom, (next_enclosed_block node) unless pinned
+          ink_caption node, category: :image, end: :bottom, block_align: alignment, block_width: rendered_w, max_width: caption_max_width if caption_end == :bottom && node.title?
+          if !pinned && (block_next = next_enclosed_block node)
+            if float_to && (supports_float_wrapping? block_next) && rendered_w < bounds.width
+              init_float_box node, rendered_w, rendered_h + caption_h, float_to
+            else
+              theme_margin :block, :bottom, block_next
+            end
+          end
         rescue => e
           raise if ::StopIteration === e
           on_image_error :exception, node, target, (opts.merge message: %(could not embed image: #{image_path}; #{e.message}#{::Prawn::Errors::UnsupportedImageType === e && !(defined? ::GMagick::Image) ? '; install prawn-gmagick gem to add support' : ''}))
         end
       end
 
+      def supports_float_wrapping? node
+        node.context == :paragraph
+      end
+
+      def init_float_box _node, block_width, block_height, float_to
+        gap = ::Array === (gap = @theme.image_float_gap) ? gap.dup : [gap, gap]
+        float_w = block_width + (gap[0] ||= 12)
+        float_h = block_height + (gap[1] ||= 6)
+        box_l = bounds.left + (float_to == 'right' ? 0 : float_w)
+        box_t = cursor + block_height
+        box_w = bounds.width - float_w
+        box_r = box_l + box_w
+        box_h = [box_t, float_h].min
+        box_b = box_t - box_h
+        move_cursor_to box_t
+        @float_box = { page: page_number, top: box_t, right: box_r, bottom: box_b, left: box_l, width: box_w, height: box_h, gap: gap }
+      end
+
       def draw_image_border top, w, h, alignment
-        if @theme.image_border_width > 0 && @theme.image_border_color
+        if (Array @theme.image_border_width).any? {|it| it&.> 0 } && (@theme.image_border_color || @theme.base_border_color)
           if (@theme.image_border_fit || 'content') == 'auto'
             bb_width = bounds.width
           elsif alignment == :center
@@ -1684,10 +1735,10 @@ module Asciidoctor
         theme_font :image_alt do
           alignment = (alignment = node.attr 'align') ?
             ((BlockAlignmentNames.include? alignment) ? alignment.to_sym : :left) :
-            (resolve_alignment_from_role node.roles) || (@theme.image_align&.to_sym || :left)
-          inscribe_prose alt_text_template % alt_text_vars, align: alignment, margin: 0, normalize: false, single_line: true
+            (resolve_text_align_from_role node.roles) || (@theme.image_align&.to_sym || :left)
+          ink_prose alt_text_template % alt_text_vars, align: alignment, margin: 0, normalize: false, single_line: true
         end
-        inscribe_caption node, category: :image, side: :bottom if node.title?
+        ink_caption node, category: :image, end: :bottom if node.title?
         theme_margin :block, :bottom, (next_enclosed_block node) unless opts[:pinned]
         nil
       end
@@ -1696,8 +1747,8 @@ module Asciidoctor
         add_dest_for_block node if node.id
         audio_path = node.media_uri node.attr 'target'
         play_symbol = (node.document.attr? 'icons', 'font') ? %(<font name="fas">#{(icon_font_data 'fas').unicode 'play'}</font>) : RightPointer
-        inscribe_prose %(#{play_symbol}#{NoBreakSpace}<a href="#{audio_path}">#{audio_path}</a> <em>(audio)</em>), normalize: false, margin: 0, single_line: true
-        inscribe_caption node, labeled: false, side: :bottom if node.title?
+        ink_prose %(#{play_symbol}#{NoBreakSpace}<a href="#{audio_path}">#{audio_path}</a> <em>(audio)</em>), normalize: false, margin: 0, single_line: true
+        ink_caption node, labeled: false, end: :bottom if node.title?
         theme_margin :block, :bottom, (next_enclosed_block node)
       end
 
@@ -1724,8 +1775,8 @@ module Asciidoctor
         if poster.nil_or_empty?
           add_dest_for_block node if node.id
           play_symbol = (node.document.attr? 'icons', 'font') ? %(<font name="fas">#{(icon_font_data 'fas').unicode 'play'}</font>) : RightPointer
-          inscribe_prose %(#{play_symbol}#{NoBreakSpace}<a href="#{video_path}">#{video_path}</a> <em>(#{type})</em>), normalize: false, margin: 0, single_line: true
-          inscribe_caption node, labeled: false, side: :bottom if node.title?
+          ink_prose %(#{play_symbol}#{NoBreakSpace}<a href="#{video_path}">#{video_path}</a> <em>(#{type})</em>), normalize: false, margin: 0, single_line: true
+          ink_caption node, labeled: false, end: :bottom if node.title?
           theme_margin :block, :bottom, (next_enclosed_block node)
         else
           original_attributes = node.attributes.dup
@@ -1739,7 +1790,7 @@ module Asciidoctor
       end
 
       # QUESTION: can we avoid arranging fragments multiple times (conums & autofit) by eagerly preparing arranger?
-      def convert_listing_or_literal node
+      def convert_code node
         extensions = []
         source_chunks = bg_color_override = font_color_override = adjusted_font_size = nil
         theme_font :code do
@@ -1886,17 +1937,31 @@ module Asciidoctor
         theme_margin :block, :bottom, (next_enclosed_block node)
       end
 
-      alias convert_listing convert_listing_or_literal
-      alias convert_literal convert_listing_or_literal
+      alias convert_listing convert_code
+      alias convert_literal convert_code
+      alias convert_listing_or_literal convert_code
 
       def convert_pass node
-        node = node.dup
-        (subs = node.subs.dup).unshift :specialcharacters
-        node.instance_variable_set :@subs, subs.uniq
-        convert_listing_or_literal node
+        theme_font :code do
+          typeset_formatted_text [text: (guard_indentation node.content), color: @theme.base_font_color], (calc_line_metrics @base_line_height)
+        end
+        theme_margin :block, :bottom, (next_enclosed_block node)
       end
 
-      alias convert_stem convert_listing_or_literal
+      def convert_stem node
+        arrange_block node do |extent|
+          add_dest_for_block node if node.id
+          tare_first_page_content_stream { theme_fill_and_stroke_block :code, extent, caption_node: node }
+          pad_box @theme.code_padding, node do
+            theme_font :code do
+              typeset_formatted_text [text: (guard_indentation node.content), color: @font_color],
+                (calc_line_metrics @base_line_height),
+                bottom_gutter: @bottom_gutters[-1][node]
+            end
+          end
+        end
+        theme_margin :block, :bottom, (next_enclosed_block node)
+      end
 
       # Extract callout marks from string, indexed by 0-based line number
       # Return an Array with the processed string as the first argument
@@ -2024,6 +2089,7 @@ module Asciidoctor
 
         base_header_cell_data = nil
         header_cell_line_metrics = nil
+        body_cell_padding = expand_padding_value theme.table_cell_padding
 
         table_data = []
         theme_font :table do
@@ -2038,7 +2104,7 @@ module Asciidoctor
             table_header_size = head_rows.size
             head_font_info = font_info
             head_line_metrics = calc_line_metrics theme.table_head_line_height || theme.table_cell_line_height || @base_line_height
-            head_cell_padding = expand_padding_value theme.table_head_cell_padding || theme.table_cell_padding
+            head_cell_padding = ((head_cell_padding = theme.table_head_cell_padding) ? (expand_padding_value head_cell_padding) : body_cell_padding).dup
             head_cell_padding[0] += head_line_metrics.padding_top
             head_cell_padding[2] += head_line_metrics.padding_bottom
             # QUESTION: why doesn't text transform inherit from table?
@@ -2077,7 +2143,6 @@ module Asciidoctor
             text_color: @font_color,
           }
           body_cell_line_metrics = calc_line_metrics (theme.table_cell_line_height || @base_line_height)
-          body_cell_padding = expand_padding_value theme.table_cell_padding
           (body_rows + node.rows[:foot]).each do |row|
             table_data << (row.map do |cell|
               cell_data = base_cell_data.merge \
@@ -2144,7 +2209,7 @@ module Asciidoctor
                 end
                 # NOTE: line metrics get applied when AsciiDoc content is converted
                 cell_line_metrics = nil
-                asciidoc_cell = ::Prawn::Table::Cell::AsciiDoc.new self, (cell_data.merge content: cell.inner_document, padding: body_cell_padding.dup)
+                asciidoc_cell = ::Prawn::Table::Cell::AsciiDoc.new self, (cell_data.merge content: cell.inner_document, padding: body_cell_padding)
                 cell_data = { content: asciidoc_cell }
               end
               if cell_line_metrics
@@ -2190,17 +2255,17 @@ module Asciidoctor
 
         rect_side_names = [:top, :right, :bottom, :left]
         grid_axis_names = [:rows, :cols]
-        border_color = (rect_side_names.zip expand_rect_values theme.table_border_color, (theme.base_border_color || 'transparent')).to_h
+        border_color = (rect_side_names.zip expand_rect_values theme.table_border_color, 'transparent').to_h
         border_style = (rect_side_names.zip (expand_rect_values theme.table_border_style, :solid).map(&:to_sym)).to_h
         border_width = (rect_side_names.zip expand_rect_values theme.table_border_width, 0).to_h
         grid_color = (grid_axis_names.zip expand_grid_values (theme.table_grid_color || [border_color[:top], border_color[:left]]), 'transparent').to_h
         grid_style = (grid_axis_names.zip (expand_grid_values (theme.table_grid_style || [border_style[:top], border_style[:left]]), :solid).map(&:to_sym)).to_h
-        grid_width = (grid_axis_names.zip expand_grid_values theme.table_grid_width, 0).to_h
+        grid_width = (grid_axis_names.zip expand_grid_values (theme.table_grid_width || [border_width[:top], border_width[:left]]), 0).to_h
 
         if table_header_size
           head_border_bottom_color = theme.table_head_border_bottom_color || grid_color[:rows]
           head_border_bottom_style = theme.table_head_border_bottom_style&.to_sym || grid_style[:rows]
-          head_border_bottom_width = theme.table_head_border_bottom_width || grid_width[:rows]
+          head_border_bottom_width = theme.table_head_border_bottom_width || (grid_width[:rows] * 2.5)
         end
 
         case (grid = node.attr 'grid', 'all', 'table-grid')
@@ -2241,7 +2306,7 @@ module Asciidoctor
           alignment = theme.table_align&.to_sym || :left
         end
 
-        caption_side = theme.table_caption_side&.to_sym || :top
+        caption_end = theme.table_caption_end&.to_sym || :top
         caption_max_width = theme.table_caption_max_width || 'fit-content'
 
         table_settings = {
@@ -2270,7 +2335,7 @@ module Asciidoctor
         table table_data, table_settings do
           # NOTE: call width to capture resolved table width
           table_width = width
-          @pdf.inscribe_table_caption node, alignment, table_width, caption_max_width if node.title? && caption_side == :top
+          @pdf.ink_table_caption node, alignment, table_width, caption_max_width if node.title? && caption_end == :top
           # NOTE: align using padding instead of bounding_box as prawn-table does
           # using a bounding_box across pages mangles the margin box of subsequent pages
           if alignment != :left && table_width != (this_bounds = @pdf.bounds).width
@@ -2343,20 +2408,23 @@ module Asciidoctor
           bounds.subtract_left_padding left_padding
           bounds.subtract_right_padding right_padding if right_padding
         end
-        inscribe_table_caption node, alignment, table_width, caption_max_width, caption_side if node.title? && caption_side == :bottom
+        ink_table_caption node, alignment, table_width, caption_max_width, caption_end if node.title? && caption_end == :bottom
         theme_margin :block, :bottom, (next_enclosed_block node)
       rescue ::Prawn::Errors::CannotFit
         log :error, (message_with_context 'cannot fit contents of table cell into specified column width', source_location: node.source_location)
       end
 
       def convert_thematic_break node
-        theme_margin :thematic_break, :top
-        stroke_horizontal_rule @theme.thematic_break_border_color, line_width: @theme.thematic_break_border_width, line_style: (@theme.thematic_break_border_style&.to_sym || :solid)
-        theme_margin :thematic_break, ((block_next = next_enclosed_block node) ? :bottom : :top), block_next || true
+        pad_box @theme.thematic_break_padding || [@theme.thematic_break_margin_top, 0] do
+          stroke_horizontal_rule @theme.thematic_break_border_color,
+            line_width: @theme.thematic_break_border_width,
+            line_style: (@theme.thematic_break_border_style&.to_sym || :solid)
+        end
+        conceal_page_top { theme_margin :block, :bottom, (next_enclosed_block node) }
       end
 
       def convert_toc node, opts = {}
-        # NOTE: only allow document to have a single toc
+        # NOTE: only allow document to have a single managed toc
         return if @toc_extent
         is_macro = (placement = opts[:placement] || 'macro') == 'macro'
         if ((doc = node.document).attr? 'toc-placement', placement) && (doc.attr? 'toc') && doc.sections?
@@ -2365,11 +2433,11 @@ module Asciidoctor
             start_new_page if @ppbook && verso_page? && !(is_macro && (node.option? 'nonfacing'))
           end
           add_dest_for_block node, id: (node.id || 'toc') if is_macro
-          allocate_toc doc, (doc.attr 'toclevels', 2).to_i, cursor, (title_page_on = is_book || (doc.attr? 'title-page'))
-          @index.start_page_number = @toc_extent.to.page + 1 if title_page_on && @theme.page_numbering_start_at == 'after-toc'
+          toc_extent = @toc_extent = allocate_toc doc, (doc.attr 'toclevels', 2).to_i, cursor, (title_page_on = is_book || (doc.attr? 'title-page'))
+          @index.start_page_number = toc_extent.to.page + 1 if title_page_on && @theme.page_numbering_start_at == 'after-toc'
           if is_macro
-            @disable_running_content[:header] += @toc_extent.page_range if node.option? 'noheader'
-            @disable_running_content[:footer] += @toc_extent.page_range if node.option? 'nofooter'
+            @disable_running_content[:header] += toc_extent.page_range if node.option? 'noheader'
+            @disable_running_content[:footer] += toc_extent.page_range if node.option? 'nofooter'
           end
         end
         nil
@@ -2387,7 +2455,7 @@ module Asciidoctor
 
         if at_page_top?
           if page_layout && page_layout != page.layout && page.empty?
-            delete_page
+            delete_current_page
             advance_page layout: page_layout
           end
         elsif page_layout
@@ -2397,48 +2465,50 @@ module Asciidoctor
         end
       end
 
-      def convert_index_section _node
+      def convert_index_section node
         space_needed_for_category = @theme.description_list_term_spacing + (2 * (height_of_typeset_text 'A'))
-        column_box [0, cursor], columns: @theme.index_columns, width: bounds.width, reflow_margins: true do
-          def @bounding_box.move_past_bottom *args # rubocop:disable Lint/NestedMethodDefinition
-            super(*args)
-            @document.bounds = @parent = @document.margin_box if @current_column == 0 && @reflow_margins
-          end
+        pagenum_sequence_style = node.document.attr 'index-pagenum-sequence-style'
+        column_box [0, cursor], columns: @theme.index_columns, width: bounds.width, reflow_margins: true, spacer: @theme.index_column_gap do
           @index.categories.each do |category|
-            # NOTE: cursor method always returns 0 inside column_box; breaks reference_bounds.move_past_bottom
-            bounds.move_past_bottom if space_needed_for_category > y - reference_bounds.absolute_bottom
-            inscribe_prose category.name,
+            bounds.move_past_bottom if space_needed_for_category > cursor
+            ink_prose category.name,
               align: :left,
               inline_format: false,
               margin_bottom: @theme.description_list_term_spacing,
-              style: @theme.description_list_term_font_style.to_sym
-            category.terms.each {|term| convert_index_list_item term }
-            # NOTE: see previous note for why we can't use margin_bottom method
-            if @theme.prose_margin_bottom > y - reference_bounds.absolute_bottom
-              bounds.move_past_bottom
-            else
-              move_down @theme.prose_margin_bottom
-            end
+              style: @theme.description_list_term_font_style&.to_sym
+            category.terms.each {|term| convert_index_list_item term, pagenum_sequence_style }
+            @theme.prose_margin_bottom > cursor ? bounds.move_past_bottom : (move_down @theme.prose_margin_bottom)
           end
         end
         nil
       end
 
-      def convert_index_list_item term
+      def convert_index_list_item term, pagenum_sequence_style = nil
         text = escape_xml term.name
         unless term.container?
           if @media == 'screen'
-            pagenums = term.dests.map {|dest| %(<a anchor="#{dest[:anchor]}">#{dest[:page]}</a>) }
+            case pagenum_sequence_style
+            when 'page'
+              pagenums = term.dests.uniq {|dest| dest[:page] }.map {|dest| %(<a anchor="#{dest[:anchor]}">#{dest[:page]}</a>) }
+            when 'range'
+              first_anchor_per_page = term.dests.each_with_object({}) {|dest, accum| accum[dest[:page]] ||= dest[:anchor] }
+              pagenums = (consolidate_ranges first_anchor_per_page.keys).map do |range|
+                anchor = first_anchor_per_page[(range.include? '-') ? (range.partition '-')[0] : range]
+                %(<a anchor="#{anchor}">#{range}</a>)
+              end
+            else # term
+              pagenums = term.dests.map {|dest| %(<a anchor="#{dest[:anchor]}">#{dest[:page]}</a>) }
+            end
           else
-            pagenums = consolidate_ranges term.dests.uniq {|dest| dest[:page] }.map {|dest| dest[:page] } # rubocop:disable Lint/AmbiguousBlockAssociation
+            pagenums = consolidate_ranges term.dests.map {|dest| dest[:page] }.uniq
           end
           text = %(#{text}, #{pagenums.join ', '})
         end
         subterm_indent = @theme.description_list_description_indent
-        inscribe_prose text, align: :left, margin: 0, hanging_indent: subterm_indent * 2
+        ink_prose text, align: :left, margin: 0, hanging_indent: subterm_indent * 2
         indent subterm_indent do
           term.subterms.each do |subterm|
-            convert_index_list_item subterm
+            convert_index_list_item subterm, pagenum_sequence_style
           end
         end unless term.leaf?
       end
@@ -2723,7 +2793,7 @@ module Asciidoctor
       end
 
       # Returns a Boolean indicating whether the title page was created
-      def inscribe_title_page doc
+      def ink_title_page doc
         return unless doc.header? && !doc.notitle && @theme.title_page != false
 
         # NOTE: a new page may have already been started at this point, so decide what to do with it
@@ -2799,7 +2869,7 @@ module Asciidoctor
             move_down @theme.title_page_title_margin_top || 0
             indent (@theme.title_page_title_margin_left || 0), (@theme.title_page_title_margin_right || 0) do
               theme_font :title_page_title do
-                inscribe_prose doctitle.main, align: title_align, margin: 0
+                ink_prose doctitle.main, align: title_align, margin: 0
               end
             end
             move_down @theme.title_page_title_margin_bottom || 0
@@ -2808,7 +2878,7 @@ module Asciidoctor
             move_down @theme.title_page_subtitle_margin_top || 0
             indent (@theme.title_page_subtitle_margin_left || 0), (@theme.title_page_subtitle_margin_right || 0) do
               theme_font :title_page_subtitle do
-                inscribe_prose subtitle, align: title_align, margin: 0
+                ink_prose subtitle, align: title_align, margin: 0
               end
             end
             move_down @theme.title_page_subtitle_margin_bottom || 0
@@ -2833,7 +2903,7 @@ module Asciidoctor
                 end
               end.join @theme.title_page_authors_delimiter
               theme_font :title_page_authors do
-                inscribe_prose authors, align: title_align, margin: 0, normalize: true
+                ink_prose authors, align: title_align, margin: 0, normalize: true
               end
             end
             move_down @theme.title_page_authors_margin_bottom || 0
@@ -2846,18 +2916,18 @@ module Asciidoctor
             end
             indent (@theme.title_page_revision_margin_left || 0), (@theme.title_page_revision_margin_right || 0) do
               theme_font :title_page_revision do
-                inscribe_prose revision_text, align: title_align, margin: 0, normalize: false
+                ink_prose revision_text, align: title_align, margin: 0, normalize: false
               end
             end
             move_down @theme.title_page_revision_margin_bottom || 0
           end
         end
 
-        inscribe_prose DummyText, margin: 0, line_height: 1, normalize: false if page.empty?
+        ink_prose DummyText, margin: 0, line_height: 1, normalize: false if page.empty?
         true
       end
 
-      def inscribe_cover_page doc, face
+      def ink_cover_page doc, face
         image_path, image_opts = resolve_background_image doc, @theme, %(#{face}-cover-image), theme_key: %(cover_#{face}_image).to_sym, symbolic_paths: ['', '~']
         if image_path
           if image_path.empty?
@@ -2903,92 +2973,178 @@ module Asciidoctor
 
       def start_new_chapter chapter
         start_new_page unless at_page_top?
-        # TODO: must call update_colors before advancing to next page if start_new_page is called in inscribe_chapter_title
+        # TODO: must call update_colors before advancing to next page if start_new_page is called in ink_chapter_title
         start_new_page if @ppbook && verso_page? && !(chapter.option? 'nonfacing')
       end
 
       alias start_new_part start_new_chapter
 
-      def arrange_section sect, title, opts
-        if sect.option? 'breakable'
+      # Position the cursor for where to ink the specified section title or discrete heading node.
+      #
+      # This method computes whether there is enough room on the page to prevent the specified node
+      # from being orphaned. If there is not enough room, the method will advance the cursor to
+      # the next page. This method is not called if the cursor is already at the top of the page or
+      # whether this node has no node that follows it in document order.
+      def arrange_heading node, title, opts
+        if node.option? 'breakable'
           orphaned = nil
           dry_run single_page: true do
             start_page = page
             theme_font :heading, level: opts[:level] do
               if opts[:part]
-                inscribe_part_title sect, title, opts
+                ink_part_title node, title, opts
               elsif opts[:chapterlike]
-                inscribe_chapter_title sect, title, opts
+                ink_chapter_title node, title, opts
               else
-                inscribe_general_heading sect, title, opts
+                ink_general_heading node, title, opts
               end
             end
             if page == start_page
               page.tare_content_stream
-              orphaned = stop_if_first_page_empty { traverse sect }
+              orphaned = stop_if_first_page_empty do
+                node.context == :section ? (traverse node) : (convert (siblings = node.parent.blocks)[(siblings.index node) + 1])
+              end
             end
           end
           start_new_page if orphaned
         else
           theme_font :heading, level: (hlevel = opts[:level]) do
-            # FIXME: this height doesn't account for impact of text transform or inline formatting
-            heading_height =
-              (height_of_typeset_text title) +
-              (@theme[%(heading_h#{hlevel}_margin_top)] || @theme.heading_margin_top) +
-              (@theme[%(heading_h#{hlevel}_margin_bottom)] || @theme.heading_margin_bottom)
-            heading_height += @theme.heading_min_height_after if sect.blocks? && @theme.heading_min_height_after
-            start_new_page unless cursor > heading_height
+            h_padding_t, h_padding_r, h_padding_b, h_padding_l = expand_padding_value @theme[%(heading_h#{hlevel}_padding)]
+            h_fits = indent h_padding_l, h_padding_r do
+              # FIXME: this height doesn't account for impact of text transform or inline formatting
+              heading_h = (height_of_typeset_text title) +
+                (@theme[%(heading_h#{hlevel}_margin_top)] || @theme.heading_margin_top) +
+                (@theme[%(heading_h#{hlevel}_margin_bottom)] || @theme.heading_margin_bottom) + h_padding_t + h_padding_b
+              if (min_height_after = @theme.heading_min_height_after) &&
+                  (node.context == :section ? node.blocks? : node != node.parent.blocks[-1])
+                heading_h += min_height_after
+              end
+              cursor >= heading_h
+            end
+            start_new_page unless h_fits
           end
         end
         nil
       end
 
-      def inscribe_chapter_title node, title, opts = {}
-        inscribe_general_heading node, title, (opts.merge outdent: true)
+      def ink_chapter_title node, title, opts = {}
+        ink_general_heading node, title, (opts.merge outdent: true)
       end
 
-      alias inscribe_part_title inscribe_chapter_title
+      alias ink_part_title ink_chapter_title
 
-      def inscribe_general_heading _node, title, opts = {}
-        inscribe_heading title, opts
+      def ink_general_heading _node, title, opts = {}
+        ink_heading title, opts
       end
 
-      # NOTE: inscribe_heading doesn't set the theme font because it's used for various types of headings
-      def inscribe_heading string, opts = {}
-        hlevel = opts[:level]
+      # NOTE: ink_heading doesn't set the theme font because it's used for various types of headings
+      def ink_heading string, opts = {}
+        if (h_level = opts[:level])
+          h_category = %(heading_h#{h_level})
+        end
         unless (top_margin = (margin = (opts.delete :margin)) || (opts.delete :margin_top))
           if at_page_top?
-            if hlevel && (top_margin = @theme[%(heading_h#{hlevel}_margin_page_top)] || @theme.heading_margin_page_top) > 0
+            if h_category && (top_margin = @theme[%(#{h_category}_margin_page_top)] || @theme.heading_margin_page_top) > 0
               move_down top_margin
             end
             top_margin = 0
           else
-            top_margin = (hlevel ? @theme[%(heading_h#{hlevel}_margin_top)] : nil) || @theme.heading_margin_top
+            top_margin = (h_category ? @theme[%(#{h_category}_margin_top)] : nil) || @theme.heading_margin_top
           end
         end
-        bot_margin = margin || (opts.delete :margin_bottom) || (hlevel ? @theme[%(heading_h#{hlevel}_margin_bottom)] : nil) || @theme.heading_margin_bottom
+        bot_margin = margin || (opts.delete :margin_bottom) || (h_category ? @theme[%(#{h_category}_margin_bottom)] : nil) || @theme.heading_margin_bottom
         if (transform = resolve_text_transform opts)
           string = transform_text string, transform
         end
         outdent_section opts.delete :outdent do
           margin_top top_margin
-          # QUESTION: should we move inherited styles to typeset_text?
-          if (inherited = apply_text_decoration font_styles, :heading, hlevel).empty?
-            inline_format_opts = true
-          else
-            inline_format_opts = [{ inherited: inherited }]
+          start_cursor = cursor
+          start_page_number = page_number
+          pad_box h_category ? @theme[%(#{h_category}_padding)] : nil do
+            # QUESTION: should we move inherited styles to typeset_text?
+            if (inherited = apply_text_decoration font_styles, :heading, h_level).empty?
+              inline_format_opts = true
+            else
+              inline_format_opts = [{ inherited: inherited }]
+            end
+            typeset_text string, (calc_line_metrics (opts.delete :line_height) || @base_line_height), {
+              color: @font_color,
+              inline_format: inline_format_opts,
+              align: @base_text_align.to_sym,
+            }.merge(opts)
+          end
+          if h_category && @theme[%(#{h_category}_border_width)] &&
+              (@theme[%(#{h_category}_border_color)] || @theme.base_border_color) && page_number == start_page_number
+            float do
+              bounding_box [bounds.left, start_cursor], width: bounds.width, height: start_cursor - cursor do
+                theme_fill_and_stroke_bounds h_category
+              end
+            end
           end
-          typeset_text string, (calc_line_metrics (opts.delete :line_height) || @base_line_height), {
-            color: @font_color,
-            inline_format: inline_format_opts,
-            align: @base_text_align.to_sym,
-          }.merge(opts)
           margin_bottom bot_margin
         end
       end
 
+      # private
+      def ink_paragraph_in_float_box node, float_box, prose_opts, role_keys, block_next, insert_margin_bottom
+        @float_box = para_font_descender = para_font_size = end_cursor = nil
+        if role_keys
+          line_metrics = theme_font_cascade role_keys do
+            para_font_descender = font.descender
+            para_font_size = font_size
+            calc_line_metrics @base_line_height
+          end
+        else
+          para_font_descender = font.descender
+          para_font_size = font_size
+          line_metrics = calc_line_metrics @base_line_height
+        end
+        # allocate the space of at least one empty line below block
+        line_height_length = line_metrics.height + line_metrics.leading + line_metrics.padding_top
+        start_page_number = float_box[:page]
+        start_cursor = cursor
+        block_bottom = (float_box_bottom = float_box[:bottom]) + float_box[:gap][1]
+        # use :at to incorporate padding top from line metrics
+        # use :final_gap to incorporate padding bottom from line metrics
+        # use :draw_text_callback to track end cursor (requires applying :final_gap to result manually)
+        prose_opts.update \
+          at: [float_box[:left], start_cursor - line_metrics.padding_top],
+          width: float_box[:width],
+          height: [cursor, float_box[:height] - (float_box[:top] - start_cursor) + line_height_length].min,
+          final_gap: para_font_descender + line_metrics.padding_bottom,
+          draw_text_callback: (proc do |text, opts|
+            draw_text! text, opts
+            end_cursor = opts[:at][1] # does not include :final_gap value
+          end)
+        overflow_text = role_keys ?
+          theme_font_cascade(role_keys) { ink_prose node.content, prose_opts } :
+          (ink_prose node.content, prose_opts)
+        move_cursor_to end_cursor -= prose_opts[:final_gap] if end_cursor # ink_prose with :height does not move cursor
+        if overflow_text.empty?
+          if block_next && (supports_float_wrapping? block_next)
+            insert_margin_bottom.call
+            @float_box = float_box if page_number == start_page_number && cursor > start_cursor - prose_opts[:height]
+          elsif end_cursor > block_bottom
+            move_cursor_to block_bottom
+            theme_margin :block, :bottom, block_next
+          else
+            insert_margin_bottom.call
+          end
+        else
+          overflow_prose_opts = { align: prose_opts[:align] || @base_text_align.to_sym }
+          unless end_cursor
+            overflow_prose_opts[:indent_paragraphs] = prose_opts[:indent_paragraphs]
+            move_cursor_to float_box_bottom if start_cursor > float_box_bottom
+          end
+          role_keys ?
+            theme_font_cascade(role_keys) { typeset_formatted_text overflow_text, line_metrics, overflow_prose_opts } :
+            (typeset_formatted_text overflow_text, line_metrics, overflow_prose_opts)
+          insert_margin_bottom.call
+        end
+      end
+
       # NOTE: inline_format is true by default
-      def inscribe_prose string, opts = {}
+      def ink_prose string, opts = {}
         top_margin = (margin = (opts.delete :margin)) || (opts.delete :margin_top) || 0
         bot_margin = margin || (opts.delete :margin_bottom) || @theme.prose_margin_bottom
         if (transform = resolve_text_transform opts)
@@ -3009,12 +3165,13 @@ module Asciidoctor
             text_decoration_width: (opts.delete :text_decoration_width),
           }.compact
         end
-        typeset_text string, (calc_line_metrics (opts.delete :line_height) || @base_line_height), {
+        result = typeset_text string, (calc_line_metrics (opts.delete :line_height) || @base_line_height), {
           color: @font_color,
           inline_format: [inline_format_opts],
           align: @base_text_align.to_sym,
         }.merge(opts)
         margin_bottom bot_margin
+        result
       end
 
       def generate_manname_section node
@@ -3035,13 +3192,14 @@ module Asciidoctor
       # The subject argument can either be a String or an AbstractNode. If
       # subject is an AbstractNode, only call this method if the node has a
       # title (i.e., subject.title? returns true).
-      def inscribe_caption subject, opts = {}
+      def ink_caption subject, opts = {}
         if opts.delete :dry_run
-          force_top_margin = !at_page_top? if (force_top_margin = opts.delete :force_top_margin).nil?
           return (dry_run keep_together: true, single_page: :enforce do
-            # TODO: encapsulate this logic to force top margin to be applied
-            margin_box.instance_variable_set :@y, margin_box.absolute_top + 0.0001 if force_top_margin
-            inscribe_caption subject, opts
+            if opts.delete :force_top_margin
+              conceal_page_top { ink_caption subject, opts }
+            else
+              ink_caption subject, opts
+            end
           end).single_page_height
         end
         if ::Asciidoctor::AbstractBlock === subject
@@ -3069,11 +3227,22 @@ module Asciidoctor
         if (max_width = opts.delete :max_width) && max_width != 'none'
           if ::String === max_width
             if max_width.start_with? 'fit-content'
-              if max_width.end_with? 't', '()'
-                max_width = block_width || container_width
-              else
-                max_width = (block_width || container_width) * (max_width.slice 12, max_width.length - 1).to_f / 100.0
+              block_width ||= container_width
+              unless max_width.end_with? 't', '()'
+                max_width = block_width * (max_width.slice 12, max_width.length - 1).to_f / 100.0
+                if (caption_width_delta = block_width - max_width) > 0
+                  case align
+                  when :right
+                    indent_by[0] += caption_width_delta
+                  when :center
+                    indent_by[0] += caption_width_delta * 0.5
+                    indent_by[1] += caption_width_delta * 0.5
+                  else # :left, nil
+                    indent_by[1] += caption_width_delta
+                  end
+                end
               end
+              max_width = block_width
             elsif max_width.end_with? '%'
               max_width = [max_width.to_f / 100 * bounds.width, bounds.width].min
               block_align = align
@@ -3088,16 +3257,17 @@ module Asciidoctor
           if (remainder = container_width - max_width) > 0
             case block_align
             when :right
-              indent_by = [remainder, 0]
+              indent_by[0] += remainder
             when :center
-              indent_by = [(side_margin = remainder * 0.5), side_margin]
+              indent_by[0] += remainder * 0.5
+              indent_by[1] += remainder * 0.5
             else # :left, nil
-              indent_by = [0, remainder]
+              indent_by[1] += remainder
             end
           end
         end
         theme_font_cascade [:caption, category_caption] do
-          if ((opts.delete :side) || :top) == :top
+          if ((opts.delete :end) || (opts.delete :side) || :top) == :top
             margin = { top: caption_margin_outside, bottom: caption_margin_inside }
           else
             margin = { top: caption_margin_inside, bottom: caption_margin_outside }
@@ -3111,7 +3281,7 @@ module Asciidoctor
             float { bounding_box(fill_at, width: container_width, height: caption_height) { fill_bounds bg_color } }
           end
           indent(*indent_by) do
-            inscribe_prose string, ({
+            ink_prose string, ({
               margin_top: margin[:top],
               margin_bottom: margin[:bottom],
               align: text_align,
@@ -3125,16 +3295,22 @@ module Asciidoctor
       end
 
       # Render the caption for a table and return the height of the rendered content
-      def inscribe_table_caption node, table_alignment = :left, table_width = nil, max_width = nil, side = :top
-        inscribe_caption node, category: :table, side: side, block_align: table_alignment, block_width: table_width, max_width: max_width
+      def ink_table_caption node, table_alignment = :left, table_width = nil, max_width = nil, end_ = :top
+        ink_caption node, category: :table, end: end_, block_align: table_alignment, block_width: table_width, max_width: max_width
       end
 
       def allocate_toc doc, toc_num_levels, toc_start_cursor, title_page_on
-        toc_start_page = page_number
+        toc_start_page_number = page_number
+        to_page = nil
         extent = dry_run onto: self do
-          inscribe_toc doc, toc_num_levels, toc_start_page, toc_start_cursor
+          to_page = (ink_toc doc, toc_num_levels, toc_start_page_number, toc_start_cursor).end
           margin_bottom @theme.block_margin_bottom unless title_page_on
         end
+        # NOTE: patch for custom converters that allocate extra TOC pages without actually creating them
+        if to_page > extent.to.page
+          extent.to.page = to_page
+          extent.to.cursor = bounds.height
+        end
         # NOTE: reserve pages for the toc; leaves cursor on page after last page in toc
         if title_page_on
           extent.each_page { start_new_page }
@@ -3142,18 +3318,22 @@ module Asciidoctor
           extent.each_page {|first_page| start_new_page unless first_page }
           move_cursor_to extent.to.cursor
         end
-        @toc_extent = extent
+        extent
+      end
+
+      def get_entries_for_toc node
+        node.sections
       end
 
       # NOTE: num_front_matter_pages not used during a dry run
-      def inscribe_toc doc, num_levels, toc_page_number, start_cursor, num_front_matter_pages = 0
+      def ink_toc doc, num_levels, toc_page_number, start_cursor, num_front_matter_pages = 0
         go_to_page toc_page_number unless (page_number == toc_page_number) || scratch?
         start_page_number = page_number
         move_cursor_to start_cursor
         unless (toc_title = doc.attr 'toc-title').nil_or_empty?
           theme_font_cascade [[:heading, level: 2], :toc_title] do
             toc_title_align = (@theme.toc_title_text_align || @theme.heading_h2_text_align || @theme.heading_text_align || @base_text_align).to_sym
-            inscribe_general_heading doc, toc_title, align: toc_title_align, level: 2, outdent: true, role: :toctitle
+            ink_general_heading doc, toc_title, align: toc_title_align, level: 2, outdent: true, role: :toctitle
           end
         end
         # QUESTION: should we skip this whole method if num_levels < 0?
@@ -3178,7 +3358,7 @@ module Asciidoctor
             }
           end
           theme_margin :toc, :top
-          inscribe_toc_level doc.sections, num_levels, dot_leader, num_front_matter_pages
+          ink_toc_level (get_entries_for_toc doc), num_levels, dot_leader, num_front_matter_pages
         end
         # NOTE: range must be calculated relative to toc_page_number; absolute page number in scratch document is arbitrary
         toc_page_numbers = (toc_page_number..(toc_page_number + (page_number - start_page_number)))
@@ -3186,38 +3366,48 @@ module Asciidoctor
         toc_page_numbers
       end
 
-      def inscribe_toc_level sections, num_levels, dot_leader, num_front_matter_pages
+      def ink_toc_level entries, num_levels, dot_leader, num_front_matter_pages
         # NOTE: font options aren't always reliable, so store size separately
         toc_font_info = theme_font :toc do
           { font: font, size: @font_size }
         end
         hanging_indent = @theme.toc_hanging_indent
-        sections.each do |sect|
-          next if (num_levels_for_sect = (sect.attr 'toclevels', num_levels).to_i) < sect.level
-          theme_font :toc, level: (sect.level + 1) do
-            sect_title = @text_transform ? (transform_text sect.numbered_title, @text_transform) : sect.numbered_title
-            next if sect_title.empty?
+        entries.each do |entry|
+          next if (num_levels_for_entry = (entry.attr 'toclevels', num_levels).to_i) < (entry_level = entry.level + 1).pred
+          theme_font :toc, level: entry_level do
+            next unless (entry_anchor = (entry.attr 'pdf-anchor') || entry.id)
+            entry_title = entry.context == :section ? entry.numbered_title : (entry.title? ? entry.title : (entry.xreftext 'basic'))
+            next if entry_title.empty?
+            entry_title = transform_text entry_title, @text_transform if @text_transform
             pgnum_label_placeholder_width = rendered_width_of_string '0' * @toc_max_pagenum_digits
-            # NOTE: only write section title (excluding dots and page number) if this is a dry run
+            # NOTE: only write title (excluding dots and page number) if this is a dry run
             if scratch?
               indent 0, pgnum_label_placeholder_width do
                 # NOTE: must wrap title in empty anchor element in case links are styled with different font family / size
-                inscribe_prose sect_title, anchor: true, normalize: false, hanging_indent: hanging_indent, normalize_line_height: true, margin: 0
+                ink_prose entry_title, anchor: true, normalize: false, hanging_indent: hanging_indent, normalize_line_height: true, margin: 0
               end
             else
-              physical_pgnum = sect.attr 'pdf-page-start'
-              virtual_pgnum = physical_pgnum - num_front_matter_pages
-              pgnum_label = (virtual_pgnum < 1 ? (RomanNumeral.new physical_pgnum, :lower) : virtual_pgnum).to_s
+              if !(physical_pgnum = entry.attr 'pdf-page-start') &&
+                  (target_page_ref = (get_dest entry_anchor)&.first) &&
+                  (target_page_idx = state.pages.index {|candidate| candidate.dictionary == target_page_ref })
+                physical_pgnum = target_page_idx + 1
+              end
+              if physical_pgnum
+                virtual_pgnum = physical_pgnum - num_front_matter_pages
+                pgnum_label = (virtual_pgnum < 1 ? (RomanNumeral.new physical_pgnum, :lower) : virtual_pgnum).to_s
+              else
+                pgnum_label = '?'
+              end
               start_page_number = page_number
               start_cursor = cursor
               start_dots = nil
-              sect_title_inherited = (apply_text_decoration ::Set.new, :toc, sect.level.next).merge anchor: (sect_anchor = sect.attr 'pdf-anchor'), color: @font_color
+              entry_title_inherited = (apply_text_decoration ::Set.new, :toc, entry_level).merge anchor: entry_anchor, color: @font_color
               # NOTE: use text formatter to add anchor overlay to avoid using inline format with synthetic anchor tag
-              sect_title_fragments = text_formatter.format sect_title, inherited: sect_title_inherited
+              entry_title_fragments = text_formatter.format entry_title, inherited: entry_title_inherited
               line_metrics = calc_line_metrics @base_line_height
               indent 0, pgnum_label_placeholder_width do
-                (sect_title_fragments[-1][:callback] ||= []) << (last_fragment_pos = ::Asciidoctor::PDF::FormattedText::FragmentPositionRenderer.new)
-                typeset_formatted_text sect_title_fragments, line_metrics, hanging_indent: hanging_indent, normalize_line_height: true
+                (entry_title_fragments[-1][:callback] ||= []) << (last_fragment_pos = ::Asciidoctor::PDF::FormattedText::FragmentPositionRenderer.new)
+                typeset_formatted_text entry_title_fragments, line_metrics, hanging_indent: hanging_indent, normalize_line_height: true
                 start_dots = last_fragment_pos.right + hanging_indent
                 last_fragment_cursor = last_fragment_pos.top + line_metrics.padding_top
                 start_cursor = last_fragment_cursor if last_fragment_pos.page_number > start_page_number || (start_cursor - last_fragment_cursor) > line_metrics.height
@@ -3225,7 +3415,7 @@ module Asciidoctor
               end_cursor = cursor
               move_cursor_to start_cursor
               # NOTE: we're guaranteed to be on the same page as the final line of the entry
-              if dot_leader[:width] > 0 && (dot_leader[:levels].include? sect.level)
+              if dot_leader[:width] > 0 && (dot_leader[:levels].include? entry_level.pred)
                 pgnum_label_width = rendered_width_of_string pgnum_label
                 pgnum_label_font_settings = { color: @font_color, font: font_family, size: @font_size, styles: font_styles }
                 save_font do
@@ -3237,18 +3427,18 @@ module Asciidoctor
                   typeset_formatted_text [
                     { text: dot_leader[:text] * num_dots, color: dot_leader[:font_color] },
                     dot_leader[:spacer],
-                    ({ text: pgnum_label, anchor: sect_anchor }.merge pgnum_label_font_settings),
+                    ({ text: pgnum_label, anchor: entry_anchor }.merge pgnum_label_font_settings),
                   ], line_metrics, align: :right
                 end
               else
-                typeset_formatted_text [{ text: pgnum_label, color: @font_color, anchor: sect_anchor }], line_metrics, align: :right
+                typeset_formatted_text [{ text: pgnum_label, color: @font_color, anchor: entry_anchor }], line_metrics, align: :right
               end
               move_cursor_to end_cursor
             end
           end
           indent @theme.toc_indent do
-            inscribe_toc_level sect.sections, num_levels_for_sect, dot_leader, num_front_matter_pages
-          end if num_levels_for_sect > sect.level
+            ink_toc_level (get_entries_for_toc entry), num_levels_for_entry, dot_leader, num_front_matter_pages
+          end if num_levels_for_entry >= entry_level
         end
       end
 
@@ -3275,15 +3465,15 @@ module Asciidoctor
         icon_data
       end
 
-      # TODO: delegate to inscribe_page_header and inscribe_page_footer per page
-      def inscribe_running_content periphery, doc, skip = [1, 1], body_start_page_number = 1
+      # TODO: delegate to ink_page_header and ink_page_footer per page
+      def ink_running_content periphery, doc, skip = [1, 1], body_start_page_number = 1
         skip_pages, skip_pagenums = skip
         # NOTE: find and advance to first non-imported content page to use as model page
-        return unless (content_start_page = state.pages[skip_pages..-1].index {|it| !it.imported_page? })
-        content_start_page += (skip_pages + 1)
+        return unless (content_start_page_number = state.pages[skip_pages..-1].index {|it| !it.imported_page? })
+        content_start_page_number += (skip_pages + 1)
         num_pages = page_count
         prev_page_number = page_number
-        go_to_page content_start_page
+        go_to_page content_start_page_number
 
         # FIXME: probably need to treat doctypes differently
         is_book = doc.doctype == 'book'
@@ -3379,7 +3569,7 @@ module Asciidoctor
         pagenums_enabled = doc.attr? 'pagenums'
         periphery_layout_cache = {}
         # NOTE: this block is invoked during PDF generation, after #write -> #render_file and thus after #convert_document
-        repeat (content_start_page..num_pages), dynamic: true do
+        repeat (content_start_page_number..num_pages), dynamic: true do
           pgnum = page_number
           # NOTE: don't write on pages which are imported / inserts (otherwise we can get a corrupt PDF)
           next if page.imported_page? || (disable_on_pages.include? pgnum)
@@ -3416,7 +3606,7 @@ module Asciidoctor
           theme_font periphery do
             canvas do
               bounding_box [trim_styles[:content_left][side], trim_styles[:top][side]], width: trim_styles[:content_width][side], height: trim_styles[:height] do
-                if (trim_column_rule_width = trim_styles[:column_rule_width]) > 0
+                if trim_styles[:column_rule_color] && (trim_column_rule_width = trim_styles[:column_rule_width]) > 0
                   trim_column_rule_spacing = trim_styles[:column_rule_spacing]
                 else
                   trim_column_rule_width = nil
@@ -3468,8 +3658,9 @@ module Asciidoctor
                         content = apply_subs_discretely doc, content, drop_lines_with_unresolved_attributes: true, imagesdir: @themesdir
                         content = transform_text content, @text_transform if @text_transform
                       end
-                      formatted_text_box (parse_text content, color: @font_color, inline_format: [normalize: true]),
+                      formatted_text_box (parse_text content, inline_format: [normalize: true]),
                         at: [left, bounds.top - trim_styles[:padding][side][0] - trim_styles[:content_offset] + ((Array trim_styles[:valign])[0] == :center ? font.descender * 0.5 : 0)],
+                        color: @font_color,
                         width: colwidth,
                         height: trim_styles[:prose_content_height][side],
                         align: colspec[:align],
@@ -3501,7 +3692,7 @@ module Asciidoctor
           trim_content_margin_recto = @theme[%(#{periphery}_recto_content_margin)] || @theme[%(#{periphery}_content_margin)] || [0, 'inherit', 0, 'inherit']
           trim_content_margin_recto = (expand_margin_value trim_content_margin_recto).map.with_index {|v, i| i.odd? && v == 'inherit' ? page_margin_recto[i] - trim_margin_recto[i] : v.to_f }
           if (trim_padding_recto = @theme[%(#{periphery}_recto_padding)] || @theme[%(#{periphery}_padding)])
-            trim_padding_recto = (expand_margin_value trim_padding_recto).map.with_index {|v, i| v + trim_content_margin_recto[i] }
+            trim_padding_recto = (expand_padding_value trim_padding_recto).map.with_index {|v, i| v + trim_content_margin_recto[i] }
           else
             trim_padding_recto = trim_content_margin_recto
           end
@@ -3511,7 +3702,7 @@ module Asciidoctor
           trim_content_margin_verso = @theme[%(#{periphery}_verso_content_margin)] || @theme[%(#{periphery}_content_margin)] || [0, 'inherit', 0, 'inherit']
           trim_content_margin_verso = (expand_margin_value trim_content_margin_verso).map.with_index {|v, i| i.odd? && v == 'inherit' ? page_margin_verso[i] - trim_margin_verso[i] : v.to_f }
           if (trim_padding_verso = @theme[%(#{periphery}_verso_padding)] || @theme[%(#{periphery}_padding)])
-            trim_padding_verso = (expand_margin_value trim_padding_verso).map.with_index {|v, i| v + trim_content_margin_verso[i] }
+            trim_padding_verso = (expand_padding_value trim_padding_verso).map.with_index {|v, i| v + trim_content_margin_verso[i] }
           else
             trim_padding_verso = trim_content_margin_verso
           end
@@ -3524,12 +3715,12 @@ module Asciidoctor
             # NOTE: we've already verified this property is set
             height: (trim_height = @theme[%(#{periphery}_height)]),
             bg_color: (resolve_theme_color %(#{periphery}_background_color).to_sym),
-            border_color: (trim_border_color = resolve_theme_color %(#{periphery}_border_color).to_sym),
+            border_width: (trim_border_width = @theme[%(#{periphery}_border_width)] || 0),
+            border_color: trim_border_width > 0 ? (resolve_theme_color %(#{periphery}_border_color).to_sym, @theme.base_border_color) : nil,
             border_style: (@theme[%(#{periphery}_border_style)]&.to_sym || :solid),
-            border_width: (trim_border_width = trim_border_color ? @theme[%(#{periphery}_border_width)] || @theme.base_border_width : 0),
-            column_rule_color: (trim_column_rule_color = resolve_theme_color %(#{periphery}_column_rule_color).to_sym),
+            column_rule_width: (trim_column_rule_width = @theme[%(#{periphery}_column_rule_width)] || 0),
+            column_rule_color: trim_column_rule_width > 0 ? (resolve_theme_color %(#{periphery}_column_rule_color).to_sym) : nil,
             column_rule_style: (@theme[%(#{periphery}_column_rule_style)]&.to_sym || :solid),
-            column_rule_width: (trim_column_rule_color ? @theme[%(#{periphery}_column_rule_width)] || 0 : 0),
             column_rule_spacing: (@theme[%(#{periphery}_column_rule_spacing)] || 0),
             valign: valign_offset ? [valign, valign_offset] : valign,
             img_valign: @theme[%(#{periphery}_image_vertical_align)],
@@ -3697,8 +3888,9 @@ module Asciidoctor
         outline.define do
           initial_pagenum = has_front_cover ? 2 : 1
           # FIXME: use sanitize: :plain_text on Document#doctitle once available
-          if document.page_count >= initial_pagenum && (doctitle = document.resolve_doctitle doc)
-            page title: (document.sanitize doctitle), destination: (document.dest_top initial_pagenum)
+          if document.page_count >= initial_pagenum && (outline_title = doc.attr 'outline-title') &&
+              (outline_title.empty? ? (outline_title = document.resolve_doctitle doc) : outline_title)
+            page title: (document.sanitize outline_title), destination: (document.dest_top initial_pagenum)
           end
           # QUESTION: is there any way to get add_outline_level to invoke in the context of the outline?
           document.add_outline_level self, doc.sections, num_levels, expand_levels
@@ -3760,7 +3952,14 @@ module Asciidoctor
           pdf_doc.render_file target
           # QUESTION: restore attributes first?
           @pdfmark&.generate_file target
-          (Optimizer.new @optimize, pdf_doc.min_version).optimize_file target if @optimize
+          if (quality = @optimize)
+            if quality.include? ','
+              quality, compliance = quality.split ',', 2
+            elsif quality.include? '/'
+              quality, compliance = nil, quality
+            end
+            (Optimizer.new quality, pdf_doc.min_version, compliance).optimize_file target
+          end
           to_file = true
         end
         if !ENV['KEEP_ARTIFACTS']
@@ -3812,7 +4011,7 @@ module Asciidoctor
       end
 
       def resolve_text_transform key, use_fallback = true
-        if (transform = ::Hash === key ? (key.delete :text_transform) : @theme[key.to_s])
+        if (transform = ::Hash === key ? (key.delete :text_transform) : @theme[key])
           transform == 'none' ? nil : transform
         elsif use_fallback
           @text_transform
@@ -3821,9 +4020,9 @@ module Asciidoctor
 
       # QUESTION: should we pass a category as an argument?
       # QUESTION: should we make this a method on the theme ostruct? (e.g., @theme.resolve_color key, fallback)
-      def resolve_theme_color key, fallback_color = nil
-        if (color = @theme[key.to_s]) && color != 'transparent'
-          color
+      def resolve_theme_color key, fallback_color = nil, transparent_color = fallback_color
+        if (color = @theme[key])
+          color == 'transparent' ? transparent_color : color
         else
           fallback_color
         end
@@ -3834,7 +4033,7 @@ module Asciidoctor
       end
 
       def theme_fill_and_stroke_bounds category, opts = {}
-        fill_and_stroke_bounds opts[:background_color], @theme[%(#{category}_border_color)],
+        fill_and_stroke_bounds opts[:background_color], @theme[%(#{category}_border_color)] || @theme.base_border_color,
           line_width: @theme[%(#{category}_border_width)],
           line_style: (@theme[%(#{category}_border_style)]&.to_sym || :solid),
           radius: @theme[%(#{category}_border_radius)]
@@ -3843,7 +4042,7 @@ module Asciidoctor
       def theme_fill_and_stroke_block category, extent, opts = {}
         node_with_caption = nil unless (node_with_caption = opts[:caption_node])&.title?
         unless extent
-          inscribe_caption node_with_caption, category: category if node_with_caption
+          ink_caption node_with_caption, category: category if node_with_caption
           return
         end
         if (b_width = (opts.key? :border_width) ? opts[:border_width] : @theme[%(#{category}_border_width)])
@@ -3857,14 +4056,12 @@ module Asciidoctor
           bg_color = nil
         end
         unless b_width || bg_color
-          inscribe_caption node_with_caption, category: category if node_with_caption
+          ink_caption node_with_caption, category: category if node_with_caption
           return
         end
-        if (b_color = @theme[%(#{category}_border_color)]) == 'transparent'
-          b_color = @page_bg_color
-        end
+        b_color = resolve_theme_color %(#{category}_border_color).to_sym, @theme.base_border_color, @page_bg_color
         b_radius ||= (@theme[%(#{category}_border_radius)] || 0) + (b_width || 0)
-        if b_width && b_color
+        if b_width
           if b_color == @page_bg_color # let page background cut into block background
             b_gap_color, b_shift = @page_bg_color, (b_width * 0.5)
           elsif (b_gap_color = bg_color) && b_gap_color != b_color
@@ -3875,7 +4072,7 @@ module Asciidoctor
         else # let page background cut into block background; guarantees b_width is set
           b_shift, b_gap_color = (b_width ||= 0.5) * 0.5, @page_bg_color
         end
-        inscribe_caption node_with_caption, category: category if node_with_caption
+        ink_caption node_with_caption, category: category if node_with_caption
         extent.from.page += 1 unless extent.from.page == page_number # sanity check
         float do
           extent.each_page do |first_page, last_page|
@@ -4012,9 +4209,7 @@ module Asciidoctor
         # NOTE: it also removes zero-width spaces
         arranger.finalize_line
         actual_width = width_of_fragments arranger.fragments
-        unless ::Array === (padding = @theme[%(#{category}_padding)])
-          padding = ::Array.new 4, padding
-        end
+        padding = expand_padding_value @theme[%(#{category}_padding)]
         if actual_width > (available_width = bounds.width - padding[3].to_f - padding[1].to_f)
           adjusted_font_size = ((available_width * font_size).to_f / actual_width).truncate 4
           if (min = @theme[%(#{category}_font_size_min)] || @theme.base_font_size_min) && adjusted_font_size < min
@@ -4088,9 +4283,10 @@ module Asciidoctor
 
       # TODO: document me, esp the first line formatting functionality
       def typeset_text string, line_metrics, opts = {}
-        move_down line_metrics.padding_top
         opts = { leading: line_metrics.leading, final_gap: line_metrics.final_gap }.merge opts
         string = string.gsub CjkLineBreakRx, ZeroWidthSpace if @cjk_line_breaks
+        return text_box string, opts if opts[:height]
+        move_down line_metrics.padding_top
         if (hanging_indent = (opts.delete :hanging_indent) || 0) > 0
           indent hanging_indent do
             text string, (opts.merge indent_paragraphs: -hanging_indent)
@@ -4254,10 +4450,11 @@ module Asciidoctor
         end
       end
 
-      def resolve_alignment_from_role roles, use_theme: false
+      def resolve_text_align_from_role roles, query_theme: false, remove_predefined: false
         if (align_role = roles.reverse.find {|r| TextAlignmentRoles.include? r })
+          roles.replace roles - TextAlignmentRoles if remove_predefined
           (align_role.slice 5, align_role.length).to_sym
-        elsif use_theme
+        elsif query_theme
           roles.reverse.each do |role|
             if (align = @theme[%(role_#{role}_text_align)])
               return align.to_sym
@@ -4267,6 +4464,9 @@ module Asciidoctor
         end
       end
 
+      # Deprecated
+      alias resolve_alignment_from_role resolve_text_align_from_role
+
       # QUESTION: is this method still necessary?
       def resolve_imagesdir doc
         if (imagesdir = doc.attr 'imagesdir').nil_or_empty? || (imagesdir = imagesdir.chomp '/') == '.'
@@ -4596,24 +4796,35 @@ module Asciidoctor
       end
 
       # Deprecated method names
-      alias layout_footnotes inscribe_footnotes
-      alias layout_title_page inscribe_title_page
-      alias layout_cover_page inscribe_cover_page
-      alias layout_chapter_title inscribe_chapter_title
-      alias layout_part_title inscribe_part_title
-      alias layout_general_heading inscribe_general_heading
-      alias layout_heading inscribe_heading
-      alias layout_prose inscribe_prose
-      alias layout_caption inscribe_caption
-      alias layout_table_caption inscribe_table_caption
-      alias layout_toc inscribe_toc
-      alias layout_toc_level inscribe_toc_level
-      alias layout_running_content inscribe_running_content
-
-      def self.method_added method
-        if (method_name = method.to_s).start_with? 'layout_'
-          alias_method %(inscribe_#{method_name.slice 7, method_name.length}).to_sym, method
-        end
+      alias layout_footnotes ink_footnotes
+      alias layout_title_page ink_title_page
+      alias layout_cover_page ink_cover_page
+      alias layout_chapter_title ink_chapter_title
+      alias layout_part_title ink_part_title
+      alias layout_general_heading ink_general_heading
+      alias layout_heading ink_heading
+      alias layout_prose ink_prose
+      alias layout_caption ink_caption
+      alias layout_table_caption ink_table_caption
+      alias layout_toc ink_toc
+      alias layout_toc_level ink_toc_level
+      alias layout_running_content ink_running_content
+
+      # intercepts "class CustomPDFConverter < (Asciidoctor::Converter.for 'pdf')"
+      def self.method_added method_sym
+        if (method_name = method_sym.to_s).start_with? 'layout_'
+          alias_method %(ink_#{method_name.slice 7, method_name.length}).to_sym, method_sym
+        elsif method_name == 'convert_listing_or_literal' || method_name == 'convert_code'
+          alias_method :convert_listing, method_sym
+          alias_method :convert_literal, method_sym
+        end
+      end
+
+      # intercepts "(Asciidoctor::Converter.for 'pdf').prepend CustomConverterExtensions"
+      def self.prepend *mods
+        super
+        mods.each {|mod| (mod.instance_methods false).each {|method| method_added method } }
+        self
       end
 
       private