asciidoctor-pdf 1.6.2 → 2.0.0.alpha.1

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

@@ -4,7 +4,7 @@ Prawn::Font::AFM.instance_variable_set :@hide_m17n_warning, true
 
 require 'prawn/icon'
 
-Prawn::Icon::Compatibility.send :prepend, (::Module.new { def warning *args; end })
+Prawn::Icon::Compatibility.send :prepend, (::Module.new { def warning *_args; end })
 
 module Asciidoctor
   module Prawn
@@ -22,7 +22,7 @@ module Asciidoctor
         italic: [:italic].to_set,
         bold_italic: [:bold, :italic].to_set,
       }).default = ::Set.new
-      # NOTE must use a visible char for placeholder or else Prawn won't reserve space for the fragment
+      # NOTE: must use a visible char for placeholder or else Prawn won't reserve space for the fragment
       PlaceholderChar = ?\u2063
 
       # - :height is the height of a line
@@ -32,6 +32,91 @@ module Asciidoctor
       # - :final_gap determines whether a gap is added below the last line
       LineMetrics = ::Struct.new :height, :leading, :padding_top, :padding_bottom, :final_gap
 
+      Position = ::Struct.new :page, :cursor
+
+      Extent = ::Struct.new :current, :from, :to do
+        def initialize current_page, current_cursor, start_page, start_cursor, end_page, end_cursor
+          self.from = self.current = Position.new current_page, current_cursor
+          self.from = Position.new start_page, start_cursor unless start_page == current_page && start_cursor == current_cursor
+          self.to = Position.new end_page, end_cursor
+        end
+
+        def each_page
+          from.page.upto to.page do |pgnum|
+            yield pgnum == from.page && from, pgnum == to.page && to, pgnum
+          end
+        end
+
+        def single_page?
+          from.page == to.page
+        end
+
+        def single_page_height
+          single_page? ? from.cursor - to.cursor : nil
+        end
+
+        def page_range
+          (from.page..to.page)
+        end
+      end
+
+      ScratchExtent = ::Struct.new :from, :to do
+        def initialize start_page, start_cursor, end_page, end_cursor
+          self.from = Position.new start_page, start_cursor
+          self.to = Position.new end_page, end_cursor
+        end
+
+        def position_onto pdf, keep_together = nil
+          current_page = pdf.page_number
+          current_cursor = pdf.cursor
+          from_page = current_page + (advance_by = from.page - 1)
+          to_page = current_page + (to.page - 1)
+          if advance_by > 0
+            advance_by.times { pdf.advance_page }
+          elsif keep_together && single_page? && !(try_to_fit_on_previous current_cursor)
+            pdf.advance_page
+            from_page += 1
+            to_page += 1
+          end
+          Extent.new current_page, current_cursor, from_page, from.cursor, to_page, to.cursor
+        end
+
+        def single_page?
+          from.page == to.page
+        end
+
+        def single_page_height
+          single_page? ? from.cursor - to.cursor : nil
+        end
+
+        def try_to_fit_on_previous reference_cursor
+          if (height = from.cursor - to.cursor) <= reference_cursor
+            from.cursor = reference_cursor
+            to.cursor = reference_cursor - height
+            true
+          else
+            false
+          end
+        end
+      end
+
+      NewPageRequiredError = ::Class.new ::StopIteration
+
+      InhibitNewPageProc = proc do |pdf|
+        pdf.delete_page
+        raise NewPageRequiredError
+      end
+
+      DetectEmptyFirstPage = ::Module.new
+
+      DetectEmptyFirstPageProc = proc do |delegate, pdf|
+        if pdf.state.pages[pdf.page_number - 2].empty?
+          pdf.delete_page
+          raise NewPageRequiredError
+        end
+        delegate.call pdf if (pdf.state.on_page_create_callback = delegate)
+      end
+
       # Core
 
       # Retrieves the catalog reference data for the PDF.
@@ -54,14 +139,6 @@ module Asciidoctor
         page.dimensions[2]
       end
 
-      # Returns the effective (writable) width of the page
-      #
-      # If inside a bounding box, returns width of box.
-      #
-      def effective_page_width
-        reference_bounds.width
-      end
-
       # Returns the height of the current page from edge-to-edge
       #
       def page_height
@@ -70,13 +147,13 @@ module Asciidoctor
 
       # Returns the effective (writable) height of the page
       #
-      # If inside a fixed-height bounding box, returns width of box.
+      # If inside a fixed-height bounding box, returns height of box.
       #
       def effective_page_height
         reference_bounds.height
       end
 
-      # workaround for https://github.com/prawnpdf/prawn/issues/1121
+      # remove once fixed upstream; see https://github.com/prawnpdf/prawn/pull/1122
       def generate_margin_box
         page_w, page_h = (page = state.page).dimensions.slice 2, 2
         page_m = page.margins
@@ -108,7 +185,7 @@ module Asciidoctor
       # Returns the margins for the current page as a 4 element array (top, right, bottom, left)
       #
       def page_margin
-        [page.margins[:top], page.margins[:right], page.margins[:bottom], page.margins[:left]]
+        [page_margin_top, page_margin_right, page_margin_bottom, page_margin_left]
       end
 
       # Returns the width of the left margin for the current page
@@ -116,16 +193,12 @@ module Asciidoctor
       def page_margin_left
         page.margins[:left]
       end
