asciidoctor-pdf 1.5.0.alpha.13 → 1.5.0.alpha.14

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

@@ -1,5 +1,7 @@
 module Asciidoctor
 module Image
+  DataUriRx = /^data:image\/(?<fmt>png|jpe?g|gif|pdf|bmp|tiff);base64,(?<data>.*)$/
+
   class << self
     def format path, node = nil
       (node && (node.attr 'format', nil, false)) || (::File.extname path).downcase[1..-1]
@@ -12,7 +14,11 @@ module Image
 
   def target_and_format
     image_path = inline? ? target : (attr 'target')
-    [image_path, (attr 'format', nil, false) || (::File.extname image_path).downcase[1..-1]]
+    if (image_path.start_with? 'data:') && (m = DataUriRx.match image_path)
+      [(m[:data].extend ::Base64), m[:fmt]]
+    else
+      [image_path, (attr 'format', nil, false) || (::File.extname image_path).downcase[1..-1]]
+    end
   end
 end
 end

data/lib/asciidoctor-pdf/converter.rb

@@ -1,20 +1,27 @@
 # encoding: UTF-8
 # TODO cleanup imports...decide what belongs in asciidoctor-pdf.rb
 require 'prawn'
-require 'prawn-svg'
-require 'prawn/table'
+begin
+  require 'prawn/gmagick'
+rescue LoadError
+end unless defined? GMagick::Image
+require_relative 'prawn-svg_ext'
+require_relative 'prawn-table_ext'
 require 'prawn/templates'
 require_relative 'core_ext'
-require_relative 'pdf_core_ext'
+require_relative 'pdf-core_ext'
 require_relative 'temporary_path'
+require_relative 'measurements'
 require_relative 'sanitizer'
 require_relative 'prawn_ext'
 require_relative 'formatted_text'
-require_relative 'pdfmarks'
+require_relative 'pdfmark'
 require_relative 'asciidoctor_ext'
 require_relative 'theme_loader'
 require_relative 'roman_numeral'
+require_relative 'index_catalog'
 
+autoload :StringIO, 'stringio'
 autoload :Tempfile, 'tempfile'
 
 module Asciidoctor
@@ -38,7 +45,8 @@ class Converter < ::Prawn::Document
     tip:       { name: 'fa-lightbulb-o', stroke_color: '111111', size: 24 },
     warning:   { name: 'fa-exclamation-triangle', stroke_color: 'BF6900', size: 24 }
   }
-  AlignmentNames = ['left', 'center', 'right']
+  TextAlignmentNames = ['left', 'center', 'right', 'justify']
+  BlockAlignmentNames = ['left', 'center', 'right']
   AlignmentTable = { '<' => :left, '=' => :center, '>' => :right }
   ColumnPositions = [:left, :center, :right]
   PageSides = [:recto, :verso]
@@ -57,8 +65,10 @@ class Converter < ::Prawn::Document
   NarrowNoBreakSpace = %(\u202f)
   ZeroWidthSpace = %(\u200b)
   HairSpace = %(\u200a)
-  DotLeaderDefault = '. '
+  DummyText = %(\u0000)
+  DotLeaderTextDefault = '. '
   EmDash = %(\u2014)
+  RightPointer = %(\u25ba)
   LowercaseGreekA = %(\u03b1)
   Bullets = {
     disc: %(\u2022),
@@ -71,16 +81,20 @@ class Converter < ::Prawn::Document
     unchecked: %(\u2610)
   }
   SimpleAttributeRefRx = /(?<!\\)\{\w+(?:[\-]\w+)*\}/
-  MeasurementRxt = '\\d+(?:\\.\\d+)?(?:in|cm|mm|pt|px)?'
-  MeasurementPartsRx = /^(\d+(?:\.\d+)?)(in|mm|cm|pt|px)?$/
+  MeasurementRxt = '\\d+(?:\\.\\d+)?(?:in|cm|mm|p[txc])?'
+  MeasurementPartsRx = /^(\d+(?:\.\d+)?)(in|mm|cm|p[txc])?$/
   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}(.*?)\[(.*?)\]$/
