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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da863e1bc05edaf64e5e443bb042fdaa01cc048ac559c9955bac4d7c27fff1c1
-  data.tar.gz: 0712e9ee6655c004b82f64c78d3c1eb326c182576e447669cce11e4ff7ca34db
+  metadata.gz: 7688a2448dace024b0e6057e878d556ec99ee1ac97bf4c91803d59346a136741
+  data.tar.gz: 13807213320754c03cce6304300745ec31a349a8e95441e1495ddc6e6401a99a
 SHA512:
-  metadata.gz: 8626792d427b27b635a6836fa0c1c7bf75faff5d82f1a71d74a23333e516086475e268cd524a5f5d2c0cfc9827b5b0f72a9d41fd6cc6b7c568506d914daf6840
-  data.tar.gz: 764bc2e6b6f069d437583c095a92f9e92969e306c872ea92c52e805c0063fa1d810390a303b597252adb9ca33015bd340f5e8d3851a0d64bb96d0cdc5d523329
+  metadata.gz: f3207de1db655ec85350df8b37530306e1ac13d1c1108b091886a8b45fcd5ce42fdc417fc759ef40ba77945925518e76e31341d12ec951ee648772c5b81364da
+  data.tar.gz: ab345b122e4137e33ed8ab0956270ce067f20b8b8b4f6aba3737f54f002b60b0653d5e9fbc356778d3787f9601b2f4ed9a6e0a5694bab5c9f376365297ae0626

data/CHANGELOG.adoc

@@ -5,6 +5,35 @@
 This document provides a high-level view of the changes to the {project-name} by release.
 For a detailed view of what has changed, refer to the {uri-repo}/commits/main[commit history] on GitHub.
 