-      # deprecated
-      alias left_margin page_margin_left
 
       # Returns the width of the right margin for the current page
       #
       def page_margin_right
         page.margins[:right]
       end
-      # deprecated
-      alias right_margin page_margin_right
 
       # Returns the width of the top margin for the current page
       #
@@ -157,7 +230,7 @@ module Asciidoctor
         if invert
           (recto_page? pgnum) ? :verso : :recto
         else
-          (recto_page? pgnum) ? :recto : :verso
+          (verso_page? pgnum) ? :verso : :recto
         end
       end
 
@@ -243,16 +316,10 @@ module Asciidoctor
         { family: font.options[:family], style: (font.options[:style] || :normal), size: @font_size }
       end
 
-      # Sets the font style for the scope of the block to which this method
-      # yields. If the style is nil and no block is given, return the current
-      # font style.
+      # Set the font style on the document, if a style is given, otherwise return the current font style.
       #
       def font_style style = nil
-        if block_given?
-          font font.options[:family], style: style do
-            yield
-          end
-        elsif style
+        if style
           font font.options[:family], style: style
         else
           font.options[:style] || :normal
@@ -264,12 +331,10 @@ module Asciidoctor
       # implementation to carry out the built-in functionality.
       #
       #--
-      # QUESTION should we round the result?
+      # QUESTION: should we round the result?
       def font_size points = nil
         return @font_size unless points
-        if points == 1
-          super @font_size
-        elsif String === points
+        if ::String === points
           if points.end_with? 'rem'
             super @root_font_size * points.to_f
           elsif points.end_with? 'em'
@@ -279,8 +344,8 @@ module Asciidoctor
           else
             super points.to_f
           end
-        # FIXME: HACK assume em value
-        elsif points < 1
+        # NOTE: assume em value (since a font size of 1 is extremely unlikely)
+        elsif points <= 1
           super @font_size * points
         else
           super points
@@ -304,37 +369,9 @@ module Asciidoctor
         FontStyleToSet[style].dup
       end
 
-      # Apply the font settings (family, size, styles and character spacing) from
-      # the fragment to the document, then yield to the block.
-      #
-      # The original font settings are restored before this method returns.
-      #
-      def fragment_font fragment
-        f_info = font_info
-        f_family = fragment[:font] || f_info[:family]
-        f_size = fragment[:size] || f_info[:size]
-        if (f_styles = fragment[:styles])
-          f_style = resolve_font_style f_styles
-        else
-          f_style = :normal
-        end
-
-        if (c_spacing = fragment[:character_spacing])
-          character_spacing c_spacing do
-            font f_family, size: f_size, style: f_style do
-              yield
-            end
-          end
-        else
-          font f_family, size: f_size, style: f_style do
-            yield
-          end
-        end
-      end
-
       # Override width of string to check for placeholder char, which uses character spacing to control width
       #
-      def width_of_string string, options = {}
+      def width_of_string string, options
         string == PlaceholderChar ? @character_spacing : super
       end
 