+  UriBreakCharsRx = /(?:\/|\?|&amp;|#)(?!$)/
+  UriBreakCharRepl = %(\\&#{ZeroWidthSpace})
+  UriSchemeBoundaryRx = /(?<=:\/\/)/
   LineScanRx = /\n|.+/
   BlankLineRx = /\n[[:blank:]]*\n/
   WhitespaceChars = %( \t\n)
   SourceHighlighters = ['coderay', 'pygments', 'rouge'].to_set
+  PygmentsBgColorRx = /^\.highlight +{ *background: *#([^;]+);/
   ViewportWidth = ::Module.new
 
   def initialize backend, opts
@@ -134,6 +148,21 @@ class Converter < ::Prawn::Document
     end
     #assign_missing_section_ids doc
 
+    # promote anonymous preface (defined using preamble block) to preface section
+    # FIXME this should be done in core
+    if doc.doctype == 'book' && (blk_0 = doc.blocks[0]) && blk_0.context == :preamble &&
+        blk_0.title? && blk_0.blocks[0].style != 'abstract' && (blk_1 = doc.blocks[1]) && blk_1.context == :section
+      preface = Section.new doc, blk_1.level, false, attributes: { 1 => 'preface', 'style' => 'preface' }
+      preface.special = true
+      preface.sectname = 'preface'
+      preface.title = doc.attr 'preface-title', 'Preface'
+      # QUESTION should ID be generated from raw or converted title? core is not clear about this
+      preface.id = preface.generate_id
+      preface.blocks.replace blk_0.blocks.map {|b| b.parent = preface; b }
+      doc.blocks[0] = preface
+      blk_0 = blk_1 = preface = nil
+    end
+
     # NOTE on_page_create is called within a float context
     # NOTE on_page_create is not called for imported pages, front and back cover pages, and other image pages
     on_page_create do
@@ -170,7 +199,7 @@ class Converter < ::Prawn::Document
     #start_new_page if @ppbook && verso_page?
     start_new_page if @media == 'prepress' && verso_page?
 
-    num_front_matter_pages = page_number - 1
+    num_front_matter_pages = (@index.start_page_number = page_number) - 1
     font @theme.base_font_family, size: @theme.base_font_size, style: @theme.base_font_style.to_sym
     doc.set_attr 'pdf-anchor', (doc_anchor = derive_anchor_from_id doc.id, 'top')
     add_dest_for_block doc, doc_anchor
@@ -233,9 +262,11 @@ class Converter < ::Prawn::Document
     @page_bg_color = resolve_theme_color :page_background_color, 'FFFFFF'
     @fallback_fonts = [*theme.font_fallbacks]
     @font_color = theme.base_font_color
+    @base_align = (align = doc.attr 'text-alignment') && (TextAlignmentNames.include? align) ? align : theme.base_align
     @text_transform = nil
-    # NOTE we have to init pdfmarks here while we have a reference to the doc
-    @pdfmarks = (doc.attr? 'pdfmarks') ? (Pdfmarks.new doc) : nil
+    @index = IndexCatalog.new
+    # NOTE we have to init Pdfmark class here while we have reference to the doc
+    @pdfmark = (doc.attr? 'pdfmark') ? (Pdfmark.new doc) : nil
     init_scratch_prototype
     self
   end
@@ -246,7 +277,7 @@ class Converter < ::Prawn::Document
       #optimize_objects: true,
       info: (build_pdf_info doc),
       margin: theme.page_margin,
-      page_layout: theme.page_layout.to_sym,
+      page_layout: ((doc.attr 'pdf-page-layout') || theme.page_layout).to_sym,
       skip_page_creation: true,
     }
 
@@ -280,13 +311,8 @@ class Converter < ::Prawn::Document
           # 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
-          val
+          # NOTE truncate to max precision retained by PDF::Core
+          (to_pt m[1].to_f, m[2]).truncate_to_precision 4
         else
           break
         end
@@ -303,30 +329,40 @@ class Converter < ::Prawn::Document
   def build_pdf_info doc
     info = {}
     # FIXME use sanitize: :plain_text once available
-    info[:Title] = str2pdfval sanitize(doc.doctitle use_fallback: true)
+    info[:Title] = sanitize(doc.doctitle use_fallback: true).as_pdf
     if doc.attr? 'authors'
-      info[:Author] = str2pdfval(doc.attr 'authors')
+      info[:Author] = (doc.attr 'authors').as_pdf
     end
     if doc.attr? 'subject'
-      info[:Subject] = str2pdfval(doc.attr 'subject')
+      info[:Subject] = (doc.attr 'subject').as_pdf
     end
     if doc.attr? 'keywords'
-      info[:Keywords] = str2pdfval(doc.attr 'keywords')
+      info[:Keywords] = (doc.attr 'keywords').as_pdf
     end
     if (doc.attr? 'publisher')
-      info[:Producer] = str2pdfval(doc.attr 'publisher')
+      info[:Producer] = (doc.attr 'publisher').as_pdf
     end
-    info[:Creator] = str2pdfval %(Asciidoctor PDF #{::Asciidoctor::Pdf::VERSION}, based on Prawn #{::Prawn::VERSION})
+    info[:Creator] = %(Asciidoctor PDF #{::Asciidoctor::Pdf::VERSION}, based on Prawn #{::Prawn::VERSION}).as_pdf
     info[:Producer] ||= (info[:Author] || info[:Creator])
-    # FIXME use docdate attribute
-    info[:ModDate] = info[:CreationDate] = ::Time.now unless doc.attr? 'reproducible'
+    unless doc.attr? 'reproducible'
+      # NOTE since we don't track the creation date of the input file, we map the ModDate header to the last modified
+      # date of the input document and the CreationDate header to the date the PDF was produced by the converter.
+      info[:ModDate] = ::Time.parse(doc.attr 'docdatetime') rescue (now ||= ::Time.now)
+      info[:CreationDate] = ::Time.parse(doc.attr 'localdatetime') rescue (now ||= ::Time.now)
+    end
     info
   end
 
   def convert_section sect, opts = {}
+    if sect.special && sect.sectname == 'abstract'
+      # HACK cheat a bit to hide this section from TOC; TOC should filter these sections
+      sect.context = :open
+      return convert_abstract sect
+    end
+
     theme_font :heading, level: (hlevel = sect.level + 1) do
       title = sect.numbered_title formal: true
-      align = (@theme[%(heading_h#{hlevel}_align)] || @theme.heading_align || @theme.base_align).to_sym
+      align = (@theme[%(heading_h#{hlevel}_align)] || @theme.heading_align || @base_align).to_sym
       type = nil
       if sect.part_or_chapter?
         if sect.chapter?
@@ -355,7 +391,7 @@ class Converter < ::Prawn::Document
       end
     end
 
-    convert_content_for_block sect
+    sect.special && sect.sectname == 'index' ? (convert_index_section sect) : (convert_content_for_block sect)
     sect.set_attr 'pdf-page-end', page_number
   end
 
@@ -363,13 +399,18 @@ class Converter < ::Prawn::Document
     add_dest_for_block node if node.id
     # QUESTION should we decouple styles from section titles?
     theme_font :heading, level: (hlevel = node.level + 1) do
-      layout_heading node.title, align: (@theme[%(heading_h#{hlevel}_align)] || @theme.heading_align || @theme.base_align).to_sym
+      layout_heading node.title, align: (@theme[%(heading_h#{hlevel}_align)] || @theme.heading_align || @base_align).to_sym
     end
   end
 
   def convert_abstract node
     add_dest_for_block node if node.id
     pad_box @theme.abstract_padding do
+      if node.title?
+        theme_font :abstract_title do
+          layout_heading node.title, align: (@theme.abstract_title_align || @base_align).to_sym
+        end
+      end
       theme_font :abstract do
         prose_opts = { line_height: @theme.abstract_line_height }
         # FIXME control more first_line_options using theme
@@ -399,11 +440,11 @@ class Converter < ::Prawn::Document
   end
 
   def convert_preamble node
-    # FIXME should only use lead for first paragraph
-    # add lead role to first paragraph then delegate to convert_content_for_block
-    theme_font :lead do
-      convert_content_for_block node
+    # TODO find_by needs to support a depth argument
+    if (first_p = (node.find_by context: :paragraph)[0]) && first_p.parent == node
+      first_p.add_role 'lead'
     end
+    convert_content_for_block node
   end
 
   # TODO add prose around image logic (use role to add special logic for headshot)
@@ -441,58 +482,134 @@ class Converter < ::Prawn::Document
     end
   end
 
-  # FIXME alignment of content is off
   def convert_admonition node
     add_dest_for_block node if node.id
     theme_margin :block, :top
-    icons = node.document.attr? 'icons', 'font'
-    label = icons ? (node.attr 'name').to_sym : node.caption.upcase
+    type = node.attr 'name'
+    label_align = (@theme.admonition_label_align || :center).to_sym
+    # TODO allow vertical_align to be a number
+    if (label_valign = (@theme.admonition_label_vertical_align || :middle).to_sym) == :middle
+      label_valign = :center
+    end
+    if (label_min_width = @theme.admonition_label_min_width)
+      label_min_width = label_min_width.to_f
+    end
+    icons = (node.document.attr? 'icons') ? (node.document.attr 'icons') : false
+    if icons == 'font' && !(node.attr? 'icon', nil, false)
+      icon_data = admonition_icon_data(label_text = type.to_sym)
+      label_width = label_min_width ? label_min_width : (icon_data[:size] * 1.5)
+    # NOTE icon_uri will consider icon attribute on node first, then type
+    elsif icons && ::File.readable?(icon_path = (node.icon_uri type))
+      icons = true
+      # TODO introduce @theme.admonition_image_width? or use size key from admonition_icon_<name>?
+      label_width = label_min_width ? label_min_width : 36.0
+    else
+      if icons
+        icons = false
+        warn %(asciidoctor: WARNING: admonition icon image not found or not readable: #{icon_path}) unless scratch?
+      end
+      label_text = node.caption
+      theme_font :admonition_label do
+        theme_font %(admonition_label_#{type}) do
+          if (transform = @text_transform) && transform != 'none'
+            label_text = transform_text label_text, transform
+          end
+          label_width = width_of label_text
+          label_width = label_min_width if label_min_width && label_min_width > label_width
+        end
+      end
+    end
+    unless ::Array === (cpad = @theme.admonition_padding)
+      cpad = ::Array.new 4, cpad
+    end
+    unless ::Array === (lpad = @theme.admonition_label_padding || cpad)
+      lpad = ::Array.new 4, lpad
+    end
     # FIXME this shift stuff is a real hack until we have proper margin collapsing
     shift_base = @theme.prose_margin_bottom
-    #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
-        # FIXME this is a fudge calculation for the icon width
-        label_width = icons ? (bounds.width / 12.0) : (width_of label)
-        abs_left = bounds.absolute_left
-        abs_right = bounds.absolute_right
-        pad_box @theme.admonition_padding do
-          left_padding = bounds.absolute_left - abs_left
-          right_padding = abs_right - bounds.absolute_right
-          if box_height
+      pad_box [0, cpad[1], 0, lpad[3]] do
+        if box_height
+          if (rule_color = @theme.admonition_column_rule_color) &&
+              (rule_width = @theme.admonition_column_rule_width || @theme.base_border_width) && rule_width > 0
             float do
-              bounding_box [0, cursor], width: label_width + right_padding, height: box_height do
+              bounding_box [0, cursor], width: label_width + lpad[1], height: box_height do
+                stroke_vertical_rule rule_color,
+                    at: bounds.width,
+                    line_style: (@theme.admonition_column_rule_style || :solid).to_sym,
+                    line_width: rule_width
+              end
+            end
+          end
+          float do
+            bounding_box [0, cursor], width: label_width, height: box_height do
+              if icons == 'font'
+                # FIXME we're assume icon is a square
+                icon_size = fit_icon_to_bounds icon_data[:size]
+                # NOTE Prawn's vertical center is not reliable, so calculate it manually
+                if label_valign == :center
+                  label_valign = :top
+                  if (vcenter_pos = (box_height - icon_size) * 0.5) > 0
+                    move_down vcenter_pos
+                  end
+                end
+                icon icon_data[:name],
+                    valign: label_valign,
+                    align: label_align,
+                    color: icon_data[:stroke_color],
+                    size: icon_size
+              elsif icons
+                begin
+                  image_obj, image_info = build_image_object icon_path
+                  icon_aspect_ratio = image_info.width.fdiv image_info.height
+                  # NOTE don't scale image up if smaller than label_width
+                  icon_width = [(to_pt image_info.width, :px), label_width].min
+                  if (icon_height = icon_width * (1 / icon_aspect_ratio)) > box_height
+                    icon_width *= box_height / icon_height
+                    icon_height = box_height
+                  end
+                  embed_image image_obj, image_info, width: icon_width, position: label_align, vposition: label_valign
+                rescue => e
+                  # QUESTION should we show the label in this case?
+                  warn %(asciidoctor: WARNING: could not embed admonition icon image: #{icon_path}; #{e.message})
+                end
+              else
                 # 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
-                # FIXME HACK make title in this location look right
-                label_margin_top = node.title? ? @theme.caption_margin_inside : 0
-                if icons
-                  icon_data = admonition_icon_data label
-                  icon icon_data[:name], {
-                    valign: :center,
-                    align: :center,
-                    color: icon_data[:stroke_color],
-                    size: (fit_icon_size node, icon_data[:size])
-                  }
-                else
-                  layout_prose label, valign: :center, style: :bold, line_height: 1, margin_top: label_margin_top, margin_bottom: 0
+                theme_font :admonition_label do
+                  theme_font %(admonition_label_#{type}) do
+                    # NOTE Prawn's vertical center is not reliable, so calculate it manually
+                    if label_valign == :center
+                      label_valign = :top
+                      if (vcenter_pos = (box_height - (height_of_typeset_text label_text, line_height: 1)) * 0.5) > 0
+                        move_down vcenter_pos
+                      end
+                    end
+                    @text_transform = nil # already applied to label
+                    layout_prose label_text,
+                        align: label_align,
+                        valign: label_valign,
+                        line_height: 1,
+                        margin: 0,
+                        inline_format: false
+                  end
                 end
               end
             end
           end
-          indent label_width + left_padding + right_padding do
-            move_down shift_top
-            layout_caption node.title if node.title?
+        end
+        pad_box [cpad[0], 0, cpad[2], label_width + lpad[1] + cpad[3]] do
+          move_down shift_top
+          layout_caption node.title if node.title?
+          theme_font :admonition do
             convert_content_for_block node
-            # FIXME HACK compensate for margin bottom of admonition content
-            move_up shift_bottom unless at_page_top?
           end
+          # FIXME HACK compensate for margin bottom of admonition content
+          move_up shift_bottom unless at_page_top?
         end
-      #end
+      end
     end
     theme_margin :block, :bottom
   end
@@ -519,18 +636,15 @@ class Converter < ::Prawn::Document
   end
 
   def convert_open node
-    case node.style
-    when 'abstract'
+    if node.style == 'abstract'
       convert_abstract node
-    when 'partintro'
-      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
+    elsif node.style == 'partintro' && node.blocks.size == 1 && node.blocks.first.style == 'abstract'
+      # TODO process block title and id
+      # TODO process abstract child even when partintro has multiple blocks
+      convert_abstract node.blocks.first
     else
       add_dest_for_block node if node.id
+      layout_caption node.title if node.title?
       convert_content_for_block node
     end
   end
@@ -543,6 +657,7 @@ class Converter < ::Prawn::Document
     keep_together do |box_height = nil|
       start_page_number = page_number
       start_cursor = cursor
+      caption_height = node.title? ? (layout_caption node) : 0
       pad_box @theme.blockquote_padding do
         theme_font :blockquote do
           if node.context == :quote
@@ -559,8 +674,9 @@ class Converter < ::Prawn::Document
         end
       end
       # FIXME we want to draw graphics before content, but box_height is not reliable when spanning pages
-      if box_height
-        page_spread = (end_page_number = page_number) - start_page_number + 1
+      # FIXME border extends to bottom of content area if block terminates at bottom of page
+      if box_height && b_width > 0
+        page_spread = page_number - start_page_number + 1
         end_cursor = cursor
         go_to_page start_page_number
         move_cursor_to start_cursor
@@ -573,9 +689,20 @@ class Converter < ::Prawn::Document
             y_draw = cursor
             b_height = page_spread - 1 == i ? (y_draw - end_cursor) : y_draw
           end
+          # NOTE skip past caption if present
+          if caption_height > 0
+            if caption_height > cursor
+              caption_height -= cursor
+              next # keep skipping, caption is on next page
+            end
+            y_draw -= caption_height
+            b_height -= caption_height
+            caption_height = 0
+          end
+          # NOTE b_height is 0 when block terminates at bottom of page
           bounding_box [0, y_draw], width: bounds.width, height: b_height do
             stroke_vertical_rule b_color, line_width: b_width, at: b_width / 2.0
-          end
+          end unless b_height == 0
         end
       end
     end
@@ -600,7 +727,7 @@ class Converter < ::Prawn::Document
         if node.title?
           theme_font :sidebar_title do
             # QUESTION should we allow margins of sidebar title to be customized?
-            layout_heading node.title, align: (@theme.sidebar_title_align || @theme.base_align).to_sym, margin_top: 0
+            layout_heading node.title, align: (@theme.sidebar_title_align || @base_align).to_sym, margin_top: 0
           end
         end
         theme_font :sidebar do
@@ -685,6 +812,7 @@ class Converter < ::Prawn::Document
   def convert_olist node
     add_dest_for_block node if node.id
     @list_numbers ||= []
+    # TODO move list_number resolve to a method
     list_number = case node.style
     when 'arabic'
       '1'
@@ -824,120 +952,103 @@ class Converter < ::Prawn::Document
     node.extend ::Asciidoctor::Image unless ::Asciidoctor::Image === node
     target, image_format = node.target_and_format
 
-    if image_format == 'gif'
-      warn %(asciidoctor: WARNING: GIF image format not supported. Please convert #{target} to PNG.) unless scratch?
+    if image_format == 'gif' && !(defined? ::GMagick::Image)
+      warn %(asciidoctor: WARNING: GIF image format not supported. Install the prawn-gmagick gem or convert #{target} to PNG.) unless scratch?
       image_path = false
+    elsif ::Base64 === target
+      image_path = target
     elsif (image_path = resolve_image_path node, target, (opts.fetch :relative_to_imagesdir, true), image_format) &&
         (::File.readable? image_path)
       # NOTE import_page automatically advances to next page afterwards
       # QUESTION should we add destination to top of imported page?
-      return import_page image_path if image_format == 'pdf'
+      return import_page image_path, replace: page_is_empty? if image_format == 'pdf'
     else
       warn %(asciidoctor: WARNING: image to embed not found or not readable: #{image_path || target}) unless scratch?
-      image_path = false
       # QUESTION should we use alt text in this case?
       return if image_format == 'pdf'
+      image_path = false
     end
 
-    # QUESTION if we advance to new page, shouldn't dest point there too?
-    add_dest_for_block node if node.id
-    alignment = ((node.attr 'align', nil, false) || @theme.image_align).to_sym
+    theme_margin :block, :top unless (pinned = opts[:pinned])
 
-    theme_margin :block, :top
+    return on_image_error :missing, node, target, opts unless image_path
 
-    unless image_path
-      if (link = node.attr 'link', nil, false)
-        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: alignment
-      layout_caption node, side: :bottom if node.title?
-      theme_margin :block, :bottom
-      return
-    end
+    # TODO move this calculation into a method, such as layout_caption node, side: :bottom, dry_run: true
+    caption_h = 0
+    dry_run do
+      move_down 0.0001 # hack to force top margin to be applied
+      # NOTE we assume caption fits on a single page, which seems reasonable
+      caption_h = layout_caption node, side: :bottom
+    end if node.title?
 
     # TODO support cover (aka canvas) image layout using "canvas" (or "cover") role
-    width = resolve_explicit_width node.attributes, bounds.width, support_vw: true, use_fallback: true
-    if (width_relative_to_page = ViewportWidth === width)
-      width = (width.to_f / 100) * page_width
-      overflow = [bounds_margin_left, bounds_margin_right]
-    else
-      overflow = 0
-    end
+    width = resolve_explicit_width node.attributes, (available_w = bounds.width), support_vw: true, use_fallback: true
+    # TODO add `to_pt page_width` method to ViewportWidth type
+    width = (width.to_f / 100) * page_width if (width_relative_to_page = ViewportWidth === width)
+
+    alignment = ((node.attr 'align', nil, false) || @theme.image_align).to_sym
 
-    span_page_width_if width_relative_to_page do
-      case image_format
-      when 'svg'
-        begin
-          svg_data = ::IO.read image_path
+    begin
+      span_page_width_if width_relative_to_page do
+        if image_format == 'svg'
+          if ::Base64 === image_path
+            svg_data = ::Base64.decode64 image_path
+            file_request_root = false
+          else
+            svg_data = ::IO.read image_path
+            file_request_root = ::File.dirname image_path
+          end
           svg_obj = ::Prawn::Svg::Interface.new svg_data, self,
               position: alignment,
               width: width,
-              fallback_font_name: (fallback_font_name = default_svg_font),
-              enable_web_requests: (enable_web_requests = node.document.attr? 'allow-uri-read'),
+              fallback_font_name: default_svg_font,
+              enable_web_requests: (node.document.attr? 'allow-uri-read'),
               # TODO enforce jail in safe mode
-              enable_file_requests_with_root: (file_request_root = ::File.dirname image_path)
+              enable_file_requests_with_root: file_request_root
           rendered_w = (svg_size = svg_obj.document.sizing).output_width
           if !width && (svg_obj.document.root.attributes.key? 'width')
-            # NOTE scale native width & height by 75% to convert px to pt; restrict width to bounds.width
-            if (adjusted_w = [bounds.width, rendered_w * 0.75].min) != rendered_w
-              # FIXME would be nice to have a resize method (available as of prawn-svg 0.25.2); for now, just reconstruct
-              svg_obj = ::Prawn::Svg::Interface.new svg_data, self,
-                  position: alignment,
-                  width: (rendered_w = adjusted_w),
-                  fallback_font_name: fallback_font_name,
-                  enable_web_requests: enable_web_requests,
-                  enable_file_requests_with_root: file_request_root
-              svg_size = svg_obj.document.sizing
+            # NOTE scale native width & height from px to pt and restrict width to available width
+            if (adjusted_w = [available_w, (to_pt rendered_w, :px)].min) != rendered_w
+              svg_size = svg_obj.resize width: (rendered_w = adjusted_w)
             end
           end
-          # TODO shrink image to fit on a single page if height exceeds page height
-          rendered_h = svg_size.output_height
-          # 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
-            # NOTE prawn-svg 0.24.0, 0.25.0, & 0.25.1 didn't restore font after call to draw (see mogest/prawn-svg#80)
-            svg_obj.draw
-            if box_height && (link = node.attr 'link', nil, false)
-              link_annotation [(abs_left = svg_obj.position[0] + bounds.absolute_left), y, (abs_left + rendered_w), (y + rendered_h)],
-                  Border: [0, 0, 0],
-                  A: { Type: :Action, S: :URI, URI: (str2pdfval link) }
+          # NOTE shrink image so it fits within available space; group image & caption
+          if (rendered_h = svg_size.output_height) > (available_h = cursor - caption_h)
+            unless pinned || at_page_top?
+              start_new_page
+              available_h = cursor - caption_h
+            end
+            if rendered_h > available_h
+              rendered_w = (svg_size = svg_obj.resize height: (rendered_h = available_h)).output_width
             end
-            indent(*overflow) do
-              layout_caption node, side: :bottom
-            end if node.title?
           end
-        rescue => e
-          warn %(asciidoctor: WARNING: could not embed image: #{image_path}; #{e.message})
-        end
-      else
-        begin
+          add_dest_for_block node if node.id
+          # NOTE workaround to fix Prawn not adding fill and stroke commands on page that only has an image;
+          # breakage occurs when running content (stamps) are added to page
+          update_colors if graphic_state.color_space.empty?
+          # NOTE prawn-svg 0.24.0, 0.25.0, & 0.25.1 didn't restore font after call to draw (see mogest/prawn-svg#80)
+          # NOTE cursor advanced automatically
+          svg_obj.draw
+          if (link = node.attr 'link', nil, false)
+            link_box = [(abs_left = svg_obj.position[0] + bounds.absolute_left), y, (abs_left + rendered_w), (y + rendered_h)]
+            link_annotation link_box, Border: [0, 0, 0], A: { Type: :Action, S: :URI, URI: link.as_pdf }
+          end
+        else
           # FIXME this code really needs to be better organized!
-          # FIXME temporary workaround to group caption & image
           # NOTE use low-level API to access intrinsic dimensions; build_image_object caches image data previously loaded
-          image_obj, image_info = ::File.open(image_path, 'rb') {|fd| build_image_object fd }
-          if width
-            rendered_w, rendered_h = image_info.calc_image_dimensions width: width
-          else
-            # NOTE scale native width & height by 75% to convert px to pt; restrict width to 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
-          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 height exceeds page height
-            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
-              # NOTE this no longer seems to be an issue
-              fill_color self.fill_color
-              stroke_color self.stroke_color
+          image_obj, image_info = ::Base64 === image_path ?
+              ::StringIO.open((::Base64.decode64 image_path), 'rb') {|fd| build_image_object fd } :
+              ::File.open(image_path, 'rb') {|fd| build_image_object fd }
+          # NOTE if width is not specified, scale native width & height from px to pt and restrict width to available width
+          rendered_w, rendered_h = image_info.calc_image_dimensions width: (width || [available_w, (to_pt image_info.width, :px)].min)
+          # NOTE shrink image so it fits within available space; group image & caption
+          if rendered_h > (available_h = cursor - caption_h)
+            unless pinned || at_page_top?
+              start_new_page
+              available_h = cursor - caption_h
+            end
+            if rendered_h > available_h
+              rendered_w, rendered_h = image_info.calc_image_dimensions height: (rendered_h = available_h)
             end
           end
           # NOTE must calculate link position before embedding to get proper boundaries
@@ -945,25 +1056,100 @@ class Converter < ::Prawn::Document
             img_x, img_y = image_position rendered_w, rendered_h, position: alignment
             link_box = [img_x, (img_y - rendered_h), (img_x + rendered_w), img_y]
           end
-          embed_image image_obj, image_info, width: rendered_w, position: alignment
-          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: #{image_path}; #{e.message})
+          image_top = cursor
+          add_dest_for_block node if node.id
+          # NOTE workaround to fix Prawn not adding fill and stroke commands on page that only has an image;
+          # breakage occurs when running content (stamps) are added to page
+          update_colors if graphic_state.color_space.empty?
+          # NOTE specify both width and height to avoid recalculation
+          embed_image image_obj, image_info, width: rendered_w, height: rendered_h, position: alignment
+          link_annotation link_box, Border: [0, 0, 0], A: { Type: :Action, S: :URI, URI: link.as_pdf } if link
+          # NOTE Asciidoctor disables automatic advancement of cursor for raster images, so move cursor manually
+          move_down rendered_h if cursor == image_top
         end
-        indent(*overflow) do
-          layout_caption node, side: :bottom
-        end if node.title?
       end
+      layout_caption node, side: :bottom if node.title?
+      theme_margin :block, :bottom unless pinned
+    rescue => e
+      on_image_error :exception, node, target, (opts.merge message: %(asciidoctor: WARNING: could not embed image: #{image_path}; #{e.message}))
     end
-    theme_margin :block, :bottom
   ensure
     unlink_tmp_file image_path if image_path
   end
 
+  def on_image_error reason, node, target, opts = {}
+    warn opts[:message] if opts.key? :message
+    alt_text = (link = node.attr 'link', nil, false) ?
+        %(<a href="#{link}">[#{node.attr 'alt'}]</a> | <em>#{target}</em>) :
+        %([#{node.attr 'alt'}] | <em>#{target}</em>)
+    layout_prose alt_text,
+        align: ((node.attr 'align', nil, false) || @theme.image_align).to_sym,
+        margin: 0,
+        normalize: false,
+        single_line: true
+    layout_caption node, side: :bottom if node.title?
+    theme_margin :block, :bottom unless opts[:pinned]
+    nil
+  end
+
+  def convert_audio node
+    add_dest_for_block node if node.id
+    theme_margin :block, :top
+    audio_path = node.media_uri(node.attr 'target')
+    play_symbol = (node.document.attr? 'icons', 'font') ?
+        %(<font name="fa">#{::Prawn::Icon::FontData.load(self, 'fa').unicode 'play'}</font>) : RightPointer
+    layout_prose %(#{play_symbol}#{NoBreakSpace}<a href="#{audio_path}">#{audio_path}</a> <em>(audio)</em>), normalize: false, margin: 0, single_line: true
+    layout_caption node, side: :bottom if node.title?
+    theme_margin :block, :bottom
+  end
+
+  def convert_video node
+    case (poster = node.attr 'poster', nil, false)
+    when 'youtube'
+      video_path = %(https://www.youtube.com/watch?v=#{video_id = node.attr 'target'})
+      # see http://stackoverflow.com/questions/2068344/how-do-i-get-a-youtube-video-thumbnail-from-the-youtube-api
+      poster = (node.document.attr? 'allow-uri-read') ? %(https://img.youtube.com/vi/#{video_id}/maxresdefault.jpg) : nil
+      type = 'YouTube video'
+    when 'vimeo'
+      video_path = %(https://vimeo.com/#{video_id = node.attr 'target'})
+      if node.document.attr? 'allow-uri-read'
+        if node.document.attr? 'cache-uri'
+          Helpers.require_library 'open-uri/cached', 'open-uri-cached' unless defined? ::OpenURI::Cache
+        else
+          ::OpenURI
+        end
+        poster = open(%(http://vimeo.com/api/v2/video/#{video_id}.xml), 'r') do |f|
+          (/<thumbnail_large>(.*?)<\/thumbnail_large>/.match f.read)[1]
+        end
+      else
+        poster = nil
+      end
+      type = 'Vimeo video'
+    else
+      video_path = node.media_uri(node.attr 'target')
+      type = 'video'
+    end
+
+    if poster.nil_or_empty?
+      add_dest_for_block node if node.id
+      theme_margin :block, :top
+      play_symbol = (node.document.attr? 'icons', 'font') ?
+          %(<font name="fa">#{::Prawn::Icon::FontData.load(self, 'fa').unicode 'play'}</font>) : RightPointer
+      layout_prose %(#{play_symbol}#{NoBreakSpace}<a href="#{video_path}">#{video_path}</a> <em>(#{type})</em>), normalize: false, margin: 0, single_line: true
+      layout_caption node, side: :bottom if node.title?
+      theme_margin :block, :bottom
+    else
+      original_attributes = node.attributes.dup
+      begin
+        node.update_attributes 'target' => poster, 'link' => video_path
+        #node.set_attr 'pdfwidth', '100%' unless (node.attr? 'width') || (node.attr? 'pdfwidth')
+        convert_image node
+      ensure
+        node.attributes.replace original_attributes
+      end
+    end
+  end
+
   # 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
@@ -1001,6 +1187,8 @@ class Converter < ::Prawn::Document
       source_string = preserve_indentation node.content, (node.attr 'tabsize')
     end
 
+    bg_color_override = nil
+
     source_chunks = case highlighter
     when 'coderay'
       Helpers.require_library CodeRayRequirePath, 'coderay' unless defined? ::Asciidoctor::Prawn::CodeRayEncoder
@@ -1010,13 +1198,28 @@ class Converter < ::Prawn::Document
     when 'pygments'
       Helpers.require_library 'pygments', 'pygments.rb' unless defined? ::Pygments
       lexer = ::Pygments::Lexer[node.attr 'language', 'text', false] || ::Pygments::Lexer['text']
-      pygments_config = { nowrap: true, noclasses: true, stripnl: false, style: (node.document.attr 'pygments-style') || 'pastie' }
+      pygments_config = {
+        nowrap: true,
+        noclasses: true,
+        stripnl: false,
+        style: style = (node.document.attr 'pygments-style') || 'pastie'
+      }
       # TODO enable once we support background color on spans
       #if node.attr? 'highlight', nil, false
       #  unless (hl_lines = node.resolve_lines_to_highlight(node.attr 'highlight', nil, false)).empty?
       #    pygments_config[:hl_lines] = hl_lines * ' '
       #  end
       #end
+      # QUESTION should we treat white background as inherit?
+      # QUESTION allow border color to be set by theme for highlighted block?
+      if (node.document.attr? 'pygments-bgcolor')
+        bg_color_override = node.document.attr 'pygments-bgcolor'
+      elsif style == 'pastie'
+        node.document.set_attr 'pygments-bgcolor', (bg_color_override = nil)
+      else
+        node.document.set_attr 'pygments-bgcolor',
+            (bg_color_override = PygmentsBgColorRx =~ (::Pygments.css '.highlight', style: style) ? $1 : nil)
+      end
       source_string, conum_mapping = extract_conums source_string
       # NOTE pygments.rb strips trailing whitespace; preserve it in case there are conums on last line
       num_trailing_spaces = source_string.size - (source_string = source_string.rstrip).size if conum_mapping
@@ -1026,7 +1229,9 @@ class Converter < ::Prawn::Document
     when 'rouge'
       Helpers.require_library RougeRequirePath, 'rouge' unless defined? ::Rouge::Formatters::Prawn
       lexer = ::Rouge::Lexer.find(node.attr 'language', 'text', false) || ::Rouge::Lexers::PlainText
-      formatter = (@rouge_formatter ||= ::Rouge::Formatters::Prawn.new theme: (node.document.attr 'rouge-style'))
+      formatter = (@rouge_formatter ||= ::Rouge::Formatters::Prawn.new theme: (node.document.attr 'rouge-style'), line_gap: @theme.code_line_gap)
+      # QUESTION allow border color to be set by theme for highlighted block?
+      bg_color_override = formatter.background_color
       source_string, conum_mapping = extract_conums source_string
       # NOTE trailing endline is added to address https://github.com/jneen/rouge/issues/279
       fragments = formatter.format (lexer.lex %(#{source_string}#{LF})), line_numbers: (node.attr? 'linenums')
@@ -1057,7 +1262,7 @@ class Converter < ::Prawn::Document
             # 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
+              b_gap_color = bg_color_override || @theme.code_background_color || @page_bg_color
             end
             remaining_height = box_height - caption_height
             i = 0
@@ -1065,17 +1270,17 @@ class Converter < ::Prawn::Document
               start_new_page if (started_new_page = 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
+                theme_fill_and_stroke_bounds :code, background_color: bg_color_override
                 unless b_width == 0
                   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
+                    stroke_horizontal_rule b_gap_color, line_width: b_width, line_style: :dashed
                   end if started_new_page
                   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
+                      stroke_horizontal_rule b_gap_color, line_width: b_width, line_style: :dashed
                     end
                   end
                 end
@@ -1207,11 +1412,13 @@ class Converter < ::Prawn::Document
     even_row_bg_color = resolve_theme_color :table_even_row_background_color, tbl_bg_color
 
     table_data = []
-    node.rows[:head].each do |rows|
+    node.rows[:head].each do |row|
       table_header = true
-      head_transform = theme.table_head_text_transform
+      if (head_transform = theme.table_head_text_transform)
+        head_transform = nil if head_transform == 'none'
+      end
       row_data = []
-      rows.each do |cell|
+      row.each do |cell|
         row_data << {
           content: (head_transform ? (transform_text cell.text, head_transform) : cell.text),
           inline_format: [normalize: true],
@@ -1223,15 +1430,15 @@ class Converter < ::Prawn::Document
           colspan: cell.colspan || 1,
           rowspan: cell.rowspan || 1,
           align: (cell.attr 'halign', nil, false).to_sym,
-          valign: (cell.attr 'valign', nil, false).to_sym
+          valign: (val = cell.attr 'valign', nil, false) == 'middle' ? :center : val.to_sym
         }
       end
       table_data << row_data
     end
 
-    (node.rows[:body] + node.rows[:foot]).each do |rows|
+    (node.rows[:body] + node.rows[:foot]).each do |row|
       row_data = []
-      rows.each do |cell|
+      row.each do |cell|
         cell_data = {
           text_color: (theme.table_font_color || @font_color),
           size: theme.table_font_size,
@@ -1250,25 +1457,22 @@ class Converter < ::Prawn::Document
           unless defined? header_cell_data
             header_cell_data = {}
             [
+              # TODO honor text_transform key
               # QUESTION should we honor alignment set by col/cell spec? how can we tell?
-              ['align', :align, true],
+              #['align', :align, true],
               ['font_color', :text_color, false],
               ['font_family', :font, false],
               ['font_size', :size, false],
               ['font_style', :font_style, true]
             ].each do |(theme_key, data_key, symbol_value)|
-              if (val = theme[%(table_header_cell_#{theme_key})])
+              if (val = theme[%(table_header_cell_#{theme_key})] || theme[%(table_head_#{theme_key})])
                 header_cell_data[data_key] = symbol_value ? val.to_sym : val
               end
             end
-            unless (header_cell_data.key? :font_style) || !(val = theme.table_head_font_style)
-              header_cell_data[:font_style] = val.to_sym
-            end
-            if (val = resolve_theme_color :table_header_cell_background_color)
+            if (val = resolve_theme_color :table_header_cell_background_color, head_bg_color)
               header_cell_data[:background_color] = val
             end
           end
-
           cell_data.update header_cell_data unless header_cell_data.empty?
         when :monospaced
           cell_data[:font] = theme.literal_font_family
@@ -1298,12 +1502,14 @@ class Converter < ::Prawn::Document
           cell_data[:content] = preserve_indentation cell.text, (node.document.attr 'tabsize')
           cell_data[:inline_format] = true
         when :asciidoc
-          # TODO finish me
+          asciidoc_cell = ::Prawn::Table::Cell::AsciiDoc.new self,
+              (cell_data.merge content: cell.inner_document, font_style: (val = theme.table_font_style) ? val.to_sym : nil)
+          cell_data = { content: asciidoc_cell }
         else
           cell_data[:font_style] = (val = theme.table_font_style) ? val.to_sym : nil
         end
         unless cell_data.key? :content
-          # NOTE effectively the same as calling cell.content
+          # NOTE effectively the same as calling cell.content (should we use that instead?)
           # TODO hard breaks not quite the same result as separate paragraphs; need custom cell impl
           if (cell_text = cell.text).include? LF
             cell_data[:content] = cell_text.split(BlankLineRx).map {|l| l.tr_s(WhitespaceChars, ' ') }.join(DoubleLF)
@@ -1318,10 +1524,17 @@ class Converter < ::Prawn::Document
       table_data << row_data
     end
 
-    table_data = [[{ content: '' }]] if table_data.empty?
+    # NOTE Prawn aborts if table data is empty, so ensure there's at least one row
+    if table_data.empty?
+      empty_row = []
+      node.columns.each do
+        empty_row << { content: '' }
+      end
+      table_data = [empty_row]
+    end
 
     border = {}
-    table_border_color = theme.table_border_color
+    table_border_color = theme.table_border_color || table_grid_color || theme.base_border_color
     table_border_width = theme.table_border_width
     table_grid_width = theme.table_grid_width || theme.table_border_width
     [:top, :bottom, :left, :right].each {|edge| border[edge] = table_border_width }
@@ -1362,8 +1575,8 @@ class Converter < ::Prawn::Document
       end
     end
 
-    if ((alignment = node.attr 'align', nil, false) && (AlignmentNames.include? alignment)) ||
-        (alignment = (node.roles & AlignmentNames).last)
+    if ((alignment = node.attr 'align', nil, false) && (BlockAlignmentNames.include? alignment)) ||
+        (alignment = (node.roles & BlockAlignmentNames).last)
       alignment = alignment.to_sym
     else
       alignment = :left
@@ -1378,7 +1591,7 @@ class Converter < ::Prawn::Document
         padding: theme.table_cell_padding,
         border_width: 0,
         # NOTE the border color of edges is set later
-        border_color: theme.table_grid_color || theme.table_border_color
+        border_color: theme.table_grid_color || theme.table_border_color || theme.base_border_color
       },
       width: table_width,
       column_widths: column_widths,
@@ -1388,7 +1601,7 @@ class Converter < ::Prawn::Document
     theme_margin :block, :top
 
     table table_data, table_settings do
-      # NOTE capture resolved table width
+      # NOTE call width to capture resolved table width
       table_width = width
       @pdf.layout_table_caption node, table_width, alignment if node.title? && caption_side == :top
       if grid == 'none' && frame == 'none'
@@ -1440,7 +1653,7 @@ class Converter < ::Prawn::Document
         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)
+        #if (foot_transform = theme.table_foot_text_transform) && foot_transform != 'none'
         #  foot_row.each {|c| c.content = (transform_text c.content, foot_transform) if c.content }
         #end
       end
@@ -1468,6 +1681,52 @@ class Converter < ::Prawn::Document
     start_new_page unless at_page_top?
   end
 
+  def convert_index_section node
+    unless @index.empty?
+      space_needed_for_category = @theme.description_list_term_spacing + (2 * (height_of_typeset_text 'A'))
+      column_box [0, cursor], columns: 2, width: bounds.width do
+        @index.categories.each do |category|
+          # NOTE cursor method always returns 0 inside column_box; breaks reference_bounds.move_past_bottom
+          bounds.move_past_bottom if space_needed_for_category > y - reference_bounds.absolute_bottom
+          layout_prose category.name,
+            align: :left,
+            inline_format: false,
+            margin_top: 0,
+            margin_bottom: @theme.description_list_term_spacing,
+            style: @theme.description_list_term_font_style.to_sym
+          category.terms.each do |term|
+            convert_index_list_item term
+          end
+          if @theme.prose_margin_bottom > y - reference_bounds.absolute_bottom
+            bounds.move_past_bottom
+          else
+            move_down @theme.prose_margin_bottom
+          end
+        end
+      end
+    end
+    nil
+  end
+
+  def convert_index_list_item term
+    text = term.name
+    unless term.container?
+      if @media == 'screen'
+        pagenums = term.dests.map {|dest| %(<a anchor="#{dest[:anchor]}">#{dest[:page]}</a>) }
+      else
+        pagenums = term.dests.uniq {|dest| dest[:page] }.map {|dest| dest[:page].to_s }
+      end
+      text = %(#{escape_xml text}, #{pagenums * ', '})
+    end
+    layout_prose text, align: :left, margin: 0
+
+    term.subterms.each do |subterm|
+      indent @theme.description_list_description_indent do
+        convert_index_list_item subterm
+      end
+    end unless term.leaf?
+  end
+
   def convert_inline_anchor node
     case node.type
     when :link
@@ -1478,11 +1737,14 @@ class Converter < ::Prawn::Document
       end
       #attrs << %( title="#{node.attr 'title'}") if node.attr? 'title'
       attrs << %( target="#{node.attr 'window'}") if node.attr? 'window', nil, false
+      if (role = node.attr 'role', nil, false) && (role == 'bare' || ((role.split ' ').include? 'bare'))
+        # QUESTION should we insert breakable chars into URI when building fragment instead?
+        %(<a href="#{node.target}"#{attrs.join}>#{breakable_uri node.text}</a>)
       # NOTE @media may not be initialized if method is called before convert phase
-      if ((@media ||= node.document.attr 'media', 'screen') != 'screen' || (node.document.attr? 'show-link-uri')) &&
-          !(node.has_role? 'bare')
-        # TODO allow style of visible link to be controlled by theme
-        %(<a href="#{target = node.target}"#{attrs.join}>#{node.text}</a> [<font size="0.85em">#{target}</font>])
+      elsif (@media ||= node.document.attr 'media', 'screen') != 'screen' || (node.document.attr? 'show-link-uri')
+        # QUESTION should we insert breakable chars into URI when building fragment instead?
+        # TODO allow style of printed link to be controlled by theme
+        %(<a href="#{target = node.target}"#{attrs.join}>#{node.text}</a> [<font size="0.85em">#{breakable_uri target}</font>])
       else
         %(<a href="#{node.target}"#{attrs.join}>#{node.text}</a>)
       end
@@ -1511,12 +1773,10 @@ class Converter < ::Prawn::Document
       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>)
+      %(<a name="#{node.target}">#{DummyText}</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}])
+      %(<a name="#{target = node.target}">#{DummyText}</a>[#{target}])
     else
       warn %(asciidoctor: WARNING: unknown anchor type: #{node.type.inspect})
     end
@@ -1581,12 +1841,13 @@ class Converter < ::Prawn::Document
     else
       node.extend ::Asciidoctor::Image unless ::Asciidoctor::Image === node
       target, image_format = node.target_and_format
-      if image_format == 'gif'
-        warn %(asciidoctor: WARNING: GIF image format not supported. Please convert #{target} to PNG.) unless scratch?
+      if image_format == 'gif' && !(defined? ::GMagick::Image)
+        warn %(asciidoctor: WARNING: GIF image format not supported. Install the prawn-gmagick gem or convert #{target} to PNG.) unless scratch?
         img = %([#{node.attr 'alt'}])
+      # NOTE an image with a data URI is handled using a temporary file
       elsif (image_path = resolve_image_path node, target, true, image_format) && (::File.readable? image_path)
-        width_attr = (node.attr? 'width', nil, false) ? %( width="#{node.attr 'width'}") : nil
-        img = %(<img src="#{image_path}" format="#{image_format}" alt="#{node.attr 'alt'}"#{width_attr} tmp="#{TemporaryPath === image_path}">)
+        width_attr = (width = preresolve_explicit_width node.attributes) ? %( width="#{width}") : nil
+        img = %(<img src="#{image_path}" format="#{image_format}" alt="[#{node.attr 'alt'}]"#{width_attr} tmp="#{TemporaryPath === image_path}">)
       else
         warn %(asciidoctor: WARNING: image to embed not found or not readable: #{image_path || target}) unless scratch?
         img = %([#{node.attr 'alt'}])
@@ -1596,7 +1857,24 @@ class Converter < ::Prawn::Document
   end
 
   def convert_inline_indexterm node
-    node.type == :visible ? node.text : nil
+    # NOTE indexterms not supported if text gets substituted before PDF is initialized
+    return '' unless instance_variable_defined? :@index
+    if scratch?
+      node.type == :visible ? node.text : ''
+    else
+      dest = {
+        anchor: (anchor_name = %(__indexterm-#{node.object_id}))
+        # NOTE page number is added in InlineDestinationMarker
+      }
+      anchor = %(<a name="#{anchor_name}" type="indexterm">#{DummyText}</a>)
+      if node.type == :visible
+        @index.store_primary_term(sanitize(visible_term = node.text), dest)
+        %(#{anchor}#{visible_term})
+      else
+        @index.store_term((node.attr 'terms').map {|term| sanitize term }, dest)
+        anchor
+      end
+    end
   end
 
   def convert_inline_kbd node
@@ -1651,7 +1929,7 @@ class Converter < ::Prawn::Document
     end
 
     # NOTE destination is created inside callback registered by FormattedTextTransform#build_fragment
-    node.id ? %(<a name="#{node.id}">#{ZeroWidthSpace}</a>#{quoted_text}) : quoted_text
+    node.id ? %(<a name="#{node.id}">#{DummyText}</a>#{quoted_text}) : quoted_text
   end
 
   # FIXME only create title page if doctype=book!
@@ -1676,8 +1954,8 @@ class Converter < ::Prawn::Document
     # 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
 
-    # QUESTION allow aligment per element on title page?
-    title_align = (@theme.title_page_align || @theme.base_align).to_sym
+    # QUESTION allow alignment per element on title page?
+    title_align = (@theme.title_page_align || @base_align).to_sym
 
     # TODO disallow .pdf as image type
     if (logo_image_path = (doc.attr 'title-logo-image', @theme.title_page_logo_image))
@@ -1703,14 +1981,12 @@ class Converter < ::Prawn::Document
       else
         logo_image_top = bounds.absolute_top - effective_page_height * logo_image_top.to_f / 100.0
       end
-      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
-        # QUESTION should we shave off margin top/bottom?
-        convert_image image_block, relative_to_imagesdir: relative_to_imagesdir
-      end
+      initial_y, @y = @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
+      # NOTE pinned option keeps image on same page
+      convert_image image_block, relative_to_imagesdir: relative_to_imagesdir, pinned: true
+      @y = initial_y
     end
 
     # TODO prevent content from spilling to next page
@@ -1745,20 +2021,23 @@ class Converter < ::Prawn::Document
       end
       if doc.attr? 'authors'
         move_down (@theme.title_page_authors_margin_top || 0)
+        # TODO provide an API in core to get authors as an array
+        authors = (1..(doc.attr 'authorcount', 1).to_i).map {|idx|
+          doc.attr(idx == 1 ? 'author' : %(author_#{idx}))
+        } * (@theme.title_page_authors_delimiter || ', ')
         theme_font :title_page_authors do
-          # TODO add support for author delimiter
-          layout_prose((doc.attr 'authors'),
+          layout_prose authors,
             align: title_align,
             margin: 0,
-            normalize: false)
+            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)
+        revision_text = revision_info * (@theme.title_page_revision_delimiter || ', ')
         theme_font :title_page_revision do
-          revision_text = revision_info * (@theme.title_page_revision_delimiter || ', ')
           layout_prose revision_text,
             align: title_align,
             margin: 0,
@@ -1813,14 +2092,14 @@ class Converter < ::Prawn::Document
   def layout_heading string, opts = {}
     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)
+    if (transform = (opts.delete :text_transform) || @text_transform) && transform != 'none'
       string = transform_text string, transform
     end
     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: @theme.base_align.to_sym
+      align: @base_align.to_sym
     }.merge(opts)
     margin_bottom bot_margin
   end
@@ -1829,24 +2108,19 @@ class Converter < ::Prawn::Document
   def layout_prose string, opts = {}
     top_margin = (margin = (opts.delete :margin)) || (opts.delete :margin_top) || @theme.prose_margin_top
     bot_margin = margin || (opts.delete :margin_bottom) || @theme.prose_margin_bottom
-    if (transform = (opts.delete :text_transform) || @text_transform)
+    if (transform = (opts.delete :text_transform) || @text_transform) && transform != 'none'
       string = transform_text string, transform
     end
+    # NOTE used by extensions; ensures linked text gets formatted using the link styles
     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)
-        # 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 = %(<a anchor="#{anchor}">#{string}</a>)
-      end
+      string = %(<a anchor="#{anchor}">#{string}</a>)
     end
     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.to_sym
+      align: @base_align.to_sym
     }.merge(opts)
     margin_bottom bot_margin
   end
@@ -1873,7 +2147,7 @@ class Converter < ::Prawn::Document
       layout_prose string, {
         margin_top: margin[:top],
         margin_bottom: margin[:bottom],
-        align: (@theme.caption_align || @theme.base_align).to_sym,
+        align: (@theme.caption_align || @base_align).to_sym,
         normalize: false
       }.merge(opts)
       if side == :top && @theme.caption_border_bottom_color
@@ -1907,17 +2181,33 @@ class Converter < ::Prawn::Document
     go_to_page toc_page_number unless (page_number == toc_page_number) || scratch?
     start_page_number = page_number
     theme_font :heading, level: 2 do
-      layout_heading((doc.attr 'toc-title'), align: (@theme.toc_title_align || @theme.base_align).to_sym)
+      theme_font :toc_title do
+        toc_title_align = (@theme.toc_title_align || @theme.heading_h2_align || @theme.heading_align || @base_align).to_sym
+        layout_heading((doc.attr 'toc-title'), align: toc_title_align)
+      end
     end
-    # QUESTION shouldn't we skip this whole method if num_levels == 0?
+    # QUESTION should 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
-      dot_width = nil
-      theme_font :toc do
-        dot_width = width_of(@theme.toc_dot_leader_content || DotLeaderDefault)
+      dot_leader = theme_font :toc do
+        # TODO we could simplify by using nested theme_font :toc_dot_leader
+        if (dot_leader_font_style = (@theme.toc_dot_leader_font_style || :normal).to_sym) != font_style
+          font_style dot_leader_font_style
+        end
+        {
+          font_color: @theme.toc_dot_leader_font_color || @font_color,
+          font_style: dot_leader_font_style,
+          levels: ((dot_leader_l = @theme.toc_dot_leader_levels) == 'none' ? ::Set.new :
+              (dot_leader_l && dot_leader_l != 'all' ? dot_leader_l.to_s.split.map(&:to_i).to_set : (1..num_levels).to_set)),
+          text: (dot_leader_text = @theme.toc_dot_leader_content || DotLeaderTextDefault),
+          width: dot_leader_text.empty? ? 0 : (width_of dot_leader_text),
+          # TODO spacer gives a little bit of room between dots and page number
+          spacer: { text: NoBreakSpace, size: (spacer_font_size = @font_size * 0.25) },
+          spacer_width: (width_of NoBreakSpace, size: spacer_font_size)
+        }
       end
-      layout_toc_level doc.sections, num_levels, line_metrics, dot_width, num_front_matter_pages
+      line_metrics = calc_line_metrics @theme.toc_line_height
+      theme_margin :toc, :top
+      layout_toc_level doc.sections, num_levels, line_metrics, dot_leader, num_front_matter_pages
     end
     # NOTE range must be calculated relative to toc_page_number; absolute page number in scratch document is arbitrary
     toc_page_numbers = (toc_page_number..(toc_page_number + (page_number - start_page_number)))
@@ -1925,51 +2215,75 @@ class Converter < ::Prawn::Document
     toc_page_numbers
   end
 
-  def layout_toc_level sections, num_levels, line_metrics, dot_width, num_front_matter_pages = 0
-    toc_dot_color = @theme.toc_dot_leader_font_color || @theme.toc_font_color || @font_color
+  def layout_toc_level sections, num_levels, line_metrics, dot_leader, num_front_matter_pages = 0
+    # NOTE font options aren't always reliable, so store size separately
+    toc_font_info = theme_font :toc do
+      { font: font, size: @font_size }
+    end
     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
-        # 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 'pdf-anchor'}"><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?
+        sect_title = (transform = @text_transform) && transform != 'none' ?
+            (transform_text sect.numbered_title, transform) : sect.numbered_title
+        # NOTE only write section title (excluding dots and page number) if this is a dry run
+        if scratch?
+          # FIXME use layout_prose
+          # NOTE must wrap title in empty anchor element in case links are styled with different font family / size
+          typeset_text %(<a>#{sect_title}</a>), line_metrics, inline_format: true
+        else
+          pgnum_label = ((sect.attr 'pdf-page-start') - num_front_matter_pages).to_s
+          start_page_number = page_number
+          start_cursor = cursor
+          # NOTE use low-level text formatter to add anchor overlay without styling text as link & force color
+          sect_title_format_override = {
+            anchor: (sect_anchor = sect.attr 'pdf-anchor'),
+            color: @font_color,
+            styles: ((@theme[%(toc_h#{sect.level + 1}_text_decoration)] || @theme.toc_text_decoration) == 'underline' ?
+                (font_styles << :underline) : font_styles)
+          }
+          (sect_title_fragments = text_formatter.format sect_title).each do |fragment|
+            fragment.update sect_title_format_override do |key, old_val, new_val|
+              key == :styles ? (old_val.merge new_val) : new_val
+            end
+          end
+          typeset_formatted_text sect_title_fragments, line_metrics
           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_pgnum_label = (sect.attr 'pdf-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_pgnum_label}), 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 },
-            # FIXME this spacing doesn't always work out; should we use graphics instead?
-            { text: NoBreakSpace, size: (@font_size * 0.5) },
-            { text: sect_pgnum_label.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
+          if dot_leader[:width] > 0 && (dot_leader[:levels].include? sect.level)
+            pgnum_label_font_settings = { color: @font_color, font: font_family, size: @font_size, styles: font_styles }
+            pgnum_label_width = width_of pgnum_label
+            sect_title_width = width_of sect_title, inline_format: true
+            save_font do
+              # NOTE the same font is used for dot leaders throughout toc
+              set_font toc_font_info[:font], toc_font_info[:size]
+              font_style dot_leader[:font_style]
+              num_dots = ((bounds.width - sect_title_width - dot_leader[:spacer_width] - pgnum_label_width) / dot_leader[:width]).floor
+              # FIXME dots don't line up in columns if width of page numbers differ
+              typeset_formatted_text [
+                  { text: (dot_leader[:text] * (num_dots < 0 ? 0 : num_dots)), color: dot_leader[:font_color] },
+                  dot_leader[:spacer],
+                  { text: pgnum_label, anchor: sect_anchor }.merge(pgnum_label_font_settings)
+                ], line_metrics, align: :right
+            end
+          else
+            typeset_formatted_text [{ text: pgnum_label, color: @font_color, anchor: sect_anchor }], line_metrics, align: :right
+          end
+          go_to_page end_page_number if page_number != end_page_number
           move_cursor_to end_cursor
         end
       end
-      if sect.level < num_levels
-        indent @theme.toc_indent do
-          layout_toc_level sect.sections, num_levels, line_metrics, dot_width, num_front_matter_pages
-        end
-      end
+      indent @theme.toc_indent do
+        layout_toc_level sect.sections, num_levels, line_metrics, dot_leader, num_front_matter_pages
+      end if sect.level < num_levels
     end
   end
 
-  # Reduce icon size to fit inside bounds.height. Icons will not render
+  # Reduce icon height to fit inside bounds.height. Icons will not render
   # properly if they are larger than the current bounds.height.
-  def fit_icon_size node, max_size = 24
-    (min_height = bounds.height.floor) < max_size ? min_height : max_size
+  def fit_icon_to_bounds preferred_size = 24
+    (max_height = bounds.height) < preferred_size ? max_height : preferred_size
   end
 
   def admonition_icon_data key
@@ -1985,37 +2299,76 @@ class Converter < ::Prawn::Document
     # QUESTION should we short-circuit if setting not specified and if so, which setting?
     return unless (periphery == :header && @theme.header_height) || (periphery == :footer && @theme.footer_height)
     skip = opts[:skip] || 1
-    start = skip + 1
+    # NOTE find and advance to first non-imported content page to use as model page
+    return unless (content_start_page = state.pages[skip..-1].index {|p| !p.imported_page? })
+    content_start_page += (skip + 1)
     num_pages = page_count - skip
+    prev_page_number = page_number
+    go_to_page content_start_page
 
     # 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
+    is_book = doc.doctype == 'book'
+    header = doc.header? ? doc.header : nil
+    # TODO make this section threshold configurable (perhaps in theme?)
+    sections = doc.find_by(context: :section) {|sect| sect.level < 3 && sect != header } || []
+
+    # FIXME we need a proper model for all this page counting
+    # FIXME we make a big assumption that part & chapter start on new pages
+    # index parts, chapters and sections by the visual page number on which they start
+    part_start_pages = {}
     chapter_start_pages = {}
     section_start_pages = {}
+    trailing_section_start_pages = {}
     sections.each do |sect|
-      if sect.chapter?
-        chapter_start_pages[(sect.attr 'pdf-page-start').to_i - skip] ||= (sect.numbered_title formal: true)
+      page_num = (sect.attr 'pdf-page-start').to_i - skip
+      if is_book && ((sect_is_part = sect.part?) || sect.chapter?)
+        if sect_is_part
+          part_start_pages[page_num] ||= (sect.numbered_title formal: true)
+        else
+          chapter_start_pages[page_num] ||= (sect.numbered_title formal: true)
+          if sect.sectname == 'appendix' && !part_start_pages.empty?
+            # FIXME need a better way to indicate that part has ended
+            part_start_pages[page_num] = ''
+          end
+        end
       else
-        section_start_pages[(sect.attr 'pdf-page-start').to_i - skip] ||= (sect.numbered_title formal: true)
+        sect_title = trailing_section_start_pages[page_num] = sect.numbered_title formal: true
+        section_start_pages[page_num] ||= sect_title
       end
     end
 
-    # index chapters and sections by the visual page number on which they appear
+    # index parts, chapters, and sections by the visual page number on which they appear
+    parts_by_page = {}
     chapters_by_page = {}
     sections_by_page = {}
-    last_chap = (doc.attr 'preface-title') || 'Preface'
+    # QUESTION should the default part be the doctitle?
+    last_part = nil
+    # QUESTION should we enforce that the preamble is preface?
+    last_chap = is_book ? (doc.attr 'preface-title', 'Preface') : nil
     last_sect = nil
+    sect_search_threshold = 1
     (1..num_pages).each do |num|
+      if (part = part_start_pages[num])
+        last_part = part
+      end
       if (chap = chapter_start_pages[num])
         last_chap = chap
       end
       if (sect = section_start_pages[num])
         last_sect = sect
-      elsif chap
+      elsif part || chap
+        sect_search_threshold = num
         last_sect = nil
+      # NOTE we didn't find a section on this page; look back to find last section started
+      elsif last_sect
+        ((sect_search_threshold)..(num - 1)).reverse_each do |prev|
+          if (sect = trailing_section_start_pages[prev])
+            last_sect = sect
+            break
+          end
+        end
       end
+      parts_by_page[num] = last_part
       chapters_by_page[num] = last_chap
       sections_by_page[num] = last_sect
     end
@@ -2026,35 +2379,8 @@ class Converter < ::Prawn::Document
     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 = PageSides.inject({}) do |acc, side|
-      side_content = {}
-      ColumnPositions.each do |position|
-        if (val = @theme[%(#{periphery}_#{side}_#{position}_content)])
-          # TODO support image URL (using resolve_image_path)
-          if (val.include? ':') && val =~ ImageAttributeValueRx &&
-              ::File.readable?(path = (ThemeLoader.resolve_theme_asset $1, (doc.attr 'pdf-stylesdir')))
-            attrs = (AttributeList.new $2).parse
-            width = resolve_explicit_width attrs, bounds.width
-            # QUESTION should we lookup and scale intrinsic width if explicit width is not given?
-            unless width
-              width = [bounds.width, (intrinsic_image_dimensions path)[:width] * 0.75].min
-            end
-            side_content[position] = { path: path, width: width }
-          else
-            side_content[position] = val
-          end
-        end
-      end
-      # NOTE set fallbacks if not explicitly disabled
-      if side_content.empty? && periphery == :footer && @theme[%(footer_#{side}_content)] != 'none'
-        side_content = { side == :recto ? :right : :left => '{page-number}' }
-      end
-
-      acc[side] = side_content
-      acc
-    end
+    allow_uri_read = doc.attr? 'allow-uri-read'
+    svg_fallback_font = default_svg_font
 
     if periphery == :header
       trim_line_metrics = calc_line_metrics(@theme.header_line_height || @theme.base_line_height)
@@ -2115,26 +2441,29 @@ class Converter < ::Prawn::Document
 
     colspec_dict = PageSides.inject({}) do |acc, side|
       side_trim_content_width = trim_content_width[side]
-      if (custom_colspecs = @theme[%(#{periphery}_#{side}_columns)])
-        colspecs = %w(<40% =20% >40%)
-        (custom_colspecs.tr ',', ' ').split[0..2].each_with_index {|c, idx| colspecs[idx] = c }
-        colspecs = { left: colspecs[0], center: colspecs[1], right: colspecs[2] }
-        cml_width = 0
+      if (custom_colspecs = @theme[%(#{periphery}_#{side}_columns)] || @theme[%(#{periphery}_columns)])
+        case (colspecs = (custom_colspecs.to_s.tr ',', ' ').split[0..2]).size
+        when 3
+          colspecs = { left: colspecs[0], center: colspecs[1], right: colspecs[2] }
+        when 2
+          colspecs = { left: colspecs[0], center: '0', right: colspecs[1] }
+        when 0, 1
+          colspecs = { left: '0', center: colspecs[0] || '100', right: '0' }
+        end
+        tot_width = 0
         side_colspecs = colspecs.map {|col, spec|
           if (alignment_char = spec.chr).to_i.to_s != alignment_char
             alignment = AlignmentTable[alignment_char] || :left
-            pcwidth = spec[1..-1].to_f
+            rel_width = spec[1..-1].to_f
           else
             alignment = :left
-            pcwidth = spec.to_f
+            rel_width = spec.to_f
           end
-          # QUESTION should we allow the columns to overlap (capping width at 100%)?
-          if (w = side_trim_content_width * (pcwidth / 100.0)) + cml_width > side_trim_content_width
-            w = side_trim_content_width - cml_width
-          end
-          cml_width += w
-          [col, { align: alignment, width: w, x: 0 }]
+          tot_width += rel_width
+          [col, { align: alignment, width: rel_width, x: 0 }]
         }.to_h
+        # QUESTION should we allow the columns to overlap (capping width at 100%)?
+        side_colspecs.each {|_, colspec| colspec[:width] = (colspec[:width] / tot_width) * side_trim_content_width }
         side_colspecs[:right][:x] = (side_colspecs[:center][:x] = side_colspecs[:left][:width]) + side_colspecs[:center][:width]
         acc[side] = side_colspecs
       else
@@ -2147,11 +2476,43 @@ class Converter < ::Prawn::Document
       acc
     end
 
+    # TODO move this to a method so it can be reused; cache results
+    content_dict = PageSides.inject({}) do |acc, side|
+      side_content = {}
+      ColumnPositions.each do |position|
+        unless (val = @theme[%(#{periphery}_#{side}_#{position}_content)]).nil_or_empty?
+          # TODO support image URL (using resolve_image_path)
+          if (val.include? ':') && val =~ ImageAttributeValueRx &&
+              ::File.readable?(path = (ThemeLoader.resolve_theme_asset $1, (doc.attr 'pdf-stylesdir')))
+            attrs = (AttributeList.new $2).parse
+            col_width = colspec_dict[side][position][:width]
+            if (fit = attrs['fit']) == 'contain'
+              width = col_width
+            else
+              unless (width = resolve_explicit_width attrs, col_width)
+                # QUESTION should we lookup and scale intrinsic width if explicit width is not given?
+                # NOTE failure message will be reported later when image is rendered
+                width = (to_pt intrinsic_image_dimensions(path)[:width], :px) rescue 0
+              end
+              width = col_width if fit == 'scale-down' && width > col_width
+            end
+            side_content[position] = { path: path, width: width, fit: !!fit }
+          else
+            side_content[position] = val
+          end
+        end
+      end
+      # NOTE set fallbacks if not explicitly disabled
+      if side_content.empty? && periphery == :footer && @theme[%(footer_#{side}_content)] != 'none'
+        side_content = { side == :recto ? :right : :left => '{page-number}' }
+      end
+
+      acc[side] = side_content
+      acc
+    end
+
     stamps = {}
     if trim_bg_color || trim_border_color
-      # NOTE switch to first content page so stamp will get created properly (can't create on imported page)
-      prev_page_number = page_number
-      go_to_page start
       PageSides.each do |side|
         create_stamp trim_stamp_name[side] do
           canvas do
@@ -2175,12 +2536,11 @@ class Converter < ::Prawn::Document
         end
       end
       stamps[periphery] = true
-      go_to_page prev_page_number
     end
 
     pagenums_enabled = doc.attr? 'pagenums'
     attribute_missing_doc = doc.attr 'attribute-missing'
-    repeat (start..page_count), dynamic: true do
+    repeat (content_start_page..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?
       pgnum_label = page_number - skip
@@ -2191,8 +2551,9 @@ class Converter < ::Prawn::Document
       colspec_by_position = colspec_dict[side]
       # TODO populate chapter-number
       # TODO populate numbered and unnumbered chapter and section titles
-      # FIXME leave page-number attribute unset once we filter lines with unresolved attributes (see below)
-      doc.set_attr 'page-number', (pagenums_enabled ? pgnum_label : '')
+      doc.set_attr 'page-number', pgnum_label.to_s if pagenums_enabled
+      # QUESTION should the fallback value be nil instead of empty string? or should we remove attribute if no value?
+      doc.set_attr 'part-title', (parts_by_page[pgnum_label] || '')
       doc.set_attr 'chapter-title', (chapters_by_page[pgnum_label] || '')
       doc.set_attr 'section-title', (sections_by_page[pgnum_label] || '')
       doc.set_attr 'section-or-chapter-title', (sections_by_page[pgnum_label] || chapters_by_page[pgnum_label] || '')
@@ -2214,12 +2575,37 @@ class Converter < ::Prawn::Document
                 float do
                   # NOTE bounding_box is redundant if trim_v_padding is 0
                   bounding_box [colspec[:x], cursor - trim_padding[0]], width: colspec[:width], height: (bounds.height - trim_v_padding) do
-                    #image content[:path], vposition: trim_img_valign, position: colspec[:align], width: content[:width]
-                    # NOTE use :fit to prevent image from overflowing page (at the cost of scaling it)
-                    image content[:path], vposition: trim_img_valign, position: colspec[:align], fit: [content[:width], bounds.height]
+                    begin
+                      if (img_path = content[:path]).downcase.end_with? '.svg'
+                        svg_data = ::IO.read img_path
+                        svg_obj = ::Prawn::Svg::Interface.new svg_data, self,
+                            position: colspec[:align],
+                            vposition: trim_img_valign,
+                            width: content[:width],
+                            # TODO enforce jail in safe mode
+                            enable_file_requests_with_root: (::File.dirname img_path),
+                            enable_web_requests: allow_uri_read,
+                            fallback_font_name: svg_fallback_font
+                        if content[:fit] && svg_obj.document.sizing.output_height > (available_h = bounds.height)
+                          svg_obj.resize height: available_h
+                        end
+                        svg_obj.draw
+                      else
+                        img_opts = { position: colspec[:align], vposition: trim_img_valign }
+                        if content[:fit]
+                          img_opts[:fit] = [content[:width], bounds.height]
+                        else
+                          img_opts[:width] = content[:width]
+                        end
+                        image img_path, img_opts
+                      end
+                    rescue => e
+                      warn %(asciidoctor: WARNING: could not embed image in running content: #{img_path}; #{e.message})
+                    end
                   end
                 end
               when ::String
+                # NOTE minor optimization
                 if content == '{page-number}'
                   content = pagenums_enabled ? pgnum_label.to_s : nil
                 else
@@ -2248,19 +2634,23 @@ class Converter < ::Prawn::Document
         end
       end
     end
+
+    go_to_page prev_page_number
     nil
   end
 
   def add_outline doc, num_levels = 2, toc_page_nums = [], num_front_matter_pages = 0
     front_matter_counter = RomanNumeral.new 0, :lower
-    page_num_labels = {}
+    pagenum_labels = {}
 
-    num_front_matter_pages.times do
-      page_num_labels[front_matter_counter.to_i] = { P: ::PDF::Core::LiteralString.new(front_matter_counter.next!.to_s) }
+    num_front_matter_pages.times do |n|
+      pagenum_labels[n] = { P: (::PDF::Core::LiteralString.new front_matter_counter.next!.to_s) }
     end
 
-    # placeholder for first page of content, in case it's not the destination of an outline entry
-    page_num_labels[front_matter_counter.to_i] = { P: ::PDF::Core::LiteralString.new('1') }
+    # add labels for each content page, which is required for reader's page navigator to work correctly
+    (num_front_matter_pages..(page_count - 1)).each_with_index do |n, i|
+      pagenum_labels[n] = { P: (::PDF::Core::LiteralString.new %(#{i + 1})) }
+    end
 
     outline.define do
       # FIXME use sanitize: :plain_text once available
@@ -2270,26 +2660,24 @@ class Converter < ::Prawn::Document
       end
       page title: (doc.attr 'toc-title'), destination: (document.dest_top toc_page_nums.first) if toc_page_nums.first
       # QUESTION any way to get add_outline_level to invoke in the context of the outline?
-      document.add_outline_level self, doc.sections, num_levels, page_num_labels, num_front_matter_pages
+      document.add_outline_level self, doc.sections, num_levels
     end
 
-    catalog.data[:PageLabels] = state.store.ref Nums: page_num_labels.flatten
+    catalog.data[:PageLabels] = state.store.ref Nums: pagenum_labels.flatten
     catalog.data[:PageMode] = :UseOutlines
     nil
   end
 
-  # TODO only nest inside root node if doctype=article
-  def add_outline_level outline, sections, num_levels, page_num_labels, num_front_matter_pages
+  # FIXME only nest inside root node if doctype=article
+  def add_outline_level outline, sections, num_levels
     sections.each do |sect|
       sect_title = sanitize sect.numbered_title formal: true
       sect_destination = sect.attr 'pdf-destination'
-      sect_pgnum_label = (sect_pgnum = sect.attr 'pdf-page-start') - num_front_matter_pages
-      page_num_labels[sect_pgnum - 1] = { P: ::PDF::Core::LiteralString.new(sect_pgnum_label.to_s) }
       if (subsections = sect.sections).empty? || sect.level == num_levels
         outline.page title: sect_title, destination: sect_destination
       elsif sect.level < num_levels + 1
         outline.section sect_title, { destination: sect_destination } do
-          add_outline_level outline, subsections, num_levels, page_num_labels, num_front_matter_pages
+          add_outline_level outline, subsections, num_levels
         end
       end
     end
@@ -2303,7 +2691,7 @@ class Converter < ::Prawn::Document
     else
       pdf_doc.render_file target
       # QUESTION restore attributes first?
-      @pdfmarks.generate_file target if @pdfmarks
+      @pdfmark.generate_file target if @pdfmark
     end
     # write scratch document if debug is enabled (or perhaps DEBUG_STEPS env)
     #get_scratch_document.render_file 'scratch.pdf'
@@ -2311,8 +2699,8 @@ class Converter < ::Prawn::Document
   end
 
   def register_fonts font_catalog, scripts = 'latin', fonts_dir
-    (font_catalog || {}).each do |key, font_styles|
-      register_font key => font_styles.map {|style, path| [style.to_sym, (font_path path, fonts_dir)]}.to_h
+    (font_catalog || {}).each do |key, styles|
+      register_font key => styles.map {|style, path| [style.to_sym, (font_path path, fonts_dir)]}.to_h
     end
 
     # FIXME read kerning setting from theme!
@@ -2338,34 +2726,35 @@ class Converter < ::Prawn::Document
     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)],
-      radius: @theme[%(#{category}_border_radius)]
+  def theme_fill_and_stroke_bounds category, opts = {}
+    background_color = opts[:background_color] || @theme[%(#{category}_background_color)]
+    fill_and_stroke_bounds 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.
-  # Start a new page if y value is greater than remaining space on page.
-  def margin_top y
-    margin y, :top
+  # Start a new page if n value is greater than remaining space on page.
+  def margin_top n
+    margin n, :top
   end
 
   # Insert a bottom margin space unless cursor is at the top of the page (not likely).
-  # Start a new page if y value is greater than remaining space on page.
-  def margin_bottom y
-    margin y, :bottom
+  # Start a new page if n value is greater than remaining space on page.
+  def margin_bottom n
+    margin n, :bottom
   end
 
   # Insert a margin space at the specified side unless cursor is at the top of the page.
-  # Start a new page if y value is greater than remaining space on page.
-  def margin y, side
-    unless y == 0 || at_page_top?
-      if cursor > y
-        move_down y
+  # Start a new page if n value is greater than remaining space on page.
+  def margin n, side
+    unless n == 0 || at_page_top?
+      # NOTE use low-level cursor calculation to workaround cursor bug in column_box context
+      if y - reference_bounds.absolute_bottom > n
+        move_down n
       else
-        # go to the next page
-        # NOTE we don't use `move_down cursor` because we often have to check at_page_top?
-        @margin_box.move_past_bottom
+        # set cursor at top of next page
+        reference_bounds.move_past_bottom
       end
     end
   end
@@ -2379,6 +2768,8 @@ class Converter < ::Prawn::Document
   end
 
   def theme_font category, opts = {}
+    result = nil
+    # TODO inheriting from generic category should be an option
     if (level = opts[:level])
       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
@@ -2400,11 +2791,12 @@ class Converter < ::Prawn::Document
     prev_transform, @text_transform = @text_transform, transform if transform
 
     font family, size: size, style: (style && style.to_sym) do
-      yield
+      result = yield
     end
 
     @font_color = prev_color if color
     @text_transform = prev_transform if transform
+    result
   end
 
   # Calculate the font size (down to the minimum font size) that would allow
@@ -2414,24 +2806,26 @@ class Converter < ::Prawn::Document
   # 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 & calculates their widths using the current font settings
       # CAUTION it also removes zero-width spaces
       arranger.finalize_line
       actual_width = width_of_fragments arranger.fragments
       unless ::Array === (padding = @theme[%(#{category}_padding)])
-        padding = [padding] * 4
+        padding = ::Array.new 4, padding
       end
       available_width = bounds.width - (padding[3] || 0) - (padding[1] || 0)
       if actual_width > available_width
-        adjusted_font_size = ((available_width * font_size).to_f / actual_width).with_precision 4
+        adjusted_font_size = ((available_width * font_size).to_f / actual_width).truncate_to_precision 4
         if (min = @theme[%(#{category}_font_size_min)] || @theme.base_font_size_min) && adjusted_font_size < min
-          adjusted_font_size = min
+          min
+        else
+          adjusted_font_size
         end
+      else
+        nil
       end
     end
-    adjusted_font_size
   end
 
   # Arrange fragments by line in an arranger and return an unfinalized arranger.
@@ -2558,7 +2952,7 @@ class Converter < ::Prawn::Document
   # If value is nil, derive an anchor name from the default_value, if given.
   def derive_anchor_from_id value, default_value = nil
     if value
-      value.ascii_only? ? value : %(0x#{::PDF::Core.string_to_hex value}) 
+      value.ascii_only? ? value : %(0x#{::PDF::Core.string_to_hex value})
     elsif default_value
       %(__anchor-#{default_value})
     end
@@ -2570,18 +2964,16 @@ class Converter < ::Prawn::Document
   # 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
+  # page, set the y position equal to the page height to improve the navigation
+  # experience. If the current x position is at or inside the left margin, set
+  # the x position equal to 0 (left edge of page) 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 = bounds.absolute_left.truncate_to_precision 4
+      # QUESTION when content is aligned to left margin, should we keep precise x value or just use 0?
       dest_x = 0 if dest_x <= page_margin_left
-      dest_y = if at_page_top? && (node.context == :section || node.context == :document)
-        page_height
-      else
-        y
-      end
+      dest_y = at_page_top? && (node.context == :section || node.context == :document) ? page_height : y
       # 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
@@ -2600,10 +2992,10 @@ class Converter < ::Prawn::Document
 
   # 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.
+  # Resolve and normalize the absolute system path of the specified image. If
+  # the image_path argument is not specified, the path is read from the target
+  # attribute of the specified document node. Resolve the path relative to the
+  # imagesdir if the relative_to_imagesdir option is specified (default: true).
   #
   # 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
@@ -2616,8 +3008,20 @@ class Converter < ::Prawn::Document
     imagesdir = relative_to_imagesdir ? (resolve_imagesdir doc) : nil
     image_path ||= node.attr 'target'
     image_format ||= ::Asciidoctor::Image.format image_path, (::Asciidoctor::Image === node ? node : nil)
+    # NOTE currently used for inline images
+    if ::Base64 === image_path
+      tmp_image = ::Tempfile.new ['image-', image_format && %(.#{image_format})]
+      tmp_image.binmode unless image_format == 'svg'
+      begin
+        tmp_image.write(::Base64.decode64 image_path)
+        tmp_image.path.extend TemporaryPath
+      rescue
+        nil
+      ensure
+        tmp_image.close
+      end
     # handle case when image is a URI
-    if (node.is_uri? image_path) || (imagesdir && (node.is_uri? imagesdir) &&
+    elsif (node.is_uri? image_path) || (imagesdir && (node.is_uri? imagesdir) &&
         (image_path = (node.normalize_web_path image_path, imagesdir, false)))
       unless doc.attr? 'allow-uri-read'
         warn %(asciidoctor: WARNING: allow-uri-read is not enabled; cannot embed remote image: #{image_path}) unless scratch?
@@ -2631,15 +3035,13 @@ class Converter < ::Prawn::Document
       tmp_image = ::Tempfile.new ['image-', image_format && %(.#{image_format})]
       tmp_image.binmode if (binary = image_format != 'svg')
       begin
-        open(image_path, (binary ? 'rb' : 'r')) {|fd| tmp_image.write(fd.read) }
-        tmp_image_path = tmp_image.path
-        tmp_image_path.extend TemporaryPath
+        open(image_path, (binary ? 'rb' : 'r')) {|fd| tmp_image.write fd.read }
+        tmp_image.path.extend TemporaryPath
       rescue
-        tmp_image_path = nil
+        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')
@@ -2676,6 +3078,22 @@ class Converter < ::Prawn::Document
     end
   end
 
+  # Resolves the explicit width as a PDF pt value if the value is specified in
+  # absolute units, but defers resolving a percentage value until later.
+  #
+  # See resolve_explicit_width method for details about which attributes are considered.
+  def preresolve_explicit_width attrs
+    if attrs.key? 'pdfwidth'
+      ((width = attrs['pdfwidth']).end_with? '%') ? width : (str_to_pt width)
+    elsif attrs.key? 'scaledwidth'
+      # NOTE the parser automatically appends % if value is unitless
+      ((width = attrs['scaledwidth']).end_with? '%') ? width : (str_to_pt width)
+    elsif attrs.key? 'width'
+      # QUESTION should we honor percentage width value?
+      to_pt attrs['width'].to_f, :px
+    end
+  end
+
   # Resolves the explicit width as a PDF pt value, if specified.
   #
   # Resolves the explicit width, first considering the pdfwidth attribute, then
@@ -2686,6 +3104,7 @@ class Converter < ::Prawn::Document
   #--
   # QUESTION should we enforce positive result?
   def resolve_explicit_width attrs, max_width = bounds.width, opts = {}
+    # QUESTION should we restrict width to max_width for pdfwidth?
     if attrs.key? 'pdfwidth'
       if (width = attrs['pdfwidth']).end_with? '%'
         (width.to_f / 100) * max_width
@@ -2695,7 +3114,12 @@ class Converter < ::Prawn::Document
         str_to_pt width
       end
     elsif attrs.key? 'scaledwidth'
-      (attrs['scaledwidth'].to_f / 100) * max_width
+      # NOTE the parser automatically appends % if value is unitless
+      if (width = attrs['scaledwidth']).end_with? '%'
+        (width.to_f / 100) * max_width
+      else
+        str_to_pt width
+      end
     elsif opts[:use_fallback] && (width = @theme.image_width)
       if width.end_with? '%'
         (width.to_f / 100) * max_width
@@ -2706,8 +3130,7 @@ class Converter < ::Prawn::Document
       end
     elsif attrs.key? 'width'
       # QUESTION should we honor percentage width value?
-      # NOTE scale width down 75% to convert px to pt; restrict width to max width
-      [max_width, attrs['width'].to_f * 0.75].min
+      [max_width, (to_pt attrs['width'].to_f, :px)].min
     end
   end
 
@@ -2721,6 +3144,15 @@ class Converter < ::Prawn::Document
     warn %(asciidoctor: WARNING: could not delete temporary image: #{path}; #{e.message})
   end
 
+  # NOTE assume URL is escaped (i.e., contains character references such as &amp;)
+  def breakable_uri uri
+    scheme, address = uri.split UriSchemeBoundaryRx, 2
+    address, scheme = scheme, address unless address
+    address = address.gsub UriBreakCharsRx, UriBreakCharRepl
+    address.slice!(-2) if address[-2] == ZeroWidthSpace
+    %(#{scheme}#{address})
+  end
+
   # QUESTION move to prawn/extensions.rb?
   def init_scratch_prototype
     # IMPORTANT don't set font before using Marshal, it causes serialization to fail