asciidoctor-pdf 1.5.0.alpha.18 → 1.5.0.beta.1

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

@@ -3,13 +3,13 @@ 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]
+    def format path, attributes = nil
+      (attributes && attributes['format']) || ((ext = ::File.extname path).downcase.slice 1, ext.length)
     end
   end
 
   def format
-    (attr 'format', nil, false) || ::File.extname(inline? ? target : (attr 'target')).downcase[1..-1]
+    (attr 'format', nil, false) || ((ext = ::File.extname(inline? ? target : (attr 'target'))).downcase.slice 1, ext.length)
   end
 
   def target_and_format
@@ -17,7 +17,7 @@ module Image
     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]]
+      [image_path, (attr 'format', nil, false) || ((ext = ::File.extname image_path).downcase.slice 1, ext.length)]
     end
   end
 end

data/lib/asciidoctor-pdf/converter.rb

@@ -57,6 +57,7 @@ class Converter < ::Prawn::Document
   ColumnPositions = [:left, :center, :right]
   PageLayouts = [:portrait, :landscape]
   PageSides = [:recto, :verso]
+  (PDFVersions = { '1.3' => 1.3, '1.4' => 1.4, '1.5' => 1.5, '1.6' => 1.6, '1.7' => 1.7 }).default = 1.4
   LF = %(\n)
   DoubleLF = %(\n\n)
   TAB = %(\t)
