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

data/lib/asciidoctor/pdf/converter.rb

@@ -164,8 +164,11 @@ module Asciidoctor
         if node.blocks?
           node.content
         elsif node.content_model != :compound && (string = node.content)
-          # TODO: this content could be cached on repeat invocations!
-          layout_prose string, (opts.merge hyphenate: true, margin_bottom: 0)
+          prose_opts = opts.merge hyphenate: true, margin_bottom: 0
+          if (bottom_gutter = @bottom_gutters[-1][node])
+            prose_opts[:bottom_gutter] = bottom_gutter
+          end
+          inscribe_prose string, prose_opts
         end
       ensure
         node.document.instance_variable_set :@converter, prev_converter if prev_converter
@@ -187,25 +190,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
-        layout_cover_page doc, :front
+        inscribe_cover_page doc, :front
         has_front_cover = page_number > marked_page_number
-
-        if (use_title_page = doc.doctype == 'book' || (doc.attr? 'title-page'))
-          layout_title_page doc
-          has_title_page = page_number == (has_front_cover ? 2 : 1)
-        end
+        has_title_page = inscribe_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: font must be set before content is written to the main or scratch document
+        # 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
         font @theme.base_font_family, size: @root_font_size, style: @theme.base_font_style unless has_title_page
 
-        unless use_title_page
+        unless title_page_on
           body_start_page_number = page_number
           theme_font :heading, level: 1 do
-            layout_general_heading doc, doc.doctitle, align: (@theme.heading_h1_align&.to_sym || :center), level: 1, role: :doctitle
+            inscribe_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,14 +216,14 @@ 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, use_title_page
+            allocate_toc doc, toc_num_levels, cursor, title_page_on
           else
             @toc_extent = nil
           end
 
           start_new_page if @ppbook && verso_page? && !(((next_block = doc.blocks[0])&.context == :preamble ? next_block.blocks[0] : next_block)&.option? 'nonfacing')
 
-          if use_title_page
+          if title_page_on
             zero_page_offset = has_front_cover ? 1 : 0
             first_page_offset = has_title_page ? zero_page_offset.next : zero_page_offset
             body_offset = (body_start_page_number = page_number) - 1
@@ -301,14 +301,14 @@ module Asciidoctor
           traverse doc
 
           # NOTE: for a book, these are leftover footnotes; for an article this is everything
-          outdent_section { layout_footnotes doc }
+          outdent_section { inscribe_footnotes doc }
 
           if @toc_extent
-            if use_title_page && !insert_toc
+            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'
             end
-            toc_page_nums = layout_toc doc, toc_num_levels, @toc_extent.from.page, @toc_extent.from.cursor, num_front_matter_pages[1]
+            toc_page_nums = inscribe_toc doc, toc_num_levels, @toc_extent.from.page, @toc_extent.from.cursor, num_front_matter_pages[1]
           else
             toc_page_nums = []
           end
@@ -319,8 +319,8 @@ module Asciidoctor
         end
 
         unless page_count < body_start_page_number
-          layout_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
-          layout_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
+          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
         end
 
         add_outline doc, (doc.attr 'outlinelevels', toc_num_levels), toc_page_nums, num_front_matter_pages[1], has_front_cover
@@ -337,7 +337,7 @@ module Asciidoctor
         catalog.data[:ViewerPreferences] = { DisplayDocTitle: true }
 
         stamp_foreground_image doc, has_front_cover
-        layout_cover_page doc, :back
+        inscribe_cover_page doc, :back
         add_dest_for_top doc
         nil
       end
@@ -402,7 +402,7 @@ module Asciidoctor
         @font_scale = 1
         @font_color = theme.base_font_color
         @text_decoration_width = theme.base_text_decoration_width
-        @base_align = (align = doc.attr 'text-align') && (TextAlignmentNames.include? align) ? align : theme.base_align
+        @base_text_align = (align = doc.attr 'text-align') && (TextAlignmentNames.include? align) ? align : theme.base_text_align
         @base_line_height = theme.base_line_height
         @cjk_line_breaks = doc.attr? 'scripts', 'cjk'
         if (hyphen_lang = doc.attr 'hyphens') &&
@@ -415,6 +415,7 @@ module Asciidoctor
         @text_transform = nil
         @list_numerals = []
         @list_bullets = []
+        @bottom_gutters = [{}]
         @rendered_footnotes = []
         @conum_glyphs = ConumSets[@theme.conum_glyphs || 'circled'] || (@theme.conum_glyphs.split ',').map do |r|
           from, to = r.lstrip.split '-', 2
