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

data/lib/asciidoctor-pdf/converter.rb

@@ -27,13 +27,11 @@ class Converter < ::Prawn::Document
 
   register_for 'pdf'
 
-  def self.unicode_char number
-    [number].pack 'U*'
-  end
-
   # NOTE require_library doesn't support require_relative and we don't modify the load path for this gem
-  CodeRayRequirePath = ::File.join((::File.dirname __FILE__), 'prawn_ext/coderay_encoder')
+  CodeRayRequirePath = ::File.join (::File.dirname __FILE__), 'prawn_ext/coderay_encoder'
+  RougeRequirePath = ::File.join (::File.dirname __FILE__), 'rouge_ext'
 
+  AsciidoctorVersion = ::Gem::Version.create ::Asciidoctor::VERSION
   AdmonitionIcons = {
     caution:   { key: 'fa-fire', color: 'BF3400' },
     important: { key: 'fa-exclamation-circle', color: 'BF0000' },
@@ -42,27 +40,34 @@ class Converter < ::Prawn::Document
     warning:   { key: 'fa-exclamation-triangle', color: 'BF6900' }
   }
   Alignments = [:left, :center, :right]
-  IndentationRx = /^ +/
-  TabSpaces = ' ' * 4
-  NoBreakSpace = unicode_char 0x00a0
-  NarrowSpace = unicode_char 0x2009
-  NarrowNoBreakSpace = unicode_char 0x202f
-  ZeroWidthSpace = unicode_char 0x200b
-  HairSpace = unicode_char 0x200a
-  DotLeaderDefault = %(. )
-  EmDash = unicode_char 0x2014
-  LowercaseGreekA = unicode_char 0x03b1
+  EOL = %(\n)
+  TAB = %(\t)
+  InnerIndent = %(\n )
+  # a no-break space is used to replace a leading space to prevent Prawn from trimming indentation
+  # a leading zero-width space can't be used as it gets dropped when calculating the line width
+  GuardedIndent = %(\u00a0)
+  GuardedInnerIndent = %(\n\u00a0)
+  TabRx = /\t/
+  TabIndentRx = /^\t+/
+  NoBreakSpace = %(\u00a0)
+  NarrowSpace = %(\u2009)
+  NarrowNoBreakSpace = %(\u202f)
+  ZeroWidthSpace = %(\u200b)
+  HairSpace = %(\u200a)
+  DotLeaderDefault = '. '
+  EmDash = %(\u2014)
+  LowercaseGreekA = %(\u03b1)
   Bullets = {
-    disc: (unicode_char 0x2022),
-    circle: (unicode_char 0x25e6),
-    square: (unicode_char 0x25aa)
+    disc: %(\u2022),
+    circle: %(\u25e6),
+    square: %(\u25aa)
   }
   # NOTE Default theme font uses ballot boxes from FontAwesome
   BallotBox = {
-    checked: (unicode_char 0x2611),
-    unchecked: (unicode_char 0x2610)
+    checked: %(\u2611),
+    unchecked: %(\u2610)
   }
