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

data/lib/asciidoctor-pdf/asciidoctor_ext.rb

@@ -1 +1,3 @@
 require_relative 'asciidoctor_ext/section'
+require_relative 'asciidoctor_ext/list'
+require_relative 'asciidoctor_ext/list_item'

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

@@ -0,0 +1,9 @@
+# TODO add these methods to Asciidoctor core
+class Asciidoctor::List
+  # Check whether this list is an outline list (unordered or ordered).
+  #
+  # Return true if this list is an outline list. Otherwise, return false.
+  def outline?
+    @context == :ulist || @context == :olist
+  end
+end

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

@@ -0,0 +1,16 @@
+# TODO add these methods to Asciidoctor core
+class Asciidoctor::ListItem
+  # Check whether this list item has complex content (i.e., nested blocks other than an outline list).
+  #
+  # Return false if the list item contains no blocks or it contains a nested outline list. Otherwise, return true.
+  def complex?
+    !simple?
+  end
+
+  # Check whether this list item has simple content (i.e., no nested blocks aside from an outline list).
+  #
+  # Return true if the list item contains no blocks or it contains a nested outline list. Otherwise, return false.
+  def simple?
+    @blocks.empty? || (@blocks.size == 1 && ::Asciidoctor::List === (blk = @blocks[0]) && blk.outline?)
+  end
+end

data/lib/asciidoctor-pdf/converter.rb

@@ -5,12 +5,17 @@ require 'prawn'
 require 'prawn-svg'
 require 'prawn/table'
 require 'prawn/templates'
+require 'prawn/icon'
+require_relative 'pdf_core_ext'
+require_relative 'sanitizer'
 require_relative 'prawn_ext'
 require_relative 'pdfmarks'
 require_relative 'asciidoctor_ext'
 require_relative 'theme_loader'
 require_relative 'roman_numeral'
 
+autoload :Tempfile, 'tempfile'
+
 module Asciidoctor
 module Pdf
 class Converter < ::Prawn::Document
@@ -24,28 +29,34 @@ class Converter < ::Prawn::Document
     [number].pack 'U*'
   end
 
+  # NOTE require_library doesn't support require_relative and we don't modify the load path for this gem
+  CodeRayRequirePath = ::File.join((::File.dirname __FILE__), 'prawn_ext/coderay_encoder')
+
+  AdmonitionIcons = {
+    caution:   { key: 'fa-fire', color: 'BF3400' },
+    important: { key: 'fa-exclamation-circle', color: 'BF0000' },
+    note:      { key: 'fa-info-circle', color: '19407C' },
+    tip:       { key: 'fa-lightbulb-o', color: '111111' },
+    warning:   { key: 'fa-exclamation-triangle', color: 'BF6900' }
+  }
+  Alignments = [:left, :center, :right]
   IndentationRx = /^ +/
   TabSpaces = ' ' * 4
   NoBreakSpace = unicode_char 0x00a0
+  NarrowSpace = unicode_char 0x2009
   NarrowNoBreakSpace = unicode_char 0x202f
+  ZeroWidthSpace = unicode_char 0x200b
   HairSpace = unicode_char 0x200a