@@ -346,7 +383,7 @@ module Asciidoctor
         ::Prawn::Icon::Compatibility::SHIMS[%(fa-#{name})]
       end
 
-      def calc_line_metrics line_height = 1, font = self.font, font_size = self.font_size
+      def calc_line_metrics line_height, font = self.font, font_size = self.font_size
         line_height_length = line_height * font_size
         leading = line_height_length - font_size
         half_leading = leading / 2
@@ -355,20 +392,6 @@ module Asciidoctor
         LineMetrics.new line_height_length, leading, padding_top, padding_bottom, false
       end
 
-=begin
-      # these line metrics attempted to figure out a correction based on the reported height and the font_size
-      # however, it only works for some fonts, and breaks down for fonts like Noto Serif
-      def calc_line_metrics line_height = 1, font = self.font, font_size = self.font_size
-        line_height_length = font_size * line_height
-        line_gap = line_height_length - font_size
-        correction = font.height - font_size
-        leading = line_gap - correction
-        shift = (font.line_gap + correction + line_gap) / 2
-        final_gap = font.line_gap != 0
-        LineMetrics.new line_height_length, leading, shift, shift, final_gap
-      end
-=end
-
       # Parse the text into an array of fragments using the text formatter.
       def parse_text string, options = {}
         return [] if string.nil?
@@ -383,22 +406,22 @@ module Asciidoctor
 
         if (color = options.delete :color)
           fragments.map do |fragment|
-            fragment[:color] ? fragment : fragment.merge(color: color)
+            fragment[:color] ? fragment : (fragment.merge color: color)
           end
         else
           fragments
         end
       end
 
-      # NOTE override built-in fill_formatted_text_box to insert leading before second line when :first_line is true
-      def fill_formatted_text_box text, opts
-        merge_text_box_positioning_options opts
-        box = ::Prawn::Text::Formatted::Box.new text, opts
+      # NOTE: override built-in fill_formatted_text_box to insert leading before second line when :first_line is true
+      def fill_formatted_text_box text, options
+        merge_text_box_positioning_options options
+        box = ::Prawn::Text::Formatted::Box.new text, options
         remaining_text = box.render
         @no_text_printed = box.nothing_printed?
         @all_text_printed = box.everything_printed?
 
-        if @final_gap || (opts[:first_line] && !(@no_text_printed || @all_text_printed))
+        if ((defined? @final_gap) && @final_gap) || (options[:first_line] && !(@no_text_printed || @all_text_printed))
           self.y -= box.height + box.line_gap + box.leading
         else
           self.y -= box.height
@@ -407,51 +430,52 @@ module Asciidoctor
         remaining_text
       end
 
-      # NOTE override built-in draw_indented_formatted_line to set first_line flag
-      def draw_indented_formatted_line string, opts
-        super string, (opts.merge first_line: true)
+      # NOTE: override built-in draw_indented_formatted_line to set first_line flag
+      def draw_indented_formatted_line string, options
+        super string, (options.merge first_line: true)
       end
 
-      # Performs the same work as Prawn::Text.text except that the first_line_opts are applied to the first line of text
+      # Performs the same work as Prawn::Text.text except that the first_line_options are applied to the first line of text
       # renderered. It's necessary to use low-level APIs in this method so we only style the first line and not the
       # remaining lines (which is the default behavior in Prawn).
-      def text_with_formatted_first_line string, first_line_opts, opts
-        color = opts.delete :color
-        fragments = parse_text string, opts
-        # NOTE the low-level APIs we're using don't recognize the :styles option, so we must resolve
-        if (styles = opts.delete :styles)
-          opts[:style] = resolve_font_style styles
-        end
-        if (first_line_styles = first_line_opts.delete :styles)
-          first_line_opts[:style] = resolve_font_style first_line_styles
-        end
-        first_line_color = (first_line_opts.delete :color) || color
-        opts = opts.merge document: self
-        # QUESTION should we merge more carefully here? (hand-select keys?)
-        first_line_opts = opts.merge(first_line_opts).merge single_line: true, first_line: true
-        box = ::Prawn::Text::Formatted::Box.new fragments, first_line_opts
-        # NOTE get remaining_fragments before we add color to fragments on first line
-        if (text_indent = opts.delete :indent_paragraphs)
+      def text_with_formatted_first_line string, first_line_options, options
+        color = options.delete :color
+        fragments = parse_text string, options
+        # NOTE: the low-level APIs we're using don't recognize the :styles option, so we must resolve
+        # NOTE: disabled until we have a need for it
+        #if (styles = options.delete :styles)
+        #  options[:style] = resolve_font_style styles
+        #end
+        if (first_line_styles = first_line_options.delete :styles)
+          first_line_options[:style] = resolve_font_style first_line_styles
+        end
+        first_line_color = (first_line_options.delete :color) || color
+        options = options.merge document: self
+        # QUESTION: should we merge more carefully here? (hand-select keys?)
+        first_line_options = (options.merge first_line_options).merge single_line: true, first_line: true
+        box = ::Prawn::Text::Formatted::Box.new fragments, first_line_options
+        # NOTE: get remaining_fragments before we add color to fragments on first line
+        if (text_indent = options.delete :indent_paragraphs)
           remaining_fragments = indent text_indent do
             box.render dry_run: true
           end
         else
           remaining_fragments = box.render dry_run: true
         end
-        # NOTE color must be applied per-fragment
-        fragments.each {|fragment| fragment[:color] ||= first_line_color } if first_line_color
+        # NOTE: color must be applied per-fragment
+        fragments.each {|fragment| fragment[:color] ||= first_line_color }
         if text_indent
           indent text_indent do
-            fill_formatted_text_box fragments, first_line_opts
+            fill_formatted_text_box fragments, first_line_options
           end
         else
-          fill_formatted_text_box fragments, first_line_opts
+          fill_formatted_text_box fragments, first_line_options
         end
         unless remaining_fragments.empty?
-          # NOTE color must be applied per-fragment
-          remaining_fragments.each {|fragment| fragment[:color] ||= color } if color
-          remaining_fragments = fill_formatted_text_box remaining_fragments, opts
-          draw_remaining_formatted_text_on_new_pages remaining_fragments, opts
+          # NOTE: color must be applied per-fragment
+          remaining_fragments.each {|fragment| fragment[:color] ||= color }
+          remaining_fragments = fill_formatted_text_box remaining_fragments, options
+          draw_remaining_formatted_text_on_new_pages remaining_fragments, options
         end
       end
 
@@ -492,7 +516,7 @@ module Asciidoctor
       # Override built-in move_text_position method to prevent Prawn from advancing
       # to next page if image doesn't fit before rendering image.
       #--
-      # NOTE could use :at option when calling image/embed_image instead
+      # NOTE: could use :at option when calling image/embed_image instead
       def move_text_position h; end
 
       # Short-circuits the call to the built-in move_down operation
@@ -504,21 +528,7 @@ module Asciidoctor
 
       # Bounds
 
-      # Overrides the built-in pad operation to allow for asymmetric paddings.
-      #
-      # Example:
-      #
-      #  pad 20, 10 do
-      #    text 'A paragraph with twice as much top padding as bottom padding.'
-      #  end
-      #
-      def pad top, bottom = nil
-        move_down top
-        yield
-        move_down(bottom || top)
-      end
-
-      # Combines the built-in pad and indent operations into a single method.
+      # Augments the built-in pad method by adding support for specifying padding on all four sizes.
       #
       # Padding may be specified as an array of four values, or as a single value.
       # The single value is used as the padding around all four sides of the box.
@@ -545,13 +555,7 @@ module Asciidoctor
             bounds.add_left_padding p_left
             bounds.add_right_padding p_right
             yield
-            # NOTE support negative bottom padding for use with quote block
-            if p_bottom < 0
-              # QUESTION should we return to previous page if top of page is reached?
-              p_bottom < cursor - reference_bounds.top ? (move_cursor_to reference_bounds.top) : (move_down p_bottom)
-            else
-              p_bottom < cursor ? (move_down p_bottom) : reference_bounds.move_past_bottom
-            end
+            cursor > p_bottom ? (move_down p_bottom) : reference_bounds.move_past_bottom unless at_page_top?
           ensure
             bounds.subtract_left_padding p_left
             bounds.subtract_right_padding p_right
@@ -559,34 +563,37 @@ module Asciidoctor
         else
           yield
         end
-
-        # alternate, delegated logic
-        #pad padding[0], padding[2] do
-        #  indent padding[1], padding[3] do
-        #    yield
-        #  end
-        #end
       end
 
-      def inflate_indent value
+      def expand_indent_value value
         (::Array === value ? (value.slice 0, 2) : (::Array.new 2, value)).map(&:to_f)
       end
 
-      # TODO: memoize the result
-      def inflate_padding padding
-        padding = (Array padding || 0).slice 0, 4
-        case padding.size
-        when 1
-          [padding[0], padding[0], padding[0], padding[0]]
-        when 2
-          [padding[0], padding[1], padding[0], padding[1]]
-        when 3
-          [padding[0], padding[1], padding[2], padding[1]]
-        else
-          padding
+      def expand_padding_value shorthand
+        unless (padding = (@side_area_shorthand_cache ||= {})[shorthand])
+          if ::Array === shorthand
+            case shorthand.size
+            when 1
+              padding = [shorthand[0], shorthand[0], shorthand[0], shorthand[0]]
+            when 2
+              padding = [shorthand[0], shorthand[1], shorthand[0], shorthand[1]]
+            when 3
+              padding = [shorthand[0], shorthand[1], shorthand[2], shorthand[1]]
+            when 4
+              padding = shorthand
+            else
+              padding = shorthand.slice 0, 4
+            end
+          else
+            padding = ::Array.new 4, (shorthand || 0)
+          end
+          @side_area_shorthand_cache[shorthand] = padding
         end
+        padding.dup
       end
 
+      alias expand_margin_value expand_padding_value
+
       # Stretch the current bounds to the left and right edges of the current page
       # while yielding the specified block if the verdict argument is true.
       # Otherwise, simply yield the specified block.
@@ -601,16 +608,15 @@ module Asciidoctor
         end
       end
 
-      # A flowing version of the bounding_box. If the content runs to another page, the cursor starts
-      # at the top of the page instead of the original cursor position. Similar to span, except
-      # you can specify an absolute left position and pass additional options through to bounding_box.
+      # A flowing version of bounding_box. If the content runs to another page, the cursor starts at
+      # the top of the page instead of from the original cursor position. Similar to span, except
+      # the :position option is limited to a numeric value and additional options are passed through
+      # to bounding_box.
       #
-      def flow_bounding_box left = 0, opts = {}
-        original_y = y
-        # QUESTION should preserving original_x be an option?
-        original_x = bounds.absolute_left - margin_box.absolute_left
+      def flow_bounding_box options = {}
+        original_y, original_x = y, bounds.absolute_left
         canvas do
-          bounding_box [margin_box.absolute_left + original_x + left, margin_box.absolute_top], opts do
+          bounding_box [original_x + (options.delete :position).to_f, @margin_box.absolute_top], options do
             self.y = original_y
             yield
           end
@@ -622,19 +628,17 @@ module Asciidoctor
       # Fills the current bounding box with the specified fill color. Before
       # returning from this method, the original fill color on the document is
       # restored.
-      def fill_bounds f_color = fill_color
-        if f_color && f_color != 'transparent'
-          prev_fill_color = fill_color
-          fill_color f_color
-          fill_rectangle bounds.top_left, bounds.width, bounds.height
-          fill_color prev_fill_color
-        end
+      def fill_bounds f_color
+        prev_fill_color = fill_color
+        fill_color f_color
+        fill_rectangle bounds.top_left, bounds.width, bounds.height
+        fill_color prev_fill_color
       end
 
       # Fills the absolute bounding box with the specified fill color. Before
       # returning from this method, the original fill color on the document is
       # restored.
-      def fill_absolute_bounds f_color = fill_color
+      def fill_absolute_bounds f_color
         canvas { fill_bounds f_color }
       end
 
@@ -645,53 +649,58 @@ module Asciidoctor
       #
       def fill_and_stroke_bounds f_color = fill_color, s_color = stroke_color, options = {}
         no_fill = !f_color || f_color == 'transparent'
-        no_stroke = !s_color || s_color == 'transparent' || options[:line_width] == 0
+        if ::Array === (s_width = options[:line_width] || 0)
+          s_width_max = s_width.map(&:to_i).max
+          radius = 0
+        else
+          radius = options[:radius] || 0
+        end
+        no_stroke = !s_color || s_color == 'transparent' || (s_width_max || s_width) == 0
         return if no_fill && no_stroke
         save_graphics_state do
-          radius = options[:radius] || 0
-
           # fill
           unless no_fill
             fill_color f_color
             fill_rounded_rectangle bounds.top_left, bounds.width, bounds.height, radius
           end
 
+          next if no_stroke
+
           # stroke
-          unless no_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
+            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
+            end
+          else
             stroke_color s_color
-            line_width(options[:line_width] || 0.5)
-            # FIXME: think about best way to indicate dashed borders
-            #if options.has_key? :dash_width
-            #  dash options[:dash_width], space: options[:dash_space] || 1
-            #end
+            case options[:line_style]
+            when :dashed
+              line_width s_width
+              dash s_width * 4
+            when :dotted
+              line_width s_width
+              dash s_width
+            when :double
+              single_line_width = s_width / 3.0
+              line_width single_line_width
+              inner_line_offset = single_line_width * 2
+              inner_top_left = [bounds.left + inner_line_offset, bounds.top - inner_line_offset]
+              stroke_rounded_rectangle bounds.top_left, bounds.width, bounds.height, radius
+              stroke_rounded_rectangle inner_top_left, bounds.width - (inner_line_offset * 2), bounds.height - (inner_line_offset * 2), radius
+              next
+            else # :solid
+              line_width s_width
+            end
             stroke_rounded_rectangle bounds.top_left, bounds.width, bounds.height, radius
-            #undash if options.has_key? :dash_width
           end
         end
       end
 
-      # Fills and, optionally, strokes the current bounds using the fill and
-      # stroke color specified, then yields to the block. The only_if option can
-      # be used to conditionally disable this behavior.
-      #
-      def shade_box color, line_color = nil, options = {}
-        if (!options.key? :only_if) || options[:only_if]
-          # FIXME: could use save_graphics_state here
-          previous_fill_color = current_fill_color
-          fill_color color
-          fill_rectangle [bounds.left, bounds.top], bounds.right, bounds.top - bounds.bottom
-          fill_color previous_fill_color
-          if line_color
-            line_width 0.5
-            previous_stroke_color = current_stroke_color
-            stroke_color line_color
-            stroke_bounds
-            stroke_color previous_stroke_color
-          end
-        end
-        yield
-      end
-
       # Strokes a horizontal line using the current bounds. The width of the line
       # can be specified using the line_width option. The offset from the cursor
       # can be set using the at option.
@@ -702,21 +711,25 @@ module Asciidoctor
         rule_width = options[:line_width] || 0.5
         rule_x_start = bounds.left
         rule_x_end = bounds.right
-        rule_inked = false
         save_graphics_state do
-          line_width rule_width
           stroke_color rule_color
           case rule_style
           when :dashed
+            line_width rule_width
             dash rule_width * 4
           when :dotted
+            line_width rule_width
             dash rule_width
           when :double
-            stroke_horizontal_line rule_x_start, rule_x_end, at: (rule_y + rule_width)
-            stroke_horizontal_line rule_x_start, rule_x_end, at: (rule_y - rule_width)
-            rule_inked = true
-          end if rule_style
-          stroke_horizontal_line rule_x_start, rule_x_end, at: rule_y unless rule_inked
+            single_rule_width = rule_width / 3.0
+            line_width single_rule_width
+            stroke_horizontal_line rule_x_start, rule_x_end, at: (rule_y + single_rule_width)
+            stroke_horizontal_line rule_x_start, rule_x_end, at: (rule_y - single_rule_width)
+            next
+          else # :solid
+            line_width rule_width
+          end
+          stroke_horizontal_line rule_x_start, rule_x_end, at: rule_y
         end
       end
 
@@ -754,14 +767,9 @@ module Asciidoctor
       def delete_page
         pg = page_number
         pdf_store = state.store
-        pdf_objs = pdf_store.instance_variable_get :@objects
-        pdf_ids = pdf_store.instance_variable_get :@identifiers
-        page_id = pdf_store.object_id_for_page pg
         content_id = page.content.identifier
-        [page_id, content_id].each do |key|
-          pdf_objs.delete key
-          pdf_ids.delete key
-        end
+        # NOTE: cannot delete objects and IDs, otherwise references get corrupted; so just reset the value
+        (pdf_store.instance_variable_get :@objects)[content_id] = ::PDF::Core::Reference.new content_id, {}
         pdf_store.pages.data[:Kids].pop
         pdf_store.pages.data[:Count] -= 1
         state.pages.pop
@@ -780,60 +788,63 @@ module Asciidoctor
       # However, due to how page creation works in Prawn, understand that advancing
       # to the next page is necessary to prevent the size & layout of the imported
       # page from affecting a newly created page.
-      def import_page file, opts = {}
+      def import_page file, options = {}
         prev_page_layout = page.layout
         prev_page_size = page.size
         state.compress = false if state.compress # can't use compression if using template
         prev_text_rendering_mode = (defined? @text_rendering_mode) ? @text_rendering_mode : nil
-        delete_page if opts[:replace]
-        # NOTE use functionality provided by prawn-templates
-        start_new_page_discretely template: file, template_page: opts[:page]
+        delete_page if options[:replace]
+        # NOTE: use functionality provided by prawn-templates
+        start_new_page_discretely template: file, template_page: options[:page]
         # prawn-templates sets text_rendering_mode to :unknown, which breaks running content; revert
         @text_rendering_mode = prev_text_rendering_mode
-        yield if block_given?
-        if opts.fetch :advance, true
-          # NOTE set page size & layout explicitly in case imported page differs
+        if page.imported_page?
+          yield if block_given?
+          # NOTE: set page size & layout explicitly in case imported page differs
           # I'm not sure it's right to start a new page here, but unfortunately there's no other
           # way atm to prevent the size & layout of the imported page from affecting subsequent pages
+          advance_page size: prev_page_size, layout: prev_page_layout if options.fetch :advance, true
+        elsif options.fetch :advance_if_missing, true
+          delete_page
+          # NOTE: see previous comment
           advance_page size: prev_page_size, layout: prev_page_layout
+        else
+          delete_page
         end
         nil
       end
 
-      # Create a new page for the specified image. If the canvas option is true,
-      # the image is positioned relative to the boundaries of the page.
+      # Create a new page for the specified image.
+      #
+      # The image is positioned relative to the boundaries of the page.
       def image_page file, options = {}
         start_new_page_discretely
-        image_page_number = page_number
-        if options.delete :canvas
-          canvas { image file, ({ position: :center, vposition: :center }.merge options) }
-        else
-          image file, (options.merge position: :center, vposition: :center, fit: [bounds.width, bounds.height])
+        ex = nil
+        float do
+          canvas do
+            image file, ({ position: :center, vposition: :center }.merge options)
+          rescue
+            ex = $!
+          end
         end
-        # NOTE advance to newly created page just in case the image function threw off the cursor
-        go_to_page image_page_number
+        raise ex if ex
         nil
       end
 
       # Perform an operation (such as creating a new page) without triggering the on_page_create callback
       #
       def perform_discretely
-        if (saved_callback = state.on_page_create_callback)
-          # equivalent to calling `on_page_create`
-          state.on_page_create_callback = nil
-          yield
-          # equivalent to calling `on_page_create &saved_callback`
-          state.on_page_create_callback = saved_callback
-        else
-          yield
-        end
+        state.on_page_create_callback = nil if (saved_callback = state.on_page_create_callback) != InhibitNewPageProc
+        yield
+      ensure
+        state.on_page_create_callback = saved_callback
       end
 
       # This method is a smarter version of start_new_page. It calls start_new_page
       # if the current page is the last page of the document. Otherwise, it simply
       # advances to the next existing page.
-      def advance_page opts = {}
-        last_page? ? (start_new_page opts) : (go_to_page page_number + 1)
+      def advance_page options = {}
+        last_page? ? (start_new_page options) : (go_to_page page_number + 1)
       end
 
       # Start a new page without triggering the on_page_create callback
@@ -844,115 +855,208 @@ module Asciidoctor
 
       # Grouping
 
-      # Conditional group operation
-      #
-      def group_if verdict
-        if verdict
-          state.optimize_objects = false # optimize_objects breaks group
-          group { yield }
-        else
-          yield
-        end
+      def allocate_prototype
+        @prototype = create_prototype { ::Marshal.load ::Marshal.dump self }
       end
 
-      def get_scratch_document
-        # marshal if not using transaction feature
-        #Marshal.load Marshal.dump @prototype
-
-        # use cached instance, tests show it's faster
-        #@prototype ||= ::Prawn::Document.new
-        @scratch ||= if defined? @prototype # rubocop:disable Naming/MemoizedInstanceVariableName
-                       scratch = Marshal.load Marshal.dump @prototype
-                       scratch.instance_variable_set :@prototype, @prototype
-                       scratch.instance_variable_set :@tmp_files, @tmp_files
-                       # TODO: set scratch number on scratch document
-                       scratch
-                     else
-                       logger.warn 'no scratch prototype available; instantiating fresh scratch document'
-                       ::Prawn::Document.new
-                     end
+      def scratch
+        @scratch ||= ((Marshal.load Marshal.dump @prototype).send :init_scratch, self)
       end
 
       def scratch?
-        (@_label ||= (state.store.info.data[:Scratch] ? :scratch : :primary)) == :scratch
-      rescue
-        false # NOTE this method may get called before the state is initialized
+        @label == :scratch
       end
       alias is_scratch? scratch?
 
-      def dry_run &block
-        scratch = get_scratch_document
-        # QUESTION should we use scratch.advance_page instead?
-        scratch.start_new_page
-        start_page_number = scratch.page_number
-        start_y = scratch.y
-        scratch_bounds = scratch.bounds
-        original_x = scratch_bounds.absolute_left
-        original_width = scratch_bounds.width
-        scratch_bounds.instance_variable_set :@x, bounds.absolute_left
-        scratch_bounds.instance_variable_set :@width, bounds.width
-        scratch.font font_family, style: font_style, size: font_size do
-          scratch.instance_exec(&block)
-        end
-        # NOTE don't count excess if cursor exceeds writable area (due to padding)
-        full_page_height = scratch.effective_page_height
-        partial_page_height = [full_page_height, start_y - scratch.y].min
-        scratch_bounds.instance_variable_set :@x, original_x
-        scratch_bounds.instance_variable_set :@width, original_width
-        whole_pages = scratch.page_number - start_page_number
-        [(whole_pages * full_page_height + partial_page_height), whole_pages, partial_page_height]
-      end
-
       def with_dry_run &block
-        total_height, = dry_run(&block)
-        instance_exec total_height, &block
+        yield dry_run(&block).position_onto self, cursor
       end
 
-      # Attempt to keep the objects generated in the block on the same page
+      # Yields to the specified block multiple times, first to determine where to render the content
+      # so it fits properly, then once more, this time providing access to the content's extent, to
+      # ink the content in the primary document.
       #
-      # TODO: short-circuit nested usage
-      def keep_together &block
-        available_space = cursor
-        total_height, = dry_run(&block)
-        # NOTE technically, if we're at the page top, we don't even need to do the
-        # dry run, except several uses of this method rely on the calculated height
-        if total_height > available_space && !at_page_top? && total_height <= effective_page_height
-          advance_page
-          started_new_page = true
-        else
-          started_new_page = false
+      # This method yields to the specified block in a scratch document by calling dry_run to
+      # determine where the content should start in the primary document. In the process, it also
+      # computes the extent of the content. It then returns to the primary document and yields to
+      # the block again, this time passing in the extent of the content. The extent can be used to
+      # draw a border and/or background under the content before inking it.
+      #
+      # This method is intended to enclose the conversion of a single content block, such as a
+      # sidebar or example block. The arrange logic attempts to keep unbreakable content on the same
+      # page, keeps the top caption pinned to the top of the content, computes the extent of the
+      # content for the purpose of drawing a border and/or background underneath it, and ensures
+      # that the extent does not begin near the bottom of a page if the first line of content
+      # doesn't fit. If unbreakable content does not fit on a single page, the content is treated as
+      # breakable.
+      #
+      # The block passed to this method should use advance_page to move to the next page rather than
+      # start_new_page. Using start_new_page can mangle the calculation of content block's extent.
+      #
+      def arrange_block node, &block
+        keep_together = (node.option? 'unbreakable') && !at_page_top?
+        doc = node.document
+        block_for_scratch = proc do
+          push_scratch doc
+          instance_exec(&block)
+        ensure
+          pop_scratch doc
         end
+        extent = dry_run keep_together: keep_together, onto: [self, keep_together], &block_for_scratch
+        scratch? ? block_for_scratch.call : (yield extent)
+      end
 
-        # HACK: yield doesn't work here on JRuby (at least not when called from AsciidoctorJ)
-        #yield remainder, started_new_page
-        instance_exec(total_height, started_new_page, &block)
+      # This method installs an on_page_create_callback that stops processing if the first page is
+      # exceeded while yielding to the specified block. If the content fits on a single page, the
+      # processing is not stopped. The purpose of this method is to determine if the content fits on
+      # a single page.
+      #
+      # Returns a Boolean indicating whether the content fits on a single page.
+      def perform_on_single_page
+        saved_callback, state.on_page_create_callback = state.on_page_create_callback, InhibitNewPageProc
+        yield
+        false
+      rescue NewPageRequiredError
+        true
+      ensure
+        state.on_page_create_callback = saved_callback
       end
 
-      # Attempt to keep the objects generated in the block on the same page
-      # if the verdict parameter is true.
+      # This method installs an on_page_create_callback that stops processing if a new page is
+      # created without writing content to the first page while yielding to the specified block. If
+      # any content is written to the first page, processing is not stopped. The purpose of this
+      # method is to check whether any content fits on the remaining space on the current page.
       #
-      def keep_together_if verdict, &block
-        if verdict
-          keep_together(&block)
-        else
+      # Returns a Boolean indicating whether any content is written on the first page.
+      def stop_if_first_page_empty
+        delegate = state.on_page_create_callback
+        state.on_page_create_callback = DetectEmptyFirstPageProc.curry[delegate].extend DetectEmptyFirstPage
+        yield
+        false
+      rescue NewPageRequiredError
+        true
+      ensure
+        state.on_page_create_callback = delegate
+      end
+
+      # NOTE: only used in dry_run since that's when DetectEmptyFirstPage is active
+      def tare_first_page_content_stream
+        return yield unless DetectEmptyFirstPage === (delegate = state.on_page_create_callback)
+        on_page_create_called = nil
+        state.on_page_create_callback = proc do |pdf|
+          on_page_create_called = true
+          pdf.state.pages[pdf.page_number - 2].tare_content_stream
+          delegate.call pdf
+        end
+        begin
           yield
+        ensure
+          page.tare_content_stream unless on_page_create_called
+          state.on_page_create_callback = delegate
         end
       end
 
-=begin
-      def run_with_trial &block
-        available_space = cursor
-        total_height, whole_pages, remainder = dry_run(&block)
-        if whole_pages > 0 || remainder > available_space
-          started_new_page = true
-        else
-          started_new_page = false
+      # Yields to the specified block within the context of a scratch document up to three times to
+      # acertain the extent of the content block.
+      #
+      # The purpose of this method is two-fold. First, it works out the position where the rendered
+      # content should start in the calling document. Then, it precomputes the extent of the content
+      # starting from that position.
+      #
+      # This method returns the content's extent (the range from the start page and cursor to the
+      # end page and cursor) as a ScratchExtent object or, if the onto keyword parameter is
+      # specified, an Extent object. A ScratchExtent always starts the page range at 1. When the
+      # ScratchExtent is positioned onto the primary document using ScratchExtent#position_onto,
+      # that's when the cursor may be advanced to the next page.
+      #
+      # This method performs all work in a scratch document (or documents). It begins by starting a
+      # new page in the scratch document, first creating the scratch document if necessary. It then
+      # applies all the settings from the main document to the scratch document that impact
+      # rendering. This includes the bounds, the cursor position, and the font settings.
+      #
+      # From this point, the number of attempts the method makes is determined by the value of the
+      # keep_together keyword parameter. If the value is true (or the parent document is inhibiting
+      # page creation), it starts from the top of the page, yields to the block, and tries to fit
+      # the content on the current page. If the content fits, it computes and returns the
+      # ScratchExtent (or Extent). If the content does not fit, it first checks if this scenario
+      # should stop the operation. If the parent document is inhibiting page creation, it bubbles
+      # the error. If the single_page keyword argument is :enforce, it raises a CannotFit error. If
+      # the single_page keyword argument is true, it returns a ScratchExtent (or Extent) that
+      # represents a full page. If none of those conditions are met, it restarts with the
+      # keep_together parameter unset.
+      #
+      # If the keep_together parameter is not true, the method tries to render the content in the
+      # scratch document from the location of the cursor in the main document. If the cursor is at
+      # the top of the page, no special conditions are applied (this is the last attempt). The
+      # content is rendered and the extent is computed based on where the content ended up (minus a
+      # trailing empty page). If the cursor is not at the top of the page, the method renders the
+      # content while listening for a page creation event before any content is written. If a new
+      # page is created, and no content is written on the first page, the method restarts with the
+      # cursor at the top of the page.
+      #
+      # Note that if the block has content that itself requires a dry run, that nested dry run will
+      # be performed in a separate scratch document.
+      #
+      # opts - A Hash of options that configure the dry run computation:
+      #        :keep_together - A Boolean indicating whether an attempt should be made to keep the
+      #        content on the same page (optional, default: false).
+      #        :single_page - A Boolean indicating whether the operation should stop if the content
+      #        exceeds the height of a single page.
+      #        :onto - The document onto which to position the scratch extent. If this option is
+      #        set, the method returns an Extent instead of a ScratchExtent (optional, default: nil)
+      #        :pages_advanced - The number of pages the content has been advanced during this
+      #        operation (internal only) (optional, default: 0)
+      #
+      # Returns an Extent or ScratchExtent object that describes the bounds of the content block.
+      def dry_run keep_together: nil, pages_advanced: 0, single_page: nil, onto: nil, &block
+        (scratch_pdf = scratch).start_new_page
+        scratch_bounds = scratch_pdf.bounds
+        restore_bounds = [:@total_left_padding, :@total_right_padding, :@width, :@x].each_with_object({}) do |name, accum|
+          accum[name] = scratch_bounds.instance_variable_get name
+          scratch_bounds.instance_variable_set name, (bounds.instance_variable_get name)
+        end
+        scratch_pdf.move_cursor_to cursor unless (scratch_start_at_top = keep_together || pages_advanced > 0 || at_page_top?)
+        scratch_start_cursor = scratch_pdf.cursor
+        scratch_start_page = scratch_pdf.page_number
+        inhibit_new_page = state.on_page_create_callback == InhibitNewPageProc
+        restart = nil
+        scratch_pdf.font font_family, size: font_size, style: font_style do
+          prev_font_scale, scratch_pdf.font_scale = scratch_pdf.font_scale, font_scale
+          if keep_together || inhibit_new_page
+            if (restart = scratch_pdf.perform_on_single_page { scratch_pdf.instance_exec(&block) })
+              # NOTE: propogate NewPageRequiredError from nested block, which is rendered in separate scratch document
+              raise NewPageRequiredError if inhibit_new_page
+              if single_page
+                raise ::Prawn::Errors::CannotFit if single_page == :enforce
+                # single_page and onto are mutually exclusive
+                return ScratchExtent.new scratch_start_page, scratch_start_cursor, scratch_start_page, 0
+              end
+            end
+          elsif scratch_start_at_top
+            scratch_pdf.instance_exec(&block)
+          elsif (restart = scratch_pdf.stop_if_first_page_empty { scratch_pdf.instance_exec(&block) })
+            pages_advanced += 1
+          end
+        ensure
+          scratch_pdf.font_scale = prev_font_scale
+        end
+        return dry_run pages_advanced: pages_advanced, onto: onto, &block if restart
+        scratch_end_page = scratch_pdf.page_number - scratch_start_page + (scratch_start_page = 1)
+        if pages_advanced > 0
+          scratch_start_page += pages_advanced
+          scratch_end_page += pages_advanced
+        end
+        scratch_end_cursor = scratch_pdf.cursor
+        # NOTE: drop trailing blank page and move cursor to end of previous page
+        if scratch_end_page > scratch_start_page && scratch_pdf.at_page_top?
+          scratch_end_page -= 1
+          scratch_end_cursor = 0
         end
-        # HACK yield doesn't work here on JRuby (at least not when called from AsciidoctorJ)
-        #yield remainder, started_new_page
-        instance_exec(remainder, started_new_page, &block)
+        extent = ScratchExtent.new scratch_start_page, scratch_start_cursor, scratch_end_page, scratch_end_cursor
+        onto ? extent.position_onto(*onto) : extent
+      ensure
+        restore_bounds.each {|name, val| scratch_bounds.instance_variable_set name, val }
       end
-=end
     end
   end
 end