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

data/lib/asciidoctor-pdf.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'asciidoctor' unless defined? Asciidoctor.load
 require_relative 'asciidoctor-pdf/asciidoctor_ext'
 require_relative 'asciidoctor-pdf/version'

data/lib/asciidoctor-pdf/asciidoctor_ext.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 # NOTE these are either candidates for inclusion in Asciidoctor core or backports
 require_relative 'asciidoctor_ext/abstract_block'
 require_relative 'asciidoctor_ext/document'

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 class Asciidoctor::AbstractBlock
   def sections?
     !sections.empty?

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 class Asciidoctor::Document
   alias catalog references unless method_defined? :catalog
 end

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Asciidoctor
 module Image
   DataUriRx = /^data:image\/(?<fmt>png|jpe?g|gif|pdf|bmp|tiff);base64,(?<data>.*)$/

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 # TODO add these methods to Asciidoctor core
 class Asciidoctor::List
   # Check whether this list is an outline list (unordered or ordered).

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 # TODO add these methods to Asciidoctor core
 class Asciidoctor::ListItem
   # Check whether this list item has complex content (i.e., nested blocks other than an outline list).

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Asciidoctor
   class StubLogger
     class << self

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 class Asciidoctor::Section
   def numbered_title opts = {}
     unless (@cached_numbered_title ||= nil)

data/lib/asciidoctor-pdf/converter.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 # TODO cleanup imports...decide what belongs in asciidoctor-pdf.rb
 require 'prawn'
 require_relative 'ttfunk_ext'
@@ -58,34 +58,37 @@ class Converter < ::Prawn::Document
   PageLayouts = [:portrait, :landscape]
   PageSides = [:recto, :verso]
   (PDFVersions = { '1.3' => 1.3, '1.4' => 1.4, '1.5' => 1.5, '1.6' => 1.6, '1.7' => 1.7 }).default = 1.4
-  LF = %(\n)
-  DoubleLF = %(\n\n)
-  TAB = %(\t)
-  InnerIndent = %(\n )
+  LF = ?\n
+  DoubleLF = LF * 2
+  TAB = ?\t
+  InnerIndent = LF + ' '
   # 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)
+  GuardedIndent = ?\u00a0
+  GuardedInnerIndent = LF + GuardedIndent
   TabRx = /\t/
   TabIndentRx = /^\t+/
-  NoBreakSpace = %(\u00a0)
-  NarrowNoBreakSpace = %(\u202f)
-  ZeroWidthSpace = %(\u200b)
-  DummyText = %(\u0000)
+  NoBreakSpace = ?\u00a0
+  ZeroWidthSpace = ?\u200b
+  DummyText = ?\u0000
   DotLeaderTextDefault = '. '
-  EmDash = %(\u2014)
-  RightPointer = %(\u25ba)
-  LowercaseGreekA = %(\u03b1)
+  EmDash = ?\u2014
+  RightPointer = ?\u25ba
+  LowercaseGreekA = ?\u03b1
   Bullets = {
-    disc: %(\u2022),
-    circle: %(\u25e6),
-    square: %(\u25aa),
+    disc: ?\u2022,
+    circle: ?\u25e6,
+    square: ?\u25aa,
     none: ''
   }
   # NOTE Default theme font uses ballot boxes from FontAwesome
   BallotBox = {
-    checked: %(\u2611),
-    unchecked: %(\u2610)
+    checked: ?\u2611,
+    unchecked: ?\u2610
+  }
+  ConumSets = {
+    'circled' => (?\u2460..?\u2473).to_a,
+    'filled' => (?\u2776..?\u277f).to_a + (?\u24eb..?\u24f4).to_a,
   }
   SimpleAttributeRefRx = /(?<!\\)\{\w+(?:[\-]\w+)*\}/
   MeasurementRxt = '\\d+(?:\\.\\d+)?(?:in|cm|mm|p[txc])?'
@@ -98,10 +101,14 @@ class Converter < ::Prawn::Document
   UriSchemeBoundaryRx = /(?<=:\/\/)/
   LineScanRx = /\n|.+/
   BlankLineRx = /\n{2,}/
-  WhitespaceChars = %( \t\n)
+  WhitespaceChars = ' ' + TAB + LF
   SourceHighlighters = ['coderay', 'pygments', 'rouge'].to_set
   PygmentsBgColorRx = /^\.highlight +{ *background: *#([^;]+);/
   ViewportWidth = ::Module.new
+  (TitleStyles = {
+    'toc' => [:numbered_title],
+    'basic' => [:title],
+  }).default = [:numbered_title, formal: true]
 
   def initialize backend, opts
     super
@@ -122,7 +129,6 @@ class Converter < ::Prawn::Document
 
   def convert node, name = nil, opts = {}
     method_name = %(convert_#{name ||= node.node_name})
-    result = nil
     if respond_to? method_name
       # NOTE we prepend the prefix "convert_" to avoid conflict with Prawn methods
       result = send method_name, node
@@ -175,29 +181,16 @@ class Converter < ::Prawn::Document
       blk_0 = blk_1 = preface = nil
     end
 
-    # NOTE on_page_create is called within a float context
-    # NOTE on_page_create is not called for imported pages, front and back cover pages, and other image pages
-    on_page_create do
-      # NOTE we assume in prepress that physical page number reflects page side
-      if @media == 'prepress' && (next_page_margin = @page_margin_by_side[page_side]) != page_margin
-        set_page_margin next_page_margin
-      end
-      # TODO implement as a watermark (on top)
-      if (bg_image = @page_bg_image[page_side])
-        canvas { image bg_image[0], ({ position: :center, vposition: :center }.merge bg_image[1]) }
-      elsif @page_bg_color && @page_bg_color != 'FFFFFF'
-        fill_absolute_bounds @page_bg_color
-      end
-    end if respond_to? :on_page_create
+    on_page_create &(method :init_page)
 
     layout_cover_page doc, :front
     if (insert_title_page = doc.doctype == 'book' || (doc.attr? 'title-page'))
       layout_title_page doc
       # NOTE a new page will already be started if the cover image is a PDF
-      start_new_page unless page_is_empty?
+      start_new_page unless page.empty?
     else
       # NOTE a new page will already be started if the cover image is a PDF
-      start_new_page unless page_is_empty?
+      start_new_page unless page.empty?
       body_start_page_number = page_number
       if doc.header? && !doc.notitle
         theme_font :heading, level: 1 do
@@ -208,7 +201,7 @@ class Converter < ::Prawn::Document
     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.to_sym
+    font @theme.base_font_family, size: @theme.base_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?)
@@ -271,7 +264,7 @@ class Converter < ::Prawn::Document
 
     # NOTE delete orphaned page (a page was created but there was no additional content)
     # QUESTION should we delete page if document is empty? (leaving no pages?)
-    delete_page if page_is_empty? && page_count > 1
+    delete_page if page.empty? && page_count > 1
 
     toc_page_nums = insert_toc ? (layout_toc doc, num_toc_levels, toc_page_nums.first, num_front_matter_pages[1], toc_start) : []
 
@@ -322,27 +315,32 @@ class Converter < ::Prawn::Document
     else
       @ppbook = false
     end
-    # QUESTION should ThemeLoader register fonts?
+    # QUESTION should ThemeLoader handle registering fonts instead?
     register_fonts theme.font_catalog, (doc.attr 'scripts', 'latin'), (doc.attr 'pdf-fontsdir', ThemeLoader::FontsDir)
+    default_kerning theme.base_font_kerning != 'none'
+    @fallback_fonts = [*theme.font_fallbacks]
     if (bg_image = resolve_background_image doc, theme, 'page-background-image') && bg_image[0]
       @page_bg_image = { verso: bg_image, recto: bg_image }
     else
       @page_bg_image = { verso: nil, recto: nil }
     end
     if (bg_image = resolve_background_image doc, theme, 'page-background-image-verso')
-      @page_bg_image[:verso] = bg_image[0] ? bg_image : nil
+      @page_bg_image[:verso] = bg_image[0] && bg_image
     end
-    if (bg_image = resolve_background_image doc, theme, 'page-background-image-recto') && bg_image[0]
-      @page_bg_image[:recto] = bg_image[0] ? bg_image : nil
+    if (bg_image = resolve_background_image doc, theme, 'page-background-image-recto')
+      @page_bg_image[:recto] = bg_image[0] && bg_image
     end
     @page_bg_color = resolve_theme_color :page_background_color, 'FFFFFF'
-    @fallback_fonts = [*theme.font_fallbacks]
-    @font_color = theme.base_font_color
+    @font_color = theme.base_font_color || '000000'
     @base_align = (align = doc.attr 'text-align') && (TextAlignmentNames.include? align) ? align : theme.base_align
     @text_transform = nil
     @list_numerals = []
     @list_bullets = []
     @footnotes = []
+    @conum_glyphs = ConumSets[@theme.conum_glyphs || 'circled'] || (@theme.conum_glyphs.split ',').map {|r|
+      from, to = r.rstrip.split '-', 2
+      to ? ((get_char from)..(get_char to)).to_a : [(get_char from)]
+    }.flatten
     @index = IndexCatalog.new
     # NOTE we have to init Pdfmark class here while we have reference to the doc
     @pdfmark = (doc.attr? 'pdfmark') ? (Pdfmark.new doc) : nil
@@ -354,12 +352,22 @@ class Converter < ::Prawn::Document
     @theme ||= begin
       if (theme = doc.options[:pdf_theme])
         @themesdir = theme.__dir__ || (doc.attr 'pdf-themesdir') || (doc.attr 'pdf-stylesdir')
+      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'))
+        @themesdir = theme.__dir__
       else
-        theme_name = (doc.attr 'pdf-theme') || (doc.attr 'pdf-style')
-        theme = ThemeLoader.load_theme theme_name, ((doc.attr 'pdf-themesdir') || (doc.attr 'pdf-stylesdir'))
+        theme = ThemeLoader.load_theme
         @themesdir = 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})
+      else
+        message = %(could not locate or load the built-in pdf theme `#{theme_name}')
+      end
+      logger.error message
+      raise
     end
   end
 
@@ -472,6 +480,23 @@ class Converter < ::Prawn::Document
     info
   end
 
+  # NOTE init_page is called within a float context
+  # NOTE init_page is not called for imported pages, front and back cover pages, and other image pages
+  def init_page *args
+    # NOTE we assume in prepress that physical page number reflects page side
+    if @media == 'prepress' && (next_page_margin = @page_margin_by_side[page_side]) != page_margin
+      set_page_margin next_page_margin
+    end
+    # TODO implement as a watermark (on top)
+    if (bg_image = @page_bg_image[page_side])
+      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
+  end
+
   def convert_section sect, opts = {}
     if sect.sectname == 'abstract'
       # HACK cheat a bit to hide this section from TOC; TOC should filter these sections
@@ -493,7 +518,7 @@ class Converter < ::Prawn::Document
         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 * 1.5)
+        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
       # QUESTION should we store pdf-page-start, pdf-anchor & pdf-destination in internal map?
       sect.set_attr 'pdf-page-start', (start_pgnum = page_number)
@@ -711,7 +736,7 @@ class Converter < ::Prawn::Document
                         vposition: label_valign,
                         width: label_width,
                         height: box_height,
-                        fallback_font_name: default_svg_font,
+                        fallback_font_name: fallback_svg_font_name,
                         enable_web_requests: allow_uri_read,
                         enable_file_requests_with_root: (::File.dirname icon_path)
                     if (icon_height = (svg_size = svg_obj.document.sizing).output_height) > box_height
@@ -962,9 +987,7 @@ class Converter < ::Prawn::Document
     end
     add_dest_for_block node if node.id
     @list_numerals ||= []
-    # FIXME move \u2460 to constant (or theme setting)
-    # \u2460 = circled one, \u24f5 = double circled one, \u278b = negative circled one
-    @list_numerals << %(\u2460)
+    @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|
@@ -980,13 +1003,13 @@ class Converter < ::Prawn::Document
 
   def convert_colist_item node
     marker_width = nil
+    @list_numerals << (index = @list_numerals.pop).next
     theme_font :conum do
-      marker_width = rendered_width_of_string %(#{conum_glyph 1}x)
+      marker_width = rendered_width_of_string %(#{marker = conum_glyph index}x)
       float do
         bounding_box [0, cursor], width: marker_width do
-          @list_numerals << (index = @list_numerals.pop).next
           theme_font :conum do
-            layout_prose index, align: :center, line_height: @theme.conum_line_height, inline_format: false, margin: 0
+            layout_prose marker, align: :center, line_height: @theme.conum_line_height, inline_format: false, margin: 0
           end
         end
       end
@@ -1014,26 +1037,25 @@ class Converter < ::Prawn::Document
         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 * (terms.size + 1)
+        advance_page if cursor < (@theme.base_line_height_length || (font_size * @theme.base_line_height)) * (terms.size + 1)
         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
-          term_text = term.text
-          case @theme.description_list_term_font_style.to_sym
-          when :bold
-            term_text = %(<strong>#{term_text}</strong>)
-          when :italic
-            term_text = %(<em>#{term_text}</em>)
-          when :bold_italic
-            term_text = %(<strong><em>#{term_text}</em></strong>)
+          case @theme.description_list_term_font_style.to_s
+          when 'bold'
+            term_text = %(<strong>#{term.text}</strong>)
+          when 'italic'
+            term_text = %(<em>#{term.text}</em>)
+          when 'bold_italic'
+            term_text = %(<strong><em>#{term.text}</em></strong>)
+          else
+            term_text = term.text
           end
           layout_prose term_text, margin_top: 0, margin_bottom: @theme.description_list_term_spacing, align: :left
         end
-        if desc
-          indent @theme.description_list_description_indent do
-            convert_content_for_list_item desc, :dlist_desc
-          end
-        end
+        indent(@theme.description_list_description_indent || 0) do
+          convert_content_for_list_item desc, :dlist_desc
+        end if desc
       end
     end
   end
@@ -1136,12 +1158,12 @@ class Converter < ::Prawn::Document
       if node.style == 'unstyled'
         # unstyled takes away all indentation
         list_indent = 0
-      elsif (list_indent = @theme.outline_list_indent) > 0
+      elsif (list_indent = @theme.outline_list_indent || 0) > 0
         # no-bullet aligns text with left-hand side of bullet position (as though there's no bullet)
-        list_indent = [list_indent - (rendered_width_of_string %(#{node.context == :ulist ? "\u2022" : '1.'}x)), 0].max
+        list_indent = [list_indent - (rendered_width_of_string %(#{node.context == :ulist ? ?\u2022 : '1.'}x)), 0].max
       end
     else
-      list_indent = @theme.outline_list_indent
+      list_indent = @theme.outline_list_indent || 0
     end
     indent list_indent do
       node.items.each do |item|
@@ -1154,8 +1176,7 @@ class Converter < ::Prawn::Document
     # However, don't leave gap at the bottom if list is nested in an outline list
     unless complex || (node.nested? && node.parent.parent.outline?)
       # correct bottom margin of last item
-      list_margin_bottom = @theme.prose_margin_bottom
-      margin_bottom list_margin_bottom - @theme.outline_list_item_spacing
+      margin_bottom((@theme.prose_margin_bottom || 0) - (@theme.outline_list_item_spacing || 0))
     end
   end
 
@@ -1264,7 +1285,7 @@ class Converter < ::Prawn::Document
       if ::File.readable? image_path
         # NOTE import_page automatically advances to next page afterwards
         # QUESTION should we add destination to top of imported page?
-        return import_page image_path, replace: page_is_empty? if image_format == 'pdf'
+        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?
@@ -1311,7 +1332,7 @@ class Converter < ::Prawn::Document
           svg_obj = ::Prawn::SVG::Interface.new svg_data, self,
               position: alignment,
               width: width,
-              fallback_font_name: default_svg_font,
+              fallback_font_name: fallback_svg_font_name,
               enable_web_requests: allow_uri_read,
               enable_file_requests_with_root: file_request_root
           rendered_w = (svg_size = svg_obj.document.sizing).output_width
@@ -1331,16 +1352,17 @@ class Converter < ::Prawn::Document
               rendered_w = (svg_size = svg_obj.resize height: (rendered_h = available_h)).output_width
             end
           end
+          image_y = y
           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
+          # seems to be resolved as of Prawn 2.2.2
           update_colors if graphic_state.color_space.empty?
           # NOTE prawn-svg 0.24.0, 0.25.0, & 0.25.1 didn't restore font after call to draw (see mogest/prawn-svg#80)
-          # NOTE cursor advanced automatically
+          # NOTE cursor advances automatically
           svg_obj.draw
           if (link = node.attr 'link', nil, false)
-            link_box = [(abs_left = svg_obj.position[0] + bounds.absolute_left), y, (abs_left + rendered_w), (y + rendered_h)]
-            link_annotation link_box, Border: [0, 0, 0], A: { Type: :Action, S: :URI, URI: link.as_pdf }
+            add_link_to_image link, { width: rendered_w, height: rendered_h }, position: alignment, y: image_y
           end
         else
           # FIXME this code really needs to be better organized!
@@ -1360,21 +1382,19 @@ class Converter < ::Prawn::Document
               rendered_w, rendered_h = image_info.calc_image_dimensions height: (rendered_h = available_h)
             end
           end
-          # NOTE must calculate link position before embedding to get proper boundaries
-          if (link = node.attr 'link', nil, false)
-            img_x, img_y = image_position rendered_w, rendered_h, position: alignment
-            link_box = [img_x, (img_y - rendered_h), (img_x + rendered_w), img_y]
-          end
-          image_top = cursor
+          image_y = y
           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
+          # seems to be resolved as of Prawn 2.2.2
           update_colors if graphic_state.color_space.empty?
           # NOTE specify both width and height to avoid recalculation
           embed_image image_obj, image_info, width: rendered_w, height: rendered_h, position: alignment
-          link_annotation link_box, Border: [0, 0, 0], A: { Type: :Action, S: :URI, URI: link.as_pdf } if link
+          if (link = node.attr 'link', nil, false)
+            add_link_to_image link, { width: rendered_w, height: rendered_h }, position: alignment, y: image_y
+          end
           # NOTE Asciidoctor disables automatic advancement of cursor for raster images, so move cursor manually
-          move_down rendered_h if cursor == image_top
+          move_down rendered_h if y == image_y
         end
       end
       layout_caption node, side: :bottom if node.title?
@@ -1629,7 +1649,7 @@ class Converter < ::Prawn::Document
         end
 
         pad_box @theme.code_padding do
-          typeset_formatted_text source_chunks, (calc_line_metrics @theme.code_line_height),
+          typeset_formatted_text source_chunks, (calc_line_metrics @theme.code_line_height || @theme.base_line_height),
               # QUESTION should we require the code_font_color to be set?
               color: (@theme.code_font_color || @font_color),
               size: adjusted_font_size
@@ -1712,12 +1732,7 @@ class Converter < ::Prawn::Document
   end
 
   def conum_glyph number
-    # FIXME make starting glyph a constant and/or theme setting
-    # FIXME use lookup table for glyphs instead of relying on counting
-    # \u2460 = circled one, \u24f5 = double circled one, \u278b = negative circled one
-    glyph = %(\u2460)
-    (number - 1).times { glyph = glyph.next }
-    glyph
+    @conum_glyphs[number - 1]
   end
 
   # Adds guards to preserve indentation
@@ -1952,7 +1967,7 @@ class Converter < ::Prawn::Document
         (alignment = (node.roles & BlockAlignmentNames)[-1])
       alignment = alignment.to_sym
     else
-      alignment = :left
+      alignment = (theme.table_align || :left).to_sym
     end
 
     caption_side = (theme.table_caption_side || :top).to_sym
@@ -1960,7 +1975,8 @@ class Converter < ::Prawn::Document
 
     table_settings = {
       header: table_header,
-      position: alignment,
+      # NOTE position is handled by this method
+      position: :left,
       cell_style: {
         # NOTE the border color and style of the outer frame is set later
         border_color: table_grid_color,
@@ -1986,11 +2002,23 @@ class Converter < ::Prawn::Document
 
     theme_margin :block, :top
 
+    left_padding = right_padding = nil
     table table_data, table_settings do
       # NOTE call width to capture resolved table width
       table_width = width
       caption_max_width = caption_max_width == 'fit-content' ? table_width : nil
       @pdf.layout_table_caption node, alignment, caption_max_width if node.title? && caption_side == :top
+      # NOTE align using padding instead of bounding_box as prawn-table does
+      # using a bounding_box across pages mangles the margin box of subsequent pages
+      if alignment != :left && table_width != (this_bounds = @pdf.bounds).width
+        if alignment == :center
+          left_padding = right_padding = (this_bounds.width - width) * 0.5
+          this_bounds.add_left_padding left_padding
+          this_bounds.add_right_padding right_padding
+        else # :right
+          this_bounds.add_left_padding(left_padding = this_bounds.width - width)
+        end
+      end
       if grid == 'none' && frame == 'none'
         if table_header
           rows(0).tap do |r|
@@ -2049,6 +2077,10 @@ class Converter < ::Prawn::Document
         #end
       end
     end
+    if left_padding
+      bounds.subtract_left_padding left_padding
+      bounds.subtract_right_padding right_padding if right_padding
+    end
     layout_table_caption node, alignment, caption_max_width, caption_side if node.title? && caption_side == :bottom
     theme_margin :block, :bottom
   end
@@ -2078,7 +2110,7 @@ class Converter < ::Prawn::Document
     end
 
     if at_page_top?
-      if page_layout && page_layout != page.layout && page_is_empty?
+      if page_layout && page_layout != page.layout && page.empty?
         delete_page
         advance_page layout: page_layout
       end
@@ -2244,22 +2276,29 @@ class Converter < ::Prawn::Document
       else
         size_attr = ''
       end
-      begin
-        if icon_set == 'fa'
+      if icon_set == 'fa'
+        # legacy name from Font Awesome < 5
+        if (remapped_icon_name = resolve_legacy_icon_name icon_name)
+          requested_icon_name = icon_name
+          icon_set, icon_name = remapped_icon_name.split '-', 2
+          glyph = (icon_font_data icon_set).unicode icon_name
+          logger.info { %(#{requested_icon_name} icon found in deprecated fa icon set; using #{icon_name} from #{icon_set} icon set instead) }
+        # new name in Font Awesome >= 5 (but document is configured to use fa icon set)
+        else
           font_data = nil
-          resolved_icon_set = FontAwesomeIconSets.find {|candidate| (font_data = icon_font_data candidate).unicode icon_name rescue nil }
-          if resolved_icon_set
+          if (resolved_icon_set = FontAwesomeIconSets.find {|candidate| (font_data = icon_font_data candidate).unicode icon_name rescue nil })
             icon_set = resolved_icon_set
-            logger.info { %(#{icon_name} icon found in deprecated fa icon set; use #{icon_set} icon set instead) }
-          else
-            raise
+            glyph = font_data.unicode icon_name
+            logger.info { %(#{icon_name} icon not found in deprecated fa icon set; using match found in #{resolved_icon_set} icon set instead) }
           end
-        else
-          font_data = icon_font_data icon_set
         end
+      else
+        glyph = (icon_font_data icon_set).unicode icon_name rescue nil
+      end
+      if glyph
         # TODO support rotate and flip attributes
-        %(<font name="#{icon_set}"#{size_attr}>#{font_data.unicode icon_name}</font>)
-      rescue
+        %(<font name="#{icon_set}"#{size_attr}>#{glyph}</font>)
+      else
         logger.warn %(#{icon_name} is not a valid icon name in the #{icon_set} icon set)
         %([#{node.attr 'alt'}])
       end
@@ -2316,9 +2355,9 @@ class Converter < ::Prawn::Document
 
   def convert_inline_kbd node
     if (keys = node.attr 'keys').size == 1
-      %(<code>#{keys[0]}</code>)
+      %(<key>#{keys[0]}</key>)
     else
-      keys.map {|key| %(<code>#{key}</code>+) }.join.chop
+      keys.map {|key| %(<key>#{key}</key>) }.join @theme.key_separator || '+'
     end
   end
 
@@ -2347,9 +2386,9 @@ class Converter < ::Prawn::Document
     when :subscript
       open, close, is_tag = ['<sub>', '</sub>', true]
     when :double
-      open, close, is_tag = ['“', '”', false]
+      open, close, is_tag = [?\u201c, ?\u201d, false]
     when :single
-      open, close, is_tag = ['‘', '’', false]
+      open, close, is_tag = [?\u2018, ?\u2019, false]
     #when :asciimath, :latexmath
     else
       open, close, is_tag = [nil, nil, false]
@@ -2372,16 +2411,24 @@ class Converter < ::Prawn::Document
   def layout_title_page doc
     return unless doc.header? && !doc.notitle
 
-    prev_bg_image = @page_bg_image[side = page_side]
+    # 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?
+      start_new_page
+    end
+
+    side = recycle ? page_side : (page_side page_number + 1)
+    prev_bg_image = @page_bg_image[side]
     prev_bg_color = @page_bg_color
-    @page_bg_image[side] = (bg_image = resolve_background_image doc, @theme, 'title-page-background-image') && bg_image[0] ? bg_image : nil
+    if (bg_image = resolve_background_image doc, @theme, 'title-page-background-image')
+      @page_bg_image[side] = bg_image[0] && bg_image
+    end
     if (bg_color = resolve_theme_color :title_page_background_color)
       @page_bg_color = bg_color
     end
-    # NOTE a new page will already be started if the cover image is a PDF
-    start_new_page unless page_is_empty?
-    start_new_page if @ppbook && verso_page?
-    @page_bg_image[side] = prev_bg_image if prev_bg_image
+    recycle ? (init_page self) : start_new_page
+    @page_bg_image[side] = prev_bg_image if bg_image
     @page_bg_color = prev_bg_color if bg_color
 
     # IMPORTANT this is the first page created, so we need to set the base font
@@ -2540,7 +2587,7 @@ class Converter < ::Prawn::Document
       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), {
+    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), {
       color: @font_color,
       inline_format: true,
       align: @base_align.to_sym
@@ -2646,10 +2693,12 @@ class Converter < ::Prawn::Document
     go_to_page toc_page_number unless (page_number == toc_page_number) || scratch?
     start_page_number = page_number
     @y = start_at if start_at
-    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((doc.attr 'toc-title'), align: toc_title_align)
+    unless (toc_title = doc.attr 'toc-title').nil_or_empty?
+      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
+        end
       end
     end
     # QUESTION should we skip this whole method if num_levels < 0?
@@ -2779,6 +2828,7 @@ class Converter < ::Prawn::Document
     sectlevels = (@theme[%(#{periphery}_sectlevels)] || 2).to_i
     sections = doc.find_by(context: :section) {|sect| sect.level <= sectlevels && sect != header } || []
 
+    title_method = TitleStyles[@theme[%(#{periphery}_title_style)]]
     # FIXME we need a proper model for all this page counting
     # FIXME we make a big assumption that part & chapter start on new pages
     # index parts, chapters and sections by the visual page number on which they start
@@ -2790,16 +2840,16 @@ class Converter < ::Prawn::Document
       page_num = (sect.attr 'pdf-page-start').to_i - skip_pagenums
       if is_book && ((sect_is_part = sect.part?) || sect.chapter?)
         if sect_is_part
-          part_start_pages[page_num] ||= (sect.numbered_title formal: true)
+          part_start_pages[page_num] ||= sect.send(*title_method)
         else
-          chapter_start_pages[page_num] ||= (sect.numbered_title formal: true)
+          chapter_start_pages[page_num] ||= sect.send(*title_method)
           if sect.sectname == 'appendix' && !part_start_pages.empty?
             # FIXME need a better way to indicate that part has ended
             part_start_pages[page_num] = ''
           end
         end
       else
-        sect_title = trailing_section_start_pages[page_num] = sect.numbered_title formal: true
+        sect_title = trailing_section_start_pages[page_num] = sect.send(*title_method)
         section_start_pages[page_num] ||= sect_title
       end
     end
@@ -2923,7 +2973,15 @@ class Converter < ::Prawn::Document
                   bounding_box [left, bounds.top - trim_styles[:padding][0] - trim_styles[:content_offset]], width: colwidth, height: trim_styles[:content_height] do
                     # NOTE image vposition respects padding; use negative image_vertical_align value to revert
                     image_opts = content[1].merge position: colspec[:align], vposition: trim_styles[:img_valign]
-                    image content[0], image_opts rescue logger.warn %(could not embed image in running content: #{content[0]}; #{$!.message})
+                    begin
+                      image_info = image content[0], image_opts
+                      if (image_link = content[2])
+                        image_info = { width: image_info.scaled_width, height: image_info.scaled_height } unless image_opts[:format] == 'svg'
+                        add_link_to_image image_link, image_info, image_opts
+                      end
+                    rescue
+                      logger.warn %(could not embed image in running content: #{content[0]}; #{$!.message})
+                    end
                   end
                 end
               when ::String
@@ -3063,7 +3121,7 @@ class Converter < ::Prawn::Document
               if ::File.readable? (image_path = (ThemeLoader.resolve_theme_asset $1, @themesdir))
                 image_attrs = (AttributeList.new $2).parse ['alt', 'width']
                 image_opts = resolve_image_options image_path, image_attrs, container_size: [colspec_dict[side][position][:width], trim_styles[:content_height]], format: image_attrs['format']
-                side_content[position] = [image_path, image_opts]
+                side_content[position] = [image_path, image_opts, image_attrs['link']]
               else
                 # NOTE allows inline image handler to report invalid reference and replace with alt text
                 side_content[position] = %(image:#{image_path}[#{$2}])
@@ -3131,7 +3189,9 @@ class Converter < ::Prawn::Document
         # FIXME link to title page if there's a cover page (skip cover page and ensure blank page)
         page title: doctitle, destination: (document.dest_top 1)
       end
-      page title: (doc.attr 'toc-title'), destination: (document.dest_top toc_page_nums.first) unless toc_page_nums.none?
+      unless toc_page_nums.none? || (toc_title = doc.attr 'toc-title').nil_or_empty?
+        page title: toc_title, destination: (document.dest_top toc_page_nums.first)
+      end
       # QUESTION any way to get add_outline_level to invoke in the context of the outline?
       document.add_outline_level self, doc.sections, num_levels
     end
@@ -3175,9 +3235,6 @@ class Converter < ::Prawn::Document
     (font_catalog || {}).each do |key, styles|
       register_font key => styles.map {|style, path| [style.to_sym, (font_path path, fonts_dir)]}.to_h
     end
-
-    # FIXME read kerning setting from theme!
-    default_kerning true
   end
 
   def font_path font_file, fonts_dir
@@ -3185,8 +3242,8 @@ class Converter < ::Prawn::Document
     ::File.absolute_path font_file, fonts_dir
   end
 
-  def default_svg_font
-    @theme.svg_font_family || @theme.base_font_family
+  def fallback_svg_font_name
+    @theme.svg_fallback_font_family || @theme.svg_font_family || @theme.base_font_family
   end
 
   attr_reader :allow_uri_read
@@ -3231,7 +3288,7 @@ class Converter < ::Prawn::Document
   # 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 || at_page_top?
+    unless (n || 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
@@ -3599,7 +3656,7 @@ class Converter < ::Prawn::Document
       image_opts = {
         enable_file_requests_with_root: (::File.dirname image_path),
         enable_web_requests: allow_uri_read,
-        fallback_font_name: default_svg_font,
+        fallback_font_name: fallback_svg_font_name,
         format: 'svg',
       }
     else
@@ -3694,7 +3751,9 @@ class Converter < ::Prawn::Document
         str_to_pt width
       end
     elsif opts[:use_fallback] && (width = @theme.image_width)
-      if width.end_with? '%'
+      if ::Numeric === width
+        width
+      elsif (width = width.to_s).end_with? '%'
         (width.to_f / 100) * max_width
       elsif opts[:support_vw] && (width.end_with? 'vw')
         (width.chomp 'vw').extend ViewportWidth
@@ -3739,6 +3798,33 @@ class Converter < ::Prawn::Document
     end
   end
 
+  def add_link_to_image uri, image_info, image_opts
+    image_width = image_info[:width]
+    image_height = image_info[:height]
+
+    case image_opts[:position]
+    when :center
+      image_x = bounds.left_side + (bounds.width - image_width) * 0.5
+    when :right
+      image_x = bounds.right_side - image_width
+    else # :left or not set
+      image_x = bounds.left_side
+    end
+
+    case image_opts[:vposition]
+    when :top
+      image_y = bounds.absolute_top
+    when :center
+      image_y = bounds.absolute_top - (bounds.height - image_height) * 0.5
+    when :bottom
+      image_y = bounds.absolute_bottom + image_height
+    else
+      image_y = y
+    end unless (image_y = image_opts[:y])
+
+    link_annotation [image_x, (image_y - image_height), (image_x + image_width), image_y], Border: [0, 0, 0], A: { Type: :Action, S: :URI, URI: uri.as_pdf }
+  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
@@ -3778,6 +3864,10 @@ class Converter < ::Prawn::Document
     end
   end
 
+  def get_char code
+    (code.start_with? '\u') ? ([((code.slice 2, code.length).to_i 16)].pack 'U1') : code
+  end
+
   # QUESTION move to prawn/extensions.rb?
   def init_scratch_prototype
     @save_state = nil