-  DotLeader = %(#{HairSpace}.)
+  DotLeaderDefault = %(. )
   EmDash = unicode_char 0x2014
   LowercaseGreekA = unicode_char 0x03b1
-  AdmonitionIcons = {
-    note: (unicode_char 0xf0eb)
-  }
   Bullets = {
     disc: (unicode_char 0x2022),
     circle: (unicode_char 0x25e6),
     square: (unicode_char 0x25aa)
   }
-  BuiltInEntityChars = {
-    '&lt;' => '<',
-    '&gt;' => '>',
-    '&amp;' => '&'
-  }
-  BuiltInEntityCharsRx = /(?:#{BuiltInEntityChars.keys * '|'})/
+  # CalloutExtractRx synced from /lib/asciidoctor.rb of Asciidoctor core
+  CalloutExtractRx = /(?:(?:\/\/|#|--|;;) ?)?(\\)?<!?(--|)(\d+)\2>(?=(?: ?\\?<!?\2\d+\2>)*$)/
   ImageAttributeValueRx = /^image:{1,2}(.*?)\[(.*?)\]$/
 
   def initialize backend, opts
@@ -57,7 +68,7 @@ class Converter < ::Prawn::Document
     @list_bullets = []
   end
 
-  def convert node, name = nil
+  def convert node, name = nil, opts = {}
     method_name = %(convert_#{name ||= node.node_name})
     result = nil
     if respond_to? method_name
@@ -68,7 +79,7 @@ class Converter < ::Prawn::Document
       warn %(asciidoctor: WARNING: conversion missing in backend #{@backend} for #{name})
     end
     # NOTE inline nodes generate pseudo-HTML strings; the remainder write directly to PDF object
-    (node.is_a? ::Asciidoctor::Inline) ? result : self
+    ::Asciidoctor::Inline === node ? result : self
   end
 
   def convert_content_for_block node, opts = {}
@@ -90,13 +101,16 @@ class Converter < ::Prawn::Document
     init_pdf doc
     # data-uri doesn't apply to PDF, so explicitly disable (is there a better place?)
     doc.attributes.delete 'data-uri'
-
-    # TODO implement page_background_image as alternative and/or page_watermark_image
-    if (bg_color = @theme.page_background_color) && !(['transparent', 'FFFFFF'].include? bg_color.to_s)
-      on_page_create do
-        canvas do
-          fill_bounds bg_color.to_s
-        end
+    #assign_missing_section_ids doc
+
+    on_page_create do
+      # TODO implement as a watermark (on top)
+      if @page_bg_image
+        # 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
+        fill_absolute_bounds @page_bg_color
       end
     end
 
@@ -128,8 +142,11 @@ class Converter < ::Prawn::Document
       (0..-1)
     end
 
-    # TODO enable pagenums by default (perhaps upstream?)
-    stamp_page_numbers skip: num_front_matter_pages if doc.attr 'pagenums'
+    # TODO enable pagenums by default
+    if doc.attr? 'pagenums'
+      layout_running_content :header, doc, skip: num_front_matter_pages
+      layout_running_content :footer, doc, skip: num_front_matter_pages
+    end
     add_outline doc, num_toc_levels, toc_page_nums, num_front_matter_pages
     catalog.data[:ViewerPreferences] = [:FitWindow]
 
@@ -146,13 +163,26 @@ class Converter < ::Prawn::Document
 
   # TODO only allow method to be called once (or we need a reset)
   def init_pdf doc
-    theme = ThemeLoader.load_theme doc.attr('pdf-style'), doc.attr('pdf-stylesdir')
+    theme = ThemeLoader.load_theme doc.attr('pdf-style'), (stylesdir = (doc.attr 'pdf-stylesdir'))
+    @theme = theme
     pdf_opts = (build_pdf_options doc, theme)
     ::Prawn::Document.instance_method(:initialize).bind(self).call pdf_opts
     # QUESTION should ThemeLoader register fonts?
     register_fonts theme.font_catalog, (doc.attr 'scripts', 'latin'), (doc.attr 'pdf-fontsdir', ThemeLoader::FontsDir)
-    @theme = theme
-    @font_color = theme.base_font_color
+    if (bg_image = theme.page_background_image) && bg_image != 'none'
+      if ::File.readable?(bg_image = (ThemeLoader.resolve_theme_asset bg_image, stylesdir))
+        @page_bg_image = bg_image
+      else
+        warn %(asciidoctor: WARNING: page background image #{bg_image} not found or readable)
+      end
+    end
+    @fallback_fonts = [*theme.font_fallbacks]
+    if ['FFFFFF', 'transparent'].include?(@page_bg_color = theme.page_background_color)
+      @page_bg_color = nil
+    end
+    @font_color = theme.base_font_color || '000000'
+    @text_transform = nil
+    @stamps = {}
     init_scratch_prototype
     self
   end
@@ -164,31 +194,75 @@ class Converter < ::Prawn::Document
       info: (build_pdf_info doc),
       margin: (theme.page_margin || 36),
       page_layout: (theme.page_layout || :portrait).to_sym,
-      page_size: (theme.page_size || 'LETTER').upcase,
       skip_page_creation: true,
     }
+
+    if doc.attr? 'pdf-page-size'
+      page_size = ::YAML.safe_load(doc.attr 'pdf-page-size')
+    else
+      page_size = theme.page_size
+    end
+
+    pdf_opts[:page_size] = case page_size
+    when ::String
+      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
+          # NOTE 4 is the max practical precision in PDFs
+          if (val = val.round 4) == (i_val = val.to_i)
+            val = i_val
+          end
+          val
+        else
+          break
+        end
+      }
+    end
+
+    pdf_opts[:page_size] ||= 'LETTER'
+
     # FIXME fix the namespace for FormattedTextFormatter
     pdf_opts[:text_formatter] ||= ::Asciidoctor::Prawn::FormattedTextFormatter.new theme: theme
     pdf_opts
   end
 
+  # FIXME PdfMarks should use the PDF info result
   def build_pdf_info doc
     info = {}
-    # TODO create helper method for creating literal PDF string
-    info[:Title] = ::PDF::Core::LiteralString.new(doc.doctitle sanitize: true, use_fallback: true)
+    # FIXME use sanitize: :plain_text once available
+    info[:Title] = str2pdfval sanitize(doc.doctitle use_fallback: true)
     if doc.attr? 'authors'
-      info[:Author] = ::PDF::Core::LiteralString.new(doc.attr 'authors')
+      info[:Author] = str2pdfval(doc.attr 'authors')
     end
     if doc.attr? 'subject'
-      info[:Subject] = ::PDF::Core::LiteralString.new(doc.attr 'subject')
+      info[:Subject] = str2pdfval(doc.attr 'subject')
     end
     if doc.attr? 'keywords'
-      info[:Keywords] = ::PDF::Core::LiteralString.new(doc.attr 'keywords')
+      info[:Keywords] = str2pdfval(doc.attr 'keywords')
     end
     if (doc.attr? 'publisher')
-      info[:Producer] = ::PDF::Core::LiteralString.new(doc.attr 'publisher')
+      info[:Producer] = str2pdfval(doc.attr 'publisher')
     end
-    info[:Creator] = ::PDF::Core::LiteralString.new %(Asciidoctor PDF #{::Asciidoctor::Pdf::VERSION}, based on Prawn #{::Prawn::VERSION})
+    info[:Creator] = str2pdfval %(Asciidoctor PDF #{::Asciidoctor::Pdf::VERSION}, based on Prawn #{::Prawn::VERSION})
     info[:Producer] ||= (info[:Author] || info[:Creator])
     # FIXME use docdate attribute
     info[:ModDate] = info[:CreationDate] = ::Time.now
@@ -208,24 +282,29 @@ class Converter < ::Prawn::Document
         end
       end
       # QUESTION should we store page_start & destination in internal map?
+      # TODO ideally, this attribute should be pdf-page-start
       sect.set_attr 'page_start', page_number
-      dest_y = at_page_top? ? page_height : y
-      sect.set_attr 'destination', (sect_destination = (dest_xyz 0, dest_y))
-      add_dest sect.id, sect_destination
+      # NOTE auto-generate an anchor if one doesn't exist so TOC works
+      # QUESTION should we just assign the section this generated id?
+      sect.set_attr 'anchor', (sect_anchor = sect.id || %(section-#{page_number}-#{dest_y.ceil}))
+      add_dest_for_block sect, sect_anchor
       sect.chapter? ? (layout_chapter_title sect, title) : (layout_heading title)
     end
 
     convert_content_for_block sect
+    # TODO ideally, this attribute should be pdf-page-end
     sect.set_attr 'page_end', page_number
   end
 
   def convert_floating_title node
+    add_dest_for_block node if node.id
     theme_font :heading, level: (node.level + 1) do
       layout_heading node.title
     end
   end
 
   def convert_abstract node
+    add_dest_for_block node if node.id
     pad_box @theme.abstract_padding do
       theme_font :abstract do
         # FIXME control first_line_options using theme
@@ -263,6 +342,7 @@ class Converter < ::Prawn::Document
 
   # TODO add prose around image logic (use role to add special logic for headshot)
   def convert_paragraph node
+    add_dest_for_block node if node.id
     is_lead = false
     prose_opts = {}
     node.roles.each do |role|
@@ -280,6 +360,10 @@ class Converter < ::Prawn::Document
       end
     end
 
+    # TODO check if we're within one line of the bottom of the page
+    # and advance to the next page if so (similar to logic for section titles)
+    layout_caption node.title if node.title?
+
     if is_lead
       theme_font :lead do
         layout_prose node.content, prose_opts
@@ -291,12 +375,19 @@ 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
+    shift_base = @theme.prose_margin_bottom || @theme.vertical_rhythm
+    #shift_top = icons ? (shift_base / 3.0) : 0
+    #shift_bottom = icons ? ((shift_base * 2) / 3.0) : shift_base
+    shift_top = shift_base / 3.0
+    shift_bottom = (shift_base * 2) / 3.0
     keep_together do |box_height = nil|
       #theme_font :admonition do
-        label = node.caption.upcase
-        label_width = width_of label
+        label_width = icons ? (bounds.width / 12.0) : (width_of label)
         # FIXME use padding from theme
         indent @theme.horizontal_rhythm, @theme.horizontal_rhythm do
           if box_height
@@ -305,17 +396,23 @@ class Converter < ::Prawn::Document
                 # IMPORTANT the label must fit in the alotted space or it shows up on another page!
                 # QUESTION anyway to prevent text overflow in the case it doesn't fit?
                 stroke_vertical_rule @theme.admonition_border_color, at: bounds.width
-                # HACK make title in this location look right
+                # FIXME HACK make title in this location look right
                 label_margin_top = node.title? ? @theme.caption_margin_inside : 0
-                layout_prose label, valign: :center, style: :bold, line_height: 1, margin_top: label_margin_top, margin_bottom: 0
+                if icons
+                  admon_icon_data = AdmonitionIcons[label]
+                  icon admon_icon_data[:key], valign: :center, align: :center, color: admon_icon_data[:color], size: (admonition_icon_size node)
+                else
+                  layout_prose label, valign: :center, style: :bold, line_height: 1, margin_top: label_margin_top, margin_bottom: 0
+                end
               end
             end
           end
           indent label_width + @theme.horizontal_rhythm * 2 do
+            move_down shift_top
             layout_caption node.title if node.title?
             convert_content_for_block node
-            # HACK compensate for margin bottom of admonition content
-            move_up(@theme.prose_margin_bottom || @theme.vertical_rhythm)
+            # FIXME HACK compensate for margin bottom of admonition content
+            move_up shift_bottom
           end
         end
       #end
@@ -325,6 +422,7 @@ class Converter < ::Prawn::Document
   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|
@@ -355,15 +453,18 @@ class Converter < ::Prawn::Document
       if node.blocks.size == 1 && node.blocks.first.style == 'abstract'
         convert_abstract node.blocks.first
       else
+        add_dest_for_block node if node.id
         convert_content_for_block node
       end
     else
+      add_dest_for_block node if node.id
       convert_content_for_block node
     end
   end
 
   def convert_quote_or_verse node
-    border_width = @theme.blockquote_border_width
+    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|
@@ -400,6 +501,7 @@ class Converter < ::Prawn::Document
   alias :convert_verse :convert_quote_or_verse
 
   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|
@@ -420,7 +522,7 @@ class Converter < ::Prawn::Document
         theme_font :sidebar do
           convert_content_for_block node
         end
-        # HACK compensate for margin bottom of sidebar content
+        # FIXME HACK compensate for margin bottom of sidebar content
         move_up(@theme.prose_margin_bottom || @theme.vertical_rhythm)
       end
     end
@@ -429,19 +531,53 @@ class Converter < ::Prawn::Document
   end
 
   def convert_colist node
-    # HACK undo the margin below the listing
-    move_up ((@theme.block_margin_bottom || @theme.vertical_rhythm) * 0.5)
+    # 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)
+    end
+    add_dest_for_block node if node.id
     @list_numbers ||= []
     # FIXME move \u2460 to constant (or theme setting)
+    # \u2460 = circled one, \u24f5 = double circled one, \u278b = negative circled one
     @list_numbers << %(\u2460)
     #stroke_horizontal_rule @theme.caption_border_bottom_color
-    # HACK fudge spacing around colist a bit; each item is shifted up by this amount (see convert_list_item)
-    move_down ((@theme.prose_margin_bottom || @theme.vertical_rhythm) * 0.5)
-    convert_outline_list 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)
+      convert_colist_item item
+    end
     @list_numbers.pop
+    # correct bottom margin of last item
+    list_margin_bottom = @theme.prose_margin_bottom || @theme.vertical_rhythm
+    margin_bottom (list_margin_bottom - (@theme.outline_list_item_spacing || (list_margin_bottom / 2.0)))
+  end
+
+  def convert_colist_item node
+    marker_width = width_of %(#{conum_glyph 1}x)
+
+    float do
+      bounding_box [0, cursor], width: marker_width do
+        @list_numbers << (index = @list_numbers.pop).next
+        theme_font :conum do
+          layout_prose index, align: :center, line_height: @theme.conum_line_height, inline_format: false, margin: 0
+        end
+      end
+    end
+
+    indent marker_width do
+      convert_content_for_list_item node,
+        margin_bottom: (@theme.outline_list_item_spacing || ((@theme.prose_margin_bottom || @theme.vertical_rhythm) / 2.0))
+    end
   end
 
   def convert_dlist node
+    add_dest_for_block node if node.id
     node.items.each do |terms, desc|
       terms = [*terms]
       # NOTE don't orphan the terms, allow for at least one line of content
@@ -459,6 +595,7 @@ class Converter < ::Prawn::Document
   end
 
   def convert_olist node
+    add_dest_for_block node if node.id
     @list_numbers ||= []
     list_number = case node.style
     when 'arabic'
@@ -488,6 +625,7 @@ class Converter < ::Prawn::Document
 
   # 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'
@@ -511,51 +649,63 @@ class Converter < ::Prawn::Document
   end
 
   def convert_outline_list node
+    line_metrics = calc_line_metrics @theme.base_line_height
+    complex = false
+    # ...or if we want to give all items in the list the same treatment
+    #complex = node.items.find(&:complex?) ? true : false
     indent @theme.outline_list_indent do
       node.items.each do |item|
-        convert_list_item 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)
+        convert_outline_list_item item, item.complex?
       end
     end
-    # NOTE children will provide the necessary bottom margin
+    # NOTE Children will provide the necessary bottom margin if last item is complex.
+    # However, don't leave gap at the bottom of a nested list
+    unless complex || (::Asciidoctor::List === node.parent && node.parent.outline?)
+      # correct bottom margin of last item
+      list_margin_bottom = @theme.prose_margin_bottom || @theme.vertical_rhythm
+      margin_bottom(list_margin_bottom - (@theme.outline_list_item_spacing || (list_margin_bottom / 2.0)))
+    end
   end
 
-  def convert_list_item node
-    # HACK quick hack to tighten items on colist
-    if node.parent.context == :colist
-      move_up ((@theme.prose_margin_bottom || @theme.vertical_rhythm) * 0.5)
+  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)
+    when :ulist
+      @list_bullets.last
+    when :olist
+      @list_numbers << (index = @list_numbers.pop).next
+      %(#{index}.)
+    else
+      warn %(asciidoctor: WARNING: unknown list type #{list_type.inspect})
+      Bullets[:disc]
     end
 
-    # NOTE we need at least one line of content, so move down if we don't have it
-    # FIXME extract ensure_space (or similar) method
-    start_new_page if cursor < @theme.base_line_height_length
-
-    # TODO move this to a draw_bullet method
+    marker_width = width_of marker
+    start_position = -marker_width + -(width_of 'x')
     float do
-      bounding_box [-@theme.outline_list_indent, cursor], width: @theme.outline_list_indent do
-        label = case node.parent.context
-        when :ulist
-          @list_bullets.last
-        when :olist
-          @list_numbers << (index = @list_numbers.pop).next
-          %(#{index}.)
-        when :colist
-          @list_numbers << (index = @list_numbers.pop).next
-          # FIXME cleaner way to do numbers in colist; need more room around number
-          theme_font :conum do
-            # QUESTION should this be align: :left or :center?
-            layout_prose index, align: :left, line_height: @theme.conum_line_height, inline_format: false, margin: 0
-          end
-          next # short circuit label
-        end
-        layout_prose label, align: :center, normalize: false, inline_format: false, margin: 0
+      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
       end
     end
-    convert_content_for_list_item node
+
+    if complex
+      convert_content_for_list_item node
+    else
+      convert_content_for_list_item node,
+        margin_bottom: (@theme.outline_list_item_spacing || ((@theme.prose_margin_bottom || @theme.vertical_rhythm) / 2.0))
+    end
   end
 
-  def convert_content_for_list_item node
+  def convert_content_for_list_item node, opts = {}
     if node.text?
-      opts = {}
       opts[:align] = :left if node.parent.style == 'bibliography'
       layout_prose node.text, opts
     end
@@ -563,18 +713,37 @@ class Converter < ::Prawn::Document
   end
 
   def convert_image node
-    #move_down @theme.block_margin_top unless at_page_top?
-    theme_margin :block, :top
+    valid_image = true
     target = node.attr 'target'
-    #if target.end_with? '.pdf'
-    #  import_page target
+    # TODO file extension should be an attribute on an image node
+    image_type = (::File.extname target)[1..-1].downcase
+
+    if image_type == 'gif'
+      valid_image = false
+      warn %(asciidoctor: WARNING: GIF image format not supported. Please convert the image #{target} to PNG.)
+    #elsif image_type == 'pdf'
+    #  import_page image_path
     #  return
-    #end
+    end
+
+    unless (image_path = resolve_image_path node, target) && (::File.readable? image_path)
+      valid_image = false
+      warn %(asciidoctor: WARNING: image to embed not found or not readable: #{image_path || target})
+    end
+
+    add_dest_for_block node if node.id
 
-    # FIXME use normalize_path here!
-    image_path = File.join((node.attr 'docdir'), (node.attr 'imagesdir') || '', target)
-    # TODO extension should be an attribute on an image node
-    image_type = File.extname(image_path)[1..-1]
+    unless valid_image
+      theme_margin :block, :top
+      layout_prose %(#{node.attr 'alt'} | #{target}), normalize: false, margin: 0, single_line: true
+      layout_caption node, position: :bottom if node.title?
+      theme_margin :block, :bottom
+      return
+    end
+
+    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'
@@ -584,32 +753,46 @@ class Converter < ::Prawn::Document
     else
       bounds.width * (@theme.image_scaled_width_default || 0.75)
     end
-    height = nil
     position = ((node.attr 'align') || @theme.image_align_default || :left).to_sym
     case image_type
     when 'svg'
-      keep_together do
-        # HACK prawn-svg can't seem to center, so do it manually for now
-        left = case position
-        when :left
-          0
-        when :right
-          bounds.width - width
-        when :center
-          ((bounds.width - width) / 2.0).floor
+      # 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
+        keep_together do |box_height = nil|
+          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
+          end
+          layout_caption node, position: :bottom if node.title?
         end
-        svg IO.read(image_path), at: [left, cursor], width: width, position: position
-        layout_caption node, position: :bottom if node.title?
+      rescue => e
+        warn %(asciidoctor: WARNING: could not embed image: #{image_path}; #{e.message})
       end
     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
-        image_obj, image_info = build_image_object node.image_uri image_path
+        # 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
+        # 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
@@ -621,50 +804,64 @@ class Converter < ::Prawn::Document
             stroke_color self.stroke_color
           end
         end
+        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]
+        end
         embed_image image_obj, image_info, width: width, height: height, position: position
+        if link
+          link_annotation link_box,
+            Border: [0, 0, 0],
+            A: { Type: :Action, S: :URI, URI: (str2pdfval link) }
+        end
       rescue => e
-        warn %(asciidoctor: WARNING: could not embed image; #{e.message})
-        return
+        warn %(asciidoctor: WARNING: could not embed image: #{image_path}; #{e.message})
       end
       layout_caption node, position: :bottom if node.title?
     end
-    #move_down @theme.block_margin_bottom
     theme_margin :block, :bottom
+  ensure
+    unlink_tmp_file image_path
   end
 
+  # TODO shrink text if it's too wide to fit in the bounding box
   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!
-    if (node.style == 'source')
-      node.subs.delete :highlight
-    end
-    # FIXME highlighter freaks out about the non-breaking space characters
-    source_string = prepare_verbatim node.content
-    source_chunks = if node.context == :listing && (node.attr? 'language') && (node.attr? 'source-highlighter')
-      case node.attr 'source-highlighter'
-      when 'coderay'
-        # FIXME use autoload here!
-        require_relative 'prawn_ext/coderay_encoder' unless defined? ::Asciidoctor::Prawn::CodeRayEncoder
-        (::CodeRay.scan source_string, (node.attr 'language', 'text').to_sym).to_prawn
-      when 'pygments'
-        # FIXME use autoload here!
-        require 'pygments.rb' unless defined? ::Pygments
-        # FIXME if lexer is nil, we don't escape specialchars!
-        if (lexer = ::Pygments::Lexer[(node.attr 'language')])
-          pygments_config = { nowrap: true, noclasses: true, style: ((node.document.attr 'pygments-style') || 'pastie') }
-          result = lexer.highlight(source_string, options: pygments_config)
-          result = result.gsub(/(?: <span style="font-style: italic">(?:\/\/|#) &lt;(?<num>\d+)&gt;<\/span>| &lt;(?<num>\d+)&gt;)$/) {
-            # FIXME move \u2460 to constant (or theme setting)
-            num = %(\u2460)
-            (($~[:num]).to_i - 1).times { num = num.next }
-            if (conum_color = @theme.conum_font_color)
-              %( <color rgb="#{conum_color}">#{num}</color>)
-            end
-          }
-          text_formatter.format result
-        end
-      end
+    # NOTE the highlight sub is only set for coderay and pygments
+    if node.style == 'source' && !scratch? && ((subs = node.subs).include? :highlight)
+      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
+    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'
+      Helpers.require_library CodeRayRequirePath, 'coderay' unless defined? ::Asciidoctor::Prawn::CodeRayEncoder
+      source_string, conum_mapping = extract_conums source_string
+      fragments = (::CodeRay.scan source_string, (node.attr 'language', 'text', false).to_sym).to_prawn
+      conum_mapping ? (restore_conums fragments, conum_mapping) : fragments
+    when 'pygments'
+      Helpers.require_library 'pygments', 'pygments.rb' unless defined? ::Pygments
+      source_string, conum_mapping = extract_conums source_string
+      lexer = ::Pygments::Lexer[node.attr 'language', 'text', false] || ::Pygments::Lexer['text']
+      pygments_config = { nowrap: true, noclasses: true, style: (node.document.attr 'pygments-style') || 'pastie' }
+      result = lexer.highlight source_string, options: pygments_config
+      fragments = text_formatter.format result
+      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 }]
     end
-    source_chunks ||= [{ text: source_string }]
+
+    node.subs.replace prev_subs if prev_subs
 
     #move_down @theme.block_margin_top unless at_page_top?
     theme_margin :block, :top
@@ -704,22 +901,118 @@ class Converter < ::Prawn::Document
   alias :convert_listing :convert_listing_or_literal
   alias :convert_literal :convert_listing_or_literal
 
+  # Extract callout marks from string, indexed by 0-based line number
+  # Return an Array with the processed string as the first argument
+  # and the mapping of lines to conums as the second.
+  def extract_conums string
+    conum_mapping = {}
+    string = string.split(EOL).map.with_index {|line, line_num|
+      # FIXME we get extra spaces before numbers if more than one on a line
+      line.gsub(CalloutExtractRx) {
+        # honor the escape
+        if $1 == '\\'
+          $&.sub '\\', ''
+        else
+          (conum_mapping[line_num] ||= []) << $3.to_i
+          ''
+        end
+      }
+    } * EOL
+    conum_mapping = nil if conum_mapping.empty?
+    [string, conum_mapping]
+  end
+
+  # Restore the conums into the Array of formatted text fragments
+  def restore_conums fragments, conum_mapping
+    lines = []
+    line_num = 0
+    # reorganize the fragments into an array of lines
+    fragments.each do |fragment|
+      line = (lines[line_num] ||= [])
+      if (text = fragment[:text]) == EOL
+        line_num += 1
+      elsif text.include? EOL
+        text.split(EOL, -1).each_with_index do |line_in_fragment, idx|
+          line = (lines[line_num += 1] ||= []) unless idx == 0
+          line << fragment.merge(text: line_in_fragment) unless line_in_fragment.empty?
+        end
+      else
+        line << fragment
+      end
+    end
+    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)
+        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 }
+      end
+      line << { text: EOL } unless line_num == last_line_num
+      line
+    end
+  end
+
+  def conum_glyph number
+    # FIXME make starting glyph a constant and/or theme setting
+    # FIXME use lookup table for glyphs instead of relying on counting
+    # \u2460 = circled one, \u24f5 = double circled one, \u278b = negative circled one
+    glyph = %(\u2460)
+    (number - 1).times { glyph = glyph.next }
+    glyph
+  end
+
   def convert_table node
+    add_dest_for_block node if node.id
     num_rows = 0
     num_cols = node.columns.size
     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
+    end
 
     table_data = []
     node.rows[:head].each do |rows|
       table_header = true
+      head_transform = theme.table_head_text_transform
       num_rows += 1
       row_data = []
       rows.each do |cell|
         row_data << {
-          content: cell.text,
-          text_color: (@theme.table_head_font_color || @font_color),
-          inline_format: true,
-          font_style: :bold,
+          content: (head_transform ? (transform_text cell.text, head_transform) : cell.text),
+          inline_format: [{ normalize: true }],
+          background_color: head_bg_color,
+          text_color: (theme.table_head_font_color || theme.table_font_color || @font_color),
+          size: (theme.table_head_font_size || theme.table_font_size),
+          font: (theme.table_head_font_family || theme.table_font_family),
+          font_style: (theme.table_head_font_style || :bold).to_sym,
           colspan: cell.colspan || 1,
           rowspan: cell.rowspan || 1,
           align: (cell.attr 'halign').to_sym,
@@ -729,30 +1022,33 @@ class Converter < ::Prawn::Document
       table_data << row_data
     end
 
-    node.rows[:body].each do |rows|
+    (node.rows[:body] + node.rows[:foot]).each do |rows|
       num_rows += 1
       row_data = []
       rows.each do |cell|
         cell_data = {
           content: cell.text,
-          text_color: (@theme.table_body_font_color || @font_color),
-          inline_format: true,
+          inline_format: [{ normalize: true }],
+          text_color: (theme.table_body_font_color || @font_color),
+          size: theme.table_font_size,
+          font: theme.table_font_family,
           colspan: cell.colspan || 1,
           rowspan: cell.rowspan || 1,
           align: (cell.attr 'halign').to_sym,
           valign: (cell.attr 'valign').to_sym
         }
+        cell_data[:valign] = :center if cell_data[:valign] == :middle
         case cell.style
         when :emphasis
           cell_data[:font_style] = :italic
-        when :strong, :header  
+        when :strong, :header
           cell_data[:font_style] = :bold
         when :monospaced
-          cell_data[:font] = @theme.literal_font_family
-          if (size = @theme.literal_font_size)
+          cell_data[:font] = theme.literal_font_family
+          if (size = theme.literal_font_size)
             cell_data[:size] = size
           end
-          if (color = @theme.literal_font_color)
+          if (color = theme.literal_font_color)
             cell_data[:text_color] = color
           end
         # TODO finish me
@@ -762,12 +1058,10 @@ class Converter < ::Prawn::Document
       table_data << row_data
     end
 
-    # TODO support footer row
-
     column_widths = node.columns.map {|col| ((col.attr 'colpcwidth') * bounds.width) / 100.0 }
 
     border = {}
-    table_border_width = @theme.table_border_width
+    table_border_width = theme.table_border_width
     [:top, :bottom, :left, :right, :cols, :rows].each {|edge| border[edge] = table_border_width }
 
     frame = (node.attr 'frame') || 'all'
@@ -794,12 +1088,12 @@ class Converter < ::Prawn::Document
     table_settings = {
       header: table_header,
       cell_style: {
-        padding: @theme.table_cell_padding,
+        padding: theme.table_cell_padding,
         border_width: 0,
-        border_color: @theme.table_border_color
+        border_color: theme.table_border_color
       },
       column_widths: column_widths,
-      row_colors: ['FFFFFF', @theme.table_background_color_alt]
+      row_colors: [odd_row_bg_color, even_row_bg_color]
     }
 
     theme_margin :block, :top
@@ -827,6 +1121,21 @@ class Converter < ::Prawn::Document
         # left edge of table
         columns(0).border_left_width = border[:left]
       end
+
+      # QUESTION should cell padding be configurable for foot row cells?
+      unless node.rows[:foot].empty?
+        foot_row = row(num_rows - 1)
+        foot_row.background_color = foot_bg_color
+        # FIXME find a way to do this when defining the cells
+        foot_row.text_color = theme.table_foot_font_color if theme.table_foot_font_color
+        foot_row.size = theme.table_foot_font_size if theme.table_foot_font_size
+        foot_row.font = theme.table_foot_font_family if theme.table_foot_font_family
+        foot_row.font_style = theme.table_foot_font_style.to_sym if theme.table_foot_font_style
+        # HACK we should do this transformation when creating the cell
+        #if (foot_transform = theme.table_foot_text_transform)
+        #  foot_row.each {|c| c.content = (transform_text c.content, foot_transform) if c.content }
+        #end
+      end
     end
     theme_margin :block, :bottom
   end
@@ -842,31 +1151,12 @@ class Converter < ::Prawn::Document
   # deprecated
   alias :convert_horizontal_rule :convert_thematic_break
 
-  # NOTE can't alias to start_new_page since methods have different arity
   def convert_page_break node
     start_new_page unless at_page_top?
   end
 
   def convert_inline_anchor node
-    target = node.target
     case node.type
-    when :xref
-      refid = (node.attr 'refid') || target
-      # NOTE we lookup text in converter because DocBook doesn't need this logic
-      if (text = node.text || (node.document.references[:ids][refid] || %([#{refid}])))
-        # FIXME shouldn't target be refid? logic seems confused here
-        %(<link anchor="#{target}">#{text}</link>)
-      # FIXME hack for bibliography references
-      # should be able to reenable once we parse inline destinations
-      else
-        %((see [#{refid}]))
-      end
-    when :ref
-      #%(<a id="#{target}"></a>)
-      ''
-    when :bibref
-      #%(<a id="#{target}"></a>[#{target}])
-      %([#{target}])
     when :link
       attrs = []
       #attrs << %( id="#{node.id}") if node.id
@@ -876,11 +1166,38 @@ class Converter < ::Prawn::Document
       #attrs << %( title="#{node.attr 'title'}") if node.attr? 'title'
       attrs << %( target="#{node.attr 'window'}") if node.attr? 'window'
       if (node.document.attr? 'showlinks') && !(node.has_role? 'bare')
-        # TODO cleanup look, perhaps put target in smaller text
-        %(<link href="#{target}"#{attrs.join}>#{node.text}</a> (#{target}))
+        # TODO allow style of visible link to be controlled by theme
+        %(<a href="#{target = node.target}"#{attrs.join}>#{node.text}</a> <font size="0.9"><em>(#{target})</em></font>)
+      else
+        %(<a href="#{node.target}"#{attrs.join}>#{node.text}</a>)
+      end
+    when :xref
+      # NOTE the presence of path indicates an inter-document xref
+      if (path = node.attributes['path'])
+        # NOTE we don't use local as that doesn't work on the web
+        # NOTE for the fragment to work in most viewers, it must be #page=<N>
+        %(<a href="#{node.target}">#{node.text || path}</a>)
       else
-        %(<link href="#{target}"#{attrs.join}>#{node.text}</a>)
+        refid = node.attributes['refid']
+        # NOTE reference table is not comprehensive (we don't catalog all inline anchors)
+        if (reftext = node.document.references[:ids][refid])
+          %(<a anchor="#{refid}">#{node.text || reftext}</a>)
+        else
+          # NOTE we don't catalog all inline anchors, so we can't warn here (maybe once conversion is complete)
+          #source = $VERBOSE ? %( in source:\n#{node.parent.lines * "\n"}) : nil
+          #warn %(asciidoctor: WARNING: reference '#{refid}' not found#{source})
+          #%[(see #{node.text || %([#{refid}])})]
+          %(<a anchor="#{refid}">#{node.text || "[#{refid}]"}</a>)
+        end
       end
+    when :ref
+      # NOTE destination is created inside callback registered by FormattedTextTransform#build_fragment
+      #%(<a name="#{node.target}"></a>)
+      %(<a name="#{node.target}">#{ZeroWidthSpace}</a>)
+    when :bibref
+      # NOTE destination is created inside callback registered by FormattedTextTransform#build_fragment
+      #%(<a name="#{target = node.target}"></a>[#{target}])
+      %(<a name="#{target = node.target}">#{ZeroWidthSpace}</a>[#{target}])
     else
       warn %(asciidoctor: WARNING: unknown anchor type: #{node.type.inspect})
     end
@@ -894,15 +1211,29 @@ class Converter < ::Prawn::Document
     %(<b>[#{NarrowNoBreakSpace}#{node.text}#{NarrowNoBreakSpace}]</b>)
   end
 
+  def convert_inline_callout node
+    if (conum_color = @theme.conum_font_color)
+      # 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
+    end
+  end
+
   def convert_inline_footnote node
     if (index = node.attr 'index')
       #text = node.document.footnotes.find {|fn| fn.index == index }.text
       %( [#{node.text}])
     elsif node.type == :xref
+      # NOTE footnote reference not found
       %( <color rgb="FF0000">[#{node.text}]</color>)
     end
   end
 
+  def convert_inline_indexterm node
+    node.type == :visible ? node.text : nil
+  end
+
   def convert_inline_kbd node
     if (keys = node.attr 'keys').size == 1
       %(<code>#{keys[0]}</code>)
@@ -953,52 +1284,149 @@ class Converter < ::Prawn::Document
       quoted_text = %(#{open}#{node.text}#{close})
     end
 
-    node.id ? %(<a id="#{node.id}"></a>#{quoted_text}) : quoted_text
+    node.id ? %(<a name="#{node.id}">#{ZeroWidthSpace}</a>#{quoted_text}) : quoted_text
   end
 
+  # FIXME only create title page if doctype=book!
   def layout_title_page doc
     return unless doc.header? && !doc.noheader && !doc.notitle
 
+    prev_bg_image = @page_bg_image
+    prev_bg_color = @page_bg_color
+    if (bg_image = (doc.attr 'title-background-image', @theme.title_page_background_image))
+      if bg_image == 'none'
+        @page_bg_image = nil
+      else
+        if bg_image =~ ImageAttributeValueRx
+          bg_image = $1
+          # QUESTION should we support width and height?
+        end
+
+        # NOTE resolve image relative to its origin
+        resolved_bg_image = if doc.attr? 'title-background-image'
+          resolve_image_path doc, bg_image
+        else
+          ThemeLoader.resolve_theme_asset bg_image, (doc.attr 'pdf-stylesdir')
+        end
+
+        if resolved_bg_image && (::File.readable? resolved_bg_image)
+          @page_bg_image = resolved_bg_image
+        else
+          warn %(asciidoctor: WARNING: title page background image #{resolved_bg_image || bg_image} not found or readable)
+          bg_image = nil
+        end
+      end
+    end
+    if !bg_image && (bg_color = @theme.title_page_background_color) && bg_color != 'transparent'
+      @page_bg_color = bg_color
+    else
+      bg_color = nil
+    end
     start_new_page
+    @page_bg_image = prev_bg_image if bg_image
+    @page_bg_color = prev_bg_color if bg_color
+
     # IMPORTANT this is the first page created, so we need to set the base font
     font @theme.base_font_family, size: @theme.base_font_size
 
-    # TODO treat title-logo like front and back cover images
-    if doc.attr? 'title-logo'
-      # FIXME theme setting
-      move_down @theme.vertical_rhythm * 2
-      # FIXME add API to Asciidoctor for creating blocks like this (extract from extensions module?)
-      image = ::Asciidoctor::Block.new doc, :image, content_model: :empty
-      attrs = { 'target' => (doc.attr 'title-logo'), 'align' => 'center' }
-      image.update_attributes attrs
-      convert_image image
-      # FIXME theme setting
-      move_down @theme.vertical_rhythm * 4
-    end
-
-    # FIXME only create title page if doctype=book!
-    # FIXME honor subtitle!
-    theme_font :heading, level: 1 do
-      layout_heading doc.doctitle, align: :center
-    end
-    # FIXME theme setting
-    move_down @theme.vertical_rhythm
-    if doc.attr? 'authors'
-      layout_prose doc.attr('authors'), align: :center, margin_top: 0, margin_bottom: @theme.vertical_rhythm / 2.0, normalize: false
+    # QUESTION allow aligment per element on title page?
+    title_align = (@theme.title_page_align || :center).to_sym
+
+    # FIXME rework image handling once fix for #134 is merged
+    if (logo_image_path = (doc.attr 'title-logo-image', @theme.title_page_logo_image))
+      if logo_image_path =~ ImageAttributeValueRx
+        logo_image_path = $1
+        logo_image_attrs = AttributeList.new($2).parse(['alt', 'width', 'height'])
+      else
+        logo_image_attrs = {}
+      end
+      # HACK quick fix to resolve image path relative to theme
+      unless doc.attr? 'title-logo-image'
+        # FIXME use ThemeLoader.resolve_theme_asset once fix for #134 is merged
+        logo_image_path = ::File.expand_path logo_image_path, (doc.attr 'pdf-stylesdir', ThemeLoader::ThemesDir)
+      end
+      logo_image_attrs['target'] = logo_image_path
+      logo_image_attrs['align'] ||= (@theme.title_page_logo_align || title_align.to_s)
+      logo_image_top = (logo_image_attrs['top'] || @theme.title_page_logo_top || '10%')
+      # FIXME delegate to method to convert page % to y value
+      logo_image_top = [(page_height - page_height * (logo_image_top.to_i / 100.0)), bounds.absolute_top].min
+      float do
+        @y = logo_image_top
+        # FIXME add API to Asciidoctor for creating blocks like this (extract from extensions module?)
+        image_block = ::Asciidoctor::Block.new doc, :image, content_model: :empty, attributes: logo_image_attrs
+        # FIXME prevent image from spilling to next page
+        convert_image image_block
+      end
+    end
+
+    # TODO prevent content from spilling to next page
+    theme_font :title_page do
+      doctitle = doc.doctitle partition: true
+      if (title_top = @theme.title_page_title_top)
+        # FIXME delegate to method to convert page % to y value
+        @y = [(page_height - page_height * (title_top.to_i / 100.0)), bounds.absolute_top].min
+      end
+      move_down (@theme.title_page_title_margin_top || 0)
+      theme_font :title_page_title do
+        layout_heading doctitle.main,
+          align: title_align,
+          margin: 0,
+          line_height: @theme.title_page_title_line_height
+      end
+      move_down (@theme.title_page_title_margin_bottom || 0)
+      if doctitle.subtitle
+        move_down (@theme.title_page_subtitle_margin_top || 0)
+        theme_font :title_page_subtitle do
+          layout_heading doctitle.subtitle,
+            align: title_align,
+            margin: 0,
+            line_height: @theme.title_page_subtitle_line_height
+        end
+        move_down (@theme.title_page_subtitle_margin_bottom || 0)
+      end
+      if doc.attr? 'authors'
+        move_down (@theme.title_page_authors_margin_top || 0)
+        theme_font :title_page_authors do
+          # TODO add support for author delimiter
+          layout_prose doc.attr('authors'),
+            align: title_align,
+            margin: 0,
+            normalize: false
+        end
+        move_down (@theme.title_page_authors_margin_bottom || 0)
+      end
+      revision_info = [(doc.attr? 'revnumber') ? %(#{doc.attr 'version-label'} #{doc.attr 'revnumber'}) : nil, (doc.attr 'revdate')].compact
+      unless revision_info.empty?
+        move_down (@theme.title_page_revision_margin_top || 0)
+        theme_font :title_page_revision do
+          revision_text = revision_info * (@theme.title_page_revision_delimiter || ', ')
+          layout_prose revision_text,
+            align: title_align,
+            margin: 0,
+            normalize: false
+        end
+        move_down (@theme.title_page_revision_margin_bottom || 0)
+      end
     end
-    layout_prose [(doc.attr? 'revnumber') ? %(#{doc.attr 'version-label'} #{doc.attr 'revnumber'}) : nil, (doc.attr 'revdate')].compact * "\n", align: :center, margin_top: @theme.vertical_rhythm * 5, margin_bottom: 0, normalize: false
   end
 
   def layout_cover_page position, doc
     # TODO turn processing of attribute with inline image a utility function in Asciidoctor
+    # FIXME verify cover_image exists!
     if (cover_image = (doc.attr %(#{position}-cover-image)))
       if cover_image =~ ImageAttributeValueRx
-        cover_image = %(#{resolve_imagesdir doc}#{$1})
+        cover_image = resolve_image_path doc, $1
       end
       # QUESTION should we go to page 1 when position == :front?
       go_to_page page_count if position == :back
-      image_page cover_image, canvas: true
+      if (::File.extname cover_image) == '.pdf'
+        import_page cover_image
+      else
+        image_page cover_image, canvas: true
+      end
     end
+  ensure
+    unlink_tmp_file cover_image
   end
 
   # NOTE can't alias to start_new_page since methods have different arity
@@ -1015,6 +1443,9 @@ class Converter < ::Prawn::Document
   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
+    if (transform = (opts.delete :text_transform) || @text_transform)
+      string = transform_text string, transform
+    end
     #move_down margin_top
     self.margin_top margin_top
     typeset_text string, calc_line_metrics((opts.delete :line_height) || @theme.heading_line_height), {
@@ -1028,30 +1459,30 @@ class Converter < ::Prawn::Document
 
   # NOTE inline_format is true by default
   def layout_prose string, opts = {}
-    margin_top = (margin = (opts.delete :margin)) || (opts.delete :margin_top) || @theme.prose_margin_top || 0
-    margin_bottom = margin || (opts.delete :margin_bottom) || @theme.prose_margin_bottom || @theme.vertical_rhythm
+    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
+    if (transform = (opts.delete :text_transform) || @text_transform)
+      string = transform_text string, transform
+    end
     if (anchor = opts.delete :anchor)
       # FIXME won't work if inline_format is true; should instead pass through as attribute w/ link color set
       if (link_color = opts.delete :link_color)
-        string = %(<link anchor="#{anchor}"><color rgb="#{link_color}">#{string}</color></link>)
+        # NOTE CMYK value gets flattened here, but is restored by formatted text parser
+        string = %(<a anchor="#{anchor}"><color rgb="#{link_color}">#{string}</color></a>)
       else
-        string = %(<link anchor="#{anchor}">#{string}</link>)
+        string = %(<a anchor="#{anchor}">#{string}</a>)
       end
     end
-    if opts.delete :preserve
-      # preserve leading space using non-breaking space chars
-      string = string.gsub(IndentationRx) { NoBreakSpace * $&.length }
-    end
-    #move_down margin_top
-    self.margin_top margin_top
+    # preserve leading space using non-breaking space chars
+    string = preserve_indentation string if opts.delete :preserve
+    margin_top top_margin
     typeset_text string, calc_line_metrics((opts.delete :line_height) || @theme.base_line_height), {
       color: @font_color,
       # NOTE normalize makes endlines soft (replaces "\n" with ' ')
       inline_format: [{ normalize: (opts.delete :normalize) != false }],
-      align: (@theme.base_align || :justify).to_sym
+      align: (@theme.base_align || :left).to_sym
     }.merge(opts)
-    #move_down margin_bottom
-    self.margin_bottom margin_bottom
+    margin_bottom bottom_margin
   end
 
   # Render the caption and return the height of the rendered content
@@ -1081,7 +1512,7 @@ class Converter < ::Prawn::Document
       }.merge(opts)
       if position == :top && @theme.caption_border_bottom_color
         stroke_horizontal_rule @theme.caption_border_bottom_color
-        # HACK move down slightly so line isn't covered by filled area (half width of line)
+        # FIXME HACK move down slightly so line isn't covered by filled area (half width of line)
         move_down 0.25
       end
     end
@@ -1094,13 +1525,18 @@ class Converter < ::Prawn::Document
   end
 
   def layout_toc doc, num_levels = 2, toc_page_number = 2, num_front_matter_pages = 0
-    go_to_page toc_page_number unless scratch? || page_number == toc_page_number
+    go_to_page toc_page_number unless (page_number == toc_page_number) || scratch?
     theme_font :heading, level: 2 do
       layout_heading doc.attr('toc-title')
     end
-    line_metrics = calc_line_metrics @theme.base_line_height
-    dot_width = width_of DotLeader
+    # QUESTION shouldn't we skip this whole method if num_levels == 0?
     if num_levels > 0
+      theme_margin :toc, :top
+      line_metrics = calc_line_metrics @theme.toc_line_height || @theme.base_line_height
+      dot_width = nil
+      theme_font :toc do
+        dot_width = width_of(@theme.toc_dot_leader_content || DotLeaderDefault)
+      end
       layout_toc_level doc.sections, num_levels, line_metrics, dot_width, num_front_matter_pages
     end
     toc_page_numbers = (toc_page_number..page_number)
@@ -1109,65 +1545,236 @@ 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
     sections.each do |sect|
-      sect_title = sect.numbered_title
-      # NOTE we do some cursor hacking here so the dots don't affect vertical alignment
-      start_page_number = page_number
-      start_cursor = cursor
-      typeset_text %(<link anchor="#{sect.id}">#{sect_title}</link>), line_metrics, inline_format: true
-      # we only write the label if this is a dry run
-      unless scratch?
-        end_page_number = page_number
-        end_cursor = cursor
-        # TODO it would be convenient to have a cursor mark / placement utility that took page number into account
-        go_to_page start_page_number if start_page_number != end_page_number
-        move_cursor_to start_cursor
-        sect_page_num = (sect.attr 'page_start') - num_front_matter_pages
-        num_dots = ((bounds.width - (width_of %(#{sect_title} #{sect_page_num}), inline_format: true)) / dot_width).floor
-        typeset_formatted_text [text: %(#{DotLeader * num_dots} #{sect_page_num}), anchor: sect.id], line_metrics, align: :right
-        go_to_page end_page_number if start_page_number != end_page_number
-        move_cursor_to end_cursor
+      theme_font :toc, level: (sect.level + 1) do
+        sect_title = @text_transform ? (transform_text sect.numbered_title, @text_transform) : sect.numbered_title
+        # NOTE we do some cursor hacking here so the dots don't affect vertical alignment
+        start_page_number = page_number
+        start_cursor = cursor
+        # NOTE CMYK value gets flattened here, but is restored by formatted text parser
+        # FIXME use layout_prose
+        typeset_text %(<a anchor="#{sect_anchor = (sect.attr 'anchor') || sect.id}"><color rgb="#{@font_color}">#{sect_title}</color></a>), line_metrics, inline_format: true
+        # we only write the label if this is a dry run
+        unless scratch?
+          end_page_number = page_number
+          end_cursor = cursor
+          # TODO it would be convenient to have a cursor mark / placement utility that took page number into account
+          go_to_page start_page_number if start_page_number != end_page_number
+          move_cursor_to start_cursor
+          sect_page_num = (sect.attr 'page_start') - num_front_matter_pages
+          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
+          # 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 },
+            { text: NoBreakSpace, size: (@font_size * 0.5) },
+            { text: sect_page_num.to_s, anchor: sect_anchor, color: @font_color }], line_metrics, align: :right
+          go_to_page end_page_number if start_page_number != end_page_number
+          move_cursor_to end_cursor
+        end
       end
       if sect.level < num_levels
-        indent @theme.horizontal_rhythm do
+        indent(@theme.toc_indent || @theme.outline_list_indent) do
           layout_toc_level sect.sections, num_levels, line_metrics, dot_width, num_front_matter_pages
         end
       end
     end
   end
 
-  def stamp_page_numbers opts = {}
+  # Reduce icon size to fit inside bounds.height. Icons will not render
+  # properly if they are larger than the current bounds.height.
+  def admonition_icon_size node, max_size = 24
+    min_height = bounds.height.floor
+    min_height < max_size ? min_height : max_size
+  end
+
+  # TODO delegate to layout_page_header and layout_page_footer per page
+  def layout_running_content position, doc, opts = {}
+    # QUESTION should we short-circuit if setting not specified and if so, which setting?
+    return unless (position == :header && @theme.header_height) || (position == :footer && @theme.footer_height)
     skip = opts[:skip] || 1
     start = skip + 1
-    pattern = page_number_pattern
-    repeat (start..page_count), dynamic: true do
-      # don't stamp pages which are imported / inserts
-      next if page.imported_page?
-      case (align = (page_number - skip).odd? ? :left : :right)
-      when :left
-        page_number_label = pattern[:left] % [page_number - skip]
-      when :right
-        page_number_label = pattern[:right] % [page_number - skip]
+    num_pages = page_count - skip
+
+    # FIXME probably need to treat doctypes differently
+    sections = doc.find_by(context: :section) {|sect| sect.level < 3 }
+
+    # index chapters and sections by the visual page number on which they start
+    chapter_start_pages = {}
+    section_start_pages = {}
+    sections.each do |sect|
+      if sect.chapter?
+        chapter_start_pages[(sect.attr 'page_start').to_i - skip] ||= (sect.numbered_title formal: true)
+      else
+        section_start_pages[(sect.attr 'page_start').to_i - skip] ||= (sect.numbered_title formal: true)
+      end
+    end
+
+    # index chapters and sections by the visual page number on which they appear
+    chapters_by_page = {}
+    sections_by_page = {}
+    last_chap = (doc.attr 'preface-title') || 'Preface'
+    last_sect = nil
+    (1..num_pages).each do |num|
+      if (chap = chapter_start_pages[num])
+        last_chap = chap
+      end
+      if (sect = section_start_pages[num])
+        last_sect = sect
+      elsif chap
+        last_sect = nil
       end
-      theme_font :footer do
+      chapters_by_page[num] = last_chap
+      sections_by_page[num] = last_sect
+    end
+
+    doctitle = doc.doctitle partition: true
+    # NOTE set doctitle again so it's properly escaped
+    doc.set_attr 'doctitle', doctitle.combined
+    doc.set_attr 'document-title', doctitle.main
+    doc.set_attr 'document-subtitle', doctitle.subtitle
+    doc.set_attr 'page-count', num_pages
+
+    # TODO move this to a method so it can be reused; cache results
+    content_dict = [:recto, :verso].inject({}) do |acc, side|
+      side_content = {}
+      Alignments.each do |align|
+        if (val = @theme[%(#{position}_#{side}_content_#{align})])
+          if ImageAttributeValueRx =~ val &&
+              ::File.readable?(path = (ThemeLoader.resolve_theme_asset $1, (doc.attr 'pdf-stylesdir')))
+            attrs = AttributeList.new($2).parse
+            attrs['width'] = attrs['width'].to_f if attrs['width']
+            side_content[align] = { path: path, width: attrs['width'] }
+          else
+            side_content[align] ||= val
+          end
+        end
+      end
+      if (acc[side] = side_content).empty? && @theme[%(footer_#{side}_content)] != 'none'
+        # NOTE set fallbacks if not explicitly disabled
+        case side
+        when :recto
+          acc[side] = { right: '{page-number}' }
+        when :verso
+          acc[side] = { left: '{page-number}' }
+        end
+      end
+      acc
+    end
+
+    # QUESTION should we support footer_line_height?
+    #trim_line_metrics = calc_line_metrics @theme.base_line_height
+    trim_line_metrics = calc_line_metrics
+    if position == :header
+      trim_top = page_height
+      # NOTE height is required atm
+      trim_height = @theme.header_height || page_margin_top
+      trim_padding = @theme.header_padding || [0, 0, 0, 0]
+      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_border_width = @theme.header_border_width || @theme.base_border_width
+      trim_border_color = @theme.header_border_color
+      trim_valign = (@theme.header_valign || :center).to_sym
+      trim_img_valign = @theme.header_image_valign || trim_valign
+    else
+      # NOTE height is required atm
+      trim_top = trim_height = @theme.footer_height || page_margin_bottom
+      trim_padding = @theme.footer_padding || [0, 0, 0, 0]
+      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_border_width = @theme.footer_border_width || @theme.base_border_width
+      trim_border_color = @theme.footer_border_color
+      trim_valign = (@theme.footer_valign || :center).to_sym
+      trim_img_valign = @theme.footer_image_valign || trim_valign
+    end
+
+    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
+    if ['top', 'center', 'bottom'].include? trim_img_valign
+      trim_img_valign = trim_img_valign.to_sym
+    end
+
+    if trim_bg_color || trim_border_color
+      create_stamp trim_stamp do
         canvas do
-          if @theme.footer_border_color && @theme.footer_border_color != 'transparent'
-            save_graphics_state do
-              line_width @theme.base_border_width
-              stroke_color @theme.footer_border_color
-              stroke_horizontal_line left_margin, bounds.width - right_margin, at: (page.margins[:bottom] / 2.0 + @theme.vertical_rhythm / 2.0)
+          if trim_bg_color
+            bounding_box [0, trim_top], width: bounds.width, height: trim_height do
+              fill_bounds trim_bg_color
+              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
+              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
             end
-          end
-          indent left_margin, right_margin do
-            formatted_text_box [text: page_number_label, color: @theme.footer_font_color], at: [0, (page.margins[:bottom] / 2.0)], align: align
           end
         end
       end
+      @stamps[position] = true
     end
-  end
 
-  def page_number_pattern
-    { left: '%s', right: '%s' }
+    repeat (start..page_count), dynamic: true do
+      # NOTE don't write on pages which are imported / inserts (otherwise we can get a corrupt PDF)
+      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]
+      doc.set_attr 'page-number', visual_pgnum
+      # TODO populate chapter-number
+      # TODO populate numbered and unnumbered chapter and section titles
+      doc.set_attr 'chapter-title', (chapters_by_page[visual_pgnum] || '')
+      doc.set_attr 'section-title', (sections_by_page[visual_pgnum] || '')
+      doc.set_attr 'section-or-chapter-title', (sections_by_page[visual_pgnum] || chapters_by_page[visual_pgnum] || '')
+
+      stamp trim_stamp if @stamps[position]
+
+      theme_font position do
+        canvas do
+          bounding_box [trim_content_left, trim_top], width: trim_content_width, height: trim_height do
+            Alignments.each do |align|
+              # FIXME we need to have a content setting for chapter pages
+              case (content = content_by_alignment[align])
+              when ::Hash
+                # FIXME prevent image from overflowing the page
+                float do
+                  # FIXME padding doesn't work when vposition is specified; how will padding bottom work?
+                  #move_down trim_padding[0]
+                  image content[:path], vposition: trim_img_valign, position: align, width: content[:width]
+                end
+              when ::String
+                content = (content == '{page-number}' ? %(#{visual_pgnum}) : (doc.apply_subs content))
+                formatted_text_box parse_text(content, color: trim_font_color, inline_format: true),
+                  at: [0, trim_content_height + trim_padding[2]],
+                  height: trim_content_height,
+                  align: align,
+                  valign: trim_valign,
+                  leading: trim_line_metrics.leading,
+                  final_gap: false,
+                  overflow: :truncate
+              end
+            end
+          end
+        end
+      end
+    end
   end
 
   # FIXME we are assuming we always have exactly one title page
@@ -1183,7 +1790,7 @@ class Converter < ::Prawn::Document
     # title page (i)
     # TODO same conditional logic as in layout_title_page; consolidate
     if doc.header? && !doc.noheader && !doc.notitle
-      page_num_labels[0] = { P: ::PDF::Core::LiteralString.new(front_matter_counter.next!.to_s) } 
+      page_num_labels[0] = { P: ::PDF::Core::LiteralString.new(front_matter_counter.next!.to_s) }
     end
 
     # toc pages (ii..?)
@@ -1198,7 +1805,8 @@ class Converter < ::Prawn::Document
     numbering_offset = front_matter_counter.to_i - 1
 
     outline.define do
-      if (doctitle = (doc.doctitle sanitize: true, use_fallback: true))
+      # FIXME use sanitize: :plain_text once available
+      if (doctitle = document.sanitize(doc.doctitle use_fallback: true))
         page title: doctitle, destination: (document.dest_top 1)
       end
       if doc.attr? 'toc'
@@ -1217,8 +1825,8 @@ class Converter < ::Prawn::Document
   # TODO only nest inside root node if doctype=article
   def add_outline_level outline, sections, num_levels, page_num_labels, numbering_offset, num_front_matter_pages
     sections.each do |sect|
-      sect_title = sanitize(sect.numbered_title formal: true)
-      sect_destination = sect.attr 'destination'
+      sect_title = sanitize sect.numbered_title formal: true
+      sect_destination = sect.attr 'pdf-destination'
       sect_page_num = (sect.attr 'page_start') - num_front_matter_pages
       page_num_labels[sect_page_num + numbering_offset] = { P: ::PDF::Core::LiteralString.new(sect_page_num.to_s) }
       if (subsections = sect.sections).empty? || sect.level == num_levels
@@ -1243,7 +1851,6 @@ class Converter < ::Prawn::Document
       register_font key => font_styles.map {|style, path| [style.to_sym, (font_path path, fonts_dir)]}.to_h
     end
 
-    @fallback_fonts ||= []
     # FIXME read kerning setting from theme!
     default_kerning true
   end
@@ -1254,10 +1861,9 @@ class Converter < ::Prawn::Document
   end
 
   def theme_fill_and_stroke_bounds category
-    fill_and_stroke_bounds @theme[%(#{category}_background_color)], @theme[%(#{category}_border_color)], {
+    fill_and_stroke_bounds @theme[%(#{category}_background_color)], @theme[%(#{category}_border_color)],
       line_width: @theme[%(#{category}_border_width)],
       radius: @theme[%(#{category}_border_radius)]
-    }
   end
 
   # Insert a top margin space unless cursor is at the top of the page.
@@ -1291,33 +1897,34 @@ class Converter < ::Prawn::Document
   end
 
   def theme_font category, opts = {}
-    # QUESTION should we fallback to base_font_* or just leave current setting?
-    family = @theme[%(#{category}_font_family)] || @theme.base_font_family
-
     if (level = opts[:level])
-      size = @theme[%(#{category}_font_size_h#{level})] || @theme.base_font_size
+      family = @theme[%(#{category}_h#{level}_font_family)] || @theme[%(#{category}_font_family)] || @theme.base_font_family
+      size = @theme[%(#{category}_h#{level}_font_size)] || @theme[%(#{category}_font_size)] || @theme.base_font_size
+      style = @theme[%(#{category}_h#{level}_font_style)] || @theme[%(#{category}_font_style)]
+      color = @theme[%(#{category}_h#{level}_font_color)] || @theme[%(#{category}_font_color)]
+      # NOTE global text_transform is not currently supported
+      transform = @theme[%(#{category}_h#{level}_text_transform)] || @theme[%(#{category}_text_transform)]
     else
-      size = @theme[%(#{category}_font_size)] || @theme.base_font_size
+      inherited_font = font_info
+      family = @theme[%(#{category}_font_family)] || inherited_font[:family]
+      size = @theme[%(#{category}_font_size)] || inherited_font[:size]
+      style = @theme[%(#{category}_font_style)] || inherited_font[:style]
+      color = @theme[%(#{category}_font_color)]
+      # NOTE global text_transform is not currently supported
+      transform = @theme[%(#{category}_text_transform)]
     end
 
-    style = (@theme[%(#{category}_font_style)] || :normal).to_sym
+    style = style.to_sym if style
 
-    if level
-      color = @theme[%(#{category}_font_color_h#{level})] || @theme[%(#{category}_font_color)]
-    else
-      color = @theme[%(#{category}_font_color)]
-    end
+    prev_color, @font_color = @font_color, color if color
+    prev_transform, @text_transform = @text_transform, transform if transform
 
-    if color
-      prev_color = @font_color
-      @font_color = color
-    end
     font family, size: size, style: style do
       yield
     end
-    if color
-      @font_color = prev_color
-    end
+
+    @font_color = prev_color if color
+    @text_transform = prev_transform if transform
   end
 
   # TODO document me, esp the first line formatting functionality
@@ -1345,21 +1952,36 @@ class Converter < ::Prawn::Document
     (height_of string, leading: line_metrics.leading, final_gap: line_metrics.final_gap) + line_metrics.padding_top + line_metrics.padding_bottom
   end
 
-  def prepare_verbatim string
-    string.gsub(BuiltInEntityCharsRx, BuiltInEntityChars)
-        .gsub(IndentationRx) { NoBreakSpace * $&.length }
-  end
-
-  # Remove all HTML tags and resolve all entities in a string
-  # FIXME add option to control escaping entities, or a filter mechanism in general
-  def sanitize string
-    string.gsub(/<[^>]+>/, '')
-        .gsub(/&#(\d{2,4});/) { [$1.to_i].pack('U*') }
-        .gsub('&lt;', '<').gsub('&gt;', '>').gsub('&amp;', '&')
-        .tr_s(' ', ' ')
-        .strip
+  def preserve_indentation string
+    string.gsub(IndentationRx) { NoBreakSpace * $&.length }
+  end
+
+  # If an id is provided or the node passed as the first argument has an id,
+  # add a named destination to the document equivalent to the node id at the
+  # current y position. If the node does not have an id and an id is not
+  # specified, do nothing.
+  #
+  # If the node is a section, and the current y position is the top of the
+  # page, set the position equal to the page height to improve the navigation
+  # experience.
+  def add_dest_for_block node, id = nil
+    if !scratch? && (id ||= node.id)
+      # QUESTION should we set precise x value of destination or just 0?
+      dest_x = bounds.absolute_left.round 2
+      dest_x = 0 if dest_x <= page_margin_left
+      dest_y = if node.context == :section && at_page_top?
+        page_height
+      else
+        y
+      end
+      # TODO find a way to store only the ref of the destination; look it up when we need it
+      node.set_attr 'pdf-destination', (node_dest = (dest_xyz dest_x, dest_y))
+      add_dest id, node_dest
+    end
+    nil
   end
 
+  # QUESTION is this method still necessary?
   def resolve_imagesdir doc
     @imagesdir ||= begin
       imagesdir = (doc.attr 'imagesdir', '.').chomp '/'
@@ -1367,6 +1989,61 @@ class Converter < ::Prawn::Document
     end
   end
 
+  # Resolve the system path of the specified image path.
+  #
+  # Resolve and normalize the absolute system path of the specified image,
+  # taking into account the imagesdir attribute. If an image path is not
+  # specified, the path is read from the target attribute of the specified
+  # document node.
+  #
+  # If the target is a URI and the allow-uri-read attribute is set on the
+  # document, read the file contents to a temporary file and return the path to
+  # 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.
+  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]
+    # 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})
+        return
+      end
+      if doc.attr? 'cache-uri'
+        Helpers.require_library 'open-uri/cached', 'open-uri-cached' unless defined? ::OpenURI::Cache
+      end
+      tmp_image = ::Tempfile.new ['image-', %(.#{image_type})]
+      tmp_image.binmode if (binary = image_type != 'svg')
+      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
+      rescue
+        tmp_image_path = nil
+      ensure
+        tmp_image.close
+      end
+      tmp_image_path
+    # handle case when image is a local file
+    else
+      ::File.expand_path(node.normalize_system_path image_path, imagesdir, nil, target_name: 'image')
+    end
+  end
+
+  # 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
+  end
+
   # QUESTION move to prawn/extensions.rb?
   def init_scratch_prototype
     # IMPORTANT don't set font before using Marshal, it causes serialization to fail
@@ -1377,6 +2054,17 @@ class Converter < ::Prawn::Document
   end
 
 =begin
+  def assign_missing_section_ids doc
+    unless doc.attr? 'sectids'
+      doc.attributes['sectids'] = ''
+      doc.find_by(context: :section).each do |sect|
+        unless sect.id
+          sect.document.register(:ids, [sect.id = sect.generate_id, (sect.attributes['reftext'] || sect.title)])
+        end
+      end
+    end
+  end
+
   def create_stamps
     create_stamp 'masthead' do
       canvas do