-  IconSets = ['fa', 'fi', 'octicon', 'pf']
+  IconSets = ['fa', 'fi', 'octicon', 'pf'].to_set
   MeasurementRxt = '\\d+(?:\\.\\d+)?(?:in|cm|mm|pt|)'
   MeasurementPartsRx = /^(\d+(?:\.\d+)?)(in|mm|cm|pt|)$/
   PageSizeRx = /^(?:\[(#{MeasurementRxt}), ?(#{MeasurementRxt})\]|(#{MeasurementRxt})(?: x |x)(#{MeasurementRxt})|\S+)$/
@@ -70,6 +75,7 @@ class Converter < ::Prawn::Document
   CalloutExtractRx = /(?:(?:\/\/|#|--|;;) ?)?(\\)?<!?(--|)(\d+)\2>(?=(?: ?\\?<!?\2\d+\2>)*$)/
   ImageAttributeValueRx = /^image:{1,2}(.*?)\[(.*?)\]$/
   LineScanRx = /\n|.+/
+  SourceHighlighters = ['coderay', 'pygments', 'rouge'].to_set
 
   def initialize backend, opts
     super
@@ -78,6 +84,9 @@ class Converter < ::Prawn::Document
     #htmlsyntax 'xml'
     @list_numbers = []
     @list_bullets = []
+    @capabilities = {
+      expands_tabs: (::Asciidoctor::VERSION.start_with? '1.5.3.') || AsciidoctorVersion >= (::Gem::Version.create '1.5.3')
+    }
   end
 
   def convert node, name = nil, opts = {}
@@ -113,14 +122,19 @@ class Converter < ::Prawn::Document
     init_pdf doc
     # data-uri doesn't apply to PDF, so explicitly disable (is there a better place?)
     doc.attributes.delete 'data-uri'
+    # set default value for pagenums if not otherwise set
+    unless (doc.attribute_locked? 'pagenums') || ((doc.instance_variable_get :@attributes_modified).include? 'pagenums')
+      doc.attributes['pagenums'] = ''
+    end
     #assign_missing_section_ids doc
 
+    # NOTE the on_page_create callback is called within a float context
     on_page_create do
       # TODO implement as a watermark (on top)
       if @page_bg_image
         # FIXME implement fitting and centering for SVG
         # TODO implement image scaling (numeric value or "fit")
-        float { canvas { image @page_bg_image, position: :center, fit: [bounds.width, bounds.height] } }
+        canvas { image @page_bg_image, position: :center, fit: [bounds.width, bounds.height] }
       elsif @page_bg_color && @page_bg_color != 'FFFFFF'
         fill_absolute_bounds @page_bg_color
       end
@@ -129,7 +143,8 @@ class Converter < ::Prawn::Document
     layout_cover_page :front, doc
     layout_title_page doc
 
-    start_new_page
+    # NOTE a new page will already be started if the cover image is a PDF
+    start_new_page unless page_is_empty?
 
     toc_start_page_num = page_number
     num_toc_levels = (doc.attr 'toclevels', 2).to_i
@@ -148,17 +163,18 @@ class Converter < ::Prawn::Document
     font @theme.base_font_family, size: @theme.base_font_size
     convert_content_for_block doc
 
+    # NOTE delete orphaned page (a page was created but there was no additional content)
+    delete_page if page_is_empty?
+
     toc_page_nums = if include_toc
       layout_toc doc, num_toc_levels, toc_start_page_num, num_front_matter_pages
     else
       (0..-1)
     end
 
-    # TODO enable pagenums by default
-    if doc.attr? 'pagenums'
-      layout_running_content :header, doc, skip: num_front_matter_pages
-      layout_running_content :footer, doc, skip: num_front_matter_pages
-    end
+    layout_running_content :header, doc, skip: num_front_matter_pages unless doc.noheader
+    layout_running_content :footer, doc, skip: num_front_matter_pages unless doc.nofooter
+
     add_outline doc, num_toc_levels, toc_page_nums, num_front_matter_pages
     catalog.data[:ViewerPreferences] = [:FitWindow]
 
@@ -178,19 +194,18 @@ class Converter < ::Prawn::Document
     theme = ThemeLoader.load_theme doc.attr('pdf-style'), (stylesdir = (doc.attr 'pdf-stylesdir'))
     @theme = theme
     pdf_opts = (build_pdf_options doc, theme)
+    # QUESTION should we preserve page options (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
     # QUESTION should ThemeLoader register fonts?
     register_fonts theme.font_catalog, (doc.attr 'scripts', 'latin'), (doc.attr 'pdf-fontsdir', ThemeLoader::FontsDir)
-    if (bg_image = theme.page_background_image) && bg_image != 'none'
-      if ::File.readable?(bg_image = (ThemeLoader.resolve_theme_asset bg_image, stylesdir))
-        @page_bg_image = bg_image
-      else
-        warn %(asciidoctor: WARNING: page background image #{bg_image} not found or readable)
-      end
+    @page_bg_image = nil
+    if (bg_image = resolve_background_image doc, theme, 'page-background-image')
+      @page_bg_image = (bg_image == 'none' ? nil : bg_image)
     end
-    @fallback_fonts = [*theme.font_fallbacks]
     @page_bg_color = resolve_theme_color :page_background_color, 'FFFFFF'
-    @font_color = theme.base_font_color || '000000'
+    @fallback_fonts = [*theme.font_fallbacks]
+    @font_color = theme.base_font_color
     @text_transform = nil
     @stamps = {}
     init_scratch_prototype
@@ -202,8 +217,8 @@ class Converter < ::Prawn::Document
       #compress: true,
       #optimize_objects: true,
       info: (build_pdf_info doc),
-      margin: (theme.page_margin || 36),
-      page_layout: (theme.page_layout || :portrait).to_sym,
+      margin: theme.page_margin,
+      page_layout: theme.page_layout.to_sym,
       skip_page_creation: true,
     }
 
@@ -391,19 +406,24 @@ class Converter < ::Prawn::Document
     theme_margin :block, :top
     icons = node.document.attr? 'icons', 'font'
     label = icons ? (node.attr 'name').to_sym : node.caption.upcase
-    shift_base = @theme.prose_margin_bottom || @theme.vertical_rhythm
+    # 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)
-        # FIXME use padding from theme
-        indent @theme.horizontal_rhythm, @theme.horizontal_rhythm do
+        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
             float do
-              bounding_box [0, cursor], width: label_width + @theme.horizontal_rhythm, height: box_height do
+              bounding_box [0, cursor], width: label_width + right_padding, height: box_height do
                 # 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
@@ -418,7 +438,7 @@ class Converter < ::Prawn::Document
               end
             end
           end
-          indent label_width + @theme.horizontal_rhythm * 2 do
+          indent label_width + left_padding + right_padding do
             move_down shift_top
             layout_caption node.title if node.title?
             convert_content_for_block node
@@ -443,7 +463,7 @@ class Converter < ::Prawn::Document
           end
         end
       end
-      pad_box [@theme.vertical_rhythm, @theme.horizontal_rhythm, 0, @theme.horizontal_rhythm] do
+      pad_box @theme.example_padding do
         theme_font :example do
           convert_content_for_block node
         end
@@ -472,17 +492,17 @@ class Converter < ::Prawn::Document
 
   def convert_quote_or_verse node
     add_dest_for_block node if node.id
-    border_width = @theme.blockquote_border_width || 0
+    border_width = @theme.blockquote_border_width
     theme_margin :block, :top
     keep_together do |box_height = nil|
       start_cursor = cursor
-      # FIXME use padding from theme
-      pad_box [@theme.vertical_rhythm / 2.0, @theme.horizontal_rhythm, -(@theme.vertical_rhythm / 2.0), @theme.horizontal_rhythm + border_width / 2.0] do
+      pad_box @theme.blockquote_padding do
         theme_font :blockquote do
           if node.context == :quote
             convert_content_for_block node
           else # verse
-            layout_prose node.content, preserve: true, normalize: false, align: :left
+            content = preserve_indentation node.content, (node.attr 'tabsize')
+            layout_prose content, normalize: false, align: :left
           end
         end
         theme_font :blockquote_cite do
@@ -517,7 +537,7 @@ class Converter < ::Prawn::Document
           end
         end
       end
-      pad_box @theme.block_padding do
+      pad_box @theme.sidebar_padding do
         if node.title?
           theme_font :sidebar_title do
             # QUESTION should we allow margins of sidebar title to be customized?
@@ -527,8 +547,6 @@ class Converter < ::Prawn::Document
         theme_font :sidebar do
           convert_content_for_block node
         end
-        # FIXME HACK compensate for margin bottom of sidebar content
-        move_up(@theme.prose_margin_bottom || @theme.vertical_rhythm)
       end
     end
     theme_margin :block, :bottom
@@ -541,10 +559,10 @@ class Converter < ::Prawn::Document
       # NOTE this logic won't work for a colist nested inside a list item until Asciidoctor 1.5.3
       if (self_idx = node.parent.blocks.index node) && self_idx > 0 &&
           [:listing, :literal].include?(node.parent.blocks[self_idx - 1].context)
-        move_up ((@theme.block_margin_bottom || @theme.vertical_rhythm) / 2.0)
+        move_up @theme.block_margin_bottom / 2.0
         # or we could do...
-        #move_up (@theme.block_margin_bottom || @theme.vertical_rhythm)
-        #move_down (@theme.caption_margin_inside * 2)
+        #move_up @theme.block_margin_bottom
+        #move_down @theme.caption_margin_inside * 2
       end
     end
     add_dest_for_block node if node.id
@@ -561,8 +579,8 @@ class Converter < ::Prawn::Document
     end
     @list_numbers.pop
     # correct bottom margin of last item
-    list_margin_bottom = @theme.prose_margin_bottom || @theme.vertical_rhythm
-    margin_bottom (list_margin_bottom - (@theme.outline_list_item_spacing || (list_margin_bottom / 2.0)))
+    list_margin_bottom = @theme.prose_margin_bottom
+    margin_bottom list_margin_bottom - @theme.outline_list_item_spacing
   end
 
   def convert_colist_item node
@@ -579,7 +597,7 @@ class Converter < ::Prawn::Document
 
     indent marker_width do
       convert_content_for_list_item node,
-        margin_bottom: (@theme.outline_list_item_spacing || ((@theme.prose_margin_bottom || @theme.vertical_rhythm) / 2.0))
+        margin_bottom: @theme.outline_list_item_spacing
     end
   end
 
@@ -591,7 +609,7 @@ class Converter < ::Prawn::Document
       # FIXME extract ensure_space (or similar) method
       start_new_page if cursor < @theme.base_line_height_length * (terms.size + 1)
       terms.each do |term|
-        layout_prose term.text, style: (@theme.description_list_term_font_style || :normal).to_sym, margin_top: 0, margin_bottom: (@theme.vertical_rhythm / 3.0), align: :left
+        layout_prose term.text, style: @theme.description_list_term_font_style.to_sym, margin_top: 0, margin_bottom: @theme.description_list_term_spacing, align: :left
       end
       if desc
         indent @theme.description_list_description_indent do
@@ -674,8 +692,8 @@ class Converter < ::Prawn::Document
     # However, don't leave gap at the bottom of a nested list
     unless complex || (::Asciidoctor::List === node.parent && node.parent.outline?)
       # correct bottom margin of last item
-      list_margin_bottom = @theme.prose_margin_bottom || @theme.vertical_rhythm
-      margin_bottom(list_margin_bottom - (@theme.outline_list_item_spacing || (list_margin_bottom / 2.0)))
+      list_margin_bottom = @theme.prose_margin_bottom
+      margin_bottom list_margin_bottom - @theme.outline_list_item_spacing
     end
   end
 
@@ -721,7 +739,7 @@ class Converter < ::Prawn::Document
       convert_content_for_list_item node
     else
       convert_content_for_list_item node,
-        margin_bottom: (@theme.outline_list_item_spacing || ((@theme.prose_margin_bottom || @theme.vertical_rhythm) / 2.0))
+        margin_bottom: @theme.outline_list_item_spacing
     end
   end
 
@@ -741,9 +759,6 @@ class Converter < ::Prawn::Document
     if image_type == 'gif'
       valid_image = false
       warn %(asciidoctor: WARNING: GIF image format not supported. Please convert #{target} to PNG.)
-    #elsif image_type == 'pdf'
-    #  import_page image_path
-    #  return
     end
 
     unless (image_path = resolve_image_path node, target) && (::File.readable? image_path)
@@ -751,9 +766,12 @@ class Converter < ::Prawn::Document
       warn %(asciidoctor: WARNING: image to embed not found or not readable: #{image_path || target})
     end
 
+    # NOTE import_page automatically advances to next page afterwards
+    return import_page image_path if image_type == 'pdf'
+
     # QUESTION if we advance to new page, shouldn't dest point there too?
     add_dest_for_block node if node.id
-    position = ((node.attr 'align') || @theme.image_align || :left).to_sym
+    position = ((node.attr 'align') || @theme.image_align).to_sym
 
     unless valid_image
       theme_margin :block, :top
@@ -762,11 +780,7 @@ class Converter < ::Prawn::Document
       else
         alt_text = %([#{NoBreakSpace}#{node.attr 'alt'}#{NoBreakSpace}] | <em>#{target}</em>)
       end
-      layout_prose alt_text,
-          normalize: false,
-          margin: 0,
-          single_line: true,
-          align: position
+      layout_prose alt_text, normalize: false, margin: 0, single_line: true, align: position
       layout_caption node, position: :bottom if node.title?
       theme_margin :block, :bottom
       return
@@ -774,34 +788,33 @@ class Converter < ::Prawn::Document
 
     theme_margin :block, :top
 
+    # NOTE image is scaled proportionally based on width (height is ignored)
     # TODO support cover (aka canvas) image layout using "canvas" (or "cover") role
-    # NOTE height values are basically ignored (image is scaled proportionally based on width)
-    width = if node.attr? 'pdfwidth'
-      if (pdfwidth = node.attr 'pdfwidth').end_with? '%'
-        (pdfwidth.to_f / 100) * bounds.width
-      else
-        str_to_pt pdfwidth
-      end
-    elsif node.attr? 'scaledwidth'
-      ((node.attr 'scaledwidth').to_f / 100) * bounds.width
-    elsif node.attr? 'width'
-      # NOTE width is in pixels, so scale by 75%; restrict to max width of bounds.width
-      [bounds.width, (node.attr 'width').to_f * 0.75].min
-    end
+    width = resolve_explicit_width node.attributes, bounds.width
 
     case image_type
     when 'svg'
       begin
-        svg_obj = ::Prawn::Svg::Interface.new (::IO.read image_path), self, position: position, width: width
-        actual_w = svg_obj.document.sizing.output_width
-        actual_h = svg_obj.document.sizing.output_height
-        rel_left = { left: 0, right: (bounds.width - actual_w), center: ((bounds.width - actual_w) / 2.0) }[position]
+        svg_data = ::IO.read image_path
+        svg_obj = ::Prawn::Svg::Interface.new svg_data, self, position: position, width: width
+        svg_size = svg_obj.document.sizing
+        rendered_w = svg_size.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/recalculate method; instead, just reconstruct
+            svg_obj = ::Prawn::Svg::Interface.new svg_data, self, position: position, width: (rendered_w = adjusted_w)
+            svg_size = svg_obj.document.sizing
+          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
           svg_obj.draw
           if box_height && (link = node.attr 'link')
-            link_annotation [(abs_left = rel_left + bounds.absolute_left), y, (abs_left + actual_w), (y + actual_h)],
+            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) }
           end
@@ -812,14 +825,14 @@ class Converter < ::Prawn::Document
       end
     else
       begin
-        # FIXME temporary workaround to group caption & image
-        # Prawn doesn't provide access to rendered width & height before placing image on page
         # 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 = build_image_object image_path
         if width
           rendered_w, rendered_h = image_info.calc_image_dimensions width: width
         else
-          # NOTE native size is in pixels, so scale by 75%; restrict to max width of bounds.width
+          # 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
@@ -828,7 +841,7 @@ class Converter < ::Prawn::Document
             (@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
+          # 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
@@ -862,18 +875,40 @@ class Converter < ::Prawn::Document
   # QUESTION can we avoid arranging fragments multiple times (conums & autofit) by eagerly preparing arranger?
   def convert_listing_or_literal node
     add_dest_for_block node if node.id
+
     # HACK disable built-in syntax highlighter; must be done before calling node.content!
-    # NOTE the highlight sub is only set for coderay and pygments
-    if node.style == 'source' && !scratch? && ((subs = node.subs).include? :highlight)
-      highlighter = node.document.attr 'source-highlighter'
-      # NOTE the source highlighter logic below handles the callouts and highlight subs
-      prev_subs = subs.dup
-      subs.delete_all :highlight, :callouts
+    if node.style == 'source' && node.attributes['language'] &&
+        (highlighter = node.document.attributes['source-highlighter']) &&
+        (SourceHighlighters.include? highlighter)
+      prev_subs = (subs = node.subs).dup
+      # NOTE the highlight sub is only set for coderay and pygments atm
+      highlight_idx = subs.index :highlight
+      # NOTE scratch? here only applies if listing block is nested inside another block
+      if scratch?
+        highlighter = nil
+        if highlight_idx
+          # switch the :highlight sub back to :specialcharacters
+          subs[highlight_idx] = :specialcharacters
+        else
+          prev_subs = nil
+        end
+        source_string = preserve_indentation node.content, (node.attr 'tabsize')
+      else
+        # NOTE the source highlighter logic below handles the callouts and highlight subs
+        if highlight_idx
+          subs.delete_all :highlight, :callouts
+        else
+          subs.delete_all :specialcharacters, :callouts
+        end
+        # the indent guard will be added by the source highlighter logic
+        source_string = preserve_indentation node.content, (node.attr 'tabsize'), false
+      end
     else
       highlighter = nil
       prev_subs = nil
+      source_string = preserve_indentation node.content, (node.attr 'tabsize')
     end
-    source_string = preserve_indentation node.content
+
     source_chunks = case highlighter
     when 'coderay'
       Helpers.require_library CodeRayRequirePath, 'coderay' unless defined? ::Asciidoctor::Prawn::CodeRayEncoder
@@ -882,14 +917,22 @@ class Converter < ::Prawn::Document
       conum_mapping ? (restore_conums fragments, conum_mapping) : fragments
     when 'pygments'
       Helpers.require_library 'pygments', 'pygments.rb' unless defined? ::Pygments
-      source_string, conum_mapping = extract_conums source_string
       lexer = ::Pygments::Lexer[node.attr 'language', 'text', false] || ::Pygments::Lexer['text']
       pygments_config = { nowrap: true, noclasses: true, style: (node.document.attr 'pygments-style') || 'pastie' }
+      source_string, conum_mapping = extract_conums source_string
       result = lexer.highlight source_string, options: pygments_config
-      fragments = text_formatter.format result
+      fragments = guard_indentation text_formatter.format result
+      conum_mapping ? (restore_conums fragments, conum_mapping) : fragments
+    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'))
+      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}#{EOL})), line_numbers: (node.attr? 'linenums')
       conum_mapping ? (restore_conums fragments, conum_mapping) : fragments
     else
-      # NOTE only format if we detect a need
+      # NOTE only format if we detect a need (callouts or inline formatting)
       if source_string =~ BuiltInEntityCharOrTagRx
         text_formatter.format source_string
       else
@@ -948,6 +991,7 @@ class Converter < ::Prawn::Document
 
         pad_box @theme.code_padding do
           typeset_formatted_text source_chunks, (calc_line_metrics @theme.code_line_height),
+              # QUESTION should we require the code_font_color to be set?
               color: (@theme.code_font_color || @font_color),
               size: adjusted_font_size
         end
@@ -997,7 +1041,7 @@ class Converter < ::Prawn::Document
       elsif text.include? EOL
         text.split(EOL, -1).each_with_index do |line_in_fragment, idx|
           line = (lines[line_num += 1] ||= []) unless idx == 0
-          line << fragment.merge(text: line_in_fragment) unless line_in_fragment.empty?
+          line << (fragment.merge text: line_in_fragment) unless line_in_fragment.empty?
         end
       else
         line << fragment
@@ -1029,6 +1073,18 @@ class Converter < ::Prawn::Document
     glyph
   end
 
+  # Adds guards to preserve indentation
+  def guard_indentation fragments 
+    start_of_line = true
+    fragments.each do |fragment|
+      next if (text = fragment[:text]).empty?
+      text[0] = GuardedIndent if start_of_line && (text.start_with? ' ')
+      text.gsub! InnerIndent, GuardedInnerIndent if text.include? InnerIndent
+      start_of_line = text.end_with? EOL
+    end
+    fragments
+  end
+
   def convert_table node
     add_dest_for_block node if node.id
     num_rows = 0
@@ -1036,12 +1092,15 @@ class Converter < ::Prawn::Document
     table_header = false
     theme = @theme
 
-    # NOTE use an explicit white background if no background color is set and table is nested inside a block
-    if (tbl_bg_color = resolve_theme_color :table_background_color, @page_bg_color)
-      tbl_bg_color = nil if tbl_bg_color == 'FFFFFF' && node.parent.context == :section
-    else
-      tbl_bg_color = 'FFFFFF' unless node.parent.context == :section
-    end
+    tbl_bg_color = resolve_theme_color :table_background_color
+    # QUESTION should we fallback to page background color? (which is never transparent)
+    #tbl_bg_color = resolve_theme_color :table_background_color, @page_bg_color
+    # ...and if so, should we try to be helpful and use @page_bg_color for tables nested in blocks?
+    #unless tbl_bg_color
+    #  tbl_bg_color = @page_bg_color unless [:section, :document].include? node.parent.context
+    #end
+
+    # NOTE emulate table bg color by using it as a fallback value for each element
     head_bg_color = resolve_theme_color :table_head_background_color, tbl_bg_color
     foot_bg_color = resolve_theme_color :table_foot_background_color, tbl_bg_color
     odd_row_bg_color = resolve_theme_color :table_odd_row_background_color, tbl_bg_color
@@ -1056,12 +1115,12 @@ class Converter < ::Prawn::Document
       rows.each do |cell|
         row_data << {
           content: (head_transform ? (transform_text cell.text, head_transform) : cell.text),
-          inline_format: [{ normalize: true }],
+          inline_format: [normalize: true],
           background_color: head_bg_color,
           text_color: (theme.table_head_font_color || theme.table_font_color || @font_color),
           size: (theme.table_head_font_size || theme.table_font_size),
           font: (theme.table_head_font_family || theme.table_font_family),
-          font_style: (theme.table_head_font_style || :bold).to_sym,
+          font_style: theme.table_head_font_style.to_sym,
           colspan: cell.colspan || 1,
           rowspan: cell.rowspan || 1,
           align: (cell.attr 'halign').to_sym,
@@ -1077,7 +1136,7 @@ class Converter < ::Prawn::Document
       rows.each do |cell|
         cell_data = {
           content: cell.text,
-          inline_format: [{ normalize: true }],
+          inline_format: [normalize: true],
           text_color: (theme.table_body_font_color || @font_color),
           size: theme.table_font_size,
           font: theme.table_font_family,
@@ -1090,8 +1149,29 @@ class Converter < ::Prawn::Document
         case cell.style
         when :emphasis
           cell_data[:font_style] = :italic
-        when :strong, :header
+        when :strong
           cell_data[:font_style] = :bold
+        when :header
+          unless defined? header_cell_data
+            header_cell_data = {}
+            {
+              'align' => :align,
+              'font_color' => :text_color,
+              'font_family' => :font,
+              'font_size' => :size,
+              'font_style' => :font_style
+            }.each do |theme_key, key|
+              if (val = theme[%(table_header_cell_#{theme_key})])
+                header_cell_data[key] = val
+              end
+            end
+            header_cell_data[:font_style] ||= :bold
+            if (val = resolve_theme_color :table_header_cell_background_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
           if (size = theme.literal_font_size)
@@ -1107,8 +1187,6 @@ class Converter < ::Prawn::Document
       table_data << row_data
     end
 
-    column_widths = node.columns.map {|col| ((col.attr 'colpcwidth') * bounds.width) / 100.0 }
-
     border = {}
     table_border_width = theme.table_border_width
     [:top, :bottom, :left, :right, :cols, :rows].each {|edge| border[edge] = table_border_width }
@@ -1134,6 +1212,13 @@ class Converter < ::Prawn::Document
       border[:top] = border[:right] = border[:bottom] = border[:left] = 0
     end
 
+    if node.option? 'autowidth'
+      column_widths = []
+    else
+      table_width = bounds.width * ((node.attr 'tablepcwidth') / 100.0)
+      column_widths = node.columns.map {|col| ((col.attr 'colpcwidth') * table_width) / 100.0 }
+    end
+
     table_settings = {
       header: table_header,
       cell_style: {
@@ -1191,7 +1276,7 @@ class Converter < ::Prawn::Document
 
   def convert_thematic_break node
     theme_margin :thematic_break, :top
-    stroke_horizontal_rule @theme.thematic_break_border_color, line_width: @theme.thematic_break_border_width, line_style: (@theme.thematic_break_border_style || :solid).to_sym
+    stroke_horizontal_rule @theme.thematic_break_border_color, line_width: @theme.thematic_break_border_width, line_style: @theme.thematic_break_border_style.to_sym
     theme_margin :thematic_break, :bottom
   end
 
@@ -1203,6 +1288,7 @@ class Converter < ::Prawn::Document
     nil
   end
 
+  # NOTE to insert sequential page breaks, you must put {nbsp} between page breaks
   def convert_page_break node
     start_new_page unless at_page_top?
   end
@@ -1275,10 +1361,10 @@ class Converter < ::Prawn::Document
   def convert_inline_footnote node
     if (index = node.attr 'index')
       #text = node.document.footnotes.find {|fn| fn.index == index }.text
-      %(<sup>[#{index}: #{node.text}]</sup>)
+      %( <color rgb="#999999">[#{index}: #{node.text}]</color>)
     elsif node.type == :xref
       # NOTE footnote reference not found
-      %(<sup><color rgb="FF0000">[#{node.text}]</color></sup>)
+      %( <color rgb="FF0000">[#{node.text}]</color>)
     end
   end
 
@@ -1386,40 +1472,19 @@ class Converter < ::Prawn::Document
 
   # FIXME only create title page if doctype=book!
   def layout_title_page doc
-    return unless doc.header? && !doc.noheader && !doc.notitle
+    return unless doc.header? && !doc.notitle
 
     prev_bg_image = @page_bg_image
     prev_bg_color = @page_bg_color
-    if (bg_image = (doc.attr 'title-background-image', @theme.title_page_background_image))
-      if bg_image == 'none'
-        @page_bg_image = nil
-      else
-        if bg_image =~ ImageAttributeValueRx
-          bg_image = $1
-          # QUESTION should we support width and height?
-        end
 
-        # NOTE resolve image relative to its origin
-        resolved_bg_image = if doc.attr? 'title-background-image'
-          resolve_image_path doc, bg_image
-        else
-          ThemeLoader.resolve_theme_asset bg_image, (doc.attr 'pdf-stylesdir')
-        end
-
-        if resolved_bg_image && (::File.readable? resolved_bg_image)
-          @page_bg_image = resolved_bg_image
-        else
-          warn %(asciidoctor: WARNING: title page background image #{resolved_bg_image || bg_image} not found or readable)
-          bg_image = nil
-        end
-      end
+    if (bg_image = resolve_background_image doc, @theme, 'title-page-background-image')
+      @page_bg_image = (bg_image == 'none' ? nil : bg_image)
     end
-    if !bg_image && (bg_color = resolve_theme_color :title_page_background_color)
+    if (bg_color = resolve_theme_color :title_page_background_color)
       @page_bg_color = bg_color
-    else
-      bg_color = nil
     end
-    start_new_page
+    # NOTE a new page will already be started if the cover image is a PDF
+    start_new_page unless page_is_empty?
     @page_bg_image = prev_bg_image if bg_image
     @page_bg_color = prev_bg_color if bg_color
 
@@ -1427,24 +1492,23 @@ class Converter < ::Prawn::Document
     font @theme.base_font_family, size: @theme.base_font_size
 
     # QUESTION allow aligment per element on title page?
-    title_align = (@theme.title_page_align || :center).to_sym
+    title_align = @theme.title_page_align.to_sym
 
-    # FIXME rework image handling once fix for #134 is merged
+    # TODO disallow .pdf as image type
     if (logo_image_path = (doc.attr 'title-logo-image', @theme.title_page_logo_image))
-      if logo_image_path =~ ImageAttributeValueRx
+      if (logo_image_path.include? ':') && logo_image_path =~ ImageAttributeValueRx
         logo_image_path = $1
-        logo_image_attrs = AttributeList.new($2).parse(['alt', 'width', 'height'])
+        logo_image_attrs = (AttributeList.new $2).parse ['alt', 'width', 'height']
       else
         logo_image_attrs = {}
       end
       # HACK quick fix to resolve image path relative to theme
       unless doc.attr? 'title-logo-image'
-        # FIXME use ThemeLoader.resolve_theme_asset once fix for #134 is merged
-        logo_image_path = ::File.expand_path logo_image_path, (doc.attr 'pdf-stylesdir', ThemeLoader::ThemesDir)
+        logo_image_path = ThemeLoader.resolve_theme_asset logo_image_path, (doc.attr 'pdf-stylesdir')
       end
       logo_image_attrs['target'] = logo_image_path
       logo_image_attrs['align'] ||= (@theme.title_page_logo_align || title_align.to_s)
-      logo_image_top = (logo_image_attrs['top'] || @theme.title_page_logo_top || '10%')
+      logo_image_top = (logo_image_attrs['top'] || @theme.title_page_logo_top)
       # FIXME delegate to method to convert page % to y value
       logo_image_top = [(page_height - page_height * (logo_image_top.to_i / 100.0)), bounds.absolute_top].min
       float do
@@ -1452,6 +1516,7 @@ class Converter < ::Prawn::Document
         # 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
       end
     end
@@ -1511,12 +1576,13 @@ class Converter < ::Prawn::Document
     # TODO turn processing of attribute with inline image a utility function in Asciidoctor
     # FIXME verify cover_image exists!
     if (cover_image = (doc.attr %(#{position}-cover-image)))
-      if cover_image =~ ImageAttributeValueRx
+      if (cover_image.include? ':') && cover_image =~ ImageAttributeValueRx
         cover_image = resolve_image_path doc, $1
       end
       # QUESTION should we go to page 1 when position == :front?
       go_to_page page_count if position == :back
       if cover_image.downcase.end_with? '.pdf'
+        # NOTE import_page automatically advances to next page afterwards
         import_page cover_image
       else
         image_page cover_image, canvas: true
@@ -1554,8 +1620,8 @@ class Converter < ::Prawn::Document
 
   # NOTE inline_format is true by default
   def layout_prose string, opts = {}
-    top_margin = (margin = (opts.delete :margin)) || (opts.delete :margin_top) || @theme.prose_margin_top || 0
-    bot_margin = margin || (opts.delete :margin_bottom) || @theme.prose_margin_bottom || @theme.vertical_rhythm
+    top_margin = (margin = (opts.delete :margin)) || (opts.delete :margin_top) || @theme.prose_margin_top
+    bot_margin = margin || (opts.delete :margin_bottom) || @theme.prose_margin_bottom
     if (transform = (opts.delete :text_transform) || @text_transform)
       string = transform_text string, transform
     end
@@ -1568,14 +1634,12 @@ class Converter < ::Prawn::Document
         string = %(<a anchor="#{anchor}">#{string}</a>)
       end
     end
-    # preserve leading space using non-breaking space chars
-    string = preserve_indentation string if opts.delete :preserve
     margin_top top_margin
     typeset_text string, calc_line_metrics((opts.delete :line_height) || @theme.base_line_height), {
       color: @font_color,
       # NOTE normalize makes endlines soft (replaces "\n" with ' ')
-      inline_format: [{ normalize: (opts.delete :normalize) != false }],
-      align: (@theme.base_align || :left).to_sym
+      inline_format: [normalize: (opts.delete :normalize) != false],
+      align: @theme.base_align.to_sym
     }.merge(opts)
     margin_bottom bot_margin
   end
@@ -1602,7 +1666,7 @@ class Converter < ::Prawn::Document
       layout_prose string, {
         margin_top: margin[:top],
         margin_bottom: margin[:bottom],
-        align: (@theme.caption_align || :left).to_sym,
+        align: @theme.caption_align.to_sym,
         normalize: false
       }.merge(opts)
       if position == :top && @theme.caption_border_bottom_color
@@ -1627,7 +1691,7 @@ class Converter < ::Prawn::Document
     # QUESTION shouldn't we skip this whole method if num_levels == 0?
     if num_levels > 0
       theme_margin :toc, :top
-      line_metrics = calc_line_metrics @theme.toc_line_height || @theme.base_line_height
+      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)
@@ -1665,6 +1729,7 @@ class Converter < ::Prawn::Document
           # 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
             { text: NoBreakSpace, size: (@font_size * 0.5) },
             { text: sect_page_num.to_s, anchor: sect_anchor, color: @font_color }], line_metrics, align: :right
           go_to_page end_page_number if start_page_number != end_page_number
@@ -1672,7 +1737,7 @@ class Converter < ::Prawn::Document
         end
       end
       if sect.level < num_levels
-        indent(@theme.toc_indent || @theme.outline_list_indent) do
+        indent @theme.toc_indent do
           layout_toc_level sect.sections, num_levels, line_metrics, dot_width, num_front_matter_pages
         end
       end
@@ -1695,7 +1760,7 @@ class Converter < ::Prawn::Document
     num_pages = page_count - skip
 
     # FIXME probably need to treat doctypes differently
-    sections = doc.find_by(context: :section) {|sect| sect.level < 3 }
+    sections = doc.find_by(context: :section) {|sect| sect.level < 3 } || []
 
     # index chapters and sections by the visual page number on which they start
     chapter_start_pages = {}
@@ -1726,49 +1791,52 @@ class Converter < ::Prawn::Document
       sections_by_page[num] = last_sect
     end
 
-    doctitle = doc.doctitle partition: true
+    doctitle = doc.doctitle partition: true, use_fallback: true
     # NOTE set doctitle again so it's properly escaped
     doc.set_attr 'doctitle', doctitle.combined
     doc.set_attr 'document-title', doctitle.main
     doc.set_attr 'document-subtitle', doctitle.subtitle
     doc.set_attr 'page-count', num_pages
 
+    fallback_footer_content = {
+      recto: { right: '{page-number}' },
+      verso: { left: '{page-number}' }
+    }
     # TODO move this to a method so it can be reused; cache results
     content_dict = [:recto, :verso].inject({}) do |acc, side|
       side_content = {}
       Alignments.each do |align|
         if (val = @theme[%(#{position}_#{side}_content_#{align})])
-          if ImageAttributeValueRx =~ val &&
+          # 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
-            attrs['width'] = attrs['width'].to_f if attrs['width']
-            side_content[align] = { path: path, width: attrs['width'] }
+            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[align] = { path: path, width: width }
           else
-            side_content[align] ||= val
+            side_content[align] = val
           end
         end
       end
-      if (acc[side] = side_content).empty? && @theme[%(footer_#{side}_content)] != 'none'
-        # NOTE set fallbacks if not explicitly disabled
-        case side
-        when :recto
-          acc[side] = { right: '{page-number}' }
-        when :verso
-          acc[side] = { left: '{page-number}' }
-        end
+      # NOTE set fallbacks if not explicitly disabled
+      if side_content.empty? && position == :footer && @theme[%(footer_#{side}_content)] != 'none'
+        side_content = fallback_footer_content[side]
       end
+
+      acc[side] = side_content
       acc
     end
 
-    # QUESTION should we support footer_line_height?
-    #trim_line_metrics = calc_line_metrics @theme.base_line_height
-    trim_line_metrics = calc_line_metrics
     if position == :header
+      trim_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 = @theme.header_padding || [0, 0, 0, 0]
-      trim_content_height = trim_height - trim_padding[0] - trim_padding[2] - trim_line_metrics.padding_top
       trim_left = page_margin_left
       trim_width = page_width - trim_left - page_margin_right
       trim_font_color = @theme.header_font_color || @font_color
@@ -1776,13 +1844,13 @@ class Converter < ::Prawn::Document
       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_valign || :center).to_sym
-      trim_img_valign = @theme.header_image_valign || trim_valign
+      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 = @theme.footer_padding || [0, 0, 0, 0]
-      trim_content_height = trim_height - trim_padding[0] - trim_padding[2] - trim_line_metrics.padding_top
       trim_left = page_margin_left
       trim_width = page_width - trim_left - page_margin_right
       trim_font_color = @theme.footer_font_color || @font_color
@@ -1790,19 +1858,29 @@ class Converter < ::Prawn::Document
       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_valign || :center).to_sym
-      trim_img_valign = @theme.footer_image_valign || trim_valign
+      trim_valign = (@theme.footer_vertical_align || :middle).to_sym
+      trim_img_valign = @theme.footer_image_vertical_align
     end
 
-    trim_stamp = %(#{position})
+    trim_stamp = position.to_s
     trim_content_left = trim_left + trim_padding[3]
+    trim_content_height = trim_height - trim_padding[0] - trim_padding[2] - trim_line_metrics.padding_top - trim_line_metrics.padding_bottom
     trim_content_width = trim_width - trim_padding[3] - trim_padding[1]
     trim_border_color = nil if trim_border_width == 0
-    if ['top', 'center', 'bottom'].include? trim_img_valign
+    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
 
     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
       create_stamp trim_stamp do
         canvas do
           if trim_bg_color
@@ -1824,17 +1902,20 @@ class Converter < ::Prawn::Document
         end
       end
       @stamps[position] = true
+      go_to_page prev_page_number
     end
 
+    pagenums_enabled = doc.attr? 'pagenums'
     repeat (start..page_count), dynamic: true do
       # NOTE don't write on pages which are imported / inserts (otherwise we can get a corrupt PDF)
       next if page.imported_page?
       visual_pgnum = page_number - skip
       # FIXME we need to have a content setting for chapter pages
       content_by_alignment = content_dict[visual_pgnum.odd? ? :recto : :verso]
-      doc.set_attr 'page-number', visual_pgnum
       # TODO populate chapter-number
       # TODO populate numbered and unnumbered chapter and section titles
+      # FIXME leave page-number attribute unset once we filter lines with unresolved attributes (see below)
+      doc.set_attr 'page-number', (pagenums_enabled ? visual_pgnum : '')
       doc.set_attr 'chapter-title', (chapters_by_page[visual_pgnum] || '')
       doc.set_attr 'section-title', (sections_by_page[visual_pgnum] || '')
       doc.set_attr 'section-or-chapter-title', (sections_by_page[visual_pgnum] || chapters_by_page[visual_pgnum] || '')
@@ -1848,16 +1929,26 @@ class Converter < ::Prawn::Document
               # FIXME we need to have a content setting for chapter pages
               case (content = content_by_alignment[align])
               when ::Hash
-                # FIXME prevent image from overflowing the page
-                float do
-                  # FIXME padding doesn't work when vposition is specified; how will padding bottom work?
-                  #move_down trim_padding[0]
-                  image content[:path], vposition: trim_img_valign, position: align, width: content[:width]
+                # NOTE image placement respects padding; use negative image_vertical_align value to revert
+                trim_v_padding = trim_padding[0] + trim_padding[2]
+                # NOTE bounding_box is redundant if trim_v_padding is 0
+                bounding_box [0, cursor - trim_padding[0]], width: bounds.width, height: (bounds.height - trim_v_padding) do
+                  # NOTE float ensures cursor position is restored and returns us to current page if we overrun
+                  float do
+                    #image content[:path], vposition: trim_img_valign, position: 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: align, fit: [content[:width], bounds.height]
+                  end
                 end
               when ::String
-                content = (content == '{page-number}' ? %(#{visual_pgnum}) : (doc.apply_subs content))
-                formatted_text_box parse_text(content, color: trim_font_color, inline_format: true),
-                  at: [0, trim_content_height + trim_padding[2]],
+                if content == '{page-number}'
+                  content = pagenums_enabled ? visual_pgnum.to_s : nil
+                else
+                  # FIXME drop lines with unresolved attributes
+                  content = doc.apply_subs content
+                end
+                formatted_text_box parse_text(content, color: trim_font_color, inline_format: [normalize: true]),
+                  at: [0, trim_content_height + trim_padding[2] + trim_line_metrics.padding_bottom],
                   height: trim_content_height,
                   align: align,
                   valign: trim_valign,
@@ -1884,7 +1975,7 @@ class Converter < ::Prawn::Document
 
     # title page (i)
     # TODO same conditional logic as in layout_title_page; consolidate
-    if doc.header? && !doc.noheader && !doc.notitle
+    if doc.header? && !doc.notitle
       page_num_labels[0] = { P: ::PDF::Core::LiteralString.new(front_matter_counter.next!.to_s) }
     end
 
@@ -1935,11 +2026,18 @@ class Converter < ::Prawn::Document
   end
 
   def write pdf_doc, target
-    pdf_doc.render_file target
+    if target.respond_to? :write
+      require_relative 'core_ext/quantifiable_stdout' unless defined? ::QuantifiableStdout
+      target = ::QuantifiableStdout.new STDOUT if target == STDOUT
+      pdf_doc.render target
+    else
+      pdf_doc.render_file target
+      # QUESTION restore attributes first?
+      @pdfmarks.generate_file target if @pdfmarks
+    end
     # write scratch document if debug is enabled (or perhaps DEBUG_STEPS env)
     #get_scratch_document.render_file 'scratch.pdf'
-    # QUESTION restore attributes first?
-    @pdfmarks.generate_file target if @pdfmarks
+    nil
   end
 
   def register_fonts font_catalog, scripts = 'latin', fonts_dir
@@ -1988,18 +2086,22 @@ class Converter < ::Prawn::Document
   # Start a new page if y value is greater than remaining space on page.
   def margin y, position
     unless y == 0 || at_page_top?
-      if cursor <= y
-        @margin_box.move_past_bottom
-      else
+      if cursor > y
         move_down y
+      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
       end
     end
   end
 
   # Lookup margin for theme element and position, then delegate to margin method.
-  # If the margin value is not found, assume 0 for position = :top and $vertical_rhythm for position = :bottom.
+  # If margin value is not found, assume:
+  # - 0 when position = :top
+  # - @theme.vertical_spacing when position = :bottom
   def theme_margin category, position
-    margin(@theme[%(#{category}_margin_#{position})] || (position == :bottom ? @theme.vertical_rhythm : 0), position)
+    margin (@theme[%(#{category}_margin_#{position})] || (position == :bottom ? @theme.vertical_spacing : 0)), position
   end
 
   def theme_font category, opts = {}
@@ -2042,22 +2144,20 @@ class Converter < ::Prawn::Document
     arranger = arrange_fragments_by_line fragments
     adjusted_font_size = nil
     theme_font category do
-      # NOTE finalizing the line here generates fragments using current font settings
+      # 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
       end
-      bounds.add_left_padding(p_left = padding[3] || 0)
-      bounds.add_right_padding(p_right = padding[1] || 0)
-      if actual_width > bounds.width
-        adjusted_font_size = ((bounds.width * font_size).to_f / actual_width).with_precision 4
+      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
         if (min = @theme[%(#{category}_font_size_min)] || @theme.base_font_size_min) && adjusted_font_size < min
           adjusted_font_size = min
         end
       end
-      bounds.subtract_left_padding p_left
-      bounds.subtract_right_padding p_right
     end
     adjusted_font_size
   end
@@ -2074,7 +2174,7 @@ class Converter < ::Prawn::Document
         by_line << fragment
       elsif txt.include? EOL
         txt.scan(LineScanRx) do |line|
-          by_line << fragment.merge(text: line)
+          by_line << (line == EOL ? { text: EOL } : (fragment.merge text: line))
         end
       else
         by_line << fragment
@@ -2125,8 +2225,60 @@ class Converter < ::Prawn::Document
     (height_of string, leading: line_metrics.leading, final_gap: line_metrics.final_gap) + line_metrics.padding_top + line_metrics.padding_bottom
   end
 
-  def preserve_indentation string
-    string.gsub(IndentationRx) { NoBreakSpace * $&.length }
+  def preserve_indentation string, tab_size = nil, guard_indent = true
+    return '' unless string
+    # expand tabs if they aren't already expanded, even if explicitly disabled
+    # NOTE Asciidoctor >= 1.5.3 already replaces tabs if tabsize attribute is positive
+    if ((tab_size = tab_size.to_i) < 1 || !@capabilities[:expands_tabs]) && (string.include? TAB)
+      # Asciidoctor <= 1.5.2 already does tab replacement in some cases, so be consistent about tab size
+      full_tab_space = ' ' * (tab_size = 4)
+      result = []
+      string.each_line do |line|
+        if line.start_with? TAB
+          # NOTE '+' operator is faster than interpolation in this case
+          if guard_indent
+            line.sub!(TabIndentRx) {|tabs| GuardedIndent + (full_tab_space * tabs.length).chop! }
+          else
+            line.sub!(TabIndentRx) {|tabs| full_tab_space * tabs.length }
+          end
+          leading_space = false
+        # QUESTION should we check for EOL first?
+        elsif line == EOL
+          result << line
+          next
+        else
+          leading_space = guard_indent && (line.start_with? ' ')
+        end
+
+        if line.include? TAB
+          # keep track of how many spaces were added to adjust offset in match data
+          spaces_added = 0
+          line.gsub!(TabRx) {
+            # calculate how many spaces this tab represents, then replace tab with spaces
+            if (offset = ($~.begin 0) + spaces_added) % tab_size == 0
+              spaces_added += (tab_size - 1)
+              full_tab_space
+            else
+              unless (spaces = tab_size - offset % tab_size) == 1
+                spaces_added += (spaces - 1)
+              end
+              ' ' * spaces
+            end
+          }
+        end
+
+        # NOTE we save time by adding indent guard per line while performing tab expansion
+        line[0] = GuardedIndent if leading_space
+        result << line
+      end
+      result.join
+    else
+      if guard_indent
+        string[0] = GuardedIndent if string.start_with? ' '
+        string.gsub! InnerIndent, GuardedInnerIndent if string.include? InnerIndent
+      end
+      string
+    end
   end
 
   # If an id is provided or the node passed as the first argument has an id,
@@ -2209,6 +2361,57 @@ class Converter < ::Prawn::Document
     end
   end
 
+  # Resolve the path to 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.
+  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?
+        bg_image = $1
+      end
+
+      if (bg_image = doc_attr_val ? (resolve_image_path doc, bg_image) :
+          (ThemeLoader.resolve_theme_asset bg_image, (doc.attr 'pdf-stylesdir')))
+        if ::File.readable? bg_image
+          bg_image
+        else
+          warn %(asciidoctor: WARNING: #{key.tr '-', ' '} #{bg_image} not found or readable)
+          nil
+        end
+      end
+    end
+  end
+
+  # Resolves the explicit width as a PDF pt value, if specified.
+  #
+  # Resolves the explicit width, first considering the pdfwidth attribute, then
+  # the scaledwidth attribute and finally the width attribute. If the specified
+  # value is in pixels, the value is scaled by 75% to perform approximate
+  # CSS px to PDF pt conversion. If the resolved width is larger than the
+  # max_width, the max_width value is returned.
+  #--
+  # QUESTION should we enforce positive result?
+  def resolve_explicit_width attrs, max_width = bounds.width
+    if attrs.key? 'pdfwidth'
+      if (pdfwidth = attrs['pdfwidth']).end_with? '%'
+        (pdfwidth.to_f / 100) * max_width
+      else
+        str_to_pt pdfwidth
+      end
+    elsif attrs.key? 'scaledwidth'
+      (attrs['scaledwidth'].to_f / 100) * max_width
+    elsif attrs.key? 'width'
+      # QUESTION should we honor percentage width value?
+      # NOTE scale width down 75% to convert px to pt; restrict width to bounds.width
+      [max_width, attrs['width'].to_f * 0.75].min
+    end
+  end
+
   # QUESTION is there a better way to do this?
   # I suppose we could have @tmp_files as an instance variable on converter instead
   # It might be sufficient to delete temporary files once per conversion