asciidoctor-pdf 1.5.0.alpha.7 → 1.5.0.alpha.8

data/lib/asciidoctor-pdf/asciidoctor_ext.rb

@@ -1,3 +1,5 @@
+# NOTE these are all candidates for inclusion in Asciidoctor core
 require_relative 'asciidoctor_ext/section'
 require_relative 'asciidoctor_ext/list'
 require_relative 'asciidoctor_ext/list_item'
+require_relative 'asciidoctor_ext/image'

data/lib/asciidoctor-pdf/asciidoctor_ext/image.rb

@@ -0,0 +1,18 @@
+module Asciidoctor
+module Image
+  class << self
+    def image_type path
+      (::File.extname path).downcase[1..-1]
+    end
+  end
+
+  def image_type
+    ::File.extname(inline? ? target : (attr 'target')).downcase[1..-1]
+  end
+
+  def target_with_image_type
+    image_path = inline? ? (target) : (attr 'target')
+    [image_path, (::File.extname image_path).downcase[1..-1]]
+  end
+end
+end

data/lib/asciidoctor-pdf/converter.rb

@@ -1,14 +1,16 @@
 # encoding: UTF-8
 # TODO cleanup imports...decide what belongs in asciidoctor-pdf.rb
-require_relative 'core_ext/array'
 require 'prawn'
 require 'prawn-svg'
 require 'prawn/table'
 require 'prawn/templates'
 require 'prawn/icon'
+require_relative 'core_ext'
 require_relative 'pdf_core_ext'
+require_relative 'temporary_path'
 require_relative 'sanitizer'
 require_relative 'prawn_ext'
+require_relative 'formatted_text'
 require_relative 'pdfmarks'
 require_relative 'asciidoctor_ext'
 require_relative 'theme_loader'
@@ -55,9 +57,19 @@ class Converter < ::Prawn::Document
     circle: (unicode_char 0x25e6),
     square: (unicode_char 0x25aa)
   }