+== 2.0.0.alpha.3 (2022-05-01) - @mojavelinux
+
+Enhancements::
+
+* allow border width of block to be specified per edge using 4-value array (#2102)
+* allow padding on block to be specified using 2-value array for ends and sides or 3-value array with implied left side value (#2104)
+* allow margins in running content to be specified using 2-value array for ends and sides or 3-value array with implied left side value (#2104)
+* allow theme to set border and padding on headings per level (#434)
+
+Improvements::
+
+* reduce top and bottom padding on quote and verse blocks in base theme
+* use uniform top and bottom padding on quote blocks in default theme
+* change `inscribe_` method prefix in converter to `ink_`
+
+Bug Fixes::
+
+* allow `ink_toc` method in extended converter to insert page above TOC page
+* remap `layout_` methods contributed to converter by prepended module
+* neutralize padding hacks in themes designed before the converter had smart margins
+* allow smallest ends or sides border width on block to be less than 1
+* cap border corners on block when width is defined using array (uniform or otherwise) (#2103)
+* fix crash in certain circumstances when theme does not define value for `base-border-width` key
+* use sensible fallbacks for table border and grid color and width (retains backwards compatibility)
+
+=== Details
+
+{url-repo}/releases/tag/v2.0.0.alpha.3[git tag] | {url-repo}/compare/v2.0.0.alpha.2\...v2.0.0.alpha.3[full diff]
+
 == 2.0.0.alpha.2 (2022-04-29) - @mojavelinux
 
 Enhancements::
@@ -12,7 +41,7 @@ Enhancements::
 * separate `align` and `text-align` keys in theme schema; remap old keys for backwards compatibility (#2095)
 * allow theme to control the border on all sides of tables independently (#902)
 * keep section title with first block of content is `breakable` option is set on section (#2075, #38)
-* pass `part`, `chapterlike`, and `hidden` options to `arrange_section` method
+* pass the `part` and `chapterlike` options to the `arrange_section` method for convenience
 * add support for `background-color` property on caption (#1995)
 * add support for image-based icons, resolved from `iconsdir` and having the `icontype` file extension (#1770)
 * add `asciidoctor/pdf/nogmagick` script to prevent Gmagick from handling PNG images (#1687)
@@ -36,7 +65,7 @@ Bug Fixes::
 * delete dests on page before deleting it (keeps generated PDF clean of obsolete destinations)
 * don't call `arrange_section` if section title is hidden
 * remove `theme_font` enclosure around call to `start_new_chapter` and `start_new_part`
-* change `layout_` method prefix to `inscribe_` in converter (#2099)
+* change `layout_` method prefix in converter to `inscribe_` (#2099)
 
 === Details
 

data/README.adoc

@@ -1,6 +1,6 @@
 = Asciidoctor PDF: A native PDF converter for AsciiDoc
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
-v2.0.0.alpha.2, 2022-04-29
+v2.0.0.alpha.3, 2022-05-01
 // Settings:
 :experimental:
 :idprefix:
@@ -24,7 +24,7 @@ endif::[]
 :project-handle: asciidoctor-pdf
 // Variables:
 :release-line: 2.0.x
-:release-version: 2.0.0.alpha.2
+:release-version: 2.0.0.alpha.3
 // URIs:
 :url-asciidoctor: http://asciidoctor.org
 :url-gem: http://rubygems.org/gems/asciidoctor-pdf

data/data/themes/base-theme.yml

@@ -76,10 +76,10 @@ admonition_label_font_style: bold
 admonition_label_text_transform: uppercase
 quote_border_color: 'EEEEEE'
 quote_border_left_width: 4
-quote_padding: [6, 12, 6, 14]
+quote_padding: [3, 12, 3, 14]
 verse_border_color: 'EEEEEE'
 verse_border_left_width: 4
-verse_padding: [6, 12, 6, 14]
+verse_padding: [3, 12, 3, 14]
 code_font_family: Courier
 code_font_size: 10.8
 code_line_height: 1.2
@@ -101,7 +101,6 @@ sidebar_title_font_style: bold
 table_border_color: '000000'
 table_border_style: solid
 table_border_width: 0.5
-table_grid_width: 0.5
 table_cell_padding: 2
 table_head_font_style: bold
 table_head_border_bottom_width: 1.25

data/data/themes/default-theme.yml

@@ -168,8 +168,8 @@ quote:
   font_size: $base_font_size_large
   border_color: $base_border_color
   border_width: 0
-  border_left_width: 5
-  padding: [0, $horizontal_rhythm, $block_margin_bottom * 0.25, $horizontal_rhythm + $quote_border_left_width / 2]
+  border_left_width: $horizontal_rhythm / 3
+  padding: [$vertical_rhythm / 4, $horizontal_rhythm, $vertical_rhythm / 4, $horizontal_rhythm + $quote_border_left_width / 2]
   cite:
     font_size: $base_font_size_small
     font_color: $role_subtitle_font_color

data/docs/theming-guide.adoc

@@ -5910,19 +5910,19 @@ Refer to the primary converter to discover the pseudo-HTML you can use for inlin
 
 So far we've just been biting around the edges.
 A more realistic use case is to customize the part title page in a multi-part book.
-Since this is a specialized section element, there's a dedicated method named `inscribe_part_title` that you'll need to override.
+Since this is a specialized section element, there's a dedicated method named `ink_part_title` that you'll need to override.
 
 Let's customize the part title page by making the background orange, making the font white, centering the title on the page, and disabling the running content.
 (You don't need to start a new page before and after the part title since that's already done for you).
 
 [source,ruby]
 ----
-  def inscribe_part_title node, title, opts = {}
-    fill_absolute_bounds 'E64C3D'
-    move_down 20
-    typeset_text title, (calc_line_metrics 1.5), color: 'FFFFFF', inline_format: true, align: :center, size: 42
-    page.instance_variable_set :@imported_page, true
-  end
+def ink_part_title node, title, opts = {}
+  fill_absolute_bounds 'E64C3D'
+  move_down 20
+  typeset_text title, (calc_line_metrics 1.5), color: 'FFFFFF', inline_format: true, align: :center, size: 42
+  page.instance_variable_set :@imported_page, true
+end
 ----
 
 The method `typeset_text` and `calc_line_metrics` are provided by Asciidoctor PDF to make writing text easier.

data/lib/asciidoctor/pdf/converter.rb

@@ -168,7 +168,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
@@ -190,22 +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
-        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
 
@@ -301,14 +301,14 @@ 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 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 = 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
@@ -319,8 +319,8 @@ module Asciidoctor
         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 +337,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 +461,8 @@ module Asciidoctor
       end
 
       def prepare_theme theme
-        theme.base_border_width || 0
+        theme.base_border_color ||= '000000'
+        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,6 +479,7 @@ module Asciidoctor
         theme.list_item_spacing ||= 0
         theme.description_list_term_spacing ||= 0
         theme.description_list_description_indent ||= 0
+        theme.table_border_width ||= 0.5
         theme.image_border_width ||= 0
         theme.code_linenum_font_color ||= '999999'
         theme.callout_list_margin_top_after_code ||= 0
@@ -687,11 +689,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 +702,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 +723,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 +732,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 +742,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
@@ -756,7 +758,7 @@ module Asciidoctor
         end
         # 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, node.title, align: align, level: hlevel, outdent: (node.parent.context == :section)
         end
       end
 
@@ -765,7 +767,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 }
@@ -787,7 +789,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_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
@@ -799,7 +801,7 @@ module Asciidoctor
                 if (align = resolve_alignment_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
@@ -834,17 +836,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)
-        inscribe_caption node, labeled: false if node.title?
+        ink_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
+          ink_prose node.content, prose_opts
         else
           theme_font_cascade (roles.map {|role| %(role_#{role}).to_sym }) do
-            inscribe_prose node.content, prose_opts
+            ink_prose node.content, prose_opts
           end
         end
 
@@ -892,12 +894,8 @@ 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
@@ -905,7 +903,7 @@ module Asciidoctor
             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
+                  (rule_width = @theme.admonition_column_rule_width || @theme.base_border_width) > 0
                 rule_style = @theme.admonition_column_rule_style&.to_sym || :solid
                 float do
                   extent.each_page do |first_page, last_page|
@@ -996,7 +994,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 +1008,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 +1042,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
@@ -1094,7 +1092,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 +1104,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
@@ -1124,7 +1122,7 @@ module Asciidoctor
           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)
+              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 if node.title?
             theme_font :sidebar do
               traverse node
@@ -1163,7 +1161,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 +1245,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 +1255,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 +1267,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,7 +1355,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)
-        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)
@@ -1454,7 +1452,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 +1480,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
@@ -1562,7 +1560,7 @@ module Asciidoctor
         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? ? (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, 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]
@@ -1645,7 +1643,7 @@ 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?
+          ink_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
@@ -1685,9 +1683,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)
-          inscribe_prose alt_text_template % alt_text_vars, align: alignment, margin: 0, normalize: false, single_line: true
+          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, side: :bottom if node.title?
         theme_margin :block, :bottom, (next_enclosed_block node) unless opts[:pinned]
         nil
       end
@@ -1696,8 +1694,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, side: :bottom if node.title?
         theme_margin :block, :bottom, (next_enclosed_block node)
       end
 
@@ -1724,8 +1722,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, side: :bottom if node.title?
           theme_margin :block, :bottom, (next_enclosed_block node)
         else
           original_attributes = node.attributes.dup
@@ -2024,6 +2022,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 +2037,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 +2076,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 +2142,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 +2188,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, theme.base_border_color).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
+        border_width = (rect_side_names.zip expand_rect_values theme.table_border_width, theme.base_border_width).to_h
+        grid_color = (grid_axis_names.zip expand_grid_values (theme.table_grid_color || [border_color[:top], border_color[:left]]), theme.base_border_color).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]]), theme.base_border_width).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')
@@ -2270,7 +2268,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_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
@@ -2343,7 +2341,7 @@ 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_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)
@@ -2407,7 +2405,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
-            inscribe_prose category.name,
+            ink_prose category.name,
               align: :left,
               inline_format: false,
               margin_bottom: @theme.description_list_term_spacing,
@@ -2435,7 +2433,7 @@ module Asciidoctor
           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
@@ -2723,7 +2721,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 +2797,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 +2806,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 +2831,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 +2844,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,7 +2901,7 @@ 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
 
@@ -2916,11 +2914,11 @@ module Asciidoctor
             start_page = page
             theme_font :heading, level: opts[:level] do
               if opts[:part]
-                inscribe_part_title sect, title, opts
+                ink_part_title sect, title, opts
               elsif opts[:chapterlike]
-                inscribe_chapter_title sect, title, opts
+                ink_chapter_title sect, title, opts
               else
-                inscribe_general_heading sect, title, opts
+                ink_general_heading sect, title, opts
               end
             end
             if page == start_page
@@ -2931,64 +2929,81 @@ module Asciidoctor
           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
+              heading_h += @theme.heading_min_height_after if @theme.heading_min_height_after && sect.blocks?
+              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)] && 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
 
       # 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)
@@ -3035,13 +3050,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 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
+            ink_caption subject, opts
           end).single_page_height
         end
         if ::Asciidoctor::AbstractBlock === subject
@@ -3111,7 +3126,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 +3140,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, side = :top
+        ink_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, 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 }
@@ -3146,14 +3167,14 @@ module Asciidoctor
       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 +3199,7 @@ module Asciidoctor
             }
           end
           theme_margin :toc, :top