@@ -96,7 +97,7 @@ class Converter < ::Prawn::Document
   UriBreakCharRepl = %(\\&#{ZeroWidthSpace})
   UriSchemeBoundaryRx = /(?<=:\/\/)/
   LineScanRx = /\n|.+/
-  BlankLineRx = /\n[[:blank:]]*\n/
+  BlankLineRx = /\n{2,}/
   WhitespaceChars = %( \t\n)
   SourceHighlighters = ['coderay', 'pygments', 'rouge'].to_set
   PygmentsBgColorRx = /^\.highlight +{ *background: *#([^;]+);/
@@ -182,16 +183,14 @@ class Converter < ::Prawn::Document
         set_page_margin next_page_margin
       end
       # TODO implement as a watermark (on top)
-      if @page_bg_image
-        # FIXME implement fitting and centering for SVG
-        # TODO implement image scaling (numeric value or "fit")
-        canvas { image @page_bg_image, position: :center, fit: [bounds.width, bounds.height] }
+      if (bg_image = @page_bg_image[page_side])
+        canvas { image bg_image[0], ({ position: :center, vposition: :center }.merge bg_image[1]) }
       elsif @page_bg_color && @page_bg_color != 'FFFFFF'
         fill_absolute_bounds @page_bg_color
       end
     end if respond_to? :on_page_create
 
-    layout_cover_page :front, doc
+    layout_cover_page doc, :front
     if (insert_title_page = doc.doctype == 'book' || (doc.attr? 'title-page'))
       layout_title_page doc
       # NOTE a new page will already be started if the cover image is a PDF
@@ -291,7 +290,7 @@ class Converter < ::Prawn::Document
     catalog.data[:OpenAction] = dest_fit_horizontally((page_height + 1), state.pages[0]) if state.pages.size > 0
     catalog.data[:ViewerPreferences] = { DisplayDocTitle: true }
 
-    layout_cover_page :back, doc
+    layout_cover_page doc, :back
     nil
   end
 
@@ -302,11 +301,12 @@ class Converter < ::Prawn::Document
 
   # TODO only allow method to be called once (or we need a reset)
   def init_pdf doc
-    theme = load_theme doc
-    pdf_opts = build_pdf_options doc, theme
-    # QUESTION should page options be preserved (otherwise, not readily available)
+    @allow_uri_read = doc.attr? 'allow-uri-read'
+    pdf_opts = build_pdf_options doc, (theme = load_theme doc)
+    # QUESTION should page options be preserved? (otherwise, not readily available)
     #@page_opts = { size: pdf_opts[:page_size], layout: pdf_opts[:page_layout] }
     ::Prawn::Document.instance_method(:initialize).bind(self).call pdf_opts
+    renderer.min_version PDFVersions[doc.attr 'pdf-version']
     @page_margin_by_side = { recto: page_margin, verso: page_margin }
     if (@media = doc.attr 'media', 'screen') == 'prepress'
       @ppbook = doc.doctype == 'book'
@@ -324,15 +324,21 @@ class Converter < ::Prawn::Document
     end
     # QUESTION should ThemeLoader register fonts?
     register_fonts theme.font_catalog, (doc.attr 'scripts', 'latin'), (doc.attr 'pdf-fontsdir', ThemeLoader::FontsDir)
-    if (bg_image = resolve_background_image doc, theme, 'page-background-image') && bg_image != 'none'
-      @page_bg_image = bg_image
+    if (bg_image = resolve_background_image doc, theme, 'page-background-image') && bg_image[0]
+      @page_bg_image = { verso: bg_image, recto: bg_image }
     else
-      @page_bg_image = nil
+      @page_bg_image = { verso: nil, recto: nil }
+    end
+    if (bg_image = resolve_background_image doc, theme, 'page-background-image-verso')
+      @page_bg_image[:verso] = bg_image[0] ? bg_image : nil
+    end
+    if (bg_image = resolve_background_image doc, theme, 'page-background-image-recto') && bg_image[0]
+      @page_bg_image[:recto] = bg_image[0] ? bg_image : nil
     end
     @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
+    @base_align = (align = doc.attr 'text-align') && (TextAlignmentNames.include? align) ? align : theme.base_align
     @text_transform = nil
     @list_numerals = []
     @list_bullets = []
@@ -345,7 +351,16 @@ class Converter < ::Prawn::Document
   end
 
   def load_theme doc
-    @theme ||= doc.options[:pdf_theme] || ThemeLoader.load_theme((doc.attr 'pdf-style'), (doc.attr 'pdf-stylesdir'))
+    @theme ||= begin
+      if (theme = doc.options[:pdf_theme])
+        @themesdir = theme.__dir__ || (doc.attr 'pdf-themesdir') || (doc.attr 'pdf-stylesdir')
+      else
+        theme_name = (doc.attr 'pdf-theme') || (doc.attr 'pdf-style')
+        theme = ThemeLoader.load_theme theme_name, ((doc.attr 'pdf-themesdir') || (doc.attr 'pdf-stylesdir'))
+        @themesdir = theme.__dir__
+      end
+      theme
+    end
   end
 
   def build_pdf_options doc, theme
@@ -637,7 +652,7 @@ class Converter < ::Prawn::Document
       label_text = node.caption
       theme_font :admonition_label do
         theme_font %(admonition_label_#{type}) do
-          if (transform = @text_transform) && transform != 'none'
+          if (transform = @text_transform)
             label_text = transform_text label_text, transform
           end
           label_width = rendered_width_of_string label_text
@@ -689,15 +704,15 @@ class Converter < ::Prawn::Document
                     color: icon_data[:stroke_color],
                     size: icon_size
               elsif icons
-                if icon_path.end_with? '.svg'
+                if (::Asciidoctor::Image.format icon_path) == 'svg'
                   begin
                     svg_obj = ::Prawn::SVG::Interface.new ::File.read(icon_path), self,
-	                    position: label_align,
+	                      position: label_align,
                         vposition: label_valign,
                         width: label_width,
                         height: box_height,
                         fallback_font_name: default_svg_font,
-                        enable_web_requests: (doc.attr? 'allow-uri-read'),
+                        enable_web_requests: allow_uri_read,
                         enable_file_requests_with_root: (::File.dirname icon_path)
                     if (icon_height = (svg_size = svg_obj.document.sizing).output_height) > box_height
                       icon_width = (svg_obj.resize height: (icon_height = box_height)).output_width
@@ -1026,10 +1041,10 @@ class Converter < ::Prawn::Document
   def convert_olist node
     add_dest_for_block node if node.id
     @list_numerals ||= []
-    # TODO move list_number resolve to a method
-    list_number = case node.style
+    # TODO move list_numeral resolve to a method
+    list_numeral = case node.style
     when 'arabic'
-      '1'
+      1
     when 'decimal'
       '01'
     when 'loweralpha'
@@ -1047,13 +1062,17 @@ class Converter < ::Prawn::Document
     when 'none'
       ''
     else
-      '1'
+      1
     end
-    # TODO support start values < 1 (issue #498)
-    if (start = ((node.attr 'start', nil, false) || ((node.option? 'reversed') ? node.items.size : 1)).to_i) > 1
-      (start - 1).times { list_number = list_number.next }
+    if list_numeral && list_numeral != '' &&
+        (start = (node.attr 'start', nil, false) || ((node.option? 'reversed') ? node.items.size : nil))
+      if (start = start.to_i) > 1
+        (start - 1).times { list_numeral = list_numeral.next }
+      elsif start < 1 && !(::String === list_numeral)
+        (start - 1).abs.times { list_numeral = list_numeral.pred }
+      end
     end
-    @list_numerals << list_number
+    @list_numerals << list_numeral
     convert_outline_list node
     @list_numerals.pop
   end
@@ -1167,7 +1186,7 @@ class Converter < ::Prawn::Document
     when :olist
       complex = node.complex?
       if (index = @list_numerals.pop)
-        if index.empty?
+        if index == ''
           marker = ''
         else
           marker = %(#{index}.)
@@ -1238,19 +1257,25 @@ class Converter < ::Prawn::Document
 
     if image_format == 'gif' && !(defined? ::GMagick::Image)
       logger.warn %(GIF image format not supported. Install the prawn-gmagick gem or convert #{target} to PNG.) unless scratch?
-      image_path = false
+      image_path = nil
     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, replace: page_is_empty? if image_format == 'pdf'
-    else
-      logger.warn %(image to embed not found or not readable: #{image_path || target}) unless scratch?
+    elsif (image_path = resolve_image_path node, target, (opts.fetch :relative_to_imagesdir, true), image_format)
+      if ::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, replace: page_is_empty? if image_format == 'pdf'
+      elsif image_format == 'pdf'
+        logger.warn %(pdf to insert not found or not readable: #{image_path}) unless scratch?
+        # QUESTION should we use alt text in this case?
+        return
+      else
+        logger.warn %(image to embed not found or not readable: #{image_path}) unless scratch?
+        image_path = nil
+      end
+    elsif image_format == 'pdf'
       # QUESTION should we use alt text in this case?
-      return if image_format == 'pdf'
-      image_path = false
+      return
     end
 
     theme_margin :block, :top unless (pinned = opts[:pinned])
@@ -1266,7 +1291,7 @@ class Converter < ::Prawn::Document
     end if node.title?
 
     # TODO support cover (aka canvas) image layout using "canvas" (or "cover") role
-    width = resolve_explicit_width node.attributes, (available_w = bounds.width), support_vw: true, use_fallback: true
+    width = resolve_explicit_width node.attributes, (available_w = bounds.width), support_vw: true, use_fallback: true, constrain_to_bounds: true
     # TODO add `to_pt page_width` method to ViewportWidth type
     width = (width.to_f / 100) * page_width if ViewportWidth === width
 
@@ -1287,8 +1312,7 @@ class Converter < ::Prawn::Document
               position: alignment,
               width: width,
               fallback_font_name: default_svg_font,
-              enable_web_requests: (node.document.attr? 'allow-uri-read'),
-              # TODO enforce jail in safe mode
+              enable_web_requests: allow_uri_read,
               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')
@@ -1392,11 +1416,11 @@ class Converter < ::Prawn::Document
     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
+      poster = 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 allow_uri_read
         if node.document.attr? 'cache-uri'
           Helpers.require_library 'open-uri/cached', 'open-uri-cached' unless defined? ::OpenURI::Cache
         else
@@ -1534,14 +1558,24 @@ class Converter < ::Prawn::Document
       fragments = restore_conums fragments, conum_mapping, num_trailing_spaces, linenums if conum_mapping
       fragments = guard_indentation fragments
     when 'rouge'
-      lexer = ::Rouge::Lexer.find(node.attr 'language', 'text', false) || ::Rouge::Lexers::PlainText
-      lexer_opts = lexer.tag == 'php' ? { start_inline: !(node.option? 'mixed') } : {}
+      if (srclang = node.attr 'language', nil, false)
+        if srclang.include? '?'
+          if (lexer = ::Rouge::Lexer.find_fancy srclang)
+            unless lexer.tag != 'php' || (node.option? 'mixed') || ((lexer_opts = lexer.options).key? 'start_inline')
+              lexer = lexer.class.new lexer_opts.merge 'start_inline' => true
+            end
+          end
+        elsif (lexer = ::Rouge::Lexer.find srclang)
+          lexer = lexer.new start_inline: true if lexer.tag == 'php' && !(node.option? 'mixed')
+        end
+      end
+      lexer ||= ::Rouge::Lexers::PlainText
       formatter = (@rouge_formatter ||= ::Rouge::Formatters::Prawn.new theme: (node.document.attr 'rouge-style'), line_gap: @theme.code_line_gap)
       formatter_opts = (node.attr? 'linenums') ? { line_numbers: true, start_line: (node.attr 'start', 1, false).to_i } : {}
       # 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
-      fragments = formatter.format((lexer.lex source_string, lexer_opts), formatter_opts)
+      fragments = formatter.format((lexer.lex source_string), formatter_opts)
       # NOTE cleanup trailing endline (handled in rouge_ext/formatters/prawn instead)
       #fragments[-1][:text] == LF ? fragments.pop : fragments[-1][:text].chop!
       conum_mapping ? (restore_conums fragments, conum_mapping) : fragments
@@ -1727,9 +1761,7 @@ class Converter < ::Prawn::Document
     table_data = []
     node.rows[:head].each do |row|
       table_header = true
-      if (head_transform = theme.table_head_text_transform)
-        head_transform = nil if head_transform == 'none'
-      end
+      head_transform = resolve_text_transform :table_head_text_transform, nil
       row_data = []
       row.each do |cell|
         row_data << {
@@ -1743,7 +1775,8 @@ class Converter < ::Prawn::Document
           colspan: cell.colspan || 1,
           rowspan: cell.rowspan || 1,
           align: (cell.attr 'halign', nil, false).to_sym,
-          valign: (val = cell.attr 'valign', nil, false) == 'middle' ? :center : val.to_sym
+          valign: (val = cell.attr 'valign', nil, false) == 'middle' ? :center : val.to_sym,
+          padding: theme.table_head_cell_padding || theme.table_cell_padding,
         }
       end
       table_data << row_data
@@ -1791,9 +1824,7 @@ class Converter < ::Prawn::Document
             end
           end
           header_cell_data = header_cell_data_cache.dup
-          if (cell_transform = header_cell_data.delete :text_transform) == 'none'
-            cell_transform = nil
-          end
+          cell_transform = resolve_text_transform header_cell_data, nil
           cell_data.update header_cell_data unless header_cell_data.empty?
           cell_line_metrics = calc_line_metrics theme.base_line_height
         when :monospaced
@@ -1871,6 +1902,11 @@ class Converter < ::Prawn::Document
     table_border_color = theme.table_border_color || theme.table_grid_color || theme.base_border_color
     table_border_style = (theme.table_border_style || :solid).to_sym
     table_border_width = theme.table_border_width
+    if table_header
+      head_border_bottom_color = theme.table_head_border_bottom_color || table_border_color
+      head_border_bottom_style = (theme.table_head_border_bottom_style || table_border_style).to_sym
+      head_border_bottom_width = theme.table_head_border_bottom_width || table_border_width
+    end
     [:top, :bottom, :left, :right].each {|edge| border_width[edge] = table_border_width }
     table_grid_color = theme.table_grid_color || table_border_color
     table_grid_style = (theme.table_grid_style || table_border_style).to_sym
@@ -1920,6 +1956,7 @@ class Converter < ::Prawn::Document
     end
 
     caption_side = (theme.table_caption_side || :top).to_sym
+    caption_max_width = (theme.table_caption_max_width || 'fit-content').to_s
 
     table_settings = {
       header: table_header,
@@ -1952,14 +1989,14 @@ class Converter < ::Prawn::Document
     table table_data, table_settings do
       # 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
+      caption_max_width = caption_max_width == 'fit-content' ? table_width : nil
+      @pdf.layout_table_caption node, alignment, caption_max_width if node.title? && caption_side == :top
       if grid == 'none' && frame == 'none'
         if table_header
-          # FIXME allow header border bottom width and style to be set by theme
           rows(0).tap do |r|
-            r.border_bottom_line, r.border_bottom_width = :solid, 1.25
-            # QUESTION should we use the table border color for the bottom border color of the header row?
-            #r.border_bottom_color, r.border_bottom_line, r.border_bottom_width = table_border_color, :solid, 1.25
+            r.border_bottom_color = head_border_bottom_color
+            r.border_bottom_line = head_border_bottom_style
+            r.border_bottom_width = head_border_bottom_width
           end
         end
       else
@@ -1967,16 +2004,15 @@ class Converter < ::Prawn::Document
         cells.border_width = [border_width[:rows], border_width[:cols], border_width[:rows], border_width[:cols]]
 
         if table_header
-          # FIXME allow header border bottom width and style to be set by theme
           rows(0).tap do |r|
-            r.border_bottom_line, r.border_bottom_width = :solid, 1.25
-            # QUESTION should we use the table border color for the bottom border color of the header row?
-            #r.border_bottom_color, r.border_bottom_line, r.border_bottom_width = table_border_color, :solid, 1.25
+            r.border_bottom_color = head_border_bottom_color
+            r.border_bottom_line = head_border_bottom_style
+            r.border_bottom_width = head_border_bottom_width
           end
           rows(1).tap do |r|
-            r.border_top_line, r.border_top_width = :solid, 1.25
-            # QUESTION should we use the table border color for the top border color of the first row?
-            #r.border_top_color, r.border_top_line, r.border_top_width = table_border_color, :solid, 1.25
+            r.border_top_color = head_border_bottom_color
+            r.border_top_line = head_border_bottom_style
+            r.border_top_width = head_border_bottom_width
           end if num_rows > 1
         end
 
@@ -2008,12 +2044,12 @@ 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) && foot_transform != 'none'
+        #if (foot_transform = resolve_text_transform :table_foot_text_transform, nil)
         #  foot_row.each {|c| c.content = (transform_text c.content, foot_transform) if c.content }
         #end
       end
     end
-    layout_table_caption node, table_width, alignment, :bottom if node.title? && caption_side == :bottom
+    layout_table_caption node, alignment, caption_max_width, caption_side if node.title? && caption_side == :bottom
     theme_margin :block, :bottom
   end
 
@@ -2033,18 +2069,23 @@ class Converter < ::Prawn::Document
 
   # NOTE to insert sequential page breaks, you must put {nbsp} between page breaks
   def convert_page_break node
-    unless at_page_top?
-      if (page_layout = node.attr 'page-layout').nil_or_empty?
-        if node.role? && (page_layout = (node.roles.map(&:to_sym) & PageLayouts)[-1])
-          advance_page layout: page_layout
-        else
-          advance_page
-        end
-      elsif PageLayouts.include?(page_layout = page_layout.to_sym)
+    if (page_layout = node.attr 'page-layout').nil_or_empty?
+      unless node.role? && (page_layout = (node.roles.map(&:to_sym) & PageLayouts)[-1])
+        page_layout = nil
+      end
+    elsif !PageLayouts.include?(page_layout = page_layout.to_sym)
+      page_layout = nil
+    end
+
+    if at_page_top?
+      if page_layout && page_layout != page.layout && page_is_empty?
+        delete_page
         advance_page layout: page_layout
-      else
-        advance_page
       end
+    elsif page_layout
+      advance_page layout: page_layout
+    else
+      advance_page
     end
   end
 
@@ -2161,8 +2202,7 @@ class Converter < ::Prawn::Document
   end
 
   def convert_inline_button node
-    %(<strong>[#{NarrowNoBreakSpace}#{node.text}#{NarrowNoBreakSpace}]</strong>)
-    #%(<strong>[#{NoBreakSpace}#{node.text}#{NoBreakSpace}]</strong>)
+    %(<button>#{(@theme.button_content || '%s').sub '%s', node.text}</button>)
   end
 
   def convert_inline_callout node
@@ -2238,11 +2278,15 @@ class Converter < ::Prawn::Document
         logger.warn %(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 = (width = preresolve_explicit_width node.attributes) ? %( width="#{width}") : nil
-        img = %(<img src="#{image_path}" format="#{image_format}" alt="[#{encode_quotes node.attr 'alt'}]"#{width_attr} tmp="#{TemporaryPath === image_path}">)
+      elsif (image_path = resolve_image_path node, target, true, image_format)
+        if ::File.readable? image_path
+          width_attr = (width = preresolve_explicit_width node.attributes) ? %( width="#{width}") : nil
+          img = %(<img src="#{image_path}" format="#{image_format}" alt="[#{encode_quotes node.attr 'alt'}]"#{width_attr} tmp="#{TemporaryPath === image_path}">)
+        else
+          logger.warn %(image to embed not found or not readable: #{image_path}) unless scratch?
+          img = %([#{node.attr 'alt'}])
+        end
       else
-        logger.warn %(image to embed not found or not readable: #{image_path || target}) unless scratch?
         img = %([#{node.attr 'alt'}])
       end
       (node.attr? 'link', nil, false) ? %(<a href="#{node.attr 'link'}">#{img}</a>) : img
@@ -2328,19 +2372,16 @@ class Converter < ::Prawn::Document
   def layout_title_page doc
     return unless doc.header? && !doc.notitle
 
-    prev_bg_image = @page_bg_image
+    prev_bg_image = @page_bg_image[side = page_side]
     prev_bg_color = @page_bg_color
-
-    if (bg_image = resolve_background_image doc, @theme, 'title-page-background-image')
-      @page_bg_image = (bg_image == 'none' ? nil : bg_image)
-    end
+    @page_bg_image[side] = (bg_image = resolve_background_image doc, @theme, 'title-page-background-image') && bg_image[0] ? bg_image : nil
     if (bg_color = resolve_theme_color :title_page_background_color)
       @page_bg_color = bg_color
     end
     # NOTE a new page will already be started if the cover image is a PDF
     start_new_page unless page_is_empty?
     start_new_page if @ppbook && verso_page?
-    @page_bg_image = prev_bg_image if bg_image
+    @page_bg_image[side] = prev_bg_image if prev_bg_image
     @page_bg_color = prev_bg_color if bg_color
 
     # IMPORTANT this is the first page created, so we need to set the base font
@@ -2360,7 +2401,7 @@ class Converter < ::Prawn::Document
         relative_to_imagesdir = false
       end
       # HACK quick fix to resolve image path relative to theme
-      logo_image_path = ThemeLoader.resolve_theme_asset logo_image_path, (doc.attr 'pdf-stylesdir') unless doc.attr? 'title-logo-image'
+      logo_image_path = ThemeLoader.resolve_theme_asset logo_image_path, @themesdir unless doc.attr? 'title-logo-image'
       logo_image_attrs['target'] = logo_image_path
       logo_image_attrs['align'] ||= (@theme.title_page_logo_align || title_align.to_s)
       # QUESTION should we allow theme to turn logo image off?
@@ -2448,30 +2489,33 @@ class Converter < ::Prawn::Document
     end
   end
 
-  def layout_cover_page face, doc
+  def layout_cover_page doc, face
     # TODO turn processing of attribute with inline image a utility function in Asciidoctor
-    if (cover_image = (doc.attr %(#{face}-cover-image)))
-      if (cover_image.include? ':') && cover_image =~ ImageAttributeValueRx
-        # TODO support explicit image format
-        cover_image = resolve_image_path doc, $1
+    if (image_path = (doc.attr %(#{face}-cover-image)))
+      if (image_path.include? ':') && image_path =~ ImageAttributeValueRx
+        image_attrs = (AttributeList.new $2).parse ['alt', 'width']
+        image_path = resolve_image_path doc, $1, true, (image_format = image_attrs['format'])
       else
-        cover_image = resolve_image_path doc, cover_image, false
+        image_path = resolve_image_path doc, image_path, false
       end
 
-      if ::File.readable? cover_image
-        go_to_page page_count if face == :back
-        if cover_image.downcase.end_with? '.pdf'
-          # NOTE import_page automatically advances to next page afterwards (can we change this behavior?)
-          import_page cover_image, advance: face != :back
-        else
-          image_page cover_image, canvas: true
-        end
+      return unless image_path
+
+      unless ::File.readable? image_path
+        logger.warn %(#{face} cover image not found or readable: #{image_path})
+        return
+      end
+
+      go_to_page page_count if face == :back
+      if image_path.downcase.end_with? '.pdf'
+        import_page image_path, advance: face != :back
       else
-        logger.warn %(#{face} cover image not found or readable: #{cover_image})
+        image_opts = resolve_image_options image_path, image_attrs, background: true, format: image_format
+        image_page image_path, (image_opts.merge canvas: true)
       end
     end
   ensure
-    unlink_tmp_file cover_image if cover_image
+    unlink_tmp_file image_path if image_path
   end
 
   def start_new_chapter chapter
@@ -2492,7 +2536,7 @@ class Converter < ::Prawn::Document
   def layout_heading string, opts = {}
     top_margin = (margin = (opts.delete :margin)) || (opts.delete :margin_top) || @theme[%(heading_h#{opts[:level]}_margin_top)] || @theme.heading_margin_top
     bot_margin = margin || (opts.delete :margin_bottom) || @theme[%(heading_h#{opts[:level]}_margin_bottom)] || @theme.heading_margin_bottom
-    if (transform = (opts.delete :text_transform) || @text_transform) && transform != 'none'
+    if (transform = resolve_text_transform opts)
       string = transform_text string, transform
     end
     margin_top top_margin
@@ -2508,7 +2552,7 @@ 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) && transform != 'none'
+    if (transform = resolve_text_transform opts)
       string = transform_text string, transform
     end
     # NOTE used by extensions; ensures linked text gets formatted using the link styles
@@ -2581,14 +2625,19 @@ class Converter < ::Prawn::Document
   end
 
   # Render the caption for a table and return the height of the rendered content
-  def layout_table_caption node, width, alignment = :left, side = :top
-    # QUESTION should we confine width of title to width of table?
-    if alignment == :left || (excess = bounds.width - width) == 0
-      layout_caption node, side: side
-    else
-      indent excess * (alignment == :center ? 0.5 : 1) do
-        layout_caption node, side: side
+  def layout_table_caption node, table_alignment = :left, max_width = nil, side = :top
+    if max_width && (remainder = bounds.width - max_width) > 0
+      case table_alignment
+      when :right
+        indent(remainder) { layout_caption node, side: side }
+      when :center
+        side_margin = remainder * 0.5
+        indent(side_margin, side_margin) { layout_caption node, side: side }
+      else # :left
+        indent(0, remainder) { layout_caption node, side: side }
       end
+    else
+      layout_caption node, side: side
     end
   end
 
@@ -2639,8 +2688,7 @@ class Converter < ::Prawn::Document
     end
     sections.each do |sect|
       theme_font :toc, level: (sect.level + 1) do
-        sect_title = (transform = @text_transform) && transform != 'none' ?
-            (transform_text sect.numbered_title, transform) : sect.numbered_title
+        sect_title = (transform = @text_transform) ? (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
@@ -2728,8 +2776,8 @@ class Converter < ::Prawn::Document
     # FIXME probably need to treat doctypes differently
     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 } || []
+    sectlevels = (@theme[%(#{periphery}_sectlevels)] || 2).to_i
+    sections = doc.find_by(context: :section) {|sect| sect.level <= sectlevels && 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
@@ -2810,168 +2858,6 @@ 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
-    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)
-      trim_top = page_height
-      # NOTE height is required atm
-      trim_height = @theme.header_height || page_margin_top
-      trim_padding = inflate_padding @theme.header_padding || 0
-      trim_bg_color = resolve_theme_color :header_background_color
-      trim_border_width = @theme.header_border_width || @theme.base_border_width
-      trim_border_style = (@theme.header_border_style || :solid).to_sym
-      trim_border_color = resolve_theme_color :header_border_color
-      trim_valign = (@theme.header_vertical_align || :middle).to_sym
-      trim_img_valign = @theme.header_image_vertical_align
-    else
-      trim_line_metrics = calc_line_metrics(@theme.footer_line_height || @theme.base_line_height)
-      # NOTE height is required atm
-      trim_top = trim_height = @theme.footer_height || page_margin_bottom
-      trim_padding = inflate_padding @theme.footer_padding || 0
-      trim_bg_color = resolve_theme_color :footer_background_color
-      trim_border_width = @theme.footer_border_width || @theme.base_border_width
-      trim_border_style = (@theme.footer_border_style || :solid).to_sym
-      trim_border_color = resolve_theme_color :footer_border_color
-      trim_valign = (@theme.footer_vertical_align || :middle).to_sym
-      trim_img_valign = @theme.footer_image_vertical_align
-    end
-
-    trim_stamp_name = {
-      recto: %(#{periphery}_recto),
-      verso: %(#{periphery}_verso)
-    }
-    trim_left = {
-      recto: @page_margin_by_side[:recto][3],
-      verso: @page_margin_by_side[:verso][3]
-    }
-    trim_width = {
-      recto: page_width - trim_left[:recto] - @page_margin_by_side[:recto][1],
-      verso: page_width - trim_left[:verso] - @page_margin_by_side[:verso][1]
-    }
-    trim_content_left = {
-      recto: trim_left[:recto] + trim_padding[3],
-      verso: trim_left[:verso] + trim_padding[3]
-    }
-    trim_content_width = {
-      recto: trim_width[:recto] - trim_padding[3] - trim_padding[1],
-      verso: trim_width[:verso] - trim_padding[3] - trim_padding[1]
-    }
-    trim_content_height = trim_height - trim_padding[0] - trim_padding[2] - trim_line_metrics.padding_top - trim_line_metrics.padding_bottom
-    trim_border_color = nil if trim_border_width == 0
-    trim_valign = :center if trim_valign == :middle
-    case trim_img_valign
-    when nil
-      trim_img_valign = trim_valign
-    when 'middle'
-      trim_img_valign = :center
-    when 'top', 'center', 'bottom'
-      trim_img_valign = trim_img_valign.to_sym
-    end
-
-    colspec_dict = PageSides.inject({}) do |acc, side|
-      side_trim_content_width = trim_content_width[side]
-      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
-            rel_width = spec[1..-1].to_f
-          else
-            alignment = :left
-            rel_width = spec.to_f
-          end
-          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
-        acc[side] = {
-          left: { align: :left, width: side_trim_content_width, x: 0 },
-          center: { align: :center, width: side_trim_content_width, x: 0 },
-          right: { align: :right, width: side_trim_content_width, x: 0 }
-        }
-      end
-      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
-            if ::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
-              logger.warn %(image to embed not found or not readable: #{path})
-              side_content[position] = val
-            end
-          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
-      PageSides.each do |side|
-        create_stamp trim_stamp_name[side] do
-          canvas do
-            if trim_bg_color
-              bounding_box [0, trim_top], width: bounds.width, height: trim_height do
-                fill_bounds trim_bg_color
-                if trim_border_color
-                  # TODO stroke_horizontal_rule should support :at
-                  move_down bounds.height if periphery == :header
-                  stroke_horizontal_rule trim_border_color, line_width: trim_border_width, line_style: trim_border_style
-                end
-              end
-            else
-              bounding_box [trim_left[side], trim_top], width: trim_width[side], height: trim_height do
-                # TODO stroke_horizontal_rule should support :at
-                move_down bounds.height if periphery == :header
-                stroke_horizontal_rule trim_border_color, line_width: trim_border_width, line_style: trim_border_style
-              end
-            end
-          end
-        end
-      end
-      stamps[periphery] = true
-    end
 
     pagenums_enabled = doc.attr? 'pagenums'
     attribute_missing_doc = doc.attr 'attribute-missing'
@@ -2985,12 +2871,15 @@ class Converter < ::Prawn::Document
     else
       folio_basis, invert_folio = :virtual, false
     end
+    periphery_layout_cache = {}
     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_pagenums
       pgnum_label = (RomanNumeral.new page_number, :lower) if pgnum_label < 1
       side = page_side((folio_basis == :physical ? page_number : pgnum_label), invert_folio)
+      # QUESTION should allocation be per side?
+      trim_styles, colspec_dict, content_dict, stamp_names = allocate_running_content_layout page, periphery, periphery_layout_cache
       # FIXME we need to have a content setting for chapter pages
       content_by_position, colspec_by_position = content_dict[side], colspec_dict[side]
       # TODO populate chapter-number
@@ -3002,77 +2891,73 @@ class Converter < ::Prawn::Document
       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] || '')
 
-      stamp trim_stamp_name[side] if stamps[periphery]
+      stamp stamp_names[side] if stamp_names
 
       theme_font periphery do
         canvas do
-          bounding_box [trim_content_left[side], trim_top], width: trim_content_width[side], height: trim_height do
+          bounding_box [trim_styles[:content_left][side], trim_styles[:top]], width: trim_styles[:content_width][side], height: trim_styles[:height] do
+            if (trim_column_rule_width = trim_styles[:column_rule_width]) > 0
+              trim_column_rule_spacing = trim_styles[:column_rule_spacing]
+            else
+              trim_column_rule_width = nil
+            end
+            prev_position = nil
             ColumnPositions.each do |position|
               next unless (content = content_by_position[position])
               next unless (colspec = colspec_by_position[position])[:width] > 0
+              left, colwidth = colspec[:x], colspec[:width]
+              if trim_column_rule_width && colwidth < bounds.width
+                if (trim_column_rule = prev_position)
+                  left += (trim_column_rule_spacing * 0.5)
+                  colwidth -= trim_column_rule_spacing
+                else
+                  colwidth -= (trim_column_rule_spacing * 0.5)
+                end
+              end
               # FIXME we need to have a content setting for chapter pages
               case content
-              when ::Hash
-                # NOTE image vposition respects padding; use negative image_vertical_align value to revert
-                trim_v_padding = trim_padding[0] + trim_padding[2]
+              when ::Array
                 # NOTE float ensures cursor position is restored and returns us to current page if we overrun
                 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
-                    begin
-                      if (img_path = content[:path]).downcase.end_with? '.svg'
-                        svg_data = ::File.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
-                      logger.warn %(could not embed image in running content: #{img_path}; #{$!.message})
-                    end
+                  # NOTE bounding_box is redundant if both vertical padding and border width are 0
+                  bounding_box [left, bounds.top - trim_styles[:padding][0] - trim_styles[:content_offset]], width: colwidth, height: trim_styles[:content_height] do
+                    # NOTE image vposition respects padding; use negative image_vertical_align value to revert
+                    image_opts = content[1].merge position: colspec[:align], vposition: trim_styles[:img_valign]
+                    image content[0], image_opts rescue logger.warn %(could not embed image in running content: #{content[0]}; #{$!.message})
                   end
                 end
               when ::String
-                # NOTE minor optimization
-                if content == '{page-number}'
-                  content = pagenums_enabled ? pgnum_label.to_s : nil
-                else
-                  # FIXME get apply_subs to handle drop-line w/o a warning
-                  doc.set_attr 'attribute-missing', 'skip' unless attribute_missing_doc == 'skip'
-                  if (content = doc.apply_subs content).include? '{'
-                    # NOTE must use &#123; in place of {, not \{, to escape attribute reference
-                    content = content.split(LF).delete_if {|line| SimpleAttributeRefRx.match? line } * LF
-                  end
-                  doc.set_attr 'attribute-missing', attribute_missing_doc unless attribute_missing_doc == 'skip'
-                end
                 theme_font %(#{periphery}_#{side}_#{position}) do
+                  # NOTE minor optimization
+                  if content == '{page-number}'
+                    content = pagenums_enabled ? pgnum_label.to_s : nil
+                  else
+                    # FIXME get apply_subs to handle drop-line w/o a warning
+                    doc.set_attr 'attribute-missing', 'skip' unless attribute_missing_doc == 'skip'
+                    if (content = doc.apply_subs content).include? '{'
+                      # NOTE must use &#123; in place of {, not \{, to escape attribute reference
+                      content = content.split(LF).delete_if {|line| SimpleAttributeRefRx.match? line } * LF
+                    end
+                    doc.set_attr 'attribute-missing', attribute_missing_doc unless attribute_missing_doc == 'skip'
+                    if (transform = @text_transform) && transform != 'none'
+                      content = transform_text content, @text_transform
+                    end
+                  end
                   formatted_text_box parse_text(content, color: @font_color, inline_format: [normalize: true]),
-                    at: [colspec[:x], trim_top - trim_padding[0] + (trim_valign == :center ? font.descender * 0.5 : 0)],
-                    width: colspec[:width],
-                    height: trim_content_height,
+                    at: [left, bounds.top - trim_styles[:padding][0] - trim_styles[:content_offset] + (trim_styles[:valign] == :center ? font.descender * 0.5 : 0)],
+                    width: colwidth,
+                    height: trim_styles[:prose_content_height],
                     align: colspec[:align],
-                    valign: trim_valign,
-                    leading: trim_line_metrics.leading,
+                    valign: trim_styles[:valign],
+                    leading: trim_styles[:line_metrics].leading,
                     final_gap: false,
                     overflow: :truncate
                 end
               end
+              bounding_box [colspec[:x], bounds.top - trim_styles[:padding][0] - trim_styles[:content_offset]], width: colspec[:width], height: trim_styles[:content_height] do
+                stroke_vertical_rule trim_styles[:column_rule_color], at: bounds.left, line_style: trim_styles[:column_rule_style], line_width: trim_column_rule_width
+              end if trim_column_rule
+              prev_position = position
             end
           end
         end
@@ -3083,6 +2968,150 @@ class Converter < ::Prawn::Document
     nil
   end
 
+  def allocate_running_content_layout page, periphery, cache
+    layout = page.layout
+    cache[layout] ||= begin
+      trim_styles = {
+        line_metrics: (trim_line_metrics = calc_line_metrics @theme[%(#{periphery}_line_height)] || @theme.base_line_height),
+        # NOTE we've already verified this property is set
+        height: (trim_height = @theme[%(#{periphery}_height)]),
+        top: periphery == :header ? page_height : trim_height,
+        padding: (trim_padding = inflate_padding @theme[%(#{periphery}_padding)] || 0),
+        bg_color: (resolve_theme_color %(#{periphery}_background_color).to_sym),
+        border_color: (trim_border_color = resolve_theme_color %(#{periphery}_border_color).to_sym),
+        border_style: (@theme[%(#{periphery}_border_style)] || :solid).to_sym,
+        border_width: (trim_border_width = trim_border_color ? @theme[%(#{periphery}_border_width)] || @theme.base_border_width || 0 : 0),
+        column_rule_color: (trim_column_rule_color = resolve_theme_color %(#{periphery}_column_rule_color).to_sym),
+        column_rule_style: (@theme[%(#{periphery}_column_rule_style)] || :solid).to_sym,
+        column_rule_width: (trim_column_rule_color ? @theme[%(#{periphery}_column_rule_width)] || 0 : 0),
+        column_rule_spacing: (trim_column_rule_spacing = @theme[%(#{periphery}_column_rule_spacing)] || 0),
+        valign: (val = (@theme[%(#{periphery}_vertical_align)] || :middle).to_sym) == :middle ? :center : val,
+        img_valign: @theme[%(#{periphery}_image_vertical_align)],
+        left: {
+          recto: (trim_left_recto = @page_margin_by_side[:recto][3]),
+          verso: (trim_left_verso = @page_margin_by_side[:verso][3]),
+        },
+        width: {
+          recto: (trim_width_recto = page_width - trim_left_recto - @page_margin_by_side[:recto][1]),
+          verso: (trim_width_verso = page_width - trim_left_verso - @page_margin_by_side[:verso][1]),
+        },
+        content_left: {
+          recto: trim_left_recto + trim_padding[3],
+          verso: trim_left_verso + trim_padding[3],
+        },
+        content_width: (trim_content_width = {
+          recto: trim_width_recto - trim_padding[1] - trim_padding[3],
+          verso: trim_width_verso - trim_padding[1] - trim_padding[3],
+        }),
+        content_height: (content_height = trim_height - trim_padding[0] - trim_padding[2] - (trim_border_width * 0.5)),
+        prose_content_height: content_height - trim_line_metrics.padding_top - trim_line_metrics.padding_bottom,
+        # NOTE content offset adjusts y position to account for border
+        content_offset: (periphery == :footer ? trim_border_width * 0.5 : 0),
+      }
+      case trim_styles[:img_valign]
+      when nil
+        trim_styles[:img_valign] = trim_styles[:valign]
+      when 'middle'
+        trim_styles[:img_valign] = :center
+      when 'top', 'center', 'bottom'
+        trim_styles[:img_valign] = trim_styles[:img_valign].to_sym
+      end
+
+      colspec_dict = PageSides.inject({}) do |acc, side|
+        side_trim_content_width = trim_content_width[side]
+        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
+              rel_width = spec[1..-1].to_f
+            else
+              alignment = :left
+              rel_width = spec.to_f
+            end
+            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
+          acc[side] = {
+            left: { align: :left, width: side_trim_content_width, x: 0 },
+            center: { align: :center, width: side_trim_content_width, x: 0 },
+            right: { align: :right, width: side_trim_content_width, x: 0 }
+          }
+        end
+        acc
+      end
+
+      content_dict = PageSides.inject({}) do |acc, side|
+        side_content = {}
+        ColumnPositions.each do |position|
+          unless (val = @theme[%(#{periphery}_#{side}_#{position}_content)]).nil_or_empty?
+            if (val.include? ':') && val =~ ImageAttributeValueRx
+              # TODO support image URL
+              if ::File.readable? (image_path = (ThemeLoader.resolve_theme_asset $1, @themesdir))
+                image_attrs = (AttributeList.new $2).parse ['alt', 'width']
+                image_opts = resolve_image_options image_path, image_attrs, container_size: [colspec_dict[side][position][:width], trim_styles[:content_height]], format: image_attrs['format']
+                side_content[position] = [image_path, image_opts]
+              else
+                # NOTE allows inline image handler to report invalid reference and replace with alt text
+                side_content[position] = %(image:#{image_path}[#{$2}])
+              end
+            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
+
+      if trim_styles[:bg_color] || trim_styles[:border_width] > 0
+        stamp_names = { recto: %(#{layout}_#{periphery}_recto), verso: %(#{layout}_#{periphery}_verso) }
+        PageSides.each do |side|
+          create_stamp stamp_names[side] do
+            canvas do
+              if trim_styles[:bg_color]
+                bounding_box [0, trim_styles[:top]], width: bounds.width, height: trim_styles[:height] do
+                  fill_bounds trim_styles[:bg_color]
+                  if trim_styles[:border_width] > 0
+                    # TODO stroke_horizontal_rule should support :at
+                    move_down bounds.height if periphery == :header
+                    stroke_horizontal_rule trim_styles[:border_color], line_width: trim_styles[:border_width], line_style: trim_styles[:border_style]
+                  end
+                end
+              else
+                bounding_box [trim_styles[:left][side], trim_styles[:top]], width: trim_styles[:width][side], height: trim_styles[:height] do
+                  # TODO stroke_horizontal_rule should support :at
+                  move_down bounds.height if periphery == :header
+                  stroke_horizontal_rule trim_styles[:border_color], line_width: trim_styles[:border_width], line_style: trim_styles[:border_style]
+                end
+              end
+            end
+          end
+        end
+      end
+
+      [trim_styles, colspec_dict, content_dict, stamp_names]
+    end
+  end
+
   def add_outline doc, num_levels = 2, toc_page_nums = [], num_front_matter_pages = 0
     front_matter_counter = RomanNumeral.new 0, :lower
     pagenum_labels = {}
@@ -3099,7 +3128,7 @@ class Converter < ::Prawn::Document
     outline.define do
       # FIXME use sanitize: :plain_text once available
       if (doctitle = document.sanitize(doc.doctitle use_fallback: true))
-        # FIXME link to title page if there's a cover page (skip cover page and ensuing blank page)
+        # FIXME link to title page if there's a cover page (skip cover page and ensure blank page)
         page title: doctitle, destination: (document.dest_top 1)
       end
       page title: (doc.attr 'toc-title'), destination: (document.dest_top toc_page_nums.first) unless toc_page_nums.none?
@@ -3160,6 +3189,16 @@ class Converter < ::Prawn::Document
     @theme.svg_font_family || @theme.base_font_family
   end
 
+  attr_reader :allow_uri_read
+
+  def resolve_text_transform key, use_fallback = true
+    if (transform = ::Hash === key ? (key.delete :text_transform) : @theme[key.to_s])
+      transform == 'none' ? nil : transform
+    elsif use_fallback
+      @text_transform
+    end
+  end
+
   # QUESTION should we pass a category as an argument?
   # QUESTION should we make this a method on the theme ostruct? (e.g., @theme.resolve_color key, fallback)
   def resolve_theme_color key, fallback_color = nil
@@ -3233,7 +3272,7 @@ class Converter < ::Prawn::Document
     end
 
     prev_color, @font_color = @font_color, color if color
-    prev_transform, @text_transform = @text_transform, transform if transform
+    prev_transform, @text_transform = @text_transform, (transform == 'none' ? nil : transform) if transform
 
     font family, size: size, style: (style && style.to_sym) do
       result = yield
@@ -3486,7 +3525,7 @@ class Converter < ::Prawn::Document
     doc = node.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)
+    image_format ||= ::Asciidoctor::Image.format image_path, (::Asciidoctor::Image === node ? node.attributes : nil)
     # NOTE currently used for inline images
     if ::Base64 === image_path
       tmp_image = ::Tempfile.create ['image-', image_format && %(.#{image_format})]
@@ -3502,7 +3541,7 @@ class Converter < ::Prawn::Document
     # handle case when image is a URI
     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'
+      unless allow_uri_read
         logger.warn %(allow-uri-read is not enabled; cannot embed remote image: #{image_path}) unless scratch?
         return
       end
@@ -3527,34 +3566,89 @@ class Converter < ::Prawn::Document
     end
   end
 
-  # Resolve the path to the background image either from a document attribute or theme key.
+  # Resolve the path and sizing of the background image either from a document attribute or theme key.
   #
-  # Returns The string "none" if the background image value is none, otherwise the resolved
-  # path to the image. If neither the document attribute or theme key are specified, or
-  # the image path cannot be resolved, return nil.
+  # Returns the argument list for the image method if the document attribute or theme key is found. Otherwise,
+  # nothing. The first argument in the argument list is the image path. If that value is nil, the background
+  # image is disabled. The second argument is the options hash to specify the dimensions, such as width and fit.
   def resolve_background_image doc, theme, key
-    if (bg_image = (doc_attr_val = (doc.attr key)) || theme[(key.tr '-', '_').to_sym])
-      return bg_image if bg_image == 'none'
-
-      if (bg_image.include? ':') && bg_image =~ ImageAttributeValueRx
-        # QUESTION should we support width and height in this case?
-        # TODO support explicit format
-        bg_image = $1
-        relative_to_imagesdir = true
+    if (image_path = (doc.attr key) || (from_theme = theme[(key.tr '-', '_').to_sym]))
+      if image_path == 'none'
+        return []
+      elsif (image_path.include? ':') && image_path =~ ImageAttributeValueRx
+        image_attrs = (AttributeList.new $2).parse ['alt', 'width']
+        # TODO support remote image when loaded from theme
+        image_path = from_theme ? (ThemeLoader.resolve_theme_asset $1, @themesdir) : (resolve_image_path doc, $1, true, (image_format = image_attrs['format']))
       else
-        relative_to_imagesdir = false
+        image_path = from_theme ? (ThemeLoader.resolve_theme_asset image_path, @themesdir) : (resolve_image_path doc, image_path, false)
       end
 
-      if (bg_image = doc_attr_val ? (resolve_image_path doc, bg_image, relative_to_imagesdir) :
-          (ThemeLoader.resolve_theme_asset bg_image, (doc.attr 'pdf-stylesdir')))
-        if ::File.readable? bg_image
-          bg_image
-        else
-          logger.warn %(#{key.tr '-', ' '} not found or readable: #{bg_image})
-          nil
+      return unless image_path
+
+      unless ::File.readable? image_path
+        logger.warn %(#{key.tr '-', ' '} not found or readable: #{image_path})
+        return
+      end
+
+      [image_path, (resolve_image_options image_path, image_attrs, background: true, format: image_format)]
+    end
+  end
+
+  def resolve_image_options image_path, image_attrs, opts = {}
+    if (image_format = opts[:format] || (::Asciidoctor::Image.format image_path)) == 'svg'
+      image_opts = {
+        enable_file_requests_with_root: (::File.dirname image_path),
+        enable_web_requests: allow_uri_read,
+        fallback_font_name: default_svg_font,
+        format: 'svg',
+      }
+    else
+      image_opts = {}
+    end
+    background = opts[:background]
+    container_size = opts.fetch :container_size, (background ? [page_width, page_height] : [bounds.width, bounds.height])
+    if image_attrs
+      if background && (image_pos = image_attrs['position']) && (image_pos = resolve_background_position image_pos, nil)
+        image_opts.update image_pos
+      end
+      if (image_fit = image_attrs['fit'])
+        container_width, container_height = container_size
+        case image_fit
+        when 'none'
+          if (image_width = resolve_explicit_width image_attrs, container_width)
+            image_opts[:width] = image_width
+          end
+        when 'scale-down'
+          # NOTE if width and height aren't set in SVG, real width and height are computed after stretching viewbox to fit page
+          if (image_width = resolve_explicit_width image_attrs, container_width) && image_width > container_width
+            image_opts[:fit] = container_size
+          elsif (image_size = intrinsic_image_dimensions image_path, image_format) &&
+              (image_width ? image_width * (image_size[:height] / image_size[:width]) > container_height : (to_pt image_size[:width], :px) > container_width || (to_pt image_size[:height], :px) > container_height)
+            image_opts[:fit] = container_size
+          elsif image_width
+            image_opts[:width] = image_width
+          end
+        when 'cover'
+          # QUESTION should we take explicit width into account?
+          if (image_size = intrinsic_image_dimensions image_path, image_format)
+            if container_width * (image_size[:height] / image_size[:width]) < container_height
+              image_opts[:height] = container_height
+            else
+              image_opts[:width] = container_width
+            end
+          end
+        else # contain
+          image_opts[:fit] = container_size
         end
+      elsif (image_width = resolve_explicit_width image_attrs, container_size[0])
+        image_opts[:width] = image_width
+      else # default to fit=contain if sizing is not specified
+        image_opts[:fit] = container_size
       end
+    else
+      image_opts[:fit] = container_size
     end
+    image_opts
   end
 
   # Resolves the explicit width as a PDF pt value if the value is specified in
@@ -3609,7 +3703,39 @@ class Converter < ::Prawn::Document
       end
     elsif attrs.key? 'width'
       # QUESTION should we honor percentage width value?
-      [max_width, (to_pt attrs['width'].to_f, :px)].min
+      width = to_pt attrs['width'].to_f, :px
+      opts[:constrain_to_bounds] ? [max_width, width].min : width
+    end
+  end
+
+  def resolve_background_position value, default_value = {}
+    if value.include? ' '
+      result = {}
+      center = nil
+      (value.split ' ', 2).each do |keyword|
+        if keyword == 'left' || keyword == 'right'
+          result[:position] = keyword.to_sym
+        elsif keyword == 'top' || keyword == 'bottom'
+          result[:vposition] = keyword.to_sym
+        elsif keyword == 'center'
+          center = true
+        end
+      end
+      if center
+        result[:position] ||= :center
+        result[:vposition] ||= :center
+        result
+      elsif (result.key? :position) && (result.key? :vposition)
+        result
+      else
+        default_value
+      end
+    elsif value == 'left' || value == 'right' || value == 'center'
+      { position: value.to_sym, vposition: :center }
+    elsif value == 'top' || value == 'bottom'
+      { position: :center, vposition: value.to_sym }
+    else
+      default_value
     end
   end