+  # NOTE Default theme font uses ballot boxes from FontAwesome
+  BallotBox = {
+    checked: (unicode_char 0x2611),
+    unchecked: (unicode_char 0x2610)
+  }
+  IconSets = ['fa', 'fi', 'octicon', 'pf']
+  MeasurementRxt = '\\d+(?:\\.\\d+)?(?:in|cm|mm|pt|)'
+  MeasurementPartsRx = /^(\d+(?:\.\d+)?)(in|mm|cm|pt|)$/
+  PageSizeRx = /^(?:\[(#{MeasurementRxt}), ?(#{MeasurementRxt})\]|(#{MeasurementRxt})(?: x |x)(#{MeasurementRxt})|\S+)$/
   # CalloutExtractRx synced from /lib/asciidoctor.rb of Asciidoctor core
   CalloutExtractRx = /(?:(?:\/\/|#|--|;;) ?)?(\\)?<!?(--|)(\d+)\2>(?=(?: ?\\?<!?\2\d+\2>)*$)/
   ImageAttributeValueRx = /^image:{1,2}(.*?)\[(.*?)\]$/
+  LineScanRx = /\n|.+/
 
   def initialize backend, opts
     super
@@ -91,7 +103,7 @@ class Converter < ::Prawn::Document
     if node.blocks?
       node.content
     elsif node.content_model != :compound && (string = node.content)
-      # TODO this content could be catched on repeat invocations!
+      # TODO this content could be cached on repeat invocations!
       layout_prose string, opts
     end
     node.document.instance_variable_set :@converter, prev_converter if prev_converter
@@ -109,10 +121,10 @@ class Converter < ::Prawn::Document
         # FIXME implement fitting and centering for SVG
         # TODO implement image scaling (numeric value or "fit")
         float { canvas { image @page_bg_image, position: :center, fit: [bounds.width, bounds.height] } }
-      elsif @page_bg_color
+      elsif @page_bg_color && @page_bg_color != 'FFFFFF'
         fill_absolute_bounds @page_bg_color
       end
-    end
+    end if respond_to? :on_page_create
 
     layout_cover_page :front, doc
     layout_title_page doc
@@ -121,12 +133,12 @@ class Converter < ::Prawn::Document
 
     toc_start_page_num = page_number
     num_toc_levels = (doc.attr 'toclevels', 2).to_i
-    if doc.attr? 'toc'
+    if (include_toc = doc.attr? 'toc')
       toc_page_nums = ()
       dry_run do
         toc_page_nums = layout_toc doc, num_toc_levels, 1
       end
-      # reserve pages for the toc
+      # NOTE reserve pages for the toc
       toc_page_nums.each do
         start_new_page
       end
@@ -136,7 +148,7 @@ class Converter < ::Prawn::Document
     font @theme.base_font_family, size: @theme.base_font_size
     convert_content_for_block doc
 
-    toc_page_nums = if doc.attr? 'toc'
+    toc_page_nums = if include_toc
       layout_toc doc, num_toc_levels, toc_start_page_num, num_front_matter_pages
     else
       (0..-1)
@@ -177,9 +189,7 @@ class Converter < ::Prawn::Document
       end
     end
     @fallback_fonts = [*theme.font_fallbacks]
-    if ['FFFFFF', 'transparent'].include?(@page_bg_color = theme.page_background_color)
-      @page_bg_color = nil
-    end
+    @page_bg_color = resolve_theme_color :page_background_color, 'FFFFFF'
     @font_color = theme.base_font_color || '000000'
     @text_transform = nil
     @stamps = {}
@@ -197,37 +207,39 @@ class Converter < ::Prawn::Document
       skip_page_creation: true,
     }
 
-    if doc.attr? 'pdf-page-size'
-      page_size = ::YAML.safe_load(doc.attr 'pdf-page-size')
+    page_size = if (doc.attr? 'pdf-page-size') && (m = PageSizeRx.match(doc.attr 'pdf-page-size'))
+      # e.g, [8.5in, 11in]
+      if m[1]
+        [m[1], m[2]]
+      # e.g, 8.5in x 11in
+      elsif m[3]
+        [m[3], m[4]]
+      # e.g, A4
+      else
+        m[0]
+      end
     else
-      page_size = theme.page_size
+      theme.page_size
     end
 
-    pdf_opts[:page_size] = case page_size
+    page_size = case page_size
     when ::String
+      # TODO extract helper method to check for named page size
       if ::PDF::Core::PageGeometry::SIZES.key?(page_size = page_size.upcase)
         page_size
-      else
-        'LETTER'
       end
     when ::Array
-      page_size.fill(0..1) {|i| page_size[i] || 0 }.map {|d|
-        if ::Numeric === d
-          break if d == 0
-          d
-        elsif ::String === d && (m = /^(\d*(?:\.\d+)?)(in|mm|cm|pt)$/.match d)
-          val = m[1].to_f
-          val = case m[2]
-          when 'in'
-            val * 72
-          when 'mm'
-            val * (72 / 25.4)
-          when 'cm'
-            val * (720 / 25.4)
-          when 'pt'
-            val
-          end
+      unless page_size.size == 2
+        page_size = page_size[0..1].fill(0..1) {|i| page_size[i] || 0}
+      end
+      page_size.map do |dim|
+        if ::Numeric === dim
+          # dimension cannot be less than 0
+          dim > 0 ? dim : break
+        elsif ::String === dim && (m = (MeasurementPartsRx.match dim))
+          val = to_pt m[1].to_f, m[2]
           # NOTE 4 is the max practical precision in PDFs
+          # QUESTION should we make rounding a feature of the to_pt method?
           if (val = val.round 4) == (i_val = val.to_i)
             val = i_val
           end
@@ -235,13 +247,12 @@ class Converter < ::Prawn::Document
         else
           break
         end
-      }
+      end
     end
 
-    pdf_opts[:page_size] ||= 'LETTER'
+    pdf_opts[:page_size] = (page_size || 'LETTER')
 
-    # FIXME fix the namespace for FormattedTextFormatter
-    pdf_opts[:text_formatter] ||= ::Asciidoctor::Prawn::FormattedTextFormatter.new theme: theme
+    pdf_opts[:text_formatter] ||= FormattedText::Formatter.new theme: theme
     pdf_opts
   end
 
@@ -328,7 +339,6 @@ class Converter < ::Prawn::Document
       end
     end
     # QUESTION should we be adding margin below the abstract??
-    #move_down @theme.block_margin_bottom
     #theme_margin :block, :bottom
   end
 
@@ -353,6 +363,8 @@ class Converter < ::Prawn::Document
         prose_opts[:align] = :right
       when 'text-justify'
         prose_opts[:align] = :justify
+      when 'text-center'
+        prose_opts[:align] = :center
       when 'lead'
         is_lead = true
       #when 'signature'
@@ -376,7 +388,6 @@ class Converter < ::Prawn::Document
   # FIXME alignment of content is off
   def convert_admonition node
     add_dest_for_block node if node.id
-    #move_down @theme.block_margin_top unless at_page_top?
     theme_margin :block, :top
     icons = node.document.attr? 'icons', 'font'
     label = icons ? (node.attr 'name').to_sym : node.caption.upcase
@@ -417,13 +428,11 @@ class Converter < ::Prawn::Document
         end
       #end
     end
-    #move_down @theme.block_margin_bottom
     theme_margin :block, :bottom
   end
 
   def convert_example node
     add_dest_for_block node if node.id
-    #move_down @theme.block_margin_top unless at_page_top?
     theme_margin :block, :top
     keep_together do |box_height = nil|
       caption_height = node.title? ? (layout_caption node) : 0
@@ -440,7 +449,6 @@ class Converter < ::Prawn::Document
         end
       end
     end
-    #move_down @theme.block_margin_bottom
     theme_margin :block, :bottom
   end
 
@@ -465,7 +473,6 @@ class Converter < ::Prawn::Document
   def convert_quote_or_verse node
     add_dest_for_block node if node.id
     border_width = @theme.blockquote_border_width || 0
-    #move_down @theme.block_margin_top unless at_page_top?
     theme_margin :block, :top
     keep_together do |box_height = nil|
       start_cursor = cursor
@@ -493,7 +500,6 @@ class Converter < ::Prawn::Document
         end
       end
     end
-    #move_down @theme.block_margin_bottom
     theme_margin :block, :bottom
   end
 
@@ -502,7 +508,6 @@ class Converter < ::Prawn::Document
 
   def convert_sidebar node
     add_dest_for_block node if node.id
-    #move_down @theme.block_margin_top unless at_page_top?
     theme_margin :block, :top
     keep_together do |box_height = nil|
       if box_height
@@ -526,19 +531,21 @@ class Converter < ::Prawn::Document
         move_up(@theme.prose_margin_bottom || @theme.vertical_rhythm)
       end
     end
-    #move_down @theme.block_margin_bottom
     theme_margin :block, :bottom
   end
 
   def convert_colist node
     # HACK undo the margin below previous listing or literal block
     # TODO allow this to be set using colist_margin_top
-    unless at_page_top? || (self_idx = node.parent.blocks.index node) == 0 ||
-        ![:listing, :literal].include?(node.parent.blocks[self_idx - 1].context)
-      move_up ((@theme.block_margin_bottom || @theme.vertical_rhythm) / 2.0)
-      # or we could do...
-      #move_up (@theme.block_margin_bottom || @theme.vertical_rhythm)
-      #move_down (@theme.caption_margin_inside * 2)
+    unless at_page_top?
+      # NOTE this logic won't work for a colist nested inside a list item until Asciidoctor 1.5.3
+      if (self_idx = node.parent.blocks.index node) && self_idx > 0 &&
+          [:listing, :literal].include?(node.parent.blocks[self_idx - 1].context)
+        move_up ((@theme.block_margin_bottom || @theme.vertical_rhythm) / 2.0)
+        # or we could do...
+        #move_up (@theme.block_margin_bottom || @theme.vertical_rhythm)
+        #move_down (@theme.caption_margin_inside * 2)
+      end
     end
     add_dest_for_block node if node.id
     @list_numbers ||= []
@@ -584,7 +591,7 @@ class Converter < ::Prawn::Document
       # FIXME extract ensure_space (or similar) method
       start_new_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.vertical_rhythm / 3.0), align: :left
+        layout_prose term.text, style: (@theme.description_list_term_font_style || :normal).to_sym, margin_top: 0, margin_bottom: (@theme.vertical_rhythm / 3.0), align: :left
       end
       if desc
         indent @theme.description_list_description_indent do
@@ -623,27 +630,30 @@ class Converter < ::Prawn::Document
     @list_numbers.pop
   end
 
-  # TODO implement checklist
   def convert_ulist node
     add_dest_for_block node if node.id
-    bullet_type = if (style = node.style)
-      case style
-      when 'bibliography'
-        :square
-      else
-        style.to_sym
-      end
+    if node.option? 'checklist'
+      @list_bullets << :checkbox
     else
-      case (node.level % 3)
-      when 1
-        :disc
-      when 2
-        :circle
-      when 0
-        :square
+      bullet_type = if (style = node.style)
+        case style
+        when 'bibliography'
+          :square
+        else
+          style.to_sym
+        end
+      else
+        case (node.level % 3)
+        when 1
+          :disc
+        when 2
+          :circle
+        when 0
+          :square
+        end
       end
+      @list_bullets << Bullets[bullet_type]
     end
-    @list_bullets << Bullets[bullet_type]
     convert_outline_list node
     @list_bullets.pop
   end
@@ -671,28 +681,39 @@ class Converter < ::Prawn::Document
 
   def convert_outline_list_item node, complex = false
     # TODO move this to a draw_bullet (or draw_marker) method
-    marker = case (list_type = node.parent.context)
+    case (list_type = node.parent.context)
     when :ulist
-      @list_bullets.last
+      marker = @list_bullets.last
+      if marker == :checkbox
+        if node.attr? 'checkbox'
+          marker = BallotBox[(node.attr? 'checked') ? :checked : :unchecked]
+        else
+          # QUESTION should we remove marker indent in this case?
+          marker = nil
+        end
+      end
     when :olist
       @list_numbers << (index = @list_numbers.pop).next
-      %(#{index}.)
+      marker = %(#{index}.)
     else
       warn %(asciidoctor: WARNING: unknown list type #{list_type.inspect})
-      Bullets[:disc]
+      marker = Bullets[:disc]
     end
 
-    marker_width = width_of marker
-    start_position = -marker_width + -(width_of 'x')
-    float do
-      bounding_box [start_position, cursor], width: marker_width do
-        layout_prose marker,
-          align: :right,
-          normalize: false,
-          inline_format: false,
-          margin: 0,
-          character_spacing: -0.5,
-          single_line: true
+    if marker
+      marker_width = width_of marker
+      start_position = -marker_width + -(width_of 'x')
+      float do
+        bounding_box [start_position, cursor], width: marker_width do
+          layout_prose marker,
+            align: :right,
+            color: (@theme.outline_list_marker_font_color || @font_color),
+            normalize: false,
+            inline_format: false,
+            margin: 0,
+            character_spacing: -0.5,
+            single_line: true
+        end
       end
     end
 
@@ -713,14 +734,13 @@ class Converter < ::Prawn::Document
   end
 
   def convert_image node
+    node.extend ::Asciidoctor::Image unless ::Asciidoctor::Image === node
     valid_image = true
-    target = node.attr 'target'
-    # TODO file extension should be an attribute on an image node
-    image_type = (::File.extname target)[1..-1].downcase
+    target, image_type = node.target_with_image_type
 
     if image_type == 'gif'
       valid_image = false
-      warn %(asciidoctor: WARNING: GIF image format not supported. Please convert the image #{target} to PNG.)
+      warn %(asciidoctor: WARNING: GIF image format not supported. Please convert #{target} to PNG.)
     #elsif image_type == 'pdf'
     #  import_page image_path
     #  return
@@ -731,11 +751,22 @@ class Converter < ::Prawn::Document
       warn %(asciidoctor: WARNING: image to embed not found or not readable: #{image_path || target})
     end
 
+    # QUESTION if we advance to new page, shouldn't dest point there too?
     add_dest_for_block node if node.id
+    position = ((node.attr 'align') || @theme.image_align || :left).to_sym
 
     unless valid_image
       theme_margin :block, :top
-      layout_prose %(#{node.attr 'alt'} | #{target}), normalize: false, margin: 0, single_line: true
+      if (link = node.attr 'link')
+        alt_text = %(<a href="#{link}">[#{NoBreakSpace}#{node.attr 'alt'}#{NoBreakSpace}]</a> | <em>#{target}</em>)
+      else
+        alt_text = %([#{NoBreakSpace}#{node.attr 'alt'}#{NoBreakSpace}] | <em>#{target}</em>)
+      end
+      layout_prose alt_text,
+          normalize: false,
+          margin: 0,
+          single_line: true,
+          align: position
       layout_caption node, position: :bottom if node.title?
       theme_margin :block, :bottom
       return
@@ -744,37 +775,35 @@ class Converter < ::Prawn::Document
     theme_margin :block, :top
 
     # TODO support cover (aka canvas) image layout using "canvas" (or "cover") role
-    width = if node.attr? 'scaledwidth'
-      ((node.attr 'scaledwidth').to_f / 100.0) * bounds.width
-    elsif image_type == 'svg'
-      bounds.width
+    # NOTE height values are basically ignored (image is scaled proportionally based on width)
+    width = if node.attr? 'pdfwidth'
+      if (pdfwidth = node.attr 'pdfwidth').end_with? '%'
+        (pdfwidth.to_f / 100) * bounds.width
+      else
+        str_to_pt pdfwidth
+      end
+    elsif node.attr? 'scaledwidth'
+      ((node.attr 'scaledwidth').to_f / 100) * bounds.width
     elsif node.attr? 'width'
-      (node.attr 'width').to_f
-    else
-      bounds.width * (@theme.image_scaled_width_default || 0.75)
+      # NOTE width is in pixels, so scale by 75%; restrict to max width of bounds.width
+      [bounds.width, (node.attr 'width').to_f * 0.75].min
     end
-    position = ((node.attr 'align') || @theme.image_align_default || :left).to_sym
+
     case image_type
     when 'svg'
-      # NOTE prawn-svg can't position, so we have to do it manually (file issue?)
-      left = case position
-      when :left
-        0
-      when :right
-        bounds.width - width
-      when :center
-        ((bounds.width - width) / 2.0).floor
-      end
       begin
-        img_data = ::IO.read image_path
+        svg_obj = ::Prawn::Svg::Interface.new (::IO.read image_path), self, position: position, width: width
+        actual_w = svg_obj.document.sizing.output_width
+        actual_h = svg_obj.document.sizing.output_height
+        rel_left = { left: 0, right: (bounds.width - actual_w), center: ((bounds.width - actual_w) / 2.0) }[position]
+        # TODO layout SVG without using keep_together (since we know the dimensions already); always render caption
         keep_together do |box_height = nil|
+          svg_obj.instance_variable_set :@prawn, self
+          svg_obj.draw
           if box_height && (link = node.attr 'link')
-            result = svg img_data, at: [left, cursor], width: width
-            link_annotation [(abs_left = left + bounds.absolute_left), y, (abs_left + width), (y + result[:height])],
-              Border: [0, 0, 0],
-              A: { Type: :Action, S: :URI, URI: (str2pdfval link) }
-          else
-            svg img_data, at: [left, cursor], width: width
+            link_annotation [(abs_left = rel_left + bounds.absolute_left), y, (abs_left + actual_w), (y + actual_h)],
+                Border: [0, 0, 0],
+                A: { Type: :Action, S: :URI, URI: (str2pdfval link) }
           end
           layout_caption node, position: :bottom if node.title?
         end
@@ -784,32 +813,37 @@ class Converter < ::Prawn::Document
     else
       begin
         # FIXME temporary workaround to group caption & image
-        # Prawn doesn't provide access to rendered width and height before placing the
-        # image on the page
+        # Prawn doesn't provide access to rendered width & height before placing image on page
         # FIXME this code really needs to be better organized!
         image_obj, image_info = build_image_object image_path
-        rendered_w, rendered_h = image_info.calc_image_dimensions width: width
+        if width
+          rendered_w, rendered_h = image_info.calc_image_dimensions width: width
+        else
+          # NOTE native size is in pixels, so scale by 75%; restrict to max width of bounds.width
+          rendered_w = [bounds.width, image_info.width * 0.75].min
+          rendered_h = (rendered_w * image_info.height) / image_info.width
+        end
         # TODO move this calculation into a method
         caption_height = node.title? ?
             (@theme.caption_margin_inside + @theme.caption_margin_outside + @theme.base_line_height_length) : 0
-        height = nil
-        if cursor < rendered_h + caption_height
-          start_new_page
-          if cursor < rendered_h + caption_height
-            height = (cursor - caption_height).floor
-            width = ((rendered_w * height) / rendered_h).floor
+        if rendered_h > (available_height = cursor - caption_height)
+          start_new_page unless at_page_top?
+          # NOTE shrink image so it fits on a single page
+          if rendered_h > (available_height = cursor - caption_height)
+            rendered_w = (rendered_w * available_height) / rendered_h
+            rendered_h = available_height
             # FIXME workaround to fix Prawn not adding fill and stroke commands
             # on page that only has an image; breakage occurs when line numbers are added
             fill_color self.fill_color
             stroke_color self.stroke_color
           end
         end
+        # NOTE must calculate link position before embedding to get proper boundaries
         if (link = node.attr 'link')
-          actual_w, actual_h = [(width || rendered_w), (height || rendered_h)]
-          img_x, img_y = image_position actual_w, actual_h, position: position
-          link_box = [img_x, (img_y - actual_h), img_x + actual_w, img_y]
+          img_x, img_y = image_position rendered_w, rendered_h, position: position
+          link_box = [img_x, (img_y - rendered_h), (img_x + rendered_w), img_y]
         end
-        embed_image image_obj, image_info, width: width, height: height, position: position
+        embed_image image_obj, image_info, width: rendered_w, position: position
         if link
           link_annotation link_box,
             Border: [0, 0, 0],
@@ -825,7 +859,7 @@ class Converter < ::Prawn::Document
     unlink_tmp_file image_path
   end
 
-  # TODO shrink text if it's too wide to fit in the bounding box
+  # QUESTION can we avoid arranging fragments multiple times (conums & autofit) by eagerly preparing arranger?
   def convert_listing_or_literal node
     add_dest_for_block node if node.id
     # HACK disable built-in syntax highlighter; must be done before calling node.content!
@@ -834,13 +868,11 @@ class Converter < ::Prawn::Document
       highlighter = node.document.attr 'source-highlighter'
       # NOTE the source highlighter logic below handles the callouts and highlight subs
       prev_subs = subs.dup
-      subs.delete :callouts
-      subs.delete :highlight
+      subs.delete_all :highlight, :callouts
     else
       highlighter = nil
       prev_subs = nil
     end
-    # FIXME source highlighter freaks out about the non-breaking space characters; does it?
     source_string = preserve_indentation node.content
     source_chunks = case highlighter
     when 'coderay'
@@ -858,28 +890,55 @@ class Converter < ::Prawn::Document
       conum_mapping ? (restore_conums fragments, conum_mapping) : fragments
     else
       # NOTE only format if we detect a need
-      (source_string =~ BuiltInEntityCharOrTagRx) ? (text_formatter.format source_string) : [{ text: source_string }]
+      if source_string =~ BuiltInEntityCharOrTagRx
+        text_formatter.format source_string
+      else
+        [{ text: source_string }]
+      end
     end
 
     node.subs.replace prev_subs if prev_subs
 
-    #move_down @theme.block_margin_top unless at_page_top?
     theme_margin :block, :top
 
+    if (node.option? 'autofit') || (node.document.attr? 'autofit-option')
+      adjusted_font_size = theme_font_size_autofit source_chunks, :code
+    else
+      adjusted_font_size = nil
+    end
+
     keep_together do |box_height = nil|
       caption_height = node.title? ? (layout_caption node) : 0
       theme_font :code do
         if box_height
           float do
-            # FIXME don't use border / border radius at page boundaries
-            # TODO move this logic to theme_fill_and_stroke_bounds
+            # TODO move the multi-page logic to theme_fill_and_stroke_bounds
+            unless (b_width = @theme.code_border_width || 0) == 0
+              b_radius = (@theme.code_border_radius || 0) + b_width
+              bg_color = @theme.code_background_color || @page_bg_color
+            end
             remaining_height = box_height - caption_height
             i = 0
             while remaining_height > 0
-              start_new_page if i > 0
+              start_new_page if (new_page_started = i > 0)
               fill_height = [remaining_height, cursor].min
               bounding_box [0, cursor], width: bounds.width, height: fill_height do
                 theme_fill_and_stroke_bounds :code
+                unless b_width == 0
+                  if new_page_started
+                    indent b_radius, b_radius do
+                      # dashed line to indicate continuation from previous page
+                      stroke_horizontal_rule bg_color, line_width: b_width, line_style: :dashed
+                    end
+                  end
+                  if remaining_height > fill_height
+                    move_down fill_height
+                    indent b_radius, b_radius do
+                      # dashed line to indicate continuation on next page
+                      stroke_horizontal_rule bg_color, line_width: b_width, line_style: :dashed
+                    end
+                  end
+                end
               end
               remaining_height -= fill_height
               i += 1
@@ -888,13 +947,14 @@ class Converter < ::Prawn::Document
         end
 
         pad_box @theme.code_padding do
-          typeset_formatted_text source_chunks, (calc_line_metrics @theme.code_line_height), color: @theme.code_font_color
+          typeset_formatted_text source_chunks, (calc_line_metrics @theme.code_line_height),
+              color: (@theme.code_font_color || @font_color),
+              size: adjusted_font_size
         end
       end
     end
     stroke_horizontal_rule @theme.caption_border_bottom_color if node.title? && @theme.caption_border_bottom_color
 
-    #move_down @theme.block_margin_bottom
     theme_margin :block, :bottom
   end
 
@@ -923,6 +983,9 @@ class Converter < ::Prawn::Document
   end
 
   # Restore the conums into the Array of formatted text fragments
+  #--
+  # QUESTION can this be done more efficiently?
+  # QUESTION can we reuse arrange_fragments_by_line?
   def restore_conums fragments, conum_mapping
     lines = []
     line_num = 0
@@ -943,16 +1006,16 @@ class Converter < ::Prawn::Document
     conum_color = @theme.conum_font_color
     last_line_num = lines.size - 1
     # append conums to appropriate lines, then flatten to an array of fragments
-    lines.flat_map.with_index do |line, line_num|
-      if (conums = conum_mapping.delete line_num)
+    lines.flat_map.with_index do |line, cur_line_num|
+      if (conums = conum_mapping.delete cur_line_num)
         conums = conums.map {|num| conum_glyph num }
         # ensure there's at least one space between content and conum(s)
         if line.size > 0 && (end_text = line.last[:text]) && !(end_text.end_with? ' ')
           line.last[:text] = %(#{end_text} )
         end
-        line << { text: (conums * ' '), color: conum_color }
+        line << (conum_color ? { text: (conums * ' '), color: conum_color } : { text: (conums * ' ') })
       end
-      line << { text: EOL } unless line_num == last_line_num
+      line << { text: EOL } unless cur_line_num == last_line_num
       line
     end
   end
@@ -973,30 +1036,16 @@ class Converter < ::Prawn::Document
     table_header = false
     theme = @theme
 
-    # FIXME this is a mess!
-    unless (page_bg_color = theme.page_background_color) && page_bg_color != 'transparent'
-      page_bg_color = nil
-    end
-
-    unless (bg_color = theme.table_background_color) && bg_color != 'transparent'
-      bg_color = page_bg_color
-    end
-
-    unless (head_bg_color = theme.table_head_background_color) && head_bg_color != 'transparent'
-      head_bg_color = bg_color
-    end
-
-    unless (foot_bg_color = theme.table_foot_background_color) && foot_bg_color != 'transparent'
-      foot_bg_color = bg_color
-    end
-
-    unless (odd_row_bg_color = theme.table_odd_row_background_color) && odd_row_bg_color != 'transparent'
-      odd_row_bg_color = bg_color
-    end
-
-    unless (even_row_bg_color = theme.table_even_row_background_color) && even_row_bg_color != 'transparent'
-      even_row_bg_color = bg_color
+    # NOTE use an explicit white background if no background color is set and table is nested inside a block
+    if (tbl_bg_color = resolve_theme_color :table_background_color, @page_bg_color)
+      tbl_bg_color = nil if tbl_bg_color == 'FFFFFF' && node.parent.context == :section
+    else
+      tbl_bg_color = 'FFFFFF' unless node.parent.context == :section
     end
+    head_bg_color = resolve_theme_color :table_head_background_color, tbl_bg_color
+    foot_bg_color = resolve_theme_color :table_foot_background_color, tbl_bg_color
+    odd_row_bg_color = resolve_theme_color :table_odd_row_background_color, tbl_bg_color
+    even_row_bg_color = resolve_theme_color :table_even_row_background_color, tbl_bg_color
 
     table_data = []
     node.rows[:head].each do |rows|
@@ -1141,16 +1190,19 @@ class Converter < ::Prawn::Document
   end
 
   def convert_thematic_break node
-    #move_down @theme.thematic_break_margin_top
     theme_margin :thematic_break, :top
-    stroke_horizontal_rule @theme.thematic_break_border_color, line_width: @theme.thematic_break_border_width
-    #move_down @theme.thematic_break_margin_bottom
+    stroke_horizontal_rule @theme.thematic_break_border_color, line_width: @theme.thematic_break_border_width, line_style: (@theme.thematic_break_border_style || :solid).to_sym
     theme_margin :thematic_break, :bottom
   end
 
   # deprecated
   alias :convert_horizontal_rule :convert_thematic_break
 
+  # NOTE manual placement not yet possible, so return nil
+  def convert_toc node
+    nil
+  end
+
   def convert_page_break node
     start_new_page unless at_page_top?
   end
@@ -1208,7 +1260,7 @@ class Converter < ::Prawn::Document
   end
 
   def convert_inline_button node
-    %(<b>[#{NarrowNoBreakSpace}#{node.text}#{NarrowNoBreakSpace}]</b>)
+    %(<strong>[#{NarrowNoBreakSpace}#{node.text}#{NarrowNoBreakSpace}]</strong>)
   end
 
   def convert_inline_callout node
@@ -1216,20 +1268,65 @@ class Converter < ::Prawn::Document
       # NOTE CMYK value gets flattened here, but is restored by formatted text parser
       %(<color rgb="#{conum_color}">#{conum_glyph node.text.to_i}</color>)
     else
-      node.text
+      conum_glyph node.text.to_i
     end
   end
 
   def convert_inline_footnote node
     if (index = node.attr 'index')
       #text = node.document.footnotes.find {|fn| fn.index == index }.text
-      %( [#{node.text}])
+      %(<sup>[#{index}: #{node.text}]</sup>)
     elsif node.type == :xref
       # NOTE footnote reference not found
-      %( <color rgb="FF0000">[#{node.text}]</color>)
+      %(<sup><color rgb="FF0000">[#{node.text}]</color></sup>)
     end
   end
 
+  def convert_inline_image node
+    img = nil
+    if node.type == 'icon'
+      if node.document.attr? 'icons', 'font'
+        if (icon_name = node.target).include? '@'
+          icon_name, icon_set = icon_name.split '@', 2
+        else
+          icon_set = node.attr 'set', (node.document.attr 'icon-set', 'fa')
+        end
+        icon_set = 'fa' unless IconSets.include? icon_set
+        if node.attr? 'size'
+          size = (size = (node.attr 'size')) == 'lg' ? '1.3333em' : (size.sub 'x', 'em')
+          size_attr = %( size="#{size}")
+        else
+          size_attr = nil
+        end
+        @icon_font_data ||= ::Prawn::Icon::FontData.load self, icon_set
+        begin
+          # TODO support rotate and flip attributes; support fw (full-width) size
+          img = %(<font name="#{icon_set}"#{size_attr}>#{@icon_font_data.unicode icon_name}</font>)
+        rescue
+          warn %(asciidoctor: WARNING: #{icon_name} is not a valid icon name in the #{icon_set} icon set)
+        end
+      end
+    else
+      node.extend ::Asciidoctor::Image unless ::Asciidoctor::Image === node
+      target, image_type = node.target_with_image_type
+      valid = true
+      if image_type == 'gif'
+        warn %(asciidoctor: WARNING: GIF image format not supported. Please convert #{target} to PNG.) unless scratch?
+        valid = false
+      end
+      unless (image_path = resolve_image_path node, target) && (::File.readable? image_path)
+        warn %(asciidoctor: WARNING: image to embed not found or not readable: #{image_path || target}) unless scratch?
+        valid = false
+      end
+      if valid
+        width_attr = (node.attr? 'width') ? %( width="#{node.attr 'width'}") : nil
+        img = %(<img src="#{image_path}" type="#{image_type}" alt="#{node.attr 'alt'}"#{width_attr} tmp="#{TemporaryPath === image_path}">)
+      end
+    end
+    img ||= %([#{node.attr 'alt'}])
+    (node.attr? 'link') ? %(<a href="#{node.attr 'link'}">#{img}</a>) : img
+  end
+
   def convert_inline_indexterm node
     node.type == :visible ? node.text : nil
   end
@@ -1317,7 +1414,7 @@ class Converter < ::Prawn::Document
         end
       end
     end
-    if !bg_image && (bg_color = @theme.title_page_background_color) && bg_color != 'transparent'
+    if !bg_image && (bg_color = resolve_theme_color :title_page_background_color)
       @page_bg_color = bg_color
     else
       bg_color = nil
@@ -1419,7 +1516,7 @@ class Converter < ::Prawn::Document
       end
       # QUESTION should we go to page 1 when position == :front?
       go_to_page page_count if position == :back
-      if (::File.extname cover_image) == '.pdf'
+      if cover_image.downcase.end_with? '.pdf'
         import_page cover_image
       else
         image_page cover_image, canvas: true
@@ -1441,26 +1538,24 @@ class Converter < ::Prawn::Document
 
   # QUESTION why doesn't layout_heading set the font??
   def layout_heading string, opts = {}
-    margin_top = (margin = (opts.delete :margin)) || (opts.delete :margin_top) || @theme.heading_margin_top
-    margin_bottom = margin || (opts.delete :margin_bottom) || @theme.heading_margin_bottom
+    top_margin = (margin = (opts.delete :margin)) || (opts.delete :margin_top) || @theme.heading_margin_top
+    bot_margin = margin || (opts.delete :margin_bottom) || @theme.heading_margin_bottom
     if (transform = (opts.delete :text_transform) || @text_transform)
       string = transform_text string, transform
     end
-    #move_down margin_top
-    self.margin_top margin_top
+    margin_top top_margin
     typeset_text string, calc_line_metrics((opts.delete :line_height) || @theme.heading_line_height), {
       color: @font_color,
       inline_format: true,
       align: :left
     }.merge(opts)
-    #move_down margin_bottom
-    self.margin_bottom margin_bottom
+    margin_bottom bot_margin
   end
 
   # NOTE inline_format is true by default
   def layout_prose string, opts = {}
     top_margin = (margin = (opts.delete :margin)) || (opts.delete :margin_top) || @theme.prose_margin_top || 0
-    bottom_margin = margin || (opts.delete :margin_bottom) || @theme.prose_margin_bottom || @theme.vertical_rhythm
+    bot_margin = margin || (opts.delete :margin_bottom) || @theme.prose_margin_bottom || @theme.vertical_rhythm
     if (transform = (opts.delete :text_transform) || @text_transform)
       string = transform_text string, transform
     end
@@ -1482,7 +1577,7 @@ class Converter < ::Prawn::Document
       inline_format: [{ normalize: (opts.delete :normalize) != false }],
       align: (@theme.base_align || :left).to_sym
     }.merge(opts)
-    margin_bottom bottom_margin
+    margin_bottom bot_margin
   end
 
   # Render the caption and return the height of the rendered content
@@ -1545,7 +1640,7 @@ class Converter < ::Prawn::Document
   end
 
   def layout_toc_level sections, num_levels, line_metrics, dot_width, num_front_matter_pages = 0
-    toc_dot_color = @theme.toc_dot_leader_color
+    toc_dot_color = @theme.toc_dot_leader_font_color || @theme.toc_font_color || @font_color
     sections.each do |sect|
       theme_font :toc, level: (sect.level + 1) do
         sect_title = @text_transform ? (transform_text sect.numbered_title, @text_transform) : sect.numbered_title
@@ -1566,6 +1661,7 @@ class Converter < ::Prawn::Document
           spacer_width = (width_of NoBreakSpace) * 0.75
           # FIXME this calculation will be wrong if a style is set per level
           num_dots = ((bounds.width - (width_of %(#{sect_title}#{sect_page_num}), inline_format: true) - spacer_width) / dot_width).floor
+          num_dots = 0 if num_dots < 0
           # FIXME dots don't line up if width of page numbers differ
           typeset_formatted_text [
             { text: %(#{(@theme.toc_dot_leader_content || DotLeaderDefault) * num_dots}), color: toc_dot_color },
@@ -1675,10 +1771,11 @@ class Converter < ::Prawn::Document
       trim_content_height = trim_height - trim_padding[0] - trim_padding[2] - trim_line_metrics.padding_top
       trim_left = page_margin_left
       trim_width = page_width - trim_left - page_margin_right
-      trim_font_color = @theme.header_font_color
-      trim_bg_color = @theme.header_background_color
+      trim_font_color = @theme.header_font_color || @font_color
+      trim_bg_color = resolve_theme_color :header_background_color
       trim_border_width = @theme.header_border_width || @theme.base_border_width
-      trim_border_color = @theme.header_border_color
+      trim_border_style = (@theme.header_border_style || :solid).to_sym
+      trim_border_color = resolve_theme_color :header_border_color
       trim_valign = (@theme.header_valign || :center).to_sym
       trim_img_valign = @theme.header_image_valign || trim_valign
     else
@@ -1688,10 +1785,11 @@ class Converter < ::Prawn::Document
       trim_content_height = trim_height - trim_padding[0] - trim_padding[2] - trim_line_metrics.padding_top
       trim_left = page_margin_left
       trim_width = page_width - trim_left - page_margin_right
-      trim_font_color = @theme.footer_font_color
-      trim_bg_color = @theme.footer_background_color
+      trim_font_color = @theme.footer_font_color || @font_color
+      trim_bg_color = resolve_theme_color :footer_background_color
       trim_border_width = @theme.footer_border_width || @theme.base_border_width
-      trim_border_color = @theme.footer_border_color
+      trim_border_style = (@theme.footer_border_style || :solid).to_sym
+      trim_border_color = resolve_theme_color :footer_border_color
       trim_valign = (@theme.footer_valign || :center).to_sym
       trim_img_valign = @theme.footer_image_valign || trim_valign
     end
@@ -1699,9 +1797,7 @@ class Converter < ::Prawn::Document
     trim_stamp = %(#{position})
     trim_content_left = trim_left + trim_padding[3]
     trim_content_width = trim_width - trim_padding[3] - trim_padding[1]
-    # NOTE FFFFFF is meaningful value for background and border, so don't scrap it
-    trim_bg_color = nil if trim_bg_color == 'transparent'
-    trim_border_color = nil if trim_border_color == 'transparent' || trim_border_width == 0
+    trim_border_color = nil if trim_border_width == 0
     if ['top', 'center', 'bottom'].include? trim_img_valign
       trim_img_valign = trim_img_valign.to_sym
     end
@@ -1715,15 +1811,14 @@ class Converter < ::Prawn::Document
               if trim_border_color
                 # TODO stroke_horizontal_rule should support :at
                 move_down bounds.height if position == :header
-                stroke_horizontal_rule trim_border_color, line_width: trim_border_width
+                stroke_horizontal_rule trim_border_color, line_width: trim_border_width, line_style: trim_border_style
               end
             end
           else
             bounding_box [trim_left, trim_top], width: trim_width, height: trim_height do
               # TODO stroke_horizontal_rule should support :at
               move_down bounds.height if position == :header
-              stroke_horizontal_rule trim_border_color, line_width: trim_border_width
-              move_up bounds.height if position == :header
+              stroke_horizontal_rule trim_border_color, line_width: trim_border_width, line_style: trim_border_style
             end
           end
         end
@@ -1736,7 +1831,7 @@ class Converter < ::Prawn::Document
       next if page.imported_page?
       visual_pgnum = page_number - skip
       # FIXME we need to have a content setting for chapter pages
-      content_by_alignment = content_dict[side = visual_pgnum.odd? ? :recto : :verso]
+      content_by_alignment = content_dict[visual_pgnum.odd? ? :recto : :verso]
       doc.set_attr 'page-number', visual_pgnum
       # TODO populate chapter-number
       # TODO populate numbered and unnumbered chapter and section titles
@@ -1841,7 +1936,8 @@ class Converter < ::Prawn::Document
 
   def write pdf_doc, target
     pdf_doc.render_file target
-    #@prototype.render_file 'scratch.pdf'
+    # write scratch document if debug is enabled (or perhaps DEBUG_STEPS env)
+    #get_scratch_document.render_file 'scratch.pdf'
     # QUESTION restore attributes first?
     @pdfmarks.generate_file target if @pdfmarks
   end
@@ -1860,6 +1956,16 @@ class Converter < ::Prawn::Document
     ::File.absolute_path font_file, fonts_dir
   end
 
+  # QUESTION should we pass a category as an argument?
+  # QUESTION should we make this a method on the theme ostruct? (e.g., @theme.resolve_color key, fallback)
+  def resolve_theme_color key, fallback_color = nil
+    if (color = @theme[key.to_s]) && color != 'transparent'
+      color
+    else
+      fallback_color
+    end
+  end
+
   def theme_fill_and_stroke_bounds category
     fill_and_stroke_bounds @theme[%(#{category}_background_color)], @theme[%(#{category}_border_color)],
       line_width: @theme[%(#{category}_border_width)],
@@ -1927,6 +2033,73 @@ class Converter < ::Prawn::Document
     @text_transform = prev_transform if transform
   end
 
+  # Calculate the font size (down to the minimum font size) that would allow
+  # all the specified fragments to fit in the available width without wrapping lines.
+  #
+  # Return the calculated font size if an adjustment is necessary or nil if no
+  # font size adjustment is necessary.
+  def theme_font_size_autofit fragments, category
+    arranger = arrange_fragments_by_line fragments
+    adjusted_font_size = nil
+    theme_font category do
+      # NOTE finalizing the line here generates fragments using current font settings
+      arranger.finalize_line
+      actual_width = width_of_fragments arranger.fragments
+      unless ::Array === (padding = @theme[%(#{category}_padding)])
+        padding = [padding] * 4
+      end
+      bounds.add_left_padding(p_left = padding[3] || 0)
+      bounds.add_right_padding(p_right = padding[1] || 0)
+      if actual_width > bounds.width
+        adjusted_font_size = ((bounds.width * font_size).to_f / actual_width).with_precision 4
+        if (min = @theme[%(#{category}_font_size_min)] || @theme.base_font_size_min) && adjusted_font_size < min
+          adjusted_font_size = min
+        end
+      end
+      bounds.subtract_left_padding p_left
+      bounds.subtract_right_padding p_right
+    end
+    adjusted_font_size
+  end
+
+  # Arrange fragments by line in an arranger and return an unfinalized arranger.
+  #
+  # Finalizing the arranger is deferred since it must be done in the context of
+  # the global font settings you want applied to each fragment.
+  def arrange_fragments_by_line fragments, opts = {}
+    arranger = ::Prawn::Text::Formatted::Arranger.new self
+    by_line = arranger.consumed = []
+    fragments.each do |fragment|
+      if (txt = fragment[:text]) == EOL
+        by_line << fragment
+      elsif txt.include? EOL
+        txt.scan(LineScanRx) do |line|
+          by_line << fragment.merge(text: line)
+        end
+      else
+        by_line << fragment
+      end
+    end
+    arranger
+  end
+
+  # Calculate the width that is needed to print all the
+  # fragments without wrapping any lines.
+  #
+  # This method assumes endlines are represented as discrete entries in the
+  # fragments array.
+  def width_of_fragments fragments
+    line_widths = [0]
+    fragments.each do |fragment|
+      if fragment.text == EOL
+        line_widths << 0
+      else
+        line_widths[-1] += fragment.width
+      end
+    end
+    line_widths.max
+  end
+
   # TODO document me, esp the first line formatting functionality
   def typeset_text string, line_metrics, opts = {}
     move_down line_metrics.padding_top
@@ -2001,17 +2174,18 @@ class Converter < ::Prawn::Document
   # the temporary file. If the target is a URI and the allow-uri-read attribute
   # is not set, or the URI cannot be read, this method returns a nil value.
   #
-  # When a temporary file is used, the file descriptor is assigned to the
-  # @tmp_file instance variable of the return string.
+  # When a temporary file is used, the TemporaryPath type is mixed into the path string.
   def resolve_image_path node, image_path = nil, image_type = nil
     imagesdir = resolve_imagesdir(doc = node.document)
     image_path ||= (node.attr 'target', nil, false)
-    image_type ||= (::File.extname image_path)[1..-1]
+    image_type ||= ::Asciidoctor::Image.image_type image_path
     # handle case when image is a URI
     if (node.is_uri? image_path) || (imagesdir && (node.is_uri? imagesdir) &&
         (image_path = (node.normalize_web_path image_path, image_base_uri, false)))
       unless doc.attr? 'allow-uri-read'
-        warn %(asciidoctor: WARNING: allow-uri-read is not enabled; cannot embed remote image: #{image_path})
+        unless scratch?
+          warn %(asciidoctor: WARNING: allow-uri-read is not enabled; cannot embed remote image: #{image_path})
+        end
         return
       end
       if doc.attr? 'cache-uri'
@@ -2022,7 +2196,7 @@ class Converter < ::Prawn::Document
       begin
         open(image_path, (binary ? 'rb' : 'r')) {|fd| tmp_image.write(fd.read) }
         tmp_image_path = tmp_image.path
-        tmp_image_path.instance_variable_set :@tmp_file, tmp_image
+        tmp_image_path.extend TemporaryPath
       rescue
         tmp_image_path = nil
       ensure
@@ -2037,11 +2211,9 @@ class Converter < ::Prawn::Document
 
   # QUESTION is there a better way to do this?
   # I suppose we could have @tmp_files as an instance variable on converter instead
-  def unlink_tmp_file holder
-    if (tmp_file = (holder.instance_variable_get :@tmp_file))
-      tmp_file.unlink
-      holder.remove_instance_variable :@tmp_file
-    end
+  # It might be sufficient to delete temporary files once per conversion
+  def unlink_tmp_file path
+    path.unlink if TemporaryPath === path
   end
 
   # QUESTION move to prawn/extensions.rb?
@@ -2064,22 +2236,6 @@ class Converter < ::Prawn::Document
       end
     end
   end
-
-  def create_stamps
-    create_stamp 'masthead' do
-      canvas do
-        save_graphics_state do
-          stroke_color '000000'
-          x_margin = mm2pt 20
-          y_margin = mm2pt 15
-          stroke_horizontal_line x_margin, bounds.right - x_margin, at: bounds.top - y_margin
-          stroke_horizontal_line x_margin, bounds.right - x_margin, at: y_margin
-        end
-      end
-    end
-
-    @stamps_initialized = true
-  end
 =end
 end
 end