asciidoctor-pdf 1.5.0.beta.2 → 1.5.0.beta.3

data/lib/asciidoctor-pdf/converter.rb

@@ -39,8 +39,8 @@ class Converter < ::Prawn::Document
   register_for 'pdf'
 
   # 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')
-  RougeRequirePath = ::File.join((::File.dirname __FILE__), 'rouge_ext')
+  CodeRayRequirePath = ::File.join __dir__, 'prawn_ext/coderay_encoder'
+  RougeRequirePath = ::File.join __dir__, 'rouge_ext'
 
   AsciidoctorVersion = ::Gem::Version.create ::Asciidoctor::VERSION
   AdmonitionIcons = {
@@ -101,6 +101,7 @@ class Converter < ::Prawn::Document
   UriSchemeBoundaryRx = /(?<=:\/\/)/
   LineScanRx = /\n|.+/
   BlankLineRx = /\n{2,}/
+  CjkLineBreakRx = /(?=[\u3000\u30a0-\u30ff\u3040-\u309f\p{Han}\uff00-\uffef])/
   WhitespaceChars = ' ' + TAB + LF
   SourceHighlighters = ['coderay', 'pygments', 'rouge'].to_set
   PygmentsBgColorRx = /^\.highlight +{ *background: *#([^;]+);/
@@ -121,7 +122,6 @@ class Converter < ::Prawn::Document
       doc.attributes['data-uri'] = ((doc.instance_variable_get :@attribute_overrides) || {})['data-uri'] = ''
     end
     @capabilities = {
-      expands_tabs: (::Asciidoctor::VERSION.start_with? '1.5.3.') || AsciidoctorVersion >= (::Gem::Version.create '1.5.3'),
       special_sectnums: AsciidoctorVersion >= (::Gem::Version.create '1.5.7'),
       syntax_highlighter: AsciidoctorVersion >= (::Gem::Version.create '2.0.0'),
     }
@@ -196,12 +196,12 @@ class Converter < ::Prawn::Document
         theme_font :heading, level: 1 do
           layout_heading doc.doctitle, align: (@theme.heading_h1_align || :center).to_sym, level: 1
         end
-        toc_start = @y
       end
+      toc_start = @y
     end
 
     # NOTE font must be set before toc dry run to ensure dry run size is accurate
-    font @theme.base_font_family, size: @theme.base_font_size, style: (@theme.base_font_style || :normal).to_sym
+    font @theme.base_font_family, size: @root_font_size, style: (@theme.base_font_style || :normal).to_sym
 
     num_toc_levels = (doc.attr 'toclevels', 2).to_i
     if (insert_toc = (doc.attr? 'toc') && doc.sections?)
@@ -222,9 +222,7 @@ class Converter < ::Prawn::Document
       end
     end
 
-    # FIXME only apply to book doctype once title and toc are moved to start page when using article doctype
-    #start_new_page if @ppbook && verso_page?
-    start_new_page if @media == 'prepress' && verso_page?
+    start_new_page if @ppbook && verso_page?
 
     if insert_title_page
       body_offset = (body_start_page_number = page_number) - 1
@@ -278,9 +276,16 @@ class Converter < ::Prawn::Document
     end
 
     add_outline doc, (doc.attr 'outlinelevels', num_toc_levels).to_i, toc_page_nums, num_front_matter_pages[1]
-    # TODO allow document (or theme) to override initial view magnification
-    # NOTE add 1 to page height to force initial scroll to 0; a nil value also seems to work
-    catalog.data[:OpenAction] = dest_fit_horizontally((page_height + 1), state.pages[0]) if state.pages.size > 0
+    if state.pages.size > 0 && (initial_zoom = @theme.page_initial_zoom)
+      case initial_zoom.to_sym
+      when :Fit
+        catalog.data[:OpenAction] = dest_fit state.pages[0]
+      when :FitV
+        catalog.data[:OpenAction] = dest_fit_vertically 0, state.pages[0]
+      when :FitH
+        catalog.data[:OpenAction] = dest_fit_horizontally page_height, state.pages[0]
+      end
+    end
     catalog.data[:ViewerPreferences] = { DisplayDocTitle: true }
 
     layout_cover_page doc, :back
@@ -294,11 +299,10 @@ class Converter < ::Prawn::Document
 
   # TODO only allow method to be called once (or we need a reset)
   def init_pdf doc
-    @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
+    ((::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'
@@ -313,12 +317,13 @@ class Converter < ::Prawn::Document
       # NOTE prepare scratch document to use page margin from recto side (which has same width as verso side)
       set_page_margin page_margin_recto unless page_margin_recto == page_margin
     else
-      @ppbook = false
+      @ppbook = nil
     end
     # QUESTION should ThemeLoader handle registering fonts instead?
-    register_fonts theme.font_catalog, (doc.attr 'scripts', 'latin'), (doc.attr 'pdf-fontsdir', ThemeLoader::FontsDir)
+    register_fonts theme.font_catalog, (doc.attr 'pdf-fontsdir', ThemeLoader::FontsDir)
     default_kerning theme.base_font_kerning != 'none'
     @fallback_fonts = [*theme.font_fallbacks]
+    @allow_uri_read = doc.attr? 'allow-uri-read'
     if (bg_image = resolve_background_image doc, theme, 'page-background-image') && bg_image[0]
       @page_bg_image = { verso: bg_image, recto: bg_image }
     else
@@ -331,8 +336,10 @@ class Converter < ::Prawn::Document
       @page_bg_image[:recto] = bg_image[0] && bg_image
     end
     @page_bg_color = resolve_theme_color :page_background_color, 'FFFFFF'
+    @root_font_size = theme.base_font_size || 12
     @font_color = theme.base_font_color || '000000'
     @base_align = (align = doc.attr 'text-align') && (TextAlignmentNames.include? align) ? align : theme.base_align
+    @cjk_line_breaks = doc.attr? 'scripts', 'cjk'
     @text_transform = nil
     @list_numerals = []
     @list_bullets = []
@@ -351,18 +358,17 @@ class Converter < ::Prawn::Document
   def load_theme doc
     @theme ||= begin
       if (theme = doc.options[:pdf_theme])
-        @themesdir = theme.__dir__ || (doc.attr 'pdf-themesdir') || (doc.attr 'pdf-stylesdir')
+        @themesdir = ::File.expand_path theme.__dir__ || (doc.attr 'pdf-themesdir') || (doc.attr 'pdf-stylesdir') || ::Dir.pwd
       elsif (theme_name = (doc.attr 'pdf-theme') || (doc.attr 'pdf-style'))
-        theme = ThemeLoader.load_theme theme_name, (theme_dir = (doc.attr 'pdf-themesdir') || (doc.attr 'pdf-stylesdir'))
+        theme = ThemeLoader.load_theme theme_name, (user_themesdir = (doc.attr 'pdf-themesdir') || (doc.attr 'pdf-stylesdir'))
         @themesdir = theme.__dir__
       else
-        theme = ThemeLoader.load_theme
-        @themesdir = theme.__dir__
+        @themesdir = (theme = ThemeLoader.load_theme).__dir__
       end
       theme
     rescue
-      if theme_dir
-        message = %(could not locate or load the pdf theme `#{theme_name}' in #{::File.absolute_path theme_dir})
+      if user_themesdir
+        message = %(could not locate or load the pdf theme `#{theme_name}' in #{user_themesdir})
       else
         message = %(could not locate or load the built-in pdf theme `#{theme_name}')
       end
@@ -457,18 +463,10 @@ class Converter < ::Prawn::Document
     info = {}
     # FIXME use sanitize: :plain_text once available
     info[:Title] = sanitize(doc.doctitle use_fallback: true).as_pdf
-    if doc.attr? 'authors'
-      info[:Author] = (doc.attr 'authors').as_pdf
-    end
-    if doc.attr? 'subject'
-      info[:Subject] = (doc.attr 'subject').as_pdf
-    end
-    if doc.attr? 'keywords'
-      info[:Keywords] = (doc.attr 'keywords').as_pdf
-    end
-    if (doc.attr? 'publisher')
-      info[:Producer] = (doc.attr 'publisher').as_pdf
-    end
+    info[:Author] = (doc.attr 'authors').as_pdf if doc.attr? 'authors'
+    info[:Subject] = (doc.attr 'subject').as_pdf if doc.attr? 'subject'
+    info[:Keywords] = (doc.attr 'keywords').as_pdf if doc.attr? 'keywords'
+    info[:Producer] = (doc.attr 'publisher').as_pdf if doc.attr? 'publisher'
     info[:Creator] = %(Asciidoctor PDF #{::Asciidoctor::PDF::VERSION}, based on Prawn #{::Prawn::VERSION}).as_pdf
     info[:Producer] ||= (info[:Author] || info[:Creator])
     unless doc.attr? 'reproducible'
@@ -487,14 +485,16 @@ class Converter < ::Prawn::Document
     if @media == 'prepress' && (next_page_margin = @page_margin_by_side[page_side]) != page_margin
       set_page_margin next_page_margin
     end
+    if @page_bg_color && @page_bg_color != 'FFFFFF'
+      tare = true
+      fill_absolute_bounds @page_bg_color
+    end
     # TODO implement as a watermark (on top)
     if (bg_image = @page_bg_image[page_side])
+      tare = true
       canvas { image bg_image[0], ({ position: :center, vposition: :center }.merge bg_image[1]) }
-      page.tare_content_stream
-    elsif @page_bg_color && @page_bg_color != 'FFFFFF'
-      fill_absolute_bounds @page_bg_color
-      page.tare_content_stream
     end
+    page.tare_content_stream if tare
   end
 
   def convert_section sect, opts = {}
@@ -511,14 +511,24 @@ class Converter < ::Prawn::Document
       if sect.part_or_chapter?
         if sect.chapter?
           type = :chapter
-          start_new_chapter sect
+          if @theme.heading_chapter_break_before == 'auto'
+            start_new_chapter sect if @theme.heading_part_break_after == 'always' && sect == sect.parent.sections[0]
+          else
+            start_new_chapter sect
+          end
         else
           type = :part
-          start_new_part sect
+          start_new_part sect unless @theme.heading_part_break_before == 'auto'
         end
-      else
-        # FIXME smarter calculation here!!
-        start_new_page unless at_page_top? || cursor > (height_of title) + @theme.heading_margin_top + @theme.heading_margin_bottom + ((@theme.base_line_height_length || (font_size * @theme.base_line_height)) * 1.5)
+      end
+      unless at_page_top?
+        # FIXME this height doesn't account for impact of text transform or inline formatting
+        heading_height =
+          (height_of_typeset_text title, line_height: (@theme[%(heading_h#{hlevel}_line_height)] || @theme.heading_line_height)) +
+          (@theme[%(heading_h#{hlevel}_margin_top)] || @theme.heading_margin_top || 0) +
+          (@theme[%(heading_h#{hlevel}_margin_bottom)] || @theme.heading_margin_bottom || 0)
+        heading_height += (@theme.heading_min_height_after || 0) if sect.blocks?
+        start_new_page unless cursor > heading_height
       end
       # QUESTION should we store pdf-page-start, pdf-anchor & pdf-destination in internal map?
       sect.set_attr 'pdf-page-start', (start_pgnum = page_number)
@@ -567,13 +577,11 @@ class Converter < ::Prawn::Document
   def convert_abstract node
     add_dest_for_block node if node.id
     pad_box @theme.abstract_padding do
-      if node.title?
-        theme_font :abstract_title do
-          layout_heading node.title, align: (@theme.abstract_title_align || @base_align).to_sym
-        end
-      end
+      theme_font :abstract_title do
+        layout_heading node.title, align: (@theme.abstract_title_align || @base_align).to_sym, margin_top: (@theme.heading_margin_top || 0), margin_bottom: (@theme.heading_margin_bottom || 0)
+      end if node.title?
       theme_font :abstract do
-        prose_opts = { line_height: @theme.abstract_line_height, align: (@theme.abstract_align || @base_align).to_sym }
+        prose_opts = { line_height: @theme.abstract_line_height, align: (initial_alignment = (@theme.abstract_align || @base_align).to_sym) }
         if (text_indent = @theme.prose_text_indent)
           prose_opts[:indent_paragraphs] = text_indent
         end
@@ -587,14 +595,21 @@ class Converter < ::Prawn::Document
             # FIXME is playback necessary here?
             child.document.playback_attributes child.attributes
             if child.context == :paragraph
+              if (alignment = resolve_alignment_from_role child.roles)
+                prose_opts[:align] = alignment
+              end
               layout_prose child.content, prose_opts
               prose_opts.delete :first_line_options
+              prose_opts[:align] = initial_alignment
             else
               # FIXME this could do strange things if the wrong kind of content shows up
               convert_content_for_block child
             end
           end
         elsif node.content_model != :compound && (string = node.content)
+          if (alignment = resolve_alignment_from_role node.roles)
+            prose_opts[:align] = alignment
+          end
           layout_prose string, prose_opts
         end
       end
@@ -657,29 +672,30 @@ class Converter < ::Prawn::Document
     if (label_min_width = @theme.admonition_label_min_width)
       label_min_width = label_min_width.to_f
     end
-    icons = ((doc = node.document).attr? 'icons') ? (doc.attr 'icons') : false
+    icons = ((doc = node.document).attr? 'icons') ? (doc.attr 'icons') : nil
     if (data_uri_enabled = doc.attr? 'data-uri')
       doc.remove_attr 'data-uri'
     end
     if icons == 'font' && !(node.attr? 'icon', nil, false)
       icon_data = admonition_icon_data(label_text = type.to_sym)
-      label_width = label_min_width ? label_min_width : (icon_data[:size] * 1.5)
+      label_width = label_min_width ? label_min_width : ((icon_size = icon_data[:size] || 24) * 1.5)
     # NOTE icon_uri will consider icon attribute on node first, then type
-    elsif icons && ::File.readable?(icon_path = (node.icon_uri type))
+    # QUESTION should we use resolve_image_path here?
+    elsif icons && (icon_path = node.icon_uri type) &&
+        (icon_path = node.normalize_system_path icon_path, nil, nil, target_name: 'admonition icon') &&
+        (::File.readable? icon_path)
       icons = true
       # TODO introduce @theme.admonition_image_width? or use size key from admonition_icon_<name>?
       label_width = label_min_width ? label_min_width : 36.0
     else
       if icons
-        icons = false
-        logger.warn %(admonition icon image not found or not readable: #{icon_path}) unless scratch?
+        icons = nil
+        logger.warn %(admonition icon not found or not readable: #{icon_path}) unless scratch?
       end
       label_text = node.caption
       theme_font :admonition_label do
         theme_font %(admonition_label_#{type}) do
-          if (transform = @text_transform)
-            label_text = transform_text label_text, transform
-          end
+          label_text = transform_text label_text, @text_transform if @text_transform
           label_width = rendered_width_of_string label_text
           label_width = label_min_width if label_min_width && label_min_width > label_width
         end
@@ -715,7 +731,7 @@ class Converter < ::Prawn::Document
             bounding_box [0, cursor], width: label_width, height: box_height do
               if icons == 'font'
                 # FIXME we're assume icon is a square
-                icon_size = fit_icon_to_bounds icon_data[:size]
+                icon_size = fit_icon_to_bounds icon_size
                 # NOTE Prawn's vertical center is not reliable, so calculate it manually
                 if label_valign == :center
                   label_valign = :top
@@ -731,7 +747,7 @@ class Converter < ::Prawn::Document
               elsif icons
                 if (::Asciidoctor::Image.format icon_path) == 'svg'
                   begin
-                    svg_obj = ::Prawn::SVG::Interface.new ::File.read(icon_path), self,
+                    svg_obj = ::Prawn::SVG::Interface.new ::File.read(icon_path, mode: 'r:UTF-8'), self,
 	                      position: label_align,
                         vposition: label_valign,
                         width: label_width,
@@ -746,7 +762,7 @@ class Converter < ::Prawn::Document
                     end
                     svg_obj.draw
                   rescue
-                    logger.warn %(could not embed admonition icon image: #{icon_path}; #{$!.message})
+                    logger.warn %(could not embed admonition icon: #{icon_path}; #{$!.message})
                   end
                 else
                   begin
@@ -761,7 +777,7 @@ class Converter < ::Prawn::Document
                     embed_image image_obj, image_info, width: icon_width, position: label_align, vposition: label_valign
                   rescue
                     # QUESTION should we show the label in this case?
-                    logger.warn %(could not embed admonition icon image: #{icon_path}; #{$!.message})
+                    logger.warn %(could not embed admonition icon: #{icon_path}; #{$!.message})
                   end
                 end
               else
@@ -807,15 +823,60 @@ class Converter < ::Prawn::Document
   def convert_example node
     add_dest_for_block node if node.id
     theme_margin :block, :top
+    caption_height = 0
+    dry_run do
+      move_down 1 # hack to force top margin to be applied
+      caption_height = (layout_caption node) - 1
+    end if node.title?
     keep_together do |box_height = nil|
       push_scratch node.document if scratch?
-      caption_height = node.title? ? (layout_caption node) : 0
       if box_height
+        # FIXME due to the calculation error logged in #789, we must advance page even when content is split across pages
+        advance_page if box_height > cursor && !at_page_top?
+        layout_caption node
         float do
-          bounding_box [0, cursor], width: bounds.width, height: box_height - caption_height do
-            theme_fill_and_stroke_bounds :example
+          # TODO move the multi-page logic to theme_fill_and_stroke_bounds
+          if (b_width = @theme.example_border_width || 0) > 0 && (b_color = @theme.example_border_color)
+            if b_color == @page_bg_color # let page background cut into example background
+              b_gap_color, b_shift = @page_bg_color, b_width
+            elsif (b_gap_color = @theme.example_background_color) && b_gap_color != b_color
+              b_shift = 0
+            else # let page background cut into border
+              b_gap_color, b_shift = @page_bg_color, 0
+            end
+          else # let page background cut into sidebar background
+            b_width = 0.5 if b_width == 0
+            b_shift, b_gap_color = b_width * 0.5, @page_bg_color
+          end
+          b_radius = (@theme.example_border_radius || 0) + b_width
+          initial_page, remaining_height = true, box_height - caption_height
+          while remaining_height > 0
+            advance_page unless initial_page
+            fragment_height = [(available_height = cursor), remaining_height].min
+            bounding_box [0, available_height], width: bounds.width, height: fragment_height do
+              theme_fill_and_stroke_bounds :example
+              unless b_width == 0
+                indent b_radius, b_radius do
+                  move_down b_shift
+                  # dashed line to indicate continuation from previous page; swell line to cover background
+                  stroke_horizontal_rule b_gap_color, line_width: b_width * 1.2, line_style: :dashed
+                  move_up b_shift
+                end unless initial_page
+                if remaining_height > fragment_height
+                  move_down fragment_height - b_shift
+                  indent b_radius, b_radius do
+                    # dashed line to indicate continuation to next page; swell line to cover background
+                    stroke_horizontal_rule b_gap_color, line_width: b_width * 1.2, line_style: :dashed
+                  end
+                end
+              end
+            end
+            remaining_height -= fragment_height
+            initial_page = false
           end
         end
+      else
+        move_down caption_height
       end
       pad_box @theme.example_padding do
         theme_font :example do
@@ -856,13 +917,13 @@ class Converter < ::Prawn::Document
           if node.context == :quote
             convert_content_for_block node
           else # verse
-            content = preserve_indentation node.content, (node.attr 'tabsize')
+            content = guard_indentation node.content
             layout_prose content, normalize: false, align: :left
           end
         end
         if node.attr? 'attribution', nil, false
           theme_font :blockquote_cite do
-            layout_prose %(#{EmDash} #{[(node.attr 'attribution'), (node.attr 'citetitle', nil, false)].compact * ', '}), align: :left, normalize: false
+            layout_prose %(#{EmDash} #{[(node.attr 'attribution'), (node.attr 'citetitle', nil, false)].compact.join ', '}), align: :left, normalize: false
           end
         end
       end
@@ -957,12 +1018,10 @@ class Converter < ::Prawn::Document
         end
       end
       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?
-            layout_heading node.title, align: (@theme.sidebar_title_align || @base_align).to_sym, margin_top: 0
-          end
-        end
+        theme_font :sidebar_title do
+          # QUESTION should we allow margins of sidebar title to be customized?
+          layout_heading node.title, align: (@theme.sidebar_title_align || @base_align).to_sym, margin_top: 0, margin_bottom: (@theme.heading_margin_bottom || 0)
+        end if node.title?
         theme_font :sidebar do
           convert_content_for_block node
         end
@@ -989,10 +1048,9 @@ class Converter < ::Prawn::Document
     @list_numerals ||= []
     @list_numerals << 1
     #stroke_horizontal_rule @theme.caption_border_bottom_color
-    line_metrics = calc_line_metrics @theme.base_line_height
-    node.items.each_with_index do |item, idx|
-      # FIXME extract to an ensure_space (or similar) method; simplify
-      advance_page if cursor < (line_metrics.height + line_metrics.leading + line_metrics.padding_top) + 1
+    line_metrics = theme_font :conum do calc_line_metrics @theme.base_line_height end
+    node.items.each do |item|
+      allocate_space_for_list_item line_metrics
       convert_colist_item item
     end
     @list_numerals.pop
@@ -1033,11 +1091,11 @@ class Converter < ::Prawn::Document
       # and advance to the next page if so (similar to logic for section titles)
       layout_caption node.title if node.title?
 
+      line_metrics = calc_line_metrics @theme.base_line_height
       node.items.each do |terms, desc|
         terms = [*terms]
-        # NOTE don't orphan the terms, allow for at least one line of content
-        # FIXME extract ensure_space (or similar) method
-        advance_page if cursor < (@theme.base_line_height_length || (font_size * @theme.base_line_height)) * (terms.size + 1)
+        # NOTE don't orphan the terms (keep together terms and at least one line of content)
+        allocate_space_for_list_item line_metrics, (terms.size + 1), ((@theme.description_list_term_spacing || 0) + 0.05)
         terms.each do |term|
           # FIXME layout_prose should pass style downward when parsing formatted text
           #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
@@ -1167,8 +1225,7 @@ class Converter < ::Prawn::Document
     end
     indent list_indent do
       node.items.each do |item|
-        # FIXME extract to an ensure_space (or similar) method; simplify
-        advance_page if cursor < (line_metrics.height + line_metrics.leading + line_metrics.padding_top)
+        allocate_space_for_list_item line_metrics
         convert_outline_list_item item, node, opts
       end
     end
@@ -1267,11 +1324,19 @@ class Converter < ::Prawn::Document
         convert_content_for_block desc
       end
     else
-      layout_prose node.text, opts if node.text?
+      if (primary_text = node.text).nil_or_empty?
+        layout_prose DummyText, opts unless node.blocks?
+      else
+        layout_prose primary_text, opts
+      end
       convert_content_for_block node
     end
   end
 
+  def allocate_space_for_list_item line_metrics, number = 1, additional_gap = 0
+    advance_page if !at_page_top? && cursor < (line_metrics.height + line_metrics.leading + line_metrics.padding_top + additional_gap) * number
+  end
+
   def convert_image node, opts = {}
     node.extend ::Asciidoctor::Image unless ::Asciidoctor::Image === node
     target, image_format = node.target_and_format
@@ -1282,15 +1347,17 @@ class Converter < ::Prawn::Document
     elsif ::Base64 === target
       image_path = target
     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.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?
+      if image_format == 'pdf'
+        if ::File.readable? image_path
+          # NOTE import_page automatically advances to next page afterwards
+          # QUESTION should we add destination to top of imported page?
+          import_page image_path, page: [(node.attr 'page').to_i, 1].max, replace: page.empty?
+        else
+          # QUESTION should we use alt text in this case?
+          logger.warn %(pdf to insert not found or not readable: #{image_path})
+        end
         return
-      else
+      elsif !(::File.readable? image_path)
         logger.warn %(image to embed not found or not readable: #{image_path}) unless scratch?
         image_path = nil
       end
@@ -1306,9 +1373,9 @@ class Converter < ::Prawn::Document
     # TODO move this calculation into a method, such as layout_caption node, side: :bottom, dry_run: true
     caption_h = 0
     dry_run do
-      move_down 0.0001 # hack to force top margin to be applied
+      move_down 1 # hack to force top margin to be applied
       # NOTE we assume caption fits on a single page, which seems reasonable
-      caption_h = layout_caption node, side: :bottom
+      caption_h = (layout_caption node, side: :bottom) - 1
     end if node.title?
 
     # TODO support cover (aka canvas) image layout using "canvas" (or "cover") role
@@ -1316,7 +1383,7 @@ class Converter < ::Prawn::Document
     # TODO add `to_pt page_width` method to ViewportWidth type
     width = (width.to_f / 100) * page_width if ViewportWidth === width
 
-    alignment = ((node.attr 'align', nil, false) || @theme.image_align).to_sym
+    alignment = ((node.attr 'align', nil, false) || @theme.image_align || :left).to_sym
     align_to_page = node.option? 'align-to-page'
 
     begin
@@ -1326,7 +1393,7 @@ class Converter < ::Prawn::Document
             svg_data = ::Base64.decode64 image_path
             file_request_root = false
           else
-            svg_data = ::File.read image_path
+            svg_data = ::File.read image_path, mode: 'r:UTF-8'
             file_request_root = ::File.dirname image_path
           end
           svg_obj = ::Prawn::SVG::Interface.new svg_data, self,
@@ -1353,6 +1420,7 @@ class Converter < ::Prawn::Document
             end
           end
           image_y = y
+          image_cursor = cursor
           add_dest_for_block node if node.id
           # NOTE workaround to fix Prawn not adding fill and stroke commands on page that only has an image;
           # breakage occurs when running content (stamps) are added to page
@@ -1361,6 +1429,7 @@ class Converter < ::Prawn::Document
           # NOTE prawn-svg 0.24.0, 0.25.0, & 0.25.1 didn't restore font after call to draw (see mogest/prawn-svg#80)
           # NOTE cursor advances automatically
           svg_obj.draw
+          draw_image_border image_cursor, rendered_w, rendered_h, alignment unless node.role? 'noborder'
           if (link = node.attr 'link', nil, false)
             add_link_to_image link, { width: rendered_w, height: rendered_h }, position: alignment, y: image_y
           end
@@ -1383,6 +1452,7 @@ class Converter < ::Prawn::Document
             end
           end
           image_y = y
+          image_cursor = cursor
           add_dest_for_block node if node.id
           # NOTE workaround to fix Prawn not adding fill and stroke commands on page that only has an image;
           # breakage occurs when running content (stamps) are added to page
@@ -1390,6 +1460,7 @@ class Converter < ::Prawn::Document
           update_colors if graphic_state.color_space.empty?
           # NOTE specify both width and height to avoid recalculation
           embed_image image_obj, image_info, width: rendered_w, height: rendered_h, position: alignment
+          draw_image_border image_cursor, rendered_w, rendered_h, alignment unless node.role? 'noborder'
           if (link = node.attr 'link', nil, false)
             add_link_to_image link, { width: rendered_w, height: rendered_h }, position: alignment, y: image_y
           end
@@ -1406,6 +1477,22 @@ class Converter < ::Prawn::Document
     unlink_tmp_file image_path if image_path
   end
 
+  def draw_image_border top, w, h, alignment
+    if (b_width = @theme.image_border_width || 0) > 0 && @theme.image_border_color
+      if (@theme.image_border_fit || 'content') == 'auto'
+        bb_width = bounds.width
+      elsif alignment == :center
+        bb_x = (bounds.width - w) * 0.5
+      elsif alignment == :right
+        bb_x = bounds.width - w
+      end
+      bounding_box [(bb_x || 0), top], width: (bb_width || w), height: h, position: alignment do
+        theme_fill_and_stroke_bounds :image, background_color: 'transparent'
+      end
+      true
+    end
+  end
+
   def on_image_error reason, node, target, opts = {}
     logger.warn opts[:message] if opts.key? :message
     alt_text = (link = node.attr 'link', nil, false) ?
@@ -1482,7 +1569,7 @@ class Converter < ::Prawn::Document
     # HACK disable built-in syntax highlighter; must be done before calling node.content!
     if node.style == 'source' && node.attributes['language'] &&
         (highlighter = node.document.attributes['source-highlighter']) && (SourceHighlighters.include? highlighter) &&
-        (@capabilities[:syntax_highlighter] ? node.document.syntax_highlighter.highlight? : true)
+        (@capabilities[:syntax_highlighter] ? (syntax_hl = node.document.syntax_highlighter) && syntax_hl.highlight? : true)
       case highlighter
       when 'coderay'
         unless defined? ::Asciidoctor::Prawn::CodeRayEncoder
@@ -1509,7 +1596,7 @@ class Converter < ::Prawn::Document
         else
           prev_subs = nil
         end
-        source_string = preserve_indentation node.content, (node.attr 'tabsize')
+        source_string = guard_indentation node.content
       else
         # NOTE the source highlighter logic below handles the callouts and highlight subs
         if highlight_idx
@@ -1518,12 +1605,12 @@ class Converter < ::Prawn::Document
           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
+        source_string = node.content || ''
       end
     else
       highlighter = nil
       prev_subs = nil
-      source_string = preserve_indentation node.content, (node.attr 'tabsize')
+      source_string = guard_indentation node.content
     end
 
     bg_color_override = nil
@@ -1551,7 +1638,7 @@ class Converter < ::Prawn::Document
       # TODO enable once we support background color on spans
       #if node.attr? 'highlight', nil, false
       #  unless (hl_lines = node.resolve_lines_to_highlight(node.attr 'highlight', nil, false)).empty?
-      #    pygments_config[:hl_lines] = hl_lines * ' '
+      #    pygments_config[:hl_lines] = hl_lines.join ' '
       #  end
       #end
       # QUESTION should we treat white background as inherit?
@@ -1576,7 +1663,7 @@ class Converter < ::Prawn::Document
       end
       fragments = text_formatter.format result
       fragments = restore_conums fragments, conum_mapping, num_trailing_spaces, linenums if conum_mapping
-      fragments = guard_indentation fragments
+      fragments = guard_indentation_in_fragments fragments
     when 'rouge'
       if (srclang = node.attr 'language', nil, false)
         if srclang.include? '?'
@@ -1685,7 +1772,7 @@ class Converter < ::Prawn::Document
       else
         line
       end
-    } * LF
+    }.join LF
     conum_mapping = nil if conum_mapping.empty?
     [string, conum_mapping]
   end
@@ -1720,10 +1807,11 @@ class Converter < ::Prawn::Document
     # append conums to appropriate lines, then flatten to an array of fragments
     lines.flat_map.with_index do |line, cur_line_num|
       last_line = cur_line_num == last_line_num
-      line.unshift text: %(#{(cur_line_num + linenums).to_s.rjust pad_size} ), color: linenum_color if linenums
+      # NOTE use ::String.new to ensure string is not frozen
+      line.unshift text: (::String.new %(#{(cur_line_num + linenums).to_s.rjust pad_size} )), color: linenum_color if linenums
       if (conums = conum_mapping.delete cur_line_num)
         line << { text: ' ' * num_trailing_spaces } if last_line && num_trailing_spaces > 0
-        conum_text = conums.map {|num| conum_glyph num } * ' '
+        conum_text = conums.map {|num| conum_glyph num }.join ' '
         line << (conum_color ? { text: conum_text, color: conum_color } : { text: conum_text })
       end
       line << { text: LF } unless last_line
@@ -1735,18 +1823,6 @@ class Converter < ::Prawn::Document
     @conum_glyphs[number - 1]
   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? LF
-    end
-    fragments
-  end
-
   def convert_table node
     add_dest_for_block node if node.id
     # TODO we could skip a lot of the logic below when num_rows == 0
@@ -1780,7 +1856,7 @@ class Converter < ::Prawn::Document
       row_data = []
       row.each do |cell|
         row_data << {
-          content: (head_transform ? (transform_text cell.text, head_transform) : cell.text),
+          content: (head_transform ? (transform_text cell.text.strip, head_transform) : cell.text.strip),
           inline_format: [normalize: true],
           background_color: head_bg_color,
           text_color: (theme.table_head_font_color || theme.table_font_color || @font_color),
@@ -1853,7 +1929,7 @@ class Converter < ::Prawn::Document
           cell_line_metrics = calc_line_metrics theme.base_line_height
         when :literal
           # FIXME core should not substitute in this case
-          cell_data[:content] = preserve_indentation((cell.instance_variable_get :@text), (node.document.attr 'tabsize'))
+          cell_data[:content] = guard_indentation cell.instance_variable_get :@text
           # NOTE the absence of the inline_format option implies it's disabled
           # QUESTION should we use literal_font_*, code_font_*, or introduce another category?
           cell_data[:font] = theme.code_font_family
@@ -1865,7 +1941,7 @@ class Converter < ::Prawn::Document
           end
           cell_line_metrics = calc_line_metrics theme.code_line_height
         when :verse
-          cell_data[:content] = preserve_indentation cell.text, (node.document.attr 'tabsize')
+          cell_data[:content] = guard_indentation cell.text
           cell_data[:inline_format] = true
           cell_line_metrics = calc_line_metrics theme.base_line_height
         when :asciidoc
@@ -1889,7 +1965,9 @@ class Converter < ::Prawn::Document
           #cell_data[:final_gap] = cell_line_metrics.final_gap
         end
         unless cell_data.key? :content
-          if (cell_text = cell_transform ? (transform_text cell.text, cell_transform) : cell.text).include? LF
+          cell_text = cell.text.strip
+          cell_text = transform_text cell_text if cell_transform
+          if cell_text.include? LF
             # NOTE effectively the same as calling cell.content (should we use that instead?)
             # FIXME hard breaks not quite the same result as separate paragraphs; need custom cell impl here
             cell_data[:content] = (cell_text.split BlankLineRx).map {|l| l.tr_s WhitespaceChars, ' ' }.join DoubleLF
@@ -1899,6 +1977,7 @@ class Converter < ::Prawn::Document
             cell_data[:inline_format] = [normalize: true]
           end
         end
+        cell_data[:background_color] = (node.document.attr 'cellbgcolor')[1..-1] if node.document.attr? 'cellbgcolor'
         row_data << cell_data
       end
       table_data << row_data
@@ -1952,7 +2031,7 @@ class Converter < ::Prawn::Document
 
     if node.option? 'autowidth'
       table_width = (node.attr? 'width', nil, false) ? bounds.width * ((node.attr 'tablepcwidth') / 100.0) :
-          ((node.has_role? 'spread') ? bounds.width : nil)
+          (((node.has_role? 'stretch') || (node.has_role? 'spread')) ? bounds.width : nil)
       column_widths = []
     else
       table_width = bounds.width * ((node.attr 'tablepcwidth') / 100.0)
@@ -2156,7 +2235,7 @@ class Converter < ::Prawn::Document
       else
         pagenums = consolidate_ranges term.dests.uniq {|dest| dest[:page] }.map {|dest| dest[:page].to_s }
       end
-      text = %(#{text}, #{pagenums * ', '})
+      text = %(#{text}, #{pagenums.join ', '})
     end
     layout_prose text, align: :left, margin: 0
 
@@ -2264,18 +2343,6 @@ class Converter < ::Prawn::Document
         icon_set = node.attr 'set', (node.document.attr 'icon-set', 'fa'), false
       end
       icon_set = 'fa' unless IconSets.include? icon_set
-      if node.attr? 'size', nil, false
-        case (size = node.attr 'size')
-        when 'lg'
-          size_attr = %( size="1.333em")
-        when 'fw'
-          size_attr = %( width="1em" align="center")
-        else
-          size_attr = %( size="#{size.sub 'x', 'em'}")
-        end
-      else
-        size_attr = ''
-      end
       if icon_set == 'fa'
         # legacy name from Font Awesome < 5
         if (remapped_icon_name = resolve_legacy_icon_name icon_name)
@@ -2296,8 +2363,21 @@ class Converter < ::Prawn::Document
         glyph = (icon_font_data icon_set).unicode icon_name rescue nil
       end
       if glyph
+        if node.attr? 'size', nil, false
+          case (size = node.attr 'size')
+          when 'lg'
+            size_attr = %( size="1.333em")
+          when 'fw'
+            size_attr = %( width="1em" align="center")
+          else
+            size_attr = %( size="#{size.sub 'x', 'em'}")
+          end
+        else
+          size_attr = ''
+        end
+        class_attr = node.role? ? %( class="#{node.role}") : ''
         # TODO support rotate and flip attributes
-        %(<font name="#{icon_set}"#{size_attr}>#{glyph}</font>)
+        %(<font name="#{icon_set}"#{size_attr}#{class_attr}>#{glyph}</font>)
       else
         logger.warn %(#{icon_name} is not a valid icon name in the #{icon_set} icon set)
         %([#{node.attr 'alt'}])
@@ -2365,7 +2445,7 @@ class Converter < ::Prawn::Document
     menu = node.attr 'menu'
     caret = (load_theme node.document).menu_caret_content || %( \u203a )
     if !(submenus = node.attr 'submenus').empty?
-      %(<strong>#{[menu, *submenus, (node.attr 'menuitem')] * caret}</strong>)
+      %(<strong>#{[menu, *submenus, (node.attr 'menuitem')].join caret}</strong>)
     elsif (menuitem = node.attr 'menuitem')
       %(<strong>#{menu}#{caret}#{menuitem}</strong>)
     else
@@ -2389,6 +2469,8 @@ class Converter < ::Prawn::Document
       open, close, is_tag = [?\u201c, ?\u201d, false]
     when :single
       open, close, is_tag = [?\u2018, ?\u2019, false]
+    when :mark
+      open, close, is_tag = ['<mark>', '</mark>', true]
     #when :asciimath, :latexmath
     else
       open, close, is_tag = [nil, nil, false]
@@ -2413,8 +2495,8 @@ class Converter < ::Prawn::Document
 
     # NOTE a new page may have already been started at this point, so decide what to do with it
     if page.empty?
-      page.reset_content if (recycle = @ppbook ? verso_page? : true)
-    elsif @ppbook && verso_page?
+      page.reset_content if (recycle = @ppbook ? recto_page? : true)
+    elsif @ppbook && page_number > 0 && recto_page?
       start_new_page
     end
 
@@ -2432,23 +2514,22 @@ class Converter < ::Prawn::Document
     @page_bg_color = prev_bg_color if bg_color
 
     # IMPORTANT this is the first page created, so we need to set the base font
-    font @theme.base_font_family, size: @theme.base_font_size
+    font @theme.base_font_family, size: @root_font_size
 
     # QUESTION allow alignment per element on title page?
     title_align = (@theme.title_page_align || @base_align).to_sym
 
     # TODO disallow .pdf as image type
-    if (logo_image_path = (doc.attr 'title-logo-image', @theme.title_page_logo_image))
+    if (logo_image_path = (doc.attr 'title-logo-image') || (logo_image_from_theme = @theme.title_page_logo_image))
       if (logo_image_path.include? ':') && logo_image_path =~ ImageAttributeValueRx
-        logo_image_path = $1
         logo_image_attrs = (AttributeList.new $2).parse ['alt', 'width', 'height']
         relative_to_imagesdir = true
+        logo_image_path = logo_image_from_theme ? (ThemeLoader.resolve_theme_asset (sub_attributes_discretely doc, $1), @themesdir) : $1
       else
         logo_image_attrs = {}
         relative_to_imagesdir = false
+        logo_image_path = ThemeLoader.resolve_theme_asset (sub_attributes_discretely doc, logo_image_path), @themesdir if logo_image_from_theme
       end
-      # HACK quick fix to resolve image path relative to theme
-      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?
@@ -2509,7 +2590,7 @@ class Converter < ::Prawn::Document
           # TODO provide an API in core to get authors as an array
           authors = (1..(doc.attr 'authorcount', 1).to_i).map {|idx|
             doc.attr(idx == 1 ? 'author' : %(author_#{idx}))
-          } * (@theme.title_page_authors_delimiter || ', ')
+          }.join (@theme.title_page_authors_delimiter || ', ')
           theme_font :title_page_authors do
             layout_prose authors,
               align: title_align,
@@ -2522,7 +2603,10 @@ class Converter < ::Prawn::Document
       revision_info = [(doc.attr? 'revnumber') ? %(#{doc.attr 'version-label'} #{doc.attr 'revnumber'}) : nil, (doc.attr 'revdate')].compact
       unless revision_info.empty?
         move_down(@theme.title_page_revision_margin_top || 0)
-        revision_text = revision_info * (@theme.title_page_revision_delimiter || ', ')
+        revision_text = revision_info.join (@theme.title_page_revision_delimiter || ', ')
+        if (revremark = doc.attr 'revremark')
+          revision_text = %(#{revision_text}: #{revremark})
+        end
         indent (@theme.title_page_revision_margin_left || 0), (@theme.title_page_revision_margin_right || 0) do
           theme_font :title_page_revision do
             layout_prose revision_text,
@@ -2555,7 +2639,7 @@ class Converter < ::Prawn::Document
 
       go_to_page page_count if face == :back
       if image_path.downcase.end_with? '.pdf'
-        import_page image_path, advance: face != :back
+        import_page image_path, page: [((image_attrs || {})['page']).to_i, 1].max, advance: face != :back
       else
         image_opts = resolve_image_options image_path, image_attrs, background: true, format: image_format
         image_page image_path, (image_opts.merge canvas: true)
@@ -2578,16 +2662,26 @@ class Converter < ::Prawn::Document
   alias start_new_part start_new_chapter
   alias layout_part_title layout_chapter_title
 
-  # QUESTION why doesn't layout_heading set the font??
+  # NOTE layout_heading doesn't set the theme font because it's used for various types of headings
   # QUESTION why doesn't layout_heading accept a node?
   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
+    hlevel = opts[:level]
+    unless (top_margin = (margin = (opts.delete :margin)) || (opts.delete :margin_top))
+      if at_page_top?
+        if hlevel && (top_margin = @theme[%(heading_h#{hlevel}_margin_page_top)] || @theme.heading_margin_page_top || 0) > 0
+          move_down top_margin
+        end
+        top_margin = 0
+      else
+        top_margin = (hlevel ? @theme[%(heading_h#{hlevel}_margin_top)] : nil) || @theme.heading_margin_top
+      end
+    end
+    bot_margin = margin || (opts.delete :margin_bottom) || (hlevel ? @theme[%(heading_h#{hlevel}_margin_bottom)] : nil) || @theme.heading_margin_bottom
     if (transform = resolve_text_transform opts)
       string = transform_text string, transform
     end
     margin_top top_margin
-    typeset_text string, calc_line_metrics((opts.delete :line_height) || @theme[%(heading_h#{opts[:level]}_line_height)] || @theme.heading_line_height || @theme.base_line_height), {
+    typeset_text string, calc_line_metrics((opts.delete :line_height) || (hlevel ? @theme[%(heading_h#{hlevel}_line_height)] : nil) || @theme.heading_line_height || @theme.base_line_height), {
       color: @font_color,
       inline_format: true,
       align: @base_align.to_sym
@@ -2697,7 +2791,7 @@ class Converter < ::Prawn::Document
       theme_font :heading, level: 2 do
         theme_font :toc_title do
           toc_title_align = (@theme.toc_title_align || @theme.heading_h2_align || @theme.heading_align || @base_align).to_sym
-          layout_heading toc_title, align: toc_title_align
+          layout_heading toc_title, align: toc_title_align, level: 2
         end
       end
     end
@@ -2737,7 +2831,7 @@ class Converter < ::Prawn::Document
     end
     sections.each do |sect|
       theme_font :toc, level: (sect.level + 1) do
-        sect_title = (transform = @text_transform) ? (transform_text sect.numbered_title, transform) : sect.numbered_title
+        sect_title = @text_transform ? (transform_text sect.numbered_title, @text_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
@@ -2910,7 +3004,6 @@ class Converter < ::Prawn::Document
     doc.set_attr 'page-count', num_pages
 
     pagenums_enabled = doc.attr? 'pagenums'
-    attribute_missing_doc = doc.attr 'attribute-missing'
     case @media == 'prepress' ? 'physical' : (doc.attr 'pdf-folio-placement')
     when 'physical'
       folio_basis, invert_folio = :physical, false
@@ -2990,16 +3083,8 @@ class Converter < ::Prawn::Document
                   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
+                    content = apply_subs_discretely doc, content, drop_lines_with_unresolved_attributes: true
+                    content = transform_text content, @text_transform if @text_transform
                   end
                   formatted_text_box parse_text(content, color: @font_color, inline_format: [normalize: true]),
                     at: [left, bounds.top - trim_styles[:padding][0] - trim_styles[:content_offset] + (trim_styles[:valign] == :center ? font.descender * 0.5 : 0)],
@@ -3075,7 +3160,7 @@ class Converter < ::Prawn::Document
         trim_styles[:img_valign] = trim_styles[:img_valign].to_sym
       end
 
-      colspec_dict = PageSides.inject({}) do |acc, side|
+      colspec_dict = PageSides.reduce({}) 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
@@ -3112,7 +3197,7 @@ class Converter < ::Prawn::Document
         acc
       end
 
-      content_dict = PageSides.inject({}) do |acc, side|
+      content_dict = PageSides.reduce({}) do |acc, side|
         side_content = {}
         ColumnPositions.each do |position|
           unless (val = @theme[%(#{periphery}_#{side}_#{position}_content)]).nil_or_empty?
@@ -3231,9 +3316,24 @@ class Converter < ::Prawn::Document
     nil
   end
 
-  def register_fonts font_catalog, scripts = 'latin', fonts_dir
-    (font_catalog || {}).each do |key, styles|
-      register_font key => styles.map {|style, path| [style.to_sym, (font_path path, fonts_dir)]}.to_h
+  def register_fonts font_catalog, fonts_dir
+    return unless font_catalog
+    dirs = (fonts_dir.split ::File::PATH_SEPARATOR, -1).map do |dir|
+      dir.empty? || dir == 'GEM_FONTS_DIR' ? ThemeLoader::FontsDir : dir
+    end
+    font_catalog.each do |key, styles|
+      styles = styles.reduce({}) do |accum, (style, path)|
+        found = dirs.find do |dir|
+          resolved_font_path = font_path path, dir
+          if ::File.readable? resolved_font_path
+            accum[style.to_sym] = resolved_font_path
+            true
+          end
+        end
+        raise ::Errno::ENOENT, %(#{path} not found in #{fonts_dir}) unless found
+        accum
+      end
+      register_font key => styles
     end
   end
 
@@ -3273,25 +3373,28 @@ class Converter < ::Prawn::Document
         radius: @theme[%(#{category}_border_radius)]
   end
 
-  # Insert a top margin space unless cursor is at the top of the page.
-  # Start a new page if n value is greater than remaining space on page.
-  def margin_top n
-    margin n, :top
+  # Insert a top margin equal to amount if cursor is not at the top of the
+  # page. Start a new page instead if amount is greater than the remaining
+  # space on the page.
+  def margin_top amount
+    margin amount, :top
   end
 
-  # Insert a bottom margin space unless cursor is at the top of the page (not likely).
-  # Start a new page if n value is greater than remaining space on page.
-  def margin_bottom n
-    margin n, :bottom
+  # Insert a bottom margin equal to amount unless cursor is at the top of the
+  # page (not likely). Start a new page instead if amount is greater than the
+  # remaining space on the page.
+  def margin_bottom amount
+    margin amount, :bottom
   end
 
-  # Insert a margin space at the specified side unless cursor is at the top of the page.
-  # Start a new page if n value is greater than remaining space on page.
-  def margin n, side
-    unless (n || 0) == 0 || at_page_top?
+  # Insert a margin at the specified side if the cursor is not at the top of
+  # the page. Start a new page if amount is greater than the remaining space on
+  # the page.
+  def margin amount, side
+    unless (amount || 0) == 0 || at_page_top?
       # NOTE use low-level cursor calculation to workaround cursor bug in column_box context
-      if y - reference_bounds.absolute_bottom > n
-        move_down n
+      if y - reference_bounds.absolute_bottom > amount
+        move_down amount
       else
         # set cursor at top of next page
         reference_bounds.move_past_bottom
@@ -3312,8 +3415,8 @@ class Converter < ::Prawn::Document
     # TODO inheriting from generic category should be an option
     if opts.key? :level
       level = opts[:level]
-      family = @theme[%(#{category}_h#{level}_font_family)] || @theme[%(#{category}_font_family)] || @theme.base_font_family
-      size = @theme[%(#{category}_h#{level}_font_size)] || @theme[%(#{category}_font_size)] || @theme.base_font_size
+      family = @theme[%(#{category}_h#{level}_font_family)] || @theme[%(#{category}_font_family)] || @theme.base_font_family || font_family
+      size = @theme[%(#{category}_h#{level}_font_size)] || @theme[%(#{category}_font_size)] || @root_font_size
       style = @theme[%(#{category}_h#{level}_font_style)] || @theme[%(#{category}_font_style)]
       color = @theme[%(#{category}_h#{level}_font_color)] || @theme[%(#{category}_font_color)]
       # NOTE global text_transform is not currently supported
@@ -3437,6 +3540,7 @@ class Converter < ::Prawn::Document
   def typeset_text string, line_metrics, opts = {}
     move_down line_metrics.padding_top
     opts = { leading: line_metrics.leading, final_gap: line_metrics.final_gap }.merge opts
+    string = string.gsub CjkLineBreakRx, ZeroWidthSpace if @cjk_line_breaks
     if (first_line_opts = opts.delete :first_line_options)
       # TODO good candidate for Prawn enhancement!
       text_with_formatted_first_line string, first_line_opts, opts
@@ -3458,62 +3562,27 @@ 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, 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
-          if guard_indent
-            # NOTE '+' operator is faster than interpolation
-            line.sub!(TabIndentRx) { GuardedIndent + (full_tab_space * $&.length).chop! }
-          else
-            line.sub!(TabIndentRx) { full_tab_space * $&.length }
-          end
-          leading_space = false
-        # QUESTION should we check for LF first?
-        elsif line == LF
-          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
+  def guard_indentation string
+    if string
+      string[0] = GuardedIndent if string.start_with? ' '
+      string.gsub! InnerIndent, GuardedInnerIndent if string.include? InnerIndent
       string
+    else
+      ''
     end
   end
 
+  def guard_indentation_in_fragments 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? LF
+    end
+    fragments
+  end
+
   # Derive a PDF-safe, ASCII-only anchor name from the given value.
   # Encodes value into hex if it contains characters outside the ASCII range.
   # If value is nil, derive an anchor name from the default_value, if given.
@@ -3619,7 +3688,7 @@ class Converter < ::Prawn::Document
       end
     # handle case when image is a local file
     else
-      ::File.expand_path(node.normalize_system_path image_path, imagesdir, nil, target_name: 'image')
+      node.normalize_system_path image_path, imagesdir, nil, target_name: 'image'
     end
   end
 
@@ -3634,10 +3703,17 @@ class Converter < ::Prawn::Document
         return []
       elsif (image_path.include? ':') && image_path =~ ImageAttributeValueRx
         image_attrs = (AttributeList.new $2).parse ['alt', 'width']
+        if from_theme
+          # TODO support remote image when loaded from theme
+          image_path = ThemeLoader.resolve_theme_asset (sub_attributes_discretely doc, $1), @themesdir
+        else
+          image_path = resolve_image_path doc, $1, true, (image_format = image_attrs['format'])
+        end
+      elsif from_theme
         # 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']))
+        image_path = ThemeLoader.resolve_theme_asset (sub_attributes_discretely doc, image_path), @themesdir
       else
-        image_path = from_theme ? (ThemeLoader.resolve_theme_asset image_path, @themesdir) : (resolve_image_path doc, image_path, false)
+        image_path = resolve_image_path doc, image_path, false
       end
 
       return unless image_path
@@ -3835,6 +3911,34 @@ class Converter < ::Prawn::Document
     logger.warn %(could not delete temporary image: #{path}; #{$!.message})
   end
 
+  def apply_subs_discretely doc, value, opts = {}
+    imagesdir = doc.attr 'imagesdir'
+    doc.set_attr 'imagesdir', @themesdir
+    # FIXME get sub_attributes to handle drop-line w/o a warning
+    doc.set_attr 'attribute-missing', 'skip' unless (attribute_missing = doc.attr 'attribute-missing') == 'skip'
+    value = value.gsub '\{', '\\\\\\{' if (escaped_attr_ref = value.include? '\{')
+    value = doc.apply_subs value
+    if opts[:drop_lines_with_unresolved_attributes] && (value.include? '{')
+      value = (value.split LF).delete_if {|line| SimpleAttributeRefRx.match? line }.join LF
+    end
+    value = value.gsub '\{', '{' if escaped_attr_ref
+    doc.set_attr 'attribute-missing', attribute_missing unless attribute_missing == 'skip'
+    if imagesdir
+      doc.set_attr 'imagesdir', imagesdir
+    else
+      # NOTE remove_attr not defined until Asciidoctor 1.5.6
+      doc.attributes.delete 'imagesdir'
+    end
+    value
+  end
+
+  def sub_attributes_discretely doc, value
+    doc.set_attr 'attribute-missing', 'skip' unless (attribute_missing = doc.attr 'attribute-missing') == 'skip'
+    value = doc.apply_subs value
+    doc.set_attr 'attribute-missing', attribute_missing unless attribute_missing == 'skip'
+    value
+  end
+
   # NOTE assume URL is escaped (i.e., contains character references such as &amp;)
   def breakable_uri uri
     scheme, address = uri.split UriSchemeBoundaryRx, 2
@@ -3850,7 +3954,7 @@ class Converter < ::Prawn::Document
   def consolidate_ranges nums
     if nums.size > 1
       prev = nil
-      nums.inject([]) {|accum, num|
+      nums.reduce([]) {|accum, num|
         if prev && (prev.to_i + 1) == num.to_i
           accum[-1][1] = num
         else