resolves #259 fill and stroke bounds of sidebar across all pages (PR #…

…781)

* resolves #259 fill and stroke bounds of sidebar across all pages
* add continuation border at page boundaries in sidebar
* add advance_page method; use in place of start_new_page when converting section content
* advanced sidebar to next page even when split across pages

data/themes/default-theme.yml

@@ -190,10 +190,10 @@ prose:
   margin_top: $block_margin_top
   margin_bottom: $block_margin_bottom
 sidebar:
-  border_color: $page_background_color
+  background_color: eeeeee
+  border_color: e1e1e1
   border_radius: $base_border_radius
   border_width: $base_border_width
-  background_color: eeeeee
   # FIXME reenable padding bottom once margin collapsing is implemented
   padding: [$vertical_rhythm, $vertical_rhythm * 1.25, 0, $vertical_rhythm * 1.25]
   title:

lib/asciidoctor-pdf/converter.rb

@@ -749,9 +749,47 @@ def convert_sidebar node
     theme_margin :block, :top
     keep_together do |box_height = nil|
       if box_height
+        # FIXME due to the calculation error logged in #789, we must advance page even when content is split across pages
+        advance_page if box_height > cursor && !at_page_top?
         float do
-          bounding_box [0, cursor], width: bounds.width, height: box_height do
-            theme_fill_and_stroke_bounds :sidebar
+          # TODO move the multi-page logic to theme_fill_and_stroke_bounds
+          if (b_width = @theme.sidebar_border_width || 0) > 0 && (b_color = @theme.sidebar_border_color)
+            if b_color == @page_bg_color # let page background cut into sidebar background
+              b_gap_color, b_shift = @page_bg_color, b_width
+            elsif (b_gap_color = @theme.sidebar_background_color) && b_gap_color != b_color
+              b_shift = 0
+            else # let page background cut into border
+              b_gap_color, b_shift = @page_bg_color, 0
+            end
+          else # let page background cut into sidebar background
+            b_width = 0.5 if b_width == 0
+            b_shift, b_gap_color = b_width * 0.5, @page_bg_color
+          end
+          b_radius = (@theme.sidebar_border_radius || 0) + b_width
+          initial_page, remaining_height = true, box_height
+          while remaining_height > 0
+            advance_page unless initial_page
+            fragment_height = [(available_height = cursor), remaining_height].min
+            bounding_box [0, available_height], width: bounds.width, height: fragment_height do
+              theme_fill_and_stroke_bounds :sidebar
+              unless b_width == 0
+                indent b_radius, b_radius do
+                  move_down b_shift
+                  # dashed line to indicate continuation from previous page; swell line to cover background
+                  stroke_horizontal_rule b_gap_color, line_width: b_width * 1.2, line_style: :dashed
+                  move_up b_shift
+                end unless initial_page
+                if remaining_height > fragment_height
+                  move_down fragment_height - b_shift
+                  indent b_radius, b_radius do
+                    # dashed line to indicate continuation to next page; swell line to cover background
+                    stroke_horizontal_rule b_gap_color, line_width: b_width * 1.2, line_style: :dashed
+                  end
+                end
+              end
+            end
+            remaining_height -= fragment_height
+            initial_page = false
           end
         end
       end
@@ -792,7 +830,7 @@ def convert_colist node
     line_metrics = calc_line_metrics @theme.base_line_height
     node.items.each_with_index do |item, idx|
       # FIXME extract to an ensure_space (or similar) method; simplify
-      start_new_page if cursor < (line_metrics.height + line_metrics.leading + line_metrics.padding_top)
+      advance_page if cursor < (line_metrics.height + line_metrics.leading + line_metrics.padding_top)
       convert_colist_item item
     end
     @list_numbers.pop
@@ -831,7 +869,7 @@ def convert_dlist node
       terms = [*terms]
       # NOTE don't orphan the terms, allow for at least one line of content
       # FIXME extract ensure_space (or similar) method
-      start_new_page if cursor < @theme.base_line_height_length * (terms.size + 1)
+      advance_page if cursor < @theme.base_line_height_length * (terms.size + 1)
       terms.each do |term|
         layout_prose term.text, style: @theme.description_list_term_font_style.to_sym, margin_top: 0, margin_bottom: @theme.description_list_term_spacing, align: :left
       end
@@ -933,7 +971,7 @@ def convert_outline_list node
     indent list_indent do
       node.items.each do |item|
         # FIXME extract to an ensure_space (or similar) method; simplify
-        start_new_page if cursor < (line_metrics.height + line_metrics.leading + line_metrics.padding_top)
+        advance_page if cursor < (line_metrics.height + line_metrics.leading + line_metrics.padding_top)
         convert_outline_list_item item, item.complex?
       end
     end
@@ -1067,7 +1105,7 @@ def convert_image node, opts = {}
           # NOTE shrink image so it fits within available space; group image & caption
           if (rendered_h = svg_size.output_height) > (available_h = cursor - caption_h)
             unless pinned || at_page_top?
-              start_new_page
+              advance_page
               available_h = cursor - caption_h
             end
             if rendered_h > available_h
@@ -1096,7 +1134,7 @@ def convert_image node, opts = {}
           # NOTE shrink image so it fits within available space; group image & caption
           if rendered_h > (available_h = cursor - caption_h)
             unless pinned || at_page_top?
-              start_new_page
+              advance_page
               available_h = cursor - caption_h
             end
             if rendered_h > available_h
@@ -1770,7 +1808,7 @@ def convert_toc node
 
   # NOTE to insert sequential page breaks, you must put {nbsp} between page breaks
   def convert_page_break node
-    start_new_page unless at_page_top?
+    advance_page unless at_page_top?
   end
 
   def convert_index_section node

lib/asciidoctor-pdf/prawn_ext/extensions.rb

@@ -736,13 +736,12 @@ def perform_discretely
     end
   end
 
-  #def advance_or_start_new_page options = {}
-  #  if last_page?
-  #    start_new_page options
-  #  else
-  #    go_to_page page_number + 1
-  #  end
-  #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
+    last_page? ? start_new_page : (go_to_page page_number + 1)
+  end
 
   # Start a new page without triggering the on_page_create callback
   #