@@ -661,22 +662,23 @@ module Asciidoctor
           title = %(#{title}\n<em class="subtitle">#{subtitle}</em>)
         end
         hlevel = sect.level + 1
-        align = (@theme[%(heading_h#{hlevel}_align)] || @theme.heading_align || @base_align).to_sym
+        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))
-        hopts = { align: align, level: hlevel, outdent: !(part || chapterlike) }
+        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
-            theme_font(:heading, level: hlevel) { start_new_part sect }
+            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
-            theme_font(:heading, level: hlevel) { start_new_chapter sect }
+            start_new_chapter sect
           end
         end
-        arrange_section sect, title, hopts unless start_new || at_page_top?
+        arrange_section sect, title, hopts unless hidden || start_new || at_page_top?
         # 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?
@@ -685,20 +687,20 @@ 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
-            layout_part_title sect, title, hopts
+            inscribe_part_title sect, title, hopts
           elsif chapterlike
-            layout_chapter_title sect, title, hopts unless sect.special && (sect.option? 'untitled')
+            inscribe_chapter_title sect, title, hopts
           else
-            layout_general_heading sect, title, hopts
+            inscribe_general_heading sect, title, hopts
           end
-        end
+        end unless hidden
 
         if index_section
           outdent_section { convert_index_section sect }
         else
           traverse sect
         end
-        outdent_section { layout_footnotes sect } if chapterlike
+        outdent_section { inscribe_footnotes sect } if chapterlike
         sect.set_attr 'pdf-page-end', page_number
       end
 
@@ -719,7 +721,7 @@ module Asciidoctor
       end
 
       # QUESTION: if a footnote ref appears in a separate chapter, should the footnote def be duplicated?
-      def layout_footnotes node
+      def inscribe_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
@@ -728,7 +730,7 @@ module Asciidoctor
             move_down delta
           end
           theme_font :footnotes do
-            (title = doc.attr 'footnotes-title') && (layout_caption title, category: :footnotes)
+            (title = doc.attr 'footnotes-title') && (inscribe_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')
@@ -738,7 +740,7 @@ module Asciidoctor
                 fn.singleton_class.send :attr_accessor, :label unless fn.respond_to? :label=
                 fn.label = %(#{label} - #{sect_xreftext})
               end
-              layout_prose %(<a id="_footnotedef_#{index}">#{DummyText}</a>[<a anchor="_footnoteref_#{index}">#{label}</a>] #{fn.text}), margin_bottom: item_spacing, hyphenate: true
+              inscribe_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
@@ -750,11 +752,11 @@ module Asciidoctor
         add_dest_for_block node if node.id
         hlevel = node.level.next
         unless (align = resolve_alignment_from_role node.roles)
-          align = (@theme[%(heading_h#{hlevel}_align)] || @theme.heading_align || @base_align).to_sym
+          align = (@theme[%(heading_h#{hlevel}_text_align)] || @theme.heading_text_align || @base_text_align).to_sym
         end
         # QUESTION: should we decouple styles from section titles?
         theme_font :heading, level: hlevel do
-          layout_general_heading node, node.title, align: align, level: hlevel, outdent: (node.parent.context == :section)
+          inscribe_general_heading node, node.title, align: align, level: hlevel, outdent: (node.parent.context == :section)
         end
       end
 
@@ -763,10 +765,10 @@ module Asciidoctor
         outdent_section do
           pad_box @theme.abstract_padding do
             theme_font :abstract_title do
-              layout_prose node.title, align: (@theme.abstract_title_align || @base_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)
+              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)
             end if node.title?
             theme_font :abstract do
-              prose_opts = { align: (@theme.abstract_align || @base_align).to_sym, hyphenate: true }
+              prose_opts = { align: (@theme.abstract_text_align || @base_text_align).to_sym, hyphenate: true }
               if (text_indent = @theme.prose_text_indent) > 0
                 prose_opts[:indent_paragraphs] = text_indent
               end
@@ -785,7 +787,7 @@ module Asciidoctor
                   if child.context == :paragraph
                     child.document.playback_attributes child.attributes
                     prose_opts[:margin_bottom] = 0 if child == last_block
-                    layout_prose child.content, ((align = resolve_alignment_from_role child.roles) ? (prose_opts.merge align: align) : prose_opts.dup)
+                    inscribe_prose child.content, ((align = resolve_alignment_from_role child.roles) ? (prose_opts.merge align: align) : prose_opts.dup)
                     prose_opts.delete :first_line_options
                     prose_opts.delete :margin_bottom
                   else
@@ -797,7 +799,7 @@ module Asciidoctor
                 if (align = resolve_alignment_from_role node.roles)
                   prose_opts[:align] = align
                 end
-                layout_prose string, (prose_opts.merge margin_bottom: 0)
+                inscribe_prose string, (prose_opts.merge margin_bottom: 0)
               end
             end
           end
@@ -809,7 +811,7 @@ module Asciidoctor
       def convert_preamble node
         # FIXME: core should not be promoting paragraph to preamble if there are no sections
         if node.blocks? && (first_block = node.blocks[0]).context == :paragraph && node.document.sections? && !first_block.role?
-          first_block.add_role 'lead'
+          first_block.role = 'lead'
         end
         traverse node
         theme_margin :block, :bottom, (next_enclosed_block node)
@@ -832,13 +834,17 @@ module Asciidoctor
 
         # TODO: check if we're within one line of the bottom of the page
         # and advance to the next page if so (similar to logic for section titles)
-        layout_caption node, labeled: false if node.title?
+        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?
-          layout_prose node.content, prose_opts
+          inscribe_prose node.content, prose_opts
         else
           theme_font_cascade (roles.map {|role| %(role_#{role}).to_sym }) do
-            layout_prose node.content, prose_opts
+            inscribe_prose node.content, prose_opts
           end
         end
 
@@ -852,7 +858,7 @@ module Asciidoctor
 
       def convert_admonition node
         type = node.attr 'name'
-        label_align = @theme.admonition_label_align&.to_sym || :center
+        label_align = @theme.admonition_label_text_align&.to_sym || :center
         # TODO: allow vertical_align to be a number
         if (label_valign = @theme.admonition_label_vertical_align&.to_sym || :middle) == :middle
           label_valign = :center
@@ -861,18 +867,21 @@ module Asciidoctor
           label_min_width = label_min_width.to_f
         end
         if (doc = node.document).attr? 'icons'
-          if (doc.attr 'icons') == 'font' && !(node.attr? 'icon')
+          if !(has_icon = node.attr? 'icon') && (doc.attr 'icons') == 'font'
             icons = 'font'
             label_text = type.to_sym
             icon_data = admonition_icon_data label_text
             icon_size = icon_data[:size] || 24
             label_width = label_min_width || (icon_size * 1.5)
-          elsif (icon_path = resolve_icon_image_path node, type) && (::File.readable? icon_path)
+          elsif (icon_path = has_icon || !(icon_path = (@theme[%(admonition_icon_#{type})] || {})[:image]) ?
+              (resolve_icon_image_path node, type) :
+              (ThemeLoader.resolve_theme_asset (apply_subs_discretely doc, icon_path, subs: [:attributes]), @themesdir)) &&
+              (::File.readable? icon_path)
             icons = true
             # TODO: introduce @theme.admonition_image_width? or use size key from admonition_icon_<name>?
             label_width = label_min_width || 36.0
           else
-            log :warn, %(admonition icon not found or not readable: #{icon_path || (resolve_icon_image_path node, type, false)})
+            log :warn, %(admonition icon image#{has_icon ? '' : ' for ' + type.upcase} not found or not readable: #{icon_path || (resolve_icon_image_path node, type, false)})
           end
         end
         unless icons
@@ -945,7 +954,7 @@ module Asciidoctor
                           log :warn, %(problem encountered in image: #{icon_path}; #{icon_warning})
                         end unless scratch?
                       rescue
-                        log :warn, %(could not embed admonition icon: #{icon_path}; #{$!.message})
+                        log :warn, %(could not embed admonition icon image: #{icon_path}; #{$!.message})
                         icons = nil
                       end
                     else
@@ -959,7 +968,7 @@ module Asciidoctor
                         end
                         embed_image image_obj, image_info, width: icon_width, position: label_align, vposition: label_valign
                       rescue
-                        log :warn, %(could not embed admonition icon: #{icon_path}; #{$!.message})
+                        log :warn, %(could not embed admonition icon image: #{icon_path}; #{$!.message})
                         icons = nil
                       end
                     end
@@ -987,7 +996,7 @@ module Asciidoctor
                         end
                       end
                       @text_transform = nil # already applied to label
-                      layout_prose label_text,
+                      inscribe_prose label_text,
                         align: label_align,
                         valign: label_valign,
                         line_height: 1,
@@ -1000,8 +1009,8 @@ module Asciidoctor
                 end
               end
             end
-            pad_box [cpad[0], 0, cpad[2], label_width + lpad[1] + cpad[3]] do
-              layout_caption node, category: :admonition, labeled: false if node.title?
+            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?
               theme_font :admonition do
                 traverse node
               end
@@ -1018,7 +1027,7 @@ module Asciidoctor
           tare_first_page_content_stream do
             theme_fill_and_stroke_block :example, extent, caption_node: node
           end
-          pad_box @theme.example_padding do
+          pad_box @theme.example_padding, node do
             theme_font :example do
               traverse node
             end
@@ -1035,13 +1044,13 @@ module Asciidoctor
           arrange_block node do
             add_dest_for_block node if id
             tare_first_page_content_stream do
-              node.context == :example ? (layout_caption %(\u25bc #{node.title})) : (layout_caption node, labeled: false)
+              node.context == :example ? (inscribe_caption %(\u25bc #{node.title})) : (inscribe_caption node, labeled: false)
             end if has_title
             traverse node
           end
         else
           add_dest_for_block node if id
-          node.context == :example ? (layout_caption %(\u25bc #{node.title})) : (layout_caption node, labeled: false) if has_title
+          node.context == :example ? (inscribe_caption %(\u25bc #{node.title})) : (inscribe_caption node, labeled: false) if has_title
           traverse node
         end
       end
@@ -1055,6 +1064,13 @@ module Asciidoctor
           b_left_width = nil
           b_width = nil if (b_width = @theme[%(#{category}_border_width)]) == 0
         end
+        if (attribution = (node.attr? 'attribution') && (node.attr 'attribution'))
+          # NOTE: temporary workaround to allow bare & to be used without having to wrap value in single quotes
+          attribution = escape_amp attribution if attribution.include? '&'
+          if (citetitle = node.attr 'citetitle') && (citetitle.include? '&')
+            citetitle = escape_amp citetitle
+          end
+        end
         arrange_block node do |extent|
           add_dest_for_block node if node.id
           tare_first_page_content_stream do
@@ -1072,27 +1088,25 @@ module Asciidoctor
               end
             end
           end
-          pad_box @theme[%(#{category}_padding)] do
+          pad_box @theme[%(#{category}_padding)], (attribution ? nil : node) do
             theme_font category do
               if category == :quote
                 traverse node
               else # :verse
                 content = guard_indentation node.content
-                layout_prose content, normalize: false, align: :left, hyphenate: true, margin_bottom: 0
+                inscribe_prose content,
+                  normalize: false,
+                  align: :left,
+                  hyphenate: true,
+                  margin_bottom: 0,
+                  bottom_gutter: (attribution ? nil : @bottom_gutters[-1][node])
               end
             end
-            if node.attr? 'attribution'
+            if attribution
               margin_bottom @theme.block_margin_bottom
               theme_font %(#{category}_cite) do
-                # NOTE: temporary workaround to allow bare & to be used without having to wrap value in single quotes
-                attribution = node.attr 'attribution'
-                attribution = escape_amp attribution if attribution.include? '&'
-                attribution_parts = [attribution]
-                if (citetitle = node.attr 'citetitle')
-                  citetitle = escape_amp citetitle if citetitle.include? '&'
-                  attribution_parts << citetitle
-                end
-                layout_prose %(#{EmDash} #{attribution_parts.join ', '}), align: :left, normalize: false, margin_bottom: 0
+                attribution_parts = citetitle ? [attribution, citetitle] : [attribution]
+                inscribe_prose %(#{EmDash} #{attribution_parts.join ', '}), align: :left, normalize: false, margin_bottom: 0
               end
             end
           end
@@ -1107,10 +1121,10 @@ module Asciidoctor
         arrange_block node do |extent|
           add_dest_for_block node if node.id
           theme_fill_and_stroke_block :sidebar, extent if extent
-          pad_box @theme.sidebar_padding do
+          pad_box @theme.sidebar_padding, node do
             theme_font :sidebar_title do
               # QUESTION: should we allow margins of sidebar title to be customized?
-              layout_prose node.title, align: (@theme.sidebar_title_align || @theme.heading_align || @base_align).to_sym, margin_bottom: @theme.heading_margin_bottom, line_height: (@theme.heading_line_height || @theme.base_line_height)
+              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)
             end if node.title?
             theme_font :sidebar do
               traverse node
@@ -1149,7 +1163,7 @@ module Asciidoctor
           marker_width = rendered_width_of_string %(#{marker = conum_glyph index}x)
           float do
             bounding_box [0, cursor], width: marker_width do
-              layout_prose marker, align: :center, inline_format: false, margin: 0
+              inscribe_prose marker, align: :center, inline_format: false, margin: 0
             end
           end
         end
@@ -1233,7 +1247,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.layout_table_caption node if node.title?
+            @pdf.inscribe_table_caption node if node.title?
           end
           theme_margin :prose, :bottom, (next_enclosed_block actual_node) #unless actual_node.nested?
         when 'qanda'
@@ -1243,7 +1257,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)
-          layout_caption node, category: :description_list, labeled: false if node.title?
+          inscribe_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' }
@@ -1255,8 +1269,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 layout_prose
-                layout_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 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
               end
             end
             indent @theme.description_list_description_indent do
@@ -1343,7 +1357,7 @@ module Asciidoctor
       def convert_list node
         # TODO: check if we're within one line of the bottom of the page
         # and advance to the next page if so (similar to logic for section titles)
-        layout_caption node, category: :list, labeled: false if node.title?
+        inscribe_caption node, category: :list, labeled: false if node.title?
 
         opts = {}
         if (align = resolve_alignment_from_role node.roles)
@@ -1440,7 +1454,7 @@ module Asciidoctor
             float do
               advance_page if @media == 'prepress' && cursor < marker_height
               flow_bounding_box position: start_position, width: marker_width do
-                layout_prose marker,
+                inscribe_prose marker,
                   align: :right,
                   character_spacing: -0.5,
                   color: marker_style[:font_color],
@@ -1468,16 +1482,16 @@ module Asciidoctor
       def traverse_list_item node, list_type, opts = {}
         if list_type == :dlist # qanda
           terms, desc = node
-          terms.each {|term| layout_prose %(<em>#{term.text}</em>), (opts.merge margin_bottom: @theme.description_list_term_spacing) }
+          terms.each {|term| inscribe_prose %(<em>#{term.text}</em>), (opts.merge margin_bottom: @theme.description_list_term_spacing) }
           if desc
-            layout_prose desc.text, (opts.merge hyphenate: true) if desc.text?
+            inscribe_prose desc.text, (opts.merge hyphenate: true) if desc.text?
             traverse desc
           end
         else
           if (primary_text = node.text).nil_or_empty?
-            layout_prose DummyText, opts unless node.blocks?
+            inscribe_prose DummyText, opts unless node.blocks?
           else
-            layout_prose primary_text, (opts.merge hyphenate: true)
+            inscribe_prose primary_text, (opts.merge hyphenate: true)
           end
           traverse node
         end
@@ -1498,24 +1512,33 @@ module Asciidoctor
         elsif (image_path = resolve_image_path node, target, image_format, (opts.fetch :relative_to_imagesdir, true))
           if image_format == 'pdf'
             if ::File.readable? image_path
-              if (id = node.id)
+              if (replace = page.empty?) && ((parent = node.parent).attr? 'pdf-page-start', page_number) && (parent.attr? 'pdf-anchor')
+                replace_parent = parent
+              end
+              if (id = node.id) || replace_parent
                 add_dest_block = proc do
-                  node.set_attr 'pdf-destination', (node_dest = dest_top)
-                  add_dest id, node_dest
+                  node_dest = dest_top
+                  if id
+                    node.set_attr 'pdf-destination', node_dest
+                    add_dest id, node_dest
+                  end
+                  if replace_parent
+                    replace_parent.set_attr 'pdf-destination', node_dest
+                    add_dest (replace_parent.attr 'pdf-anchor'), node_dest
+                  end
                 end
               end
               # NOTE: import_page automatically advances to next page afterwards
-              # QUESTION: should we add destination to top of imported page?
               if (pgnums = node.attr 'pages')
                 (resolve_pagenums pgnums).each_with_index do |pgnum, idx|
                   if idx == 0
-                    import_page image_path, page: pgnum, replace: page.empty?, &add_dest_block
+                    import_page image_path, page: pgnum, replace: replace, &add_dest_block
                   else
                     import_page image_path, page: pgnum, replace: true
                   end
                 end
               else
-                import_page image_path, page: [(node.attr 'page', nil, 1).to_i, 1].max, replace: page.empty?, &add_dest_block
+                import_page image_path, page: [(node.attr 'page', nil, 1).to_i, 1].max, replace: replace, &add_dest_block
               end
               return
             else
@@ -1532,14 +1555,14 @@ module Asciidoctor
 
         alignment = (alignment = node.attr 'align') ?
           ((BlockAlignmentNames.include? alignment) ? alignment.to_sym : :left) :
-          (resolve_alignment_from_role node.roles) || (@theme.image_align&.to_sym || :left)
+          (resolve_alignment_from_role node.roles) || @theme.image_align&.to_sym || :left
         # 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
 
         # NOTE: if width is not set explicitly and max-width is fit-content, caption height may not be accurate
-        caption_h = node.title? ? (layout_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? ? (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
 
         align_to_page = node.option? 'align-to-page'
         pinned = opts[:pinned]
@@ -1622,7 +1645,7 @@ module Asciidoctor
               move_down rendered_h if y == image_y
             end
           end
-          layout_caption node, category: :image, side: :bottom, block_align: alignment, block_width: rendered_w, max_width: @theme.image_caption_max_width if node.title?
+          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
         rescue => e
           raise if ::StopIteration === e
@@ -1662,9 +1685,9 @@ module Asciidoctor
           alignment = (alignment = node.attr 'align') ?
             ((BlockAlignmentNames.include? alignment) ? alignment.to_sym : :left) :
             (resolve_alignment_from_role node.roles) || (@theme.image_align&.to_sym || :left)
-          layout_prose alt_text_template % alt_text_vars, align: alignment, margin: 0, normalize: false, single_line: true
+          inscribe_prose alt_text_template % alt_text_vars, align: alignment, margin: 0, normalize: false, single_line: true
         end
-        layout_caption node, category: :image, side: :bottom if node.title?
+        inscribe_caption node, category: :image, side: :bottom if node.title?
         theme_margin :block, :bottom, (next_enclosed_block node) unless opts[:pinned]
         nil
       end
@@ -1673,8 +1696,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
-        layout_prose %(#{play_symbol}#{NoBreakSpace}<a href="#{audio_path}">#{audio_path}</a> <em>(audio)</em>), normalize: false, margin: 0, single_line: true
-        layout_caption node, labeled: false, side: :bottom if node.title?
+        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?
         theme_margin :block, :bottom, (next_enclosed_block node)
       end
 
@@ -1701,8 +1724,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
-          layout_prose %(#{play_symbol}#{NoBreakSpace}<a href="#{video_path}">#{video_path}</a> <em>(#{type})</em>), normalize: false, margin: 0, single_line: true
-          layout_caption node, labeled: false, side: :bottom if node.title?
+          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?
           theme_margin :block, :bottom, (next_enclosed_block node)
         else
           original_attributes = node.attributes.dup
@@ -1717,7 +1740,8 @@ module Asciidoctor
 
       # QUESTION: can we avoid arranging fragments multiple times (conums & autofit) by eagerly preparing arranger?
       def convert_listing_or_literal node
-        wrap_ext = source_chunks = bg_color_override = font_color_override = adjusted_font_size = nil
+        extensions = []
+        source_chunks = bg_color_override = font_color_override = adjusted_font_size = nil
         theme_font :code do
           # HACK: disable built-in syntax highlighter; must be done before calling node.content!
           if node.style == 'source' && (highlighter = (syntax_hl = node.document.syntax_highlighter)&.highlight? && syntax_hl.name)
@@ -1797,7 +1821,7 @@ module Asciidoctor
               if (node.option? 'linenums') || (node.attr? 'linenums')
                 linenums = (node.attr 'start', 1).to_i
                 postprocess = true
-                wrap_ext = FormattedText::SourceWrap
+                extensions << FormattedText::SourceWrap
               elsif conum_mapping || highlight_lines
                 postprocess = true
               end
@@ -1814,7 +1838,7 @@ module Asciidoctor
             else
               if (node.option? 'linenums') || (node.attr? 'linenums')
                 formatter_opts = { line_numbers: true, start_line: (node.attr 'start', 1).to_i }
-                wrap_ext = FormattedText::SourceWrap
+                extensions << FormattedText::SourceWrap
               else
                 formatter_opts = {}
               end
@@ -1848,14 +1872,13 @@ module Asciidoctor
           tare_first_page_content_stream do
             theme_fill_and_stroke_block :code, extent, background_color: bg_color_override, caption_node: node
           end
-          pad_box @theme.code_padding do
+          pad_box @theme.code_padding, node do
             theme_font :code do
-              ::Prawn::Text::Formatted::Box.extensions << wrap_ext if wrap_ext
               typeset_formatted_text source_chunks, (calc_line_metrics @base_line_height),
                 color: (font_color_override || @theme.code_font_color || @font_color),
-                size: adjusted_font_size
-            ensure
-              ::Prawn::Text::Formatted::Box.extensions.pop if wrap_ext
+                size: adjusted_font_size,
+                bottom_gutter: @bottom_gutters[-1][node],
+                extensions: extensions.empty? ? nil : extensions
             end
           end
         end
@@ -2159,45 +2182,36 @@ module Asciidoctor
           end
         end
 
-        # NOTE: Prawn aborts if table data is empty, so ensure there's at least one row
+        # NOTE: Prawn crashes if table data is empty, so ensure there's at least one row
         if table_data.empty?
           log(:warn) { message_with_context 'no rows found in table', source_location: node.source_location }
           table_data << ::Array.new([node.columns.size, 1].max) { { content: '' } }
         end
 
-        border_width = {}
-        table_border_color = theme.table_border_color || ((Array theme.table_grid_color).size == 2 ? nil : theme.table_grid_color) || theme.base_border_color
-        table_border_style = theme.table_border_style&.to_sym || :solid
-        table_border_width = theme.table_border_width
-        if table_header_size
-          head_border_bottom_color = theme.table_head_border_bottom_color || table_border_color
-          head_border_bottom_style = (theme.table_head_border_bottom_style || table_border_style).to_sym
-          head_border_bottom_width = theme.table_head_border_bottom_width || table_border_width
-        end
-        [:top, :bottom, :left, :right].each {|edge| border_width[edge] = table_border_width }
+        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_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
 
-        table_grid_color = theme.table_grid_color || table_border_color
-        if ::Array === (table_grid_style = theme.table_grid_style || table_border_style)
-          table_grid_style = table_grid_style.map(&:to_sym)
-        else
-          table_grid_style = [table_grid_style.to_sym]
-        end
-        if ::Array === (table_grid_width = theme.table_grid_width || theme.table_border_width)
-          border_width[:rows] = table_grid_width[0]
-          border_width[:cols] = table_grid_width[1]
-        else
-          [:cols, :rows].each {|edge| border_width[edge] = table_grid_width }
+        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]
         end
 
         case (grid = node.attr 'grid', 'all', 'table-grid')
         when 'all'
           # keep inner borders
         when 'cols'
-          border_width[:rows] = 0
+          grid_width[:rows] = 0
         when 'rows'
-          border_width[:cols] = 0
+          grid_width[:cols] = 0
         else # none
-          border_width[:rows] = border_width[:cols] = 0
+          grid_width[:rows] = grid_width[:cols] = 0
         end
 
         case (frame = node.attr 'frame', 'all', 'table-frame')
@@ -2234,13 +2248,8 @@ module Asciidoctor
           header: table_header_size,
           # NOTE: position is handled by this method
           position: :left,
-          cell_style: {
-            # NOTE: the border color and style of the outer frame is set later
-            border_color: table_grid_color,
-            border_lines: table_grid_style,
-            # NOTE: the border width is set later
-            border_width: 0,
-          },
+          # NOTE: the border color, style, and width of the outer frame is set in the table callback block
+          cell_style: { border_color: grid_color.values, border_lines: grid_style.values, border_width: grid_width.values },
           width: table_width,
           column_widths: column_widths,
         }
@@ -2261,7 +2270,7 @@ module Asciidoctor
         table table_data, table_settings do
           # NOTE: call width to capture resolved table width
           table_width = width
-          @pdf.layout_table_caption node, alignment, table_width, caption_max_width if node.title? && caption_side == :top
+          @pdf.inscribe_table_caption node, alignment, table_width, caption_max_width if node.title? && caption_side == :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
@@ -2282,7 +2291,7 @@ module Asciidoctor
             end if table_header_size
           else
             # apply the grid setting first across all cells
-            cells.border_width = [border_width[:rows], border_width[:cols], border_width[:rows], border_width[:cols]]
+            cells.border_width = [grid_width[:rows], grid_width[:cols], grid_width[:rows], grid_width[:cols]]
 
             if table_header_size
               (rows table_header_size - 1).tap do |r|
@@ -2299,19 +2308,19 @@ module Asciidoctor
 
             # top edge of table
             (rows 0).tap do |r|
-              r.border_top_color, r.border_top_line, r.border_top_width = table_border_color, table_border_style, border_width[:top]
+              r.border_top_color, r.border_top_line, r.border_top_width = border_color[:top], border_style[:top], border_width[:top]
             end
             # right edge of table
             (columns num_cols - 1).tap do |r|
-              r.border_right_color, r.border_right_line, r.border_right_width = table_border_color, table_border_style, border_width[:right]
+              r.border_right_color, r.border_right_line, r.border_right_width = border_color[:right], border_style[:right], border_width[:right]
             end
             # bottom edge of table
             (rows num_rows - 1).tap do |r|
-              r.border_bottom_color, r.border_bottom_line, r.border_bottom_width = table_border_color, table_border_style, border_width[:bottom]
+              r.border_bottom_color, r.border_bottom_line, r.border_bottom_width = border_color[:bottom], border_style[:bottom], border_width[:bottom]
             end
             # left edge of table
             (columns 0).tap do |r|
-              r.border_left_color, r.border_left_line, r.border_left_width = table_border_color, table_border_style, border_width[:left]
+              r.border_left_color, r.border_left_line, r.border_left_width = border_color[:left], border_style[:left], border_width[:left]
             end
           end
 
@@ -2334,7 +2343,7 @@ module Asciidoctor
           bounds.subtract_left_padding left_padding
           bounds.subtract_right_padding right_padding if right_padding
         end
-        layout_table_caption node, alignment, table_width, caption_max_width, caption_side if node.title? && caption_side == :bottom
+        inscribe_table_caption node, alignment, table_width, caption_max_width, caption_side if node.title? && caption_side == :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)
@@ -2356,8 +2365,8 @@ 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, (use_title_page = is_book || (doc.attr? 'title-page'))
-          @index.start_page_number = @toc_extent.to.page + 1 if use_title_page && @theme.page_numbering_start_at == 'after-toc'
+          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'
@@ -2398,7 +2407,7 @@ module Asciidoctor
           @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
-            layout_prose category.name,
+            inscribe_prose category.name,
               align: :left,
               inline_format: false,
               margin_bottom: @theme.description_list_term_spacing,
@@ -2426,7 +2435,7 @@ module Asciidoctor
           text = %(#{text}, #{pagenums.join ', '})
         end
         subterm_indent = @theme.description_list_description_indent
-        layout_prose text, align: :left, margin: 0, hanging_indent: subterm_indent * 2
+        inscribe_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
@@ -2527,14 +2536,14 @@ module Asciidoctor
       end
 
       def convert_inline_icon node
-        if node.document.attr? 'icons', 'font'
+        if (icons = (doc = node.document).attr 'icons') == 'font'
           if (icon_name = node.target).include? '@'
             icon_name, icon_set = icon_name.split '@', 2
             explicit_icon_set = true
           elsif (icon_set = node.attr 'set')
             explicit_icon_set = true
           else
-            icon_set = node.document.attr 'icon-set', 'fa'
+            icon_set = doc.attr 'icon-set', 'fa'
           end
           if icon_set == 'fa' || !(IconSets.include? icon_set)
             icon_set = 'fa'
@@ -2580,6 +2589,14 @@ module Asciidoctor
             log :warn, %(#{icon_name} is not a valid icon name in the #{icon_set} icon set)
             %([#{node.attr 'alt'}&#93;)
           end
+        elsif icons
+          image_path = ::File.absolute_path %(#{icon_name = node.target}.#{image_format = doc.attr 'icontype', 'png'}), (doc.attr 'iconsdir')
+          if ::File.readable? image_path
+            %(<img src="#{image_path}" format="#{image_format}" alt="#{node.attr 'alt'}" fit="line">)
+          else
+            log :warn, %(image icon for '#{icon_name}' not found or not readable: #{image_path})
+            %([#{icon_name}&#93;)
+          end
         else
           %([#{node.attr 'alt'}&#93;)
         end
@@ -2616,15 +2633,16 @@ module Asciidoctor
       end
 
       def convert_inline_indexterm node
+        visible = node.type == :visible
         if scratch?
-          node.type == :visible ? node.text : ''
+          visible ? node.text : ''
         else
           # NOTE: initialize index in case converter is called before PDF is initialized
           @index ||= IndexCatalog.new
           # NOTE: page number (:page key) is added by InlineDestinationMarker
           dest = { anchor: (anchor_name = @index.next_anchor_name) }
-          anchor = %(<a id="#{anchor_name}" type="indexterm">#{DummyText}</a>)
-          if node.type == :visible
+          anchor = %(<a id="#{anchor_name}" type="indexterm"#{visible ? ' visible="true"' : ''}>#{DummyText}</a>)
+          if visible
             visible_term = node.text
             @index.store_primary_term (sanitize visible_term), dest
             %(#{anchor}#{visible_term})
@@ -2671,8 +2689,10 @@ module Asciidoctor
           open, close, is_tag = ['<sub>', '</sub>', true]
         when :double
           open, close, is_tag = [theme.quotes[0], theme.quotes[1], false]
+          quotes = true
         when :single
           open, close, is_tag = [theme.quotes[2], theme.quotes[3], false]
+          quotes = true
         when :mark
           open, close, is_tag = ['<mark>', '</mark>', true]
         else
@@ -2681,6 +2701,11 @@ module Asciidoctor
 
         inner_text = node.text
 
+        if quotes && (len = inner_text.length) > 3 &&
+            (inner_text.end_with? '...') && !((inner_text_trunc = inner_text.slice 0, len - 3).end_with? ?\\)
+          inner_text = inner_text_trunc + '&#8230;'
+        end
+
         if (roles = node.role)
           roles.split.each do |role|
             if (text_transform = theme[%(role_#{role}_text_transform)])
@@ -2697,7 +2722,8 @@ module Asciidoctor
         node.id ? %(<a id="#{node.id}">#{DummyText}</a>#{quoted_text}) : quoted_text
       end
 
-      def layout_title_page doc
+      # Returns a Boolean indicating whether the title page was created
+      def inscribe_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
@@ -2724,7 +2750,7 @@ module Asciidoctor
         font @theme.base_font_family, size: @root_font_size, style: @theme.base_font_style
 
         # QUESTION: allow alignment per element on title page?
-        title_align = (@theme.title_page_align || @base_align).to_sym
+        title_align = (@theme.title_page_text_align || @base_text_align).to_sym
 
         if @theme.title_page_logo_display != 'none' && (logo_image_path = (doc.attr 'title-logo-image') || (logo_image_from_theme = @theme.title_page_logo_image))
           if (logo_image_path.include? ':') && logo_image_path =~ ImageAttributeValueRx
@@ -2773,7 +2799,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
-                layout_prose doctitle.main, align: title_align, margin: 0
+                inscribe_prose doctitle.main, align: title_align, margin: 0
               end
             end
             move_down @theme.title_page_title_margin_bottom || 0
@@ -2782,7 +2808,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
-                layout_prose subtitle, align: title_align, margin: 0
+                inscribe_prose subtitle, align: title_align, margin: 0
               end
             end
             move_down @theme.title_page_subtitle_margin_bottom || 0
@@ -2807,7 +2833,7 @@ module Asciidoctor
                 end
               end.join @theme.title_page_authors_delimiter
               theme_font :title_page_authors do
-                layout_prose authors, align: title_align, margin: 0, normalize: true
+                inscribe_prose authors, align: title_align, margin: 0, normalize: true
               end
             end
             move_down @theme.title_page_authors_margin_bottom || 0
@@ -2820,17 +2846,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
-                layout_prose revision_text, align: title_align, margin: 0, normalize: false
+                inscribe_prose revision_text, align: title_align, margin: 0, normalize: false
               end
             end
             move_down @theme.title_page_revision_margin_bottom || 0
           end
         end
 
-        layout_prose DummyText, margin: 0, line_height: 1, normalize: false if page.empty?
+        inscribe_prose DummyText, margin: 0, line_height: 1, normalize: false if page.empty?
+        true
       end
 
-      def layout_cover_page doc, face
+      def inscribe_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?
@@ -2876,37 +2903,58 @@ 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 layout_chapter_title
+        # TODO: must call update_colors before advancing to next page if start_new_page is called in inscribe_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
-        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
-          nil
+        if sect.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
+              elsif opts[:chapterlike]
+                inscribe_chapter_title sect, title, opts
+              else
+                inscribe_general_heading sect, title, opts
+              end
+            end
+            if page == start_page
+              page.tare_content_stream
+              orphaned = stop_if_first_page_empty { traverse sect }
+            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
+          end
         end
+        nil
       end
 
-      def layout_chapter_title node, title, opts = {}
-        layout_general_heading node, title, (opts.merge outdent: true)
+      def inscribe_chapter_title node, title, opts = {}
+        inscribe_general_heading node, title, (opts.merge outdent: true)
       end
 
-      alias layout_part_title layout_chapter_title
+      alias inscribe_part_title inscribe_chapter_title
 
-      def layout_general_heading _node, title, opts = {}
-        layout_heading title, opts
+      def inscribe_general_heading _node, title, opts = {}
+        inscribe_heading title, opts
       end
 
-      # NOTE: layout_heading doesn't set the theme font because it's used for various types of headings
-      def layout_heading string, opts = {}
+      # 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]
         unless (top_margin = (margin = (opts.delete :margin)) || (opts.delete :margin_top))
           if at_page_top?
@@ -2933,14 +2981,14 @@ module Asciidoctor
           typeset_text string, (calc_line_metrics (opts.delete :line_height) || @base_line_height), {
             color: @font_color,
             inline_format: inline_format_opts,
-            align: @base_align.to_sym,
+            align: @base_text_align.to_sym,
           }.merge(opts)
           margin_bottom bot_margin
         end
       end
 
       # NOTE: inline_format is true by default
-      def layout_prose string, opts = {}
+      def inscribe_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)
@@ -2964,7 +3012,7 @@ module Asciidoctor
         typeset_text string, (calc_line_metrics (opts.delete :line_height) || @base_line_height), {
           color: @font_color,
           inline_format: [inline_format_opts],
-          align: @base_align.to_sym,
+          align: @base_text_align.to_sym,
         }.merge(opts)
         margin_bottom bot_margin
       end
@@ -2987,13 +3035,13 @@ 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 layout_caption subject, opts = {}
+      def inscribe_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
-            layout_caption subject, opts
+            inscribe_caption subject, opts
           end).single_page_height
         end
         if ::Asciidoctor::AbstractBlock === subject
@@ -3001,21 +3049,23 @@ module Asciidoctor
         else
           string = subject.to_s
         end
+        block_align = opts.delete :block_align
+        block_width = opts.delete :block_width
         category_caption = (category = opts[:category]) ? %(#{category}_caption) : 'caption'
+        caption_margin_outside = @theme[%(#{category_caption}_margin_outside)] || @theme.caption_margin_outside
+        caption_margin_inside = @theme[%(#{category_caption}_margin_inside)] || @theme.caption_margin_inside
         container_width = bounds.width
-        block_align = opts.delete :block_align
+        indent_by = [0, 0]
         if (align = @theme[%(#{category_caption}_align)] || @theme.caption_align)
-          align = align == 'inherit' ? (block_align || @base_align.to_sym) : align.to_sym
+          align = align == 'inherit' ? (block_align || @base_text_align.to_sym) : align.to_sym
         else
-          align = @base_align.to_sym
+          align = @base_text_align.to_sym
         end
         if (text_align = @theme[%(#{category_caption}_text_align)] || @theme.caption_text_align)
           text_align = text_align == 'inherit' ? align : text_align.to_sym
         else
           text_align = align
         end
-        indent_by = [0, 0]
-        block_width = opts.delete :block_width
         if (max_width = opts.delete :max_width) && max_width != 'none'
           if ::String === max_width
             if max_width.start_with? 'fit-content'
@@ -3047,8 +3097,6 @@ module Asciidoctor
           end
         end
         theme_font_cascade [:caption, category_caption] do
-          caption_margin_outside = @theme[%(#{category_caption}_margin_outside)] || @theme.caption_margin_outside
-          caption_margin_inside = @theme[%(#{category_caption}_margin_inside)] || @theme.caption_margin_inside
           if ((opts.delete :side) || :top) == :top
             margin = { top: caption_margin_outside, bottom: caption_margin_inside }
           else
@@ -3057,8 +3105,13 @@ module Asciidoctor
           unless (inherited = apply_text_decoration [], :caption).empty?
             opts = opts.merge inherited
           end
+          unless scratch? || !(bg_color = @theme[%(#{category_caption}_background_color)] || @theme.caption_background_color)
+            caption_height = height_of_typeset_text string
+            fill_at = [0, cursor + (margin[:top] || 0)]
+            float { bounding_box(fill_at, width: container_width, height: caption_height) { fill_bounds bg_color } }
+          end
           indent(*indent_by) do
-            layout_prose string, ({
+            inscribe_prose string, ({
               margin_top: margin[:top],
               margin_bottom: margin[:bottom],
               align: text_align,
@@ -3072,18 +3125,18 @@ module Asciidoctor
       end
 
       # Render the caption for a table and return the height of the rendered content
-      def layout_table_caption node, table_alignment = :left, table_width = nil, max_width = nil, side = :top
-        layout_caption node, category: :table, side: side, block_align: table_alignment, block_width: table_width, max_width: max_width
+      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
       end
 
-      def allocate_toc doc, toc_num_levels, toc_start_cursor, use_title_page
+      def allocate_toc doc, toc_num_levels, toc_start_cursor, title_page_on
         toc_start_page = page_number
         extent = dry_run onto: self do
-          layout_toc doc, toc_num_levels, toc_start_page, toc_start_cursor
-          margin_bottom @theme.block_margin_bottom unless use_title_page
+          inscribe_toc doc, toc_num_levels, toc_start_page, toc_start_cursor
+          margin_bottom @theme.block_margin_bottom unless title_page_on
         end
         # NOTE: reserve pages for the toc; leaves cursor on page after last page in toc
-        if use_title_page
+        if title_page_on
           extent.each_page { start_new_page }
         else
           extent.each_page {|first_page| start_new_page unless first_page }
@@ -3093,14 +3146,14 @@ module Asciidoctor
       end
 
       # NOTE: num_front_matter_pages not used during a dry run
-      def layout_toc doc, num_levels, toc_page_number, start_cursor, num_front_matter_pages = 0
+      def inscribe_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_align || @theme.heading_h2_align || @theme.heading_align || @base_align).to_sym
-            layout_general_heading doc, toc_title, align: toc_title_align, level: 2, outdent: true, role: :toctitle
+            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
           end
         end
         # QUESTION: should we skip this whole method if num_levels < 0?
@@ -3125,7 +3178,7 @@ module Asciidoctor
             }
           end
           theme_margin :toc, :top
-          layout_toc_level doc.sections, num_levels, dot_leader, num_front_matter_pages
+          inscribe_toc_level doc.sections, 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)))
@@ -3133,7 +3186,7 @@ module Asciidoctor
         toc_page_numbers
       end
 
-      def layout_toc_level sections, num_levels, dot_leader, num_front_matter_pages
+      def inscribe_toc_level sections, 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 }
@@ -3149,7 +3202,7 @@ module Asciidoctor
             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
-                layout_prose sect_title, anchor: true, normalize: false, hanging_indent: hanging_indent, normalize_line_height: true, margin: 0
+                inscribe_prose sect_title, anchor: true, normalize: false, hanging_indent: hanging_indent, normalize_line_height: true, margin: 0
               end
             else
               physical_pgnum = sect.attr 'pdf-page-start'
@@ -3194,7 +3247,7 @@ module Asciidoctor
             end
           end
           indent @theme.toc_indent do
-            layout_toc_level sect.sections, num_levels_for_sect, dot_leader, num_front_matter_pages
+            inscribe_toc_level sect.sections, num_levels_for_sect, dot_leader, num_front_matter_pages
           end if num_levels_for_sect > sect.level
         end
       end
@@ -3222,8 +3275,8 @@ module Asciidoctor
         icon_data
       end
 
-      # TODO: delegate to layout_page_header and layout_page_footer per page
-      def layout_running_content periphery, doc, skip = [1, 1], body_start_page_number = 1
+      # 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
         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? })
@@ -3790,7 +3843,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
-          layout_caption node_with_caption, category: category if node_with_caption
+          inscribe_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)])
@@ -3804,7 +3857,7 @@ module Asciidoctor
           bg_color = nil
         end
         unless b_width || bg_color
-          layout_caption node_with_caption, category: category if node_with_caption
+          inscribe_caption node_with_caption, category: category if node_with_caption
           return
         end
         if (b_color = @theme[%(#{category}_border_color)]) == 'transparent'
@@ -3822,7 +3875,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
-        layout_caption node_with_caption, category: category if node_with_caption
+        inscribe_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|
@@ -4206,7 +4259,7 @@ module Asciidoctor
           (align_role.slice 5, align_role.length).to_sym
         elsif use_theme
           roles.reverse.each do |role|
-            if (align = @theme[%(role_#{role}_align)])
+            if (align = @theme[%(role_#{role}_text_align)])
               return align.to_sym
             end
           end
@@ -4542,6 +4595,27 @@ module Asciidoctor
         end
       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
+      end
+
       private
 
       def add_link_to_image uri, image_info, image_opts