-          inscribe_toc_level doc.sections, num_levels, dot_leader, num_front_matter_pages
+          ink_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)))
@@ -3186,7 +3207,7 @@ module Asciidoctor
         toc_page_numbers
       end
 
-      def inscribe_toc_level sections, num_levels, dot_leader, num_front_matter_pages
+      def ink_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 }
@@ -3202,7 +3223,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
-                inscribe_prose sect_title, anchor: true, normalize: false, hanging_indent: hanging_indent, normalize_line_height: true, margin: 0
+                ink_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'
@@ -3247,7 +3268,7 @@ module Asciidoctor
             end
           end
           indent @theme.toc_indent do
-            inscribe_toc_level sect.sections, num_levels_for_sect, dot_leader, num_front_matter_pages
+            ink_toc_level sect.sections, num_levels_for_sect, dot_leader, num_front_matter_pages
           end if num_levels_for_sect > sect.level
         end
       end
@@ -3275,15 +3296,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 +3400,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)
@@ -3501,7 +3522,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 +3532,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
@@ -3843,7 +3864,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,7 +3878,7 @@ 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'
@@ -3875,7 +3896,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 +4033,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
@@ -4596,26 +4615,34 @@ 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
-
+      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
         if (method_name = method.to_s).start_with? 'layout_'
-          alias_method %(inscribe_#{method_name.slice 7, method_name.length}).to_sym, method
+          alias_method %(ink_#{method_name.slice 7, method_name.length}).to_sym, method
         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
 
       def add_link_to_image uri, image_info, image_opts

data/lib/asciidoctor/pdf/ext/prawn/extensions.rb

@@ -538,17 +538,20 @@ module Asciidoctor
       # Example:
       #
       #  pad_box 20 do
-      #    text 'A paragraph inside a blox with even padding on all sides.'
+      #    text 'A paragraph inside a blox with even padding from all edges.'
       #  end
       #
-      #  pad_box [10, 10, 10, 20] do
-      #    text 'An indented paragraph inside a box with equal padding on all sides.'
+      #  pad_box [10, 5] do
+      #    text 'A paragraph inside a box with different padding from ends and sides.'
+      #  end
+      #
+      #  pad_box [5, 10, 15, 20] do
+      #    text 'A paragraph inside a box with different padding from each edge.'
       #  end
       #
       def pad_box padding, node = nil
         if padding
-          # TODO: implement shorthand combinations like in CSS
-          p_top, p_right, p_bottom, p_left = ::Array === padding ? padding : (::Array.new 4, padding)
+          p_top, p_right, p_bottom, p_left = expand_padding_value padding
           # logic is intentionally inlined
           begin
             if node && ((last_block = node).content_model != :compound || (last_block = node.blocks[-1])&.context == :paragraph)
@@ -560,8 +563,8 @@ module Asciidoctor
             bounds.add_left_padding p_left
             bounds.add_right_padding p_right
             yield
-            cursor > p_bottom ? (move_down p_bottom) : reference_bounds.move_past_bottom unless at_page_top?
           ensure
+            cursor > p_bottom ? (move_down p_bottom) : reference_bounds.move_past_bottom unless at_page_top?
             @bottom_gutters.pop
             bounds.subtract_left_padding p_left
             bounds.subtract_right_padding p_right
@@ -576,26 +579,25 @@ module Asciidoctor
       end
 
       def expand_padding_value shorthand
-        unless (padding = (@side_area_shorthand_cache ||= {})[shorthand])
-          if ::Array === shorthand
-            case shorthand.size
+        (@edge_shorthand_cache ||= ::Hash.new do |store, key|
+          if ::Array === key
+            case key.size
             when 1
-              padding = [shorthand[0], shorthand[0], shorthand[0], shorthand[0]]
+              value = [(value0 = key[0] || 0), value0, value0, value0]
             when 2
-              padding = [shorthand[0], shorthand[1], shorthand[0], shorthand[1]]
+              value = [(value0 = key[0] || 0), (value1 = key[1] || 0), value0, value1]
             when 3
-              padding = [shorthand[0], shorthand[1], shorthand[2], shorthand[1]]
+              value = [key[0] || 0, (value1 = key[1] || 0), key[2] || 0, value1]
             when 4
-              padding = shorthand
+              value = key.map {|it| it || 0 }
             else
-              padding = shorthand.slice 0, 4
+              value = (key.slice 0, 4).map {|it| it || 0 }
             end
           else
-            padding = ::Array.new 4, (shorthand || 0)
+            value = [(value0 = key || 0), value0, value0, value0]
           end
-          @side_area_shorthand_cache[shorthand] = padding
-        end
-        padding.dup
+          store[key] = value
+        end)[shorthand]
       end
 
       alias expand_margin_value expand_padding_value
@@ -700,7 +702,8 @@ module Asciidoctor
       def fill_and_stroke_bounds f_color = fill_color, s_color = stroke_color, options = {}
         no_fill = !f_color || f_color == 'transparent'
         if ::Array === (s_width = options[:line_width] || 0)
-          s_width_max = s_width.map(&:to_i).max
+          s_width = [s_width[0], s_width[1], s_width[0], s_width[1]] if s_width.size == 2
+          s_width_max = (s_width = s_width.map {|it| it || 0 }).max
           radius = 0
         else
           radius = options[:radius] || 0
@@ -718,13 +721,19 @@ module Asciidoctor
 
           # stroke
           if s_width_max
-            if (s_width_end = s_width[0] || 0) > 0
-              stroke_horizontal_rule s_color, line_width: s_width_end, line_style: options[:line_style]
-              stroke_horizontal_rule s_color, line_width: s_width_end, line_style: options[:line_style], at: bounds.height
+            s_width_top, s_width_right, s_width_bottom, s_width_left = s_width
+            projection_top, projection_right, projection_bottom, projection_left = s_width.map {|it| it * 0.5 }
+            if s_width_top > 0
+              stroke_horizontal_rule s_color, line_width: s_width_top, line_style: options[:line_style], left_projection: projection_left, right_projection: projection_right
+            end
+            if s_width_right > 0
+              stroke_vertical_rule s_color, line_width: s_width_right, line_style: options[:line_style], at: bounds.width, top_projection: projection_top, bottom_projection: projection_bottom
+            end
+            if s_width_bottom > 0
+              stroke_horizontal_rule s_color, line_width: s_width_bottom, line_style: options[:line_style], at: bounds.height, left_projection: projection_left, right_projection: projection_right
             end
-            if (s_width_side = s_width[1] || 0) > 0
-              stroke_vertical_rule s_color, line_width: s_width_side, line_style: options[:line_style]
-              stroke_vertical_rule s_color, line_width: s_width_side, line_style: options[:line_style], at: bounds.width
+            if s_width_left > 0
+              stroke_vertical_rule s_color, line_width: s_width_left, line_style: options[:line_style], top_projection: projection_top, bottom_projection: projection_bottom
             end
           else
             stroke_color s_color
@@ -759,8 +768,8 @@ module Asciidoctor
         rule_y = cursor - (options[:at] || 0)
         rule_style = options[:line_style]
         rule_width = options[:line_width] || 0.5
-        rule_x_start = bounds.left
-        rule_x_end = bounds.right
+        rule_x_start = bounds.left - (options[:left_projection] || 0)
+        rule_x_end = bounds.right - (options[:right_projection] || 0)
         save_graphics_state do
           stroke_color rule_color
           case rule_style
@@ -790,8 +799,8 @@ module Asciidoctor
       #
       def stroke_vertical_rule rule_color = stroke_color, options = {}
         rule_x = options[:at] || 0
-        rule_y_from = bounds.top
-        rule_y_to = bounds.bottom
+        rule_y_from = bounds.top + (options[:top_projection] || 0)
+        rule_y_to = bounds.bottom - (options[:bottom_projection] || 0)
         rule_style = options[:line_style]
         rule_width = options[:line_width] || 0.5
         save_graphics_state do

data/lib/asciidoctor/pdf/theme_loader.rb

@@ -18,6 +18,7 @@ module Asciidoctor
       AmbiguousAlignKeys = %w(base heading heading_h1 heading_h2 heading_h3 heading_h4 heading_h5 heading_h6 title_page abstract abstract_title admonition_label sidebar_title toc_title).each_with_object({}) do |prefix, accum|
         accum[%(#{prefix}_align)] = %(#{prefix}_text_align)
       end
+      PaddingBottomHackKeys = %w(example_padding quote_padding sidebar_padding verse_padding)
 
       VariableRx = /\$([a-z0-9_-]+)/
       LoneVariableRx = /^\$([a-z0-9_-]+)$/
@@ -173,6 +174,11 @@ module Asciidoctor
         elsif (rekey = AmbiguousAlignKeys[key]) ||
             ((key.start_with? 'role_') && (key.end_with? '_align') && (rekey = key.sub RoleAlignKeyRx, '_text_align'))
           data[rekey] = evaluate val, data
+        elsif PaddingBottomHackKeys.include? key
+          val = evaluate val, data
+          # normalize padding hacks for themes designed before the converter had smart margins
+          val[2] = val[0] if ::Array === val && val[0].to_f >= 0 && val[2].to_f <= 0
+          data[key] = val
         # QUESTION: do we really need to evaluate_math in this case?
         elsif key.end_with? '_color'
           if key == 'table_border_color'

data/lib/asciidoctor/pdf/version.rb

@@ -2,6 +2,6 @@
 
 module Asciidoctor
   module PDF
-    VERSION = '2.0.0.alpha.2'
+    VERSION = '2.0.0.alpha.3'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-pdf
 version: !ruby/object:Gem::Version
-  version: 2.0.0.alpha.2
+  version: 2.0.0.alpha.3
 platform: ruby
 authors:
 - Dan Allen
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-04-29 00:00:00.000000000 Z
+date: 2022-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor