asciidoctor-pdf 1.5.0.alpha.16 → 1.5.0.alpha.17

data/lib/asciidoctor-pdf.rb

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

data/lib/asciidoctor-pdf/asciidoctor_ext.rb

@@ -2,4 +2,5 @@
 require_relative 'asciidoctor_ext/section'
 require_relative 'asciidoctor_ext/list'
 require_relative 'asciidoctor_ext/list_item'
+require_relative 'asciidoctor_ext/logging_shim' unless defined? Asciidoctor::Logging
 require_relative 'asciidoctor_ext/image'

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

@@ -0,0 +1,19 @@
+module Asciidoctor
+  class StubLogger
+    class << self
+      def warn message
+        ::Kernel.warn %(asciidoctor: WARNING: #{message})
+      end
+
+      def error message
+        ::Kernel.warn %(asciidoctor: ERROR: #{message})
+      end
+    end
+  end
+
+  module LoggingShim
+    def logger
+      StubLogger
+    end
+  end
+end

data/lib/asciidoctor-pdf/converter.rb

@@ -1,4 +1,4 @@
-# encoding: UTF-8
+# encoding: utf-8
 # TODO cleanup imports...decide what belongs in asciidoctor-pdf.rb
 require 'prawn'
 require_relative 'ttfunk_ext'
@@ -17,7 +17,6 @@ require_relative 'sanitizer'
 require_relative 'prawn_ext'
 require_relative 'formatted_text'
 require_relative 'pdfmark'
-require_relative 'asciidoctor_ext'
 require_relative 'theme_loader'
 require_relative 'roman_numeral'
 require_relative 'index_catalog'
@@ -26,9 +25,14 @@ autoload :StringIO, 'stringio'
 autoload :Tempfile, 'tempfile'
 
 module Asciidoctor
-module Pdf
+module PDF
 class Converter < ::Prawn::Document
   include ::Asciidoctor::Converter
+  if defined? ::Asciidoctor::Logging
+    include ::Asciidoctor::Logging
+  else
+    include ::Asciidoctor::LoggingShim
+  end
   include ::Asciidoctor::Writer
   include ::Asciidoctor::Prawn::Extensions
 
@@ -40,13 +44,14 @@ class Converter < ::Prawn::Document
 
   AsciidoctorVersion = ::Gem::Version.create ::Asciidoctor::VERSION
   AdmonitionIcons = {
-    caution:   { name: 'fa-fire', stroke_color: 'BF3400', size: 24 },
-    important: { name: 'fa-exclamation-circle', stroke_color: 'BF0000', size: 24 },
-    note:      { name: 'fa-info-circle', stroke_color: '19407C', size: 24 },
-    tip:       { name: 'fa-lightbulb-o', stroke_color: '111111', size: 24 },
-    warning:   { name: 'fa-exclamation-triangle', stroke_color: 'BF6900', size: 24 }
+    caution:   { name: 'fas-fire', stroke_color: 'BF3400', size: 24 },
+    important: { name: 'fas-exclamation-circle', stroke_color: 'BF0000', size: 24 },
+    note:      { name: 'fas-info-circle', stroke_color: '19407C', size: 24 },
+    tip:       { name: 'far-lightbulb', stroke_color: '111111', size: 24 },
+    warning:   { name: 'fas-exclamation-triangle', stroke_color: 'BF6900', size: 24 }
   }
-  TextAlignmentNames = ['left', 'center', 'right', 'justify']
+  TextAlignmentNames = ['justify', 'left', 'center', 'right']
+  TextAlignmentRoles = ['text-justify', 'text-left', 'text-center', 'text-right']
   BlockAlignmentNames = ['left', 'center', 'right']
   AlignmentTable = { '<' => :left, '=' => :center, '>' => :right }
   ColumnPositions = [:left, :center, :right]
@@ -101,8 +106,13 @@ class Converter < ::Prawn::Document
   def initialize backend, opts
     super
     basebackend 'html'
+    filetype 'pdf'
+    htmlsyntax 'html'
     outfilesuffix '.pdf'
-    #htmlsyntax 'xml'
+    if (doc = opts[:document])
+      # NOTE enabling data-uri forces Asciidoctor Diagram to produce absolute image paths
+      doc.attributes['data-uri'] = ((doc.instance_variable_get :@attribute_overrides) || {})['data-uri'] = ''
+    end
     @list_numbers = []
     @list_bullets = []
     @capabilities = {
@@ -118,7 +128,7 @@ class Converter < ::Prawn::Document
       result = send method_name, node
     else
       # TODO delegate to convert_method_missing
-      warn %(asciidoctor: WARNING: conversion missing in backend #{@backend} for #{name})
+      logger.warn %(conversion missing in backend #{@backend} for #{name})
     end
     # NOTE inline nodes generate pseudo-HTML strings; the remainder write directly to PDF object
     ::Asciidoctor::Inline === node ? result : self
@@ -141,8 +151,6 @@ class Converter < ::Prawn::Document
 
   def convert_document doc
     init_pdf doc
-    # data-uri doesn't apply to PDF, so explicitly disable (is there a better place?)
-    doc.attributes.delete 'data-uri'
     # set default value for pagenums if not otherwise set
     unless (doc.attribute_locked? 'pagenums') || ((doc.instance_variable_get :@attributes_modified).include? 'pagenums')
       doc.attributes['pagenums'] = ''
@@ -182,37 +190,80 @@ class Converter < ::Prawn::Document
     end if respond_to? :on_page_create
 
     layout_cover_page :front, doc
-    layout_title_page doc
+    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?
+    else
+      # NOTE a new page will already be started if the cover image is a PDF
+      start_new_page unless page_is_empty?
+      body_start_page_number = page_number
+      if doc.header? && !doc.notitle
+        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
+    end
 
-    # NOTE a new page will already be started if the cover image is a PDF
-    start_new_page unless page_is_empty?
+    # 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
 
     num_toc_levels = (doc.attr 'toclevels', 2).to_i
     if (insert_toc = (doc.attr? 'toc') && doc.sections?)
       start_new_page if @ppbook && verso_page?
       toc_page_nums = page_number
-      dry_run { toc_page_nums = layout_toc doc, num_toc_levels, toc_page_nums }
+      toc_end = nil
+      dry_run do
+        toc_page_nums = layout_toc doc, num_toc_levels, toc_page_nums, 0, toc_start
+        move_down @theme.block_margin_bottom unless insert_title_page
+        toc_end = @y
+      end
       # NOTE reserve pages for the toc; leaves cursor on page after last page in toc
-      toc_page_nums.each { start_new_page }
+      if insert_title_page
+        toc_page_nums.each { start_new_page }
+      else
+        (toc_page_nums.first...toc_page_nums.last).each { start_new_page }
+        @y = toc_end
+      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?
 
-    num_front_matter_pages = (@index.start_page_number = page_number) - 1
-    font @theme.base_font_family, size: @theme.base_font_size, style: @theme.base_font_style.to_sym
+    if insert_title_page
+      body_start_page_number = page_number
+      # NOTE start running content from title or toc, if specified (default: body)
+      if @theme.running_content_start_at == 'title'
+        num_front_matter_pages = 0
+      elsif insert_toc && @theme.running_content_start_at == 'toc'
+        num_front_matter_pages = 1
+      else # body
+        num_front_matter_pages = body_start_page_number - 1
+      end
+    else
+      num_front_matter_pages = body_start_page_number - 1
+    end
+
+    @index.start_page_number = num_front_matter_pages + 1
     doc.set_attr 'pdf-anchor', (doc_anchor = derive_anchor_from_id doc.id, 'top')
     add_dest_for_block doc, doc_anchor
+
+    convert_section generate_manname_section doc if doc.doctype == 'manpage' && (doc.attr? 'manpurpose')
+
     convert_content_for_block doc
 
+    # NOTE for a book, these are leftover footnotes; for an article this is everything
+    layout_footnotes doc
+
     # 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
 
-    toc_page_nums = insert_toc ? (layout_toc doc, num_toc_levels, toc_page_nums.first, num_front_matter_pages) : []
+    toc_page_nums = insert_toc ? (layout_toc doc, num_toc_levels, toc_page_nums.first, num_front_matter_pages, toc_start) : []
 
-    if page_count > num_front_matter_pages
+    unless page_count < body_start_page_number
       unless doc.noheader || @theme.header_height.to_f.zero?
         layout_running_content :header, doc, skip: num_front_matter_pages
       end
@@ -228,16 +279,17 @@ class Converter < ::Prawn::Document
     catalog.data[:ViewerPreferences] = { DisplayDocTitle: true }
 
     layout_cover_page :back, doc
+    nil
   end
 
   # NOTE embedded only makes sense if perhaps we are building
   # on an existing Prawn::Document instance; for now, just treat
   # it the same as a full document.
-  alias :convert_embedded :convert_document
+  alias convert_embedded convert_document
 
   # TODO only allow method to be called once (or we need a reset)
   def init_pdf doc
-    @theme = theme = ThemeLoader.load_theme((doc.attr 'pdf-style'), (doc.attr 'pdf-stylesdir'))
+    theme = load_theme doc
     pdf_opts = build_pdf_options doc, theme
     # QUESTION should page options be preserved (otherwise, not readily available)
     #@page_opts = { size: pdf_opts[:page_size], layout: pdf_opts[:page_layout] }
@@ -252,7 +304,7 @@ class Converter < ::Prawn::Document
       if (page_margin_inner = theme.page_margin_inner)
         page_margin_recto[3] = @page_margin_by_side[:verso][1] = page_margin_inner
       end
-      # NOTE prepare scratch document to use page margin from recto side
+      # 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
@@ -269,6 +321,7 @@ class Converter < ::Prawn::Document
     @font_color = theme.base_font_color
     @base_align = (align = doc.attr 'text-alignment') && (TextAlignmentNames.include? align) ? align : theme.base_align
     @text_transform = nil
+    @footnotes = []
     @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
@@ -276,6 +329,10 @@ class Converter < ::Prawn::Document
     self
   end
 
+  def load_theme doc
+    @theme ||= doc.options[:pdf_theme] || ThemeLoader.load_theme((doc.attr 'pdf-style'), (doc.attr 'pdf-stylesdir'))
+  end
+
   def build_pdf_options doc, theme
     case (page_margin = (doc.attr 'pdf-page-margin') || theme.page_margin)
     when ::Array
@@ -333,7 +390,7 @@ class Converter < ::Prawn::Document
           dim > 0 ? dim : break
         elsif ::String === dim && (m = (MeasurementPartsRx.match dim))
           # NOTE truncate to max precision retained by PDF::Core
-          (to_pt m[1].to_f, m[2]).truncate_to_precision 4
+          (to_pt m[1].to_f, m[2]).truncate 4
         else
           break
         end
@@ -357,7 +414,7 @@ class Converter < ::Prawn::Document
     }
   end
 
-  # FIXME PdfMarks should use the PDF info result
+  # FIXME Pdfmark should use the PDF info result
   def build_pdf_info doc
     info = {}
     # FIXME use sanitize: :plain_text once available
@@ -374,7 +431,7 @@ class Converter < ::Prawn::Document
     if (doc.attr? 'publisher')
       info[:Producer] = (doc.attr 'publisher').as_pdf
     end
-    info[:Creator] = %(Asciidoctor PDF #{::Asciidoctor::Pdf::VERSION}, based on Prawn #{::Prawn::VERSION}).as_pdf
+    info[:Creator] = %(Asciidoctor PDF #{::Asciidoctor::PDF::VERSION}, based on Prawn #{::Prawn::VERSION}).as_pdf
     info[:Producer] ||= (info[:Author] || info[:Creator])
     unless doc.attr? 'reproducible'
       # NOTE since we don't track the creation date of the input file, we map the ModDate header to the last modified
@@ -392,10 +449,10 @@ class Converter < ::Prawn::Document
       return convert_abstract sect
     end
 
+    type = nil
     theme_font :heading, level: (hlevel = sect.level + 1) do
       title = sect.numbered_title formal: true
       align = (@theme[%(heading_h#{hlevel}_align)] || @theme.heading_align || @base_align).to_sym
-      type = nil
       if sect.part_or_chapter?
         if sect.chapter?
           type = :chapter
@@ -415,23 +472,40 @@ class Converter < ::Prawn::Document
       sect.set_attr 'pdf-anchor', (sect_anchor = derive_anchor_from_id sect.id, %(#{start_pgnum}-#{y.ceil}))
       add_dest_for_block sect, sect_anchor
       if type == :part
-        layout_part_title sect, title, align: align
+        layout_part_title sect, title, align: align, level: hlevel
       elsif type == :chapter
-        layout_chapter_title sect, title, align: align
+        layout_chapter_title sect, title, align: align, level: hlevel
       else
-        layout_heading title, align: align
+        layout_heading title, align: align, level: hlevel
       end
     end
 
     sect.sectname == 'index' ? (convert_index_section sect) : (convert_content_for_block sect)
+    layout_footnotes sect if type == :chapter
     sect.set_attr 'pdf-page-end', page_number
   end
 
+  # QUESTION if a footnote ref appears in a separate chapter, should the footnote def be duplicated?
+  def layout_footnotes node
+    return if (fns = (doc = node.document).footnotes - @footnotes).empty?
+    theme_margin :footnotes, :top
+    theme_font :footnotes do
+      # FIXME layout_caption resets the theme font for footnotes
+      (title = doc.attr 'footnotes-title') && (layout_caption title)
+      item_spacing = @theme.footnotes_item_spacing || 0
+      fns.each do |fn|
+        layout_prose %(<a name="_footnotedef_#{index = fn.index}">#{DummyText}</a>[<a anchor="_footnoteref_#{index}">#{index}</a>] #{fn.text}), margin_bottom: item_spacing
+      end
+      @footnotes += fns
+    end
+    nil
+  end
+
   def convert_floating_title node
     add_dest_for_block node if node.id
     # QUESTION should we decouple styles from section titles?
     theme_font :heading, level: (hlevel = node.level + 1) do
-      layout_heading node.title, align: (@theme[%(heading_h#{hlevel}_align)] || @theme.heading_align || @base_align).to_sym
+      layout_heading node.title, align: (@theme[%(heading_h#{hlevel}_align)] || @theme.heading_align || @base_align).to_sym, level: hlevel
     end
   end
 
@@ -444,7 +518,7 @@ class Converter < ::Prawn::Document
         end
       end
       theme_font :abstract do
-        prose_opts = { line_height: @theme.abstract_line_height }
+        prose_opts = { line_height: @theme.abstract_line_height, align: (@theme.abstract_align || @base_align).to_sym }
         # FIXME control more first_line_options using theme
         if (line1_font_style = @theme.abstract_first_line_font_style) && line1_font_style.to_sym != font_style
           prose_opts[:first_line_options] = { styles: [font_style, line1_font_style.to_sym] }
@@ -482,30 +556,17 @@ class Converter < ::Prawn::Document
   # TODO add prose around image logic (use role to add special logic for headshot)
   def convert_paragraph node
     add_dest_for_block node if node.id
-    is_lead = false
     prose_opts = {}
-    node.roles.each do |role|
-      case role
-      when 'text-left'
-        prose_opts[:align] = :left
-      when 'text-right'
-        prose_opts[:align] = :right
-      when 'text-justify'
-        prose_opts[:align] = :justify
-      when 'text-center'
-        prose_opts[:align] = :center
-      when 'lead'
-        is_lead = true
-      #when 'signature'
-      #  prose_opts[:size] = @theme.base_font_size_small
-      end
+    lead = (roles = node.roles).include? 'lead'
+    if (align = resolve_alignment_from_role roles)
+      prose_opts[:align] = align
     end
 
     # TODO check if we're within one line of the bottom of the page
     # and advance to the next page if so (similar to logic for section titles)
     layout_caption node.title if node.title?
 
-    if is_lead
+    if lead
       theme_font :lead do
         layout_prose node.content, prose_opts
       end
@@ -526,7 +587,10 @@ class Converter < ::Prawn::Document
     if (label_min_width = @theme.admonition_label_min_width)
       label_min_width = label_min_width.to_f
     end
-    icons = (node.document.attr? 'icons') ? (node.document.attr 'icons') : false
+    icons = ((doc = node.document).attr? 'icons') ? (doc.attr 'icons') : false
+    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)
@@ -538,7 +602,7 @@ class Converter < ::Prawn::Document
     else
       if icons
         icons = false
-        warn %(asciidoctor: WARNING: admonition icon image not found or not readable: #{icon_path}) unless scratch?
+        logger.warn %(admonition icon image not found or not readable: #{icon_path}) unless scratch?
       end
       label_text = node.caption
       theme_font :admonition_label do
@@ -551,6 +615,7 @@ class Converter < ::Prawn::Document
         end
       end
     end
+    doc.set_attr 'data-uri', '' if data_uri_enabled
     unless ::Array === (cpad = @theme.admonition_padding)
       cpad = ::Array.new 4, cpad
     end
@@ -593,19 +658,40 @@ class Converter < ::Prawn::Document
                     color: icon_data[:stroke_color],
                     size: icon_size
               elsif icons
-                begin
-                  image_obj, image_info = build_image_object icon_path
-                  icon_aspect_ratio = image_info.width.fdiv image_info.height
-                  # NOTE don't scale image up if smaller than label_width
-                  icon_width = [(to_pt image_info.width, :px), label_width].min
-                  if (icon_height = icon_width * (1 / icon_aspect_ratio)) > box_height
-                    icon_width *= box_height / icon_height
-                    icon_height = box_height
+                if icon_path.end_with? '.svg'
+                  begin
+                    svg_obj = ::Prawn::SVG::Interface.new ::File.read(icon_path), self,
+	                    position: label_align,
+                        vposition: label_valign,
+                        width: label_width,
+                        height: box_height,
+                        fallback_font_name: default_svg_font,
+                        enable_web_requests: (doc.attr? 'allow-uri-read'),
+                        enable_file_requests_with_root: (::File.dirname icon_path)
+                    if (icon_height = (svg_size = svg_obj.document.sizing).output_height) > box_height
+                      icon_width = (svg_obj.resize height: (icon_height = box_height)).output_width
+                    else
+                      icon_width = svg_size.output_width
+                    end
+                    svg_obj.draw
+                  rescue
+                    logger.warn %(could not embed admonition icon image: #{icon_path}; #{$!.message})
+                  end
+                else
+                  begin
+                    image_obj, image_info = build_image_object icon_path
+                    icon_aspect_ratio = image_info.width.fdiv image_info.height
+                    # NOTE don't scale image up if smaller than label_width
+                    icon_width = [(to_pt image_info.width, :px), label_width].min
+                    if (icon_height = icon_width * (1 / icon_aspect_ratio)) > box_height
+                      icon_width *= box_height / icon_height
+                      icon_height = box_height
+                    end
+                    embed_image image_obj, image_info, width: icon_width, position: label_align, vposition: label_valign
+                  rescue
+                    # QUESTION should we show the label in this case?
+                    logger.warn %(could not embed admonition icon image: #{icon_path}; #{$!.message})
                   end
-                  embed_image image_obj, image_info, width: icon_width, position: label_align, vposition: label_valign
-                rescue => e
-                  # QUESTION should we show the label in this case?
-                  warn %(asciidoctor: WARNING: could not embed admonition icon image: #{icon_path}; #{e.message})
                 end
               else
                 # IMPORTANT the label must fit in the alotted space or it shows up on another page!
@@ -741,8 +827,8 @@ class Converter < ::Prawn::Document
     theme_margin :block, :bottom
   end
 
-  alias :convert_quote :convert_quote_or_verse
-  alias :convert_verse :convert_quote_or_verse
+  alias convert_quote convert_quote_or_verse
+  alias convert_verse convert_quote_or_verse
 
   def convert_sidebar node
     add_dest_for_block node if node.id
@@ -830,7 +916,7 @@ class Converter < ::Prawn::Document
     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)
+      advance_page if cursor < (line_metrics.height + line_metrics.leading + line_metrics.padding_top) + 1
       convert_colist_item item
     end
     @list_numbers.pop
@@ -871,7 +957,18 @@ class Converter < ::Prawn::Document
       # FIXME extract ensure_space (or similar) method
       advance_page if cursor < @theme.base_line_height_length * (terms.size + 1)
       terms.each do |term|
-        layout_prose term.text, style: @theme.description_list_term_font_style.to_sym, margin_top: 0, margin_bottom: @theme.description_list_term_spacing, align: :left
+        # 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>)
+        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
@@ -926,9 +1023,9 @@ class Converter < ::Prawn::Document
           nil
         else
           if Bullets.key?(candidate = style.to_sym)
-            candidate 
+            candidate
           else
-            warn %(asciidoctor: WARNING: unknown unordered list style: #{candidate})
+            logger.warn %(unknown unordered list style: #{candidate})
             :disc
           end
         end
@@ -942,7 +1039,7 @@ class Converter < ::Prawn::Document
           :square
         end
       end
-      @list_bullets << Bullets[bullet_type]
+      @list_bullets << bullet_type
     end
     convert_outline_list node
     @list_bullets.pop
@@ -953,6 +1050,16 @@ 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?
 
+    opts = {}
+    if (align = resolve_alignment_from_role node.roles)
+      opts[:align] = align
+    elsif node.style == 'bibliography'
+      opts[:align] = :left
+    elsif (align = @theme.outline_list_text_align)
+      # NOTE theme setting only affects alignment of list text (not nested blocks)
+      opts[:align] = align.to_sym
+    end
+
     line_metrics = calc_line_metrics @theme.base_line_height
     complex = false
     # ...or if we want to give all items in the list the same treatment
@@ -972,7 +1079,7 @@ class Converter < ::Prawn::Document
       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)
-        convert_outline_list_item item, item.complex?
+        convert_outline_list_item item, item.complex?, opts
       end
     end
     # NOTE Children will provide the necessary bottom margin if last item is complex.
@@ -984,57 +1091,71 @@ class Converter < ::Prawn::Document
     end
   end
 
-  def convert_outline_list_item node, complex = false
+  def convert_outline_list_item node, complex = false, opts = {}
     # TODO move this to a draw_bullet (or draw_marker) method
+    marker_style = {}
+    marker_style[:font_color] = @theme.outline_list_marker_font_color || @font_color
+    marker_style[:font_family] = font_family
+    marker_style[:font_size] = font_size
+    marker_style[:line_height] = @theme.base_line_height
     case (list_type = node.parent.context)
     when :ulist
-      marker = @list_bullets[-1]
-      if marker == :checkbox
+      marker_type = @list_bullets[-1]
+      if marker_type == :checkbox
+        # QUESTION should we remove marker indent if not a checkbox?
         if node.attr? 'checkbox', nil, false
-          marker = BallotBox[(node.attr? 'checked', nil, false) ? :checked : :unchecked]
-        else
-          # QUESTION should we remove marker indent in this case?
-          marker = nil
+          marker_type = (node.attr? 'checked', nil, false) ? :checked : :unchecked
+          marker = @theme[%(ulist_marker_#{marker_type}_content)] || BallotBox[marker_type]
         end
+      else
+        marker = @theme[%(ulist_marker_#{marker_type}_content)] || Bullets[marker_type]
       end
+      [:font_color, :font_family, :font_size, :line_height].each do |prop|
+        marker_style[prop] = @theme[%(ulist_marker_#{marker_type}_#{prop})] || @theme[%(ulist_marker_#{prop})] || marker_style[prop]
+      end if marker
     when :olist
       dir = (node.parent.option? 'reversed') ? :pred : :next
       @list_numbers << ((index = @list_numbers.pop).public_send dir)
       marker = %(#{index}.)
     else
-      warn %(asciidoctor: WARNING: unknown list type #{list_type.inspect})
-      marker = Bullets[:disc]
+      logger.warn %(unknown list type #{list_type.inspect})
+      marker = @theme.ulist_marker_disc_content || Bullets[:disc]
     end
 
     if marker
-      marker_width = rendered_width_of_string marker
-      start_position = -marker_width + -(rendered_width_of_char 'x')
-      float do
-        flow_bounding_box start_position, width: marker_width do
-          layout_prose marker,
-            align: :right,
-            color: (@theme.outline_list_marker_font_color || @font_color),
-            normalize: false,
-            inline_format: false,
-            margin: 0,
-            character_spacing: -0.5,
-            single_line: true
+      if marker_style[:font_family] == 'fa'
+        logger.info { 'deprecated fa icon set found in theme; use fas, far, or fab instead' }
+        marker_style[:font_family] = FontAwesomeIconSets.find {|candidate| (icon_font_data candidate).yaml[candidate].value? marker } || 'fas'
+      end
+      marker_gap = rendered_width_of_char 'x'
+      font marker_style[:font_family], size: marker_style[:font_size] do
+        marker_width = rendered_width_of_string marker
+        start_position = -marker_width + -marker_gap
+        float do
+          flow_bounding_box start_position, width: marker_width do
+            layout_prose marker,
+              align: :right,
+              character_spacing: -0.5,
+              color: marker_style[:font_color],
+              inline_format: false,
+              line_height: marker_style[:line_height],
+              margin: 0,
+              normalize: false,
+              single_line: true
+          end
         end
       end
     end
 
     if complex
-      convert_content_for_list_item node
+      convert_content_for_list_item node, opts
     else
-      convert_content_for_list_item node, margin_bottom: @theme.outline_list_item_spacing
+      convert_content_for_list_item node, (opts.merge margin_bottom: @theme.outline_list_item_spacing)
     end
   end
 
   def convert_content_for_list_item node, opts = {}
-    if node.text?
-      opts[:align] = :left if node.parent.style == 'bibliography'
-      layout_prose node.text, opts
-    end
+    layout_prose node.text, opts if node.text?
     convert_content_for_block node
   end
 
@@ -1043,7 +1164,7 @@ class Converter < ::Prawn::Document
     target, image_format = node.target_and_format
 
     if image_format == 'gif' && !(defined? ::GMagick::Image)
-      warn %(asciidoctor: WARNING: GIF image format not supported. Install the prawn-gmagick gem or convert #{target} to PNG.) unless scratch?
+      logger.warn %(GIF image format not supported. Install the prawn-gmagick gem or convert #{target} to PNG.) unless scratch?
       image_path = false
     elsif ::Base64 === target
       image_path = target
@@ -1053,7 +1174,7 @@ class Converter < ::Prawn::Document
       # QUESTION should we add destination to top of imported page?
       return import_page image_path, replace: page_is_empty? if image_format == 'pdf'
     else
-      warn %(asciidoctor: WARNING: image to embed not found or not readable: #{image_path || target}) unless scratch?
+      logger.warn %(image to embed not found or not readable: #{image_path || target}) unless scratch?
       # QUESTION should we use alt text in this case?
       return if image_format == 'pdf'
       image_path = false
@@ -1074,21 +1195,22 @@ class Converter < ::Prawn::Document
     # TODO support cover (aka canvas) image layout using "canvas" (or "cover") role
     width = resolve_explicit_width node.attributes, (available_w = bounds.width), support_vw: true, use_fallback: true
     # TODO add `to_pt page_width` method to ViewportWidth type
-    width = (width.to_f / 100) * page_width if (width_relative_to_page = ViewportWidth === width)
+    width = (width.to_f / 100) * page_width if ViewportWidth === width
 
     alignment = ((node.attr 'align', nil, false) || @theme.image_align).to_sym
+    align_to_page = node.option? 'align-to-page'
 
     begin
-      span_page_width_if width_relative_to_page do
+      span_page_width_if align_to_page do
         if image_format == 'svg'
           if ::Base64 === image_path
             svg_data = ::Base64.decode64 image_path
             file_request_root = false
           else
-            svg_data = ::IO.read image_path
+            svg_data = ::File.read image_path
             file_request_root = ::File.dirname image_path
           end
-          svg_obj = ::Prawn::Svg::Interface.new svg_data, self,
+          svg_obj = ::Prawn::SVG::Interface.new svg_data, self,
               position: alignment,
               width: width,
               fallback_font_name: default_svg_font,
@@ -1160,15 +1282,15 @@ class Converter < ::Prawn::Document
       end
       layout_caption node, side: :bottom if node.title?
       theme_margin :block, :bottom unless pinned
-    rescue => e
-      on_image_error :exception, node, target, (opts.merge message: %(asciidoctor: WARNING: could not embed image: #{image_path}; #{e.message}))
+    rescue
+      on_image_error :exception, node, target, (opts.merge message: %(could not embed image: #{image_path}; #{$!.message}))
     end
   ensure
     unlink_tmp_file image_path if image_path
   end
 
   def on_image_error reason, node, target, opts = {}
-    warn opts[:message] if opts.key? :message
+    logger.warn opts[:message] if opts.key? :message
     alt_text = (link = node.attr 'link', nil, false) ?
         %(<a href="#{link}">[#{node.attr 'alt'}]</a> | <em>#{target}</em>) :
         %([#{node.attr 'alt'}] | <em>#{target}</em>)
@@ -1186,8 +1308,7 @@ class Converter < ::Prawn::Document
     add_dest_for_block node if node.id
     theme_margin :block, :top
     audio_path = node.media_uri(node.attr 'target')
-    play_symbol = (node.document.attr? 'icons', 'font') ?
-        %(<font name="fa">#{::Prawn::Icon::FontData.load(self, 'fa').unicode 'play'}</font>) : RightPointer
+    play_symbol = (node.document.attr? 'icons', 'font') ? %(<font name="fas">#{(icon_font_data 'fas').unicode 'play'}</font>) : RightPointer
     layout_prose %(#{play_symbol}#{NoBreakSpace}<a href="#{audio_path}">#{audio_path}</a> <em>(audio)</em>), normalize: false, margin: 0, single_line: true
     layout_caption node, side: :bottom if node.title?
     theme_margin :block, :bottom
@@ -1223,8 +1344,7 @@ class Converter < ::Prawn::Document
     if poster.nil_or_empty?
       add_dest_for_block node if node.id
       theme_margin :block, :top
-      play_symbol = (node.document.attr? 'icons', 'font') ?
-          %(<font name="fa">#{::Prawn::Icon::FontData.load(self, 'fa').unicode 'play'}</font>) : RightPointer
+      play_symbol = (node.document.attr? 'icons', 'font') ? %(<font name="fas">#{(icon_font_data 'fas').unicode 'play'}</font>) : RightPointer
       layout_prose %(#{play_symbol}#{NoBreakSpace}<a href="#{video_path}">#{video_path}</a> <em>(#{type})</em>), normalize: false, margin: 0, single_line: true
       layout_caption node, side: :bottom if node.title?
       theme_margin :block, :bottom
@@ -1320,30 +1440,32 @@ class Converter < ::Prawn::Document
       source_string, conum_mapping = extract_conums source_string
       # NOTE pygments.rb strips trailing whitespace; preserve it in case there are conums on last line
       num_trailing_spaces = source_string.length - (source_string = source_string.rstrip).length if conum_mapping
-      result = lexer.highlight source_string, options: lexer_opts
-      fragments = guard_indentation text_formatter.format result
-      conum_mapping ? (restore_conums fragments, conum_mapping, num_trailing_spaces) : fragments
+      # NOTE highlight can return nil if something goes wrong; fallback to encoded source string if this happens
+      result = (lexer.highlight source_string, options: lexer_opts) || (node.apply_subs source_string, [:specialcharacters])
+      if (linenums = node.attr? 'linenums')
+        linenums = (node.attr 'start', 1, false).to_i
+        @theme.code_linenum_font_color ||= '999999'
+        conum_mapping ||= {}
+      end
+      fragments = text_formatter.format result
+      fragments = restore_conums fragments, conum_mapping, num_trailing_spaces, linenums if conum_mapping
+      fragments = guard_indentation fragments
     when 'rouge'
       Helpers.require_library RougeRequirePath, 'rouge' unless defined? ::Rouge::Formatters::Prawn
       lexer = ::Rouge::Lexer.find(node.attr 'language', 'text', false) || ::Rouge::Lexers::PlainText
       lexer_opts = lexer.tag == 'php' ? { start_inline: !(node.option? 'mixed') } : {}
       formatter = (@rouge_formatter ||= ::Rouge::Formatters::Prawn.new theme: (node.document.attr 'rouge-style'), line_gap: @theme.code_line_gap)
-      formatter_opts = (node.attr? 'linenums') ? { line_numbers: true, start_line: (node.attr 'start').to_i } : {}
+      formatter_opts = (node.attr? 'linenums') ? { line_numbers: true, start_line: (node.attr 'start', 1, false).to_i } : {}
       # QUESTION allow border color to be set by theme for highlighted block?
       bg_color_override = formatter.background_color
       source_string, conum_mapping = extract_conums source_string
-      # NOTE trailing endline is added to address https://github.com/jneen/rouge/issues/279
-      fragments = formatter.format((lexer.lex %(#{source_string}#{LF}), lexer_opts), formatter_opts)
+      fragments = formatter.format((lexer.lex source_string, lexer_opts), formatter_opts)
       # NOTE cleanup trailing endline (handled in rouge_ext/formatters/prawn instead)
       #fragments[-1][:text] == LF ? fragments.pop : fragments[-1][:text].chop!
       conum_mapping ? (restore_conums fragments, conum_mapping) : fragments
     else
       # NOTE only format if we detect a need (callouts or inline formatting)
-      if source_string =~ BuiltInEntityCharOrTagRx
-        text_formatter.format source_string
-      else
-        [{ text: source_string }]
-      end
+      (XMLMarkupRx.match? source_string) ? (text_formatter.format source_string) : [{ text: source_string }]
     end
 
     node.subs.replace prev_subs if prev_subs
@@ -1403,8 +1525,8 @@ class Converter < ::Prawn::Document
     theme_margin :block, :bottom
   end
 
-  alias :convert_listing :convert_listing_or_literal
-  alias :convert_literal :convert_listing_or_literal
+  alias convert_listing convert_listing_or_literal
+  alias convert_literal convert_listing_or_literal
 
   # Extract callout marks from string, indexed by 0-based line number
   # Return an Array with the processed string as the first argument
@@ -1435,7 +1557,7 @@ class Converter < ::Prawn::Document
   #--
   # QUESTION can this be done more efficiently?
   # QUESTION can we reuse arrange_fragments_by_line?
-  def restore_conums fragments, conum_mapping, num_trailing_spaces = 0
+  def restore_conums fragments, conum_mapping, num_trailing_spaces = 0, linenums = nil
     lines = []
     line_num = 0
     # reorganize the fragments into an array of lines
@@ -1454,9 +1576,14 @@ class Converter < ::Prawn::Document
     end
     conum_color = @theme.conum_font_color
     last_line_num = lines.size - 1
+    if linenums
+      pad_size = (last_line_num + 1).to_s.length
+      linenum_color = @theme.code_linenum_font_color
+    end
     # 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
       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 } * ' '
@@ -1550,14 +1677,17 @@ class Converter < ::Prawn::Document
           colspan: cell.colspan || 1,
           rowspan: cell.rowspan || 1,
           align: (cell.attr 'halign', nil, false).to_sym,
-          valign: (val = cell.attr 'valign', nil, false) == 'middle' ? :center : val.to_sym
+          valign: (val = cell.attr 'valign', nil, false) == 'middle' ? :center : val.to_sym,
+          padding: theme.table_cell_padding
         }
         cell_transform = nil
         case cell.style
         when :emphasis
           cell_data[:font_style] = :italic
+          cell_line_metrics = calc_line_metrics theme.base_line_height
         when :strong
           cell_data[:font_style] = :bold
+          cell_line_metrics = calc_line_metrics theme.base_line_height
         when :header
           unless header_cell_data_cache
             header_cell_data_cache = {}
@@ -1582,6 +1712,7 @@ class Converter < ::Prawn::Document
             cell_transform = nil
           end
           cell_data.update header_cell_data unless header_cell_data.empty?
+          cell_line_metrics = calc_line_metrics theme.base_line_height
         when :monospaced
           cell_data[:font] = theme.literal_font_family
           if (val = theme.literal_font_size)
@@ -1590,8 +1721,7 @@ class Converter < ::Prawn::Document
           if (val = theme.literal_font_color)
             cell_data[:text_color] = val
           end
-          # TODO need to also add top and bottom padding from line metrics
-          #cell_data[:leading] = (calc_line_metrics theme.base_line_height).leading
+          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'))
@@ -1604,17 +1734,28 @@ class Converter < ::Prawn::Document
           if (val = theme.code_font_color)
             cell_data[:text_color] = val
           end
-          # TODO need to also add top and bottom padding from line metrics
-          #cell_data[:leading] = (calc_line_metrics theme.code_line_height).leading
+          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[:inline_format] = true
+          cell_line_metrics = calc_line_metrics theme.base_line_height
         when :asciidoc
           asciidoc_cell = ::Prawn::Table::Cell::AsciiDoc.new self,
               (cell_data.merge content: cell.inner_document, font_style: (val = theme.table_font_style) ? val.to_sym : nil)
           cell_data = { content: asciidoc_cell }
         else
           cell_data[:font_style] = (val = theme.table_font_style) ? val.to_sym : nil
+          cell_line_metrics = calc_line_metrics theme.base_line_height
+        end
+        if cell_line_metrics
+          unless ::Array === (cell_padding = cell_data[:padding]) && cell_padding.size == 4
+            cell_padding = cell_data[:padding] = inflate_padding cell_padding
+          end
+          cell_padding[0] += cell_line_metrics.padding_top
+          cell_padding[2] += cell_line_metrics.padding_bottom
+          cell_data[:leading] = cell_line_metrics.leading
+          # TODO patch prawn-table to pass through final_gap option
+          #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
@@ -1651,7 +1792,7 @@ class Converter < ::Prawn::Document
     table_grid_width = theme.table_grid_width || theme.table_border_width
     [:cols, :rows].each {|edge| border_width[edge] = table_grid_width }
 
-    case (grid = node.attr 'grid', 'all', false)
+    case (grid = node.attr 'grid', 'all', 'table-grid')
     when 'all'
       # keep inner borders
     when 'cols'
@@ -1662,10 +1803,10 @@ class Converter < ::Prawn::Document
       border_width[:rows] = border_width[:cols] = 0
     end
 
-    case (frame = node.attr 'frame', 'all', false)
+    case (frame = node.attr 'frame', 'all', 'table-frame')
     when 'all'
       # keep outer borders
-    when 'topbot'
+    when 'topbot', 'ends'
       border_width[:left] = border_width[:right] = 0
     when 'sides'
       border_width[:top] = border_width[:bottom] = 0
@@ -1703,15 +1844,14 @@ class Converter < ::Prawn::Document
         border_color: table_grid_color,
         border_lines: [table_grid_style],
         # NOTE the border width is set later
-        border_width: 0,
-        padding: theme.table_cell_padding
+        border_width: 0
       },
       width: table_width,
       column_widths: column_widths
     }
 
     # QUESTION should we support nth; should we support sequence of roles?
-    case node.attr 'stripes', 'even', false
+    case node.attr 'stripes', nil, 'table-stripes'
     when 'all'
       table_settings[:row_colors] = [body_stripe_bg_color]
     when 'even'
@@ -1799,7 +1939,7 @@ class Converter < ::Prawn::Document
   end
 
   # deprecated
-  alias :convert_horizontal_rule :convert_thematic_break
+  alias convert_horizontal_rule convert_thematic_break
 
   # NOTE manual placement not yet possible, so return nil
   def convert_toc node
@@ -1808,13 +1948,25 @@ class Converter < ::Prawn::Document
 
   # NOTE to insert sequential page breaks, you must put {nbsp} between page breaks
   def convert_page_break node
-    advance_page unless at_page_top?
+    unless at_page_top?
+      if (page_layout = node.attr 'page-layout').nil_or_empty?
+        if node.role? && (page_layout = (node.roles.map(&:to_sym) & PageLayouts)[-1])
+          advance_page layout: page_layout
+        else
+          advance_page
+        end
+      elsif PageLayouts.include?(page_layout = page_layout.to_sym)
+        advance_page layout: page_layout
+      else
+        advance_page
+      end
+    end
   end
 
   def convert_index_section node
     unless @index.empty?
       space_needed_for_category = @theme.description_list_term_spacing + (2 * (height_of_typeset_text 'A'))
-      column_box [0, cursor], columns: 2, width: bounds.width do
+      column_box [0, cursor], columns: 2, width: bounds.width, reflow_margins: true do
         @index.categories.each do |category|
           # NOTE cursor method always returns 0 inside column_box; breaks reference_bounds.move_past_bottom
           bounds.move_past_bottom if space_needed_for_category > y - reference_bounds.absolute_bottom
@@ -1844,7 +1996,7 @@ class Converter < ::Prawn::Document
       if @media == 'screen'
         pagenums = term.dests.map {|dest| %(<a anchor="#{dest[:anchor]}">#{dest[:page]}</a>) }
       else
-        pagenums = term.dests.uniq {|dest| dest[:page] }.map {|dest| dest[:page].to_s }
+        pagenums = consolidate_ranges term.dests.uniq {|dest| dest[:page] }.map {|dest| dest[:page].to_s }
       end
       text = %(#{text}, #{pagenums * ', '})
     end
@@ -1901,12 +2053,16 @@ class Converter < ::Prawn::Document
       end
     when :ref
       # NOTE destination is created inside callback registered by FormattedTextTransform#build_fragment
-      %(<a name="#{node.target}">#{DummyText}</a>)
+      # NOTE id is used instead of target starting in Asciidoctor 2.0.0
+      %(<a name="#{node.target || node.id}">#{DummyText}</a>)
     when :bibref
       # NOTE destination is created inside callback registered by FormattedTextTransform#build_fragment
-      %(<a name="#{target = node.target}">#{DummyText}</a>[#{target}])
+      # NOTE technically node.text should be node.reftext, but subs have already been applied to text
+      # NOTE check reftext? for compatibility with Asciidoctor <= 1.5.5
+      # NOTE id is used instead of target starting in Asciidoctor 2.0.0
+      %(<a name="#{node.target || node.id}">#{DummyText}</a>#{(reftext = node.reftext) ? reftext : "[#{node.target || node.id}]"})
     else
-      warn %(asciidoctor: WARNING: unknown anchor type: #{node.type.inspect})
+      logger.warn %(unknown anchor type: #{node.type.inspect})
     end
   end
 
@@ -1929,9 +2085,9 @@ class Converter < ::Prawn::Document
   end
 
   def convert_inline_footnote node
-    if (index = node.attr 'index')
-      #text = node.document.footnotes.find {|fn| fn.index == index }.text
-      %( <color rgb="#999999">[#{index}: #{node.text}]</color>)
+    if (index = node.attr 'index') && (node.document.footnotes.find {|fn| fn.index == index })
+      anchor = node.type == :xref ? '' : %(<a name="_footnoteref_#{index}">#{DummyText}</a>)
+      %(#{anchor}<sup>[<a anchor="_footnotedef_#{index}">#{index}</a>]</sup>)
     elsif node.type == :xref
       # NOTE footnote reference not found
       %( <color rgb="FF0000">[#{node.text}]</color>)
@@ -1947,16 +2103,34 @@ class Converter < ::Prawn::Document
       end
       icon_set = 'fa' unless IconSets.include? icon_set
       if node.attr? 'size', nil, false
-        size = (size = (node.attr 'size')) == 'lg' ? '1.3333em' : (size.sub 'x', 'em')
-        size_attr = %( size="#{size}")
+        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 = nil
+        size_attr = ''
       end
       begin
-        # TODO support rotate and flip attributes; support fw (full-width) size
-        %(<font name="#{icon_set}"#{size_attr}>#{::Prawn::Icon::FontData.load(self, icon_set).unicode icon_name}</font>)
+        if icon_set == 'fa'
+          font_data = nil
+          resolved_icon_set = FontAwesomeIconSets.find {|candidate| (font_data = icon_font_data candidate).unicode icon_name rescue nil }
+          if resolved_icon_set
+            icon_set = resolved_icon_set
+            logger.info { %(#{icon_name} icon found in deprecated fa icon set; use #{icon_set} icon set instead) }
+          else
+            raise
+          end
+        else
+          font_data = icon_font_data icon_set
+        end
+        # TODO support rotate and flip attributes
+        %(<font name="#{icon_set}"#{size_attr}>#{font_data.unicode icon_name}</font>)
       rescue
-        warn %(asciidoctor: WARNING: #{icon_name} is not a valid icon name in the #{icon_set} icon set)
+        logger.warn %(#{icon_name} is not a valid icon name in the #{icon_set} icon set)
         %([#{node.attr 'alt'}])
       end
     else
@@ -1971,14 +2145,14 @@ class Converter < ::Prawn::Document
       node.extend ::Asciidoctor::Image unless ::Asciidoctor::Image === node
       target, image_format = node.target_and_format
       if image_format == 'gif' && !(defined? ::GMagick::Image)
-        warn %(asciidoctor: WARNING: GIF image format not supported. Install the prawn-gmagick gem or convert #{target} to PNG.) unless scratch?
+        logger.warn %(GIF image format not supported. Install the prawn-gmagick gem or convert #{target} to PNG.) unless scratch?
         img = %([#{node.attr 'alt'}])
       # NOTE an image with a data URI is handled using a temporary file
       elsif (image_path = resolve_image_path node, target, true, image_format) && (::File.readable? image_path)
         width_attr = (width = preresolve_explicit_width node.attributes) ? %( width="#{width}") : nil
-        img = %(<img src="#{image_path}" format="#{image_format}" alt="[#{node.attr 'alt'}]"#{width_attr} tmp="#{TemporaryPath === image_path}">)
+        img = %(<img src="#{image_path}" format="#{image_format}" alt="[#{encode_quotes node.attr 'alt'}]"#{width_attr} tmp="#{TemporaryPath === image_path}">)
       else
-        warn %(asciidoctor: WARNING: image to embed not found or not readable: #{image_path || target}) unless scratch?
+        logger.warn %(image to embed not found or not readable: #{image_path || target}) unless scratch?
         img = %([#{node.attr 'alt'}])
       end
       (node.attr? 'link', nil, false) ? %(<a href="#{node.attr 'link'}">#{img}</a>) : img
@@ -2016,7 +2190,7 @@ class Converter < ::Prawn::Document
 
   def convert_inline_menu node
     menu = node.attr 'menu'
-    caret = @theme.menu_caret_content || %( \u203a )
+    caret = (load_theme node.document).menu_caret_content || %( \u203a )
     if !(submenus = node.attr 'submenus').empty?
       %(<strong>#{[menu, *submenus, (node.attr 'menuitem')] * caret}</strong>)
     elsif (menuitem = node.attr 'menuitem')
@@ -2061,7 +2235,6 @@ class Converter < ::Prawn::Document
     node.id ? %(<a name="#{node.id}">#{DummyText}</a>#{quoted_text}) : quoted_text
   end
 
-  # FIXME only create title page if doctype=book!
   def layout_title_page doc
     return unless doc.header? && !doc.notitle
 
@@ -2196,7 +2369,7 @@ class Converter < ::Prawn::Document
           image_page cover_image, canvas: true
         end
       else
-        warn %(asciidoctor: WARNING: #{face} cover image not found or readable: #{cover_image})
+        logger.warn %(#{face} cover image not found or readable: #{cover_image})
       end
     end
   ensure
@@ -2213,19 +2386,19 @@ class Converter < ::Prawn::Document
     layout_heading title, opts
   end
 
-  alias :start_new_part :start_new_chapter
-  alias :layout_part_title :layout_chapter_title
+  alias start_new_part start_new_chapter
+  alias layout_part_title layout_chapter_title
 
   # QUESTION why doesn't layout_heading set the font??
   # 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_margin_top
-    bot_margin = margin || (opts.delete :margin_bottom) || @theme.heading_margin_bottom
+    top_margin = (margin = (opts.delete :margin)) || (opts.delete :margin_top) || @theme[%(heading_h#{opts[:level]}_margin_top)] || @theme.heading_margin_top
+    bot_margin = margin || (opts.delete :margin_bottom) || @theme[%(heading_h#{opts[:level]}_margin_bottom)] || @theme.heading_margin_bottom
     if (transform = (opts.delete :text_transform) || @text_transform) && transform != 'none'
       string = transform_text string, transform
     end
     margin_top top_margin
-    typeset_text string, calc_line_metrics((opts.delete :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), {
       color: @font_color,
       inline_format: true,
       align: @base_align.to_sym
@@ -2254,8 +2427,20 @@ class Converter < ::Prawn::Document
     margin_bottom bot_margin
   end
 
+  def generate_manname_section node
+    title = node.attr 'manname-title', 'Name'
+    if (next_section = node.sections[0]) && (next_section_title = next_section.title) == next_section_title.upcase
+      title = title.upcase
+    end
+    sect = Section.new node, 1
+    sect.sectname = 'section'
+    sect.id = node.attr 'manname-id'
+    sect.title = title
+    sect << (Block.new sect, :paragraph, source: %(#{node.attr 'manname'} - #{node.attr 'manpurpose'}))
+    sect
+  end
+
   # Render the caption and return the height of the rendered content
-  # QUESTION should layout_caption check for title? and return 0 if false?
   # TODO allow margin to be zeroed
   def layout_caption subject, opts = {}
     mark = { cursor: cursor, page_number: page_number }
@@ -2263,7 +2448,11 @@ class Converter < ::Prawn::Document
     when ::String
       string = subject
     when ::Asciidoctor::AbstractBlock
-      string = subject.title? ? subject.captioned_title : nil
+      if subject.title?
+        string = subject.captioned_title
+      else
+        return 0
+      end
     else
       return 0
     end
@@ -2306,9 +2495,10 @@ class Converter < ::Prawn::Document
   end
 
   # NOTE num_front_matter_pages is not used during a dry run
-  def layout_toc doc, num_levels = 2, toc_page_number = 2, num_front_matter_pages = 0
+  def layout_toc doc, num_levels = 2, toc_page_number = 2, num_front_matter_pages = 0, start_at = nil
     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
@@ -2374,7 +2564,10 @@ class Converter < ::Prawn::Document
               key == :styles ? (old_val.merge new_val) : new_val
             end
           end
-          typeset_formatted_text sect_title_fragments, line_metrics
+          pgnum_label_width = rendered_width_of_string pgnum_label
+          indent 0, pgnum_label_width do
+            typeset_formatted_text sect_title_fragments, line_metrics
+          end
           end_page_number = page_number
           end_cursor = cursor
           # TODO it would be convenient to have a cursor mark / placement utility that took page number into account
@@ -2382,7 +2575,6 @@ class Converter < ::Prawn::Document
           move_cursor_to start_cursor
           if dot_leader[:width] > 0 && (dot_leader[:levels].include? sect.level)
             pgnum_label_font_settings = { color: @font_color, font: font_family, size: @font_size, styles: font_styles }
-            pgnum_label_width = rendered_width_of_string pgnum_label
             # WARNING width_of is not accurate if string must use characters from fallback font
             sect_title_width = width_of sect_title, inline_format: true
             save_font do
@@ -2478,15 +2670,17 @@ class Converter < ::Prawn::Document
     (1..num_pages).each do |num|
       if (part = part_start_pages[num])
         last_part = part
+        last_chap = nil
+        last_sect = nil
       end
       if (chap = chapter_start_pages[num])
         last_chap = chap
+        last_sect = nil
       end
       if (sect = section_start_pages[num])
         last_sect = sect
       elsif part || chap
         sect_search_threshold = num
-        last_sect = nil
       # NOTE we didn't find a section on this page; look back to find last section started
       elsif last_sect
         ((sect_search_threshold)..(num - 1)).reverse_each do |prev|
@@ -2713,8 +2907,8 @@ class Converter < ::Prawn::Document
                   bounding_box [colspec[:x], cursor - trim_padding[0]], width: colspec[:width], height: (bounds.height - trim_v_padding) do
                     begin
                       if (img_path = content[:path]).downcase.end_with? '.svg'
-                        svg_data = ::IO.read img_path
-                        svg_obj = ::Prawn::Svg::Interface.new svg_data, self,
+                        svg_data = ::File.read img_path
+                        svg_obj = ::Prawn::SVG::Interface.new svg_data, self,
                             position: colspec[:align],
                             vposition: trim_img_valign,
                             width: content[:width],
@@ -2735,8 +2929,8 @@ class Converter < ::Prawn::Document
                         end
                         image img_path, img_opts
                       end
-                    rescue => e
-                      warn %(asciidoctor: WARNING: could not embed image in running content: #{img_path}; #{e.message})
+                    rescue
+                      logger.warn %(could not embed image in running content: #{img_path}; #{$!.message})
                     end
                   end
                 end
@@ -2953,7 +3147,7 @@ class Converter < ::Prawn::Document
       end
       available_width = bounds.width - (padding[3] || 0) - (padding[1] || 0)
       if actual_width > available_width
-        adjusted_font_size = ((available_width * font_size).to_f / actual_width).truncate_to_precision 4
+        adjusted_font_size = ((available_width * font_size).to_f / actual_width).truncate 4
         if (min = @theme[%(#{category}_font_size_min)] || @theme.base_font_size_min) && adjusted_font_size < min
           min
         else
@@ -3133,7 +3327,7 @@ class Converter < ::Prawn::Document
   # experience.
   def add_dest_for_block node, id = nil
     if !scratch? && (id ||= node.id)
-      dest_x = bounds.absolute_left.truncate_to_precision 4
+      dest_x = bounds.absolute_left.truncate 4
       # QUESTION when content is aligned to left margin, should we keep precise x value or just use 0?
       dest_x = 0 if dest_x <= page_margin_left
       dest_y = at_page_top? && (node.context == :section || node.context == :document) ? page_height : y
@@ -3144,6 +3338,14 @@ class Converter < ::Prawn::Document
     nil
   end
 
+  def resolve_alignment_from_role roles
+    if (align_role = roles.reverse.find {|r| TextAlignmentRoles.include? r })
+      align_role[5..-1].to_sym
+    else
+      nil
+    end
+  end
+
   # QUESTION is this method still necessary?
   def resolve_imagesdir doc
     if (imagesdir = doc.attr 'imagesdir').nil_or_empty? || (imagesdir = imagesdir.chomp '/') == '.'
@@ -3173,7 +3375,7 @@ class Converter < ::Prawn::Document
     image_format ||= ::Asciidoctor::Image.format image_path, (::Asciidoctor::Image === node ? node : nil)
     # NOTE currently used for inline images
     if ::Base64 === image_path
-      tmp_image = ::Tempfile.new ['image-', image_format && %(.#{image_format})]
+      tmp_image = ::Tempfile.create ['image-', image_format && %(.#{image_format})]
       tmp_image.binmode unless image_format == 'svg'
       begin
         tmp_image.write(::Base64.decode64 image_path)
@@ -3187,7 +3389,7 @@ class Converter < ::Prawn::Document
     elsif (node.is_uri? image_path) || (imagesdir && (node.is_uri? imagesdir) &&
         (image_path = (node.normalize_web_path image_path, imagesdir, false)))
       unless doc.attr? 'allow-uri-read'
-        warn %(asciidoctor: WARNING: allow-uri-read is not enabled; cannot embed remote image: #{image_path}) unless scratch?
+        logger.warn %(allow-uri-read is not enabled; cannot embed remote image: #{image_path}) unless scratch?
         return
       end
       if doc.attr? 'cache-uri'
@@ -3195,7 +3397,7 @@ class Converter < ::Prawn::Document
       else
         ::OpenURI
       end
-      tmp_image = ::Tempfile.new ['image-', image_format && %(.#{image_format})]
+      tmp_image = ::Tempfile.create ['image-', image_format && %(.#{image_format})]
       tmp_image.binmode if (binary = image_format != 'svg')
       begin
         open(image_path, (binary ? 'rb' : 'r')) {|fd| tmp_image.write fd.read }
@@ -3234,7 +3436,7 @@ class Converter < ::Prawn::Document
         if ::File.readable? bg_image
           bg_image
         else
-          warn %(asciidoctor: WARNING: #{key.tr '-', ' '} not found or readable: #{bg_image})
+          logger.warn %(#{key.tr '-', ' '} not found or readable: #{bg_image})
           nil
         end
       end
@@ -3303,20 +3505,39 @@ class Converter < ::Prawn::Document
   # NOTE Ruby 1.9 will sometimes delete a tmp file before the process exits
   def unlink_tmp_file path
     path.unlink if TemporaryPath === path && path.exist?
-  rescue => e
-    warn %(asciidoctor: WARNING: could not delete temporary image: #{path}; #{e.message})
+  rescue
+    logger.warn %(could not delete temporary image: #{path}; #{$!.message})
   end
 
   # NOTE assume URL is escaped (i.e., contains character references such as &amp;)
   def breakable_uri uri
     scheme, address = uri.split UriSchemeBoundaryRx, 2
     address, scheme = scheme, address unless address
-    address = address.gsub UriBreakCharsRx, UriBreakCharRepl
-    # NOTE require at least two characters after a break
-    address.slice!(-2) if address[-2] == ZeroWidthSpace
+    unless address.nil_or_empty?
+      address = address.gsub UriBreakCharsRx, UriBreakCharRepl
+      # NOTE require at least two characters after a break
+      address.slice!(-2) if address[-2] == ZeroWidthSpace
+    end
     %(#{scheme}#{address})
   end
 
+  def consolidate_ranges nums
+    if nums.size > 1
+      prev = nil
+      nums.inject([]) {|accum, num|
+        if prev && (prev.to_i + 1) == num.to_i
+          accum[-1][1] = num
+        else
+          accum << [num]
+        end
+        prev = num
+        accum
+      }.map {|range| range.join '-' }
+    else
+      nums
+    end
+  end
+
   # QUESTION move to prawn/extensions.rb?
   def init_scratch_prototype
     # IMPORTANT don't set font before using Marshal, it causes serialization to fail
@@ -3341,4 +3562,5 @@ class Converter < ::Prawn::Document
 =end
 end
 end
+Pdf = PDF unless const_defined? :Pdf, false
 end