asciidoctor-pdf 1.5.0.beta.7 → 1.5.0.beta.8

data/lib/asciidoctor/pdf/converter.rb

@@ -14,6 +14,7 @@ require_relative 'ext/pdf-core'
 require_relative 'temporary_path'
 require_relative 'measurements'
 require_relative 'sanitizer'
+require_relative 'text_transformer'
 require_relative 'ext/prawn'
 require_relative 'formatted_text'
 require_relative 'pdfmark'
@@ -53,12 +54,14 @@ class Converter < ::Prawn::Document
   }
   TextAlignmentNames = ['justify', 'left', 'center', 'right']
   TextAlignmentRoles = ['text-justify', 'text-left', 'text-center', 'text-right']
+  TextDecorationStyleTable = { 'underline' => :underline, 'line-through' => :strikethrough }
   BlockAlignmentNames = ['left', 'center', 'right']
   AlignmentTable = { '<' => :left, '=' => :center, '>' => :right }
   ColumnPositions = [:left, :center, :right]
   PageLayouts = [:portrait, :landscape]
   PageSides = [:recto, :verso]
   (PDFVersions = { '1.3' => 1.3, '1.4' => 1.4, '1.5' => 1.5, '1.6' => 1.6, '1.7' => 1.7 }).default = 1.4
+  AuthorAttributeNames = ['author', 'authorinitials', 'firstname', 'middlename', 'lastname', 'email']
   LF = ?\n
   DoubleLF = LF * 2
   TAB = ?\t
@@ -106,6 +109,7 @@ class Converter < ::Prawn::Document
   CjkLineBreakRx = /(?=[\u3000\u30a0-\u30ff\u3040-\u309f\p{Han}\uff00-\uffef])/
   WhitespaceChars = ' ' + TAB + LF
   ValueSeparatorRx = /;|,/
+  HexColorRx = /^#[a-fA-F0-9]{6}$/
   SourceHighlighters = ['coderay', 'pygments', 'rouge'].to_set
   PygmentsBgColorRx = /^\.highlight +{ *background: *#([^;]+);/
   ViewportWidth = ::Module.new
@@ -125,16 +129,15 @@ class Converter < ::Prawn::Document
       doc.attributes['data-uri'] = ((doc.instance_variable_get :@attribute_overrides) || {})['data-uri'] = ''
     end
     @capabilities = {
-      honors_literal_cell_style: AsciidoctorVersion >= (::Gem::Version.create '1.5.6'),
       special_sectnums: AsciidoctorVersion >= (::Gem::Version.create '1.5.7'),
       syntax_highlighter: AsciidoctorVersion >= (::Gem::Version.create '2.0.0'),
     }
+    @initial_instance_variables = [:@initial_instance_variables] + instance_variables
   end
 
   def convert node, name = nil, opts = {}
     method_name = %(convert_#{name ||= node.node_name})
     if respond_to? method_name
-      # NOTE we prepend the prefix "convert_" to avoid conflict with Prawn methods
       result = send method_name, node
     else
       # TODO delegate to convert_method_missing
@@ -154,7 +157,7 @@ class Converter < ::Prawn::Document
       node.content
     elsif node.content_model != :compound && (string = node.content)
       # TODO this content could be cached on repeat invocations!
-      layout_prose string, opts
+      layout_prose string, (opts.merge hyphenate: true)
     end
     node.document.instance_variable_set :@converter, prev_converter if prev_converter
   end
@@ -259,7 +262,10 @@ 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.empty? && page_count > 1
+      if page_count > 1
+        go_to_page page_count unless last_page?
+        delete_page if page.empty?
+      end
 
       toc_page_nums = @toc_extent ? (layout_toc doc, toc_num_levels, @toc_extent[:page_nums].first, @toc_extent[:start_y], num_front_matter_pages[1]) : []
     end
@@ -273,6 +279,7 @@ class Converter < ::Prawn::Document
       end
     end
 
+    catalog.data[:PageMode] = :FullScreen if (doc.attr 'pdf-page-mode', @theme.page_mode) == 'fullscreen'
     add_outline doc, (doc.attr 'outlinelevels', toc_num_levels), toc_page_nums, num_front_matter_pages[1], has_front_cover
     if state.pages.size > 0 && (initial_zoom = @theme.page_initial_zoom)
       case initial_zoom.to_sym
@@ -296,8 +303,8 @@ class Converter < ::Prawn::Document
   # it the same as a full document.
   alias convert_embedded convert_document
 
-  # TODO only allow method to be called once (or we need a reset)
   def init_pdf doc
+    (instance_variables - @initial_instance_variables).each {|ivar| remove_instance_variable ivar } if state
     pdf_opts = build_pdf_options doc, (theme = load_theme doc)
     # QUESTION should page options be preserved? (otherwise, not readily available)
     #@page_opts = { size: pdf_opts[:page_size], layout: pdf_opts[:page_layout] }
@@ -323,6 +330,7 @@ class Converter < ::Prawn::Document
     default_kerning theme.base_font_kerning != 'none'
     @fallback_fonts = [*theme.font_fallbacks]
     @allow_uri_read = doc.attr? 'allow-uri-read'
+    @cache_uri = doc.attr? 'cache-uri'
     if (bg_image = resolve_background_image doc, theme, 'page-background-image') && bg_image[0]
       @page_bg_image = { verso: bg_image, recto: bg_image }
     else
@@ -339,6 +347,14 @@ class Converter < ::Prawn::Document
     @font_color = theme.base_font_color || '000000'
     @base_align = (align = doc.attr 'text-align') && (TextAlignmentNames.include? align) ? align : theme.base_align
     @cjk_line_breaks = doc.attr? 'scripts', 'cjk'
+    if (hyphen_lang = doc.attr 'hyphens')
+      hyphen_lang = doc.attr 'lang' if hyphen_lang.empty?
+      hyphen_lang = 'en_us' if hyphen_lang.nil_or_empty? || hyphen_lang == 'en'
+      hyphen_lang = (hyphen_lang.tr '-', '_').downcase
+      if (defined? ::Text::Hyphen) || !(Helpers.require_library 'text/hyphen', 'text-hyphen', :warn).nil?
+        @hyphenator = ::Text::Hyphen.new language: hyphen_lang
+      end
+    end
     @text_transform = nil
     @list_numerals = []
     @list_bullets = []
@@ -470,13 +486,16 @@ class Converter < ::Prawn::Document
     info[:Subject] = (doc.attr 'subject').as_pdf if doc.attr? 'subject'
     info[:Keywords] = (doc.attr 'keywords').as_pdf if doc.attr? 'keywords'
     info[:Producer] = (doc.attr 'publisher').as_pdf if doc.attr? 'publisher'
-    info[:Creator] = %(Asciidoctor PDF #{::Asciidoctor::PDF::VERSION}, based on Prawn #{::Prawn::VERSION}).as_pdf
-    info[:Producer] ||= (info[:Author] || info[:Creator])
-    unless doc.attr? 'reproducible'
+    if doc.attr? 'reproducible'
+      info[:Creator] = 'Asciidoctor PDF, based on Prawn'.as_pdf
+      info[:Producer] ||= (info[:Author] || info[:Creator])
+    else
+      info[:Creator] = %(Asciidoctor PDF #{::Asciidoctor::PDF::VERSION}, based on Prawn #{::Prawn::VERSION}).as_pdf
+      info[:Producer] ||= (info[:Author] || info[:Creator])
       # NOTE since we don't track the creation date of the input file, we map the ModDate header to the last modified
       # date of the input document and the CreationDate header to the date the PDF was produced by the converter.
-      info[:ModDate] = ::Time.parse(doc.attr 'docdatetime') rescue (now ||= ::Time.now)
-      info[:CreationDate] = ::Time.parse(doc.attr 'localdatetime') rescue (now ||= ::Time.now)
+      info[:ModDate] = (::Time.parse doc.attr 'docdatetime') rescue (now ||= ::Time.now)
+      info[:CreationDate] = (::Time.parse doc.attr 'localdatetime') rescue (now ||= ::Time.now)
     end
     info
   end
@@ -580,7 +599,7 @@ class Converter < ::Prawn::Document
       (title = doc.attr 'footnotes-title') && (layout_caption title, category: :footnotes)
       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
+        layout_prose %(<a name="_footnotedef_#{index = fn.index}">#{DummyText}</a>[<a anchor="_footnoteref_#{index}">#{index}</a>] #{fn.text}), margin_bottom: item_spacing, hyphenate: true
       end
       @footnotes += fns
     end
@@ -603,8 +622,8 @@ class Converter < ::Prawn::Document
           layout_prose node.title, align: (@theme.abstract_title_align || @base_align).to_sym, margin_top: (@theme.heading_margin_top || 0), margin_bottom: (@theme.heading_margin_bottom || 0), line_height: @theme.heading_line_height
         end if node.title?
         theme_font :abstract do
-          prose_opts = { line_height: @theme.abstract_line_height, align: (initial_alignment = (@theme.abstract_align || @base_align).to_sym) }
-          if (text_indent = @theme.prose_text_indent)
+          prose_opts = { line_height: @theme.abstract_line_height, align: (@theme.abstract_align || @base_align).to_sym, hyphenate: true }
+          if (text_indent = @theme.prose_text_indent || 0) > 0
             prose_opts[:indent_paragraphs] = text_indent
           end
           # FIXME control more first_line_options using theme
@@ -617,20 +636,16 @@ class Converter < ::Prawn::Document
               # FIXME is playback necessary here?
               child.document.playback_attributes child.attributes
               if child.context == :paragraph
-                if (alignment = resolve_alignment_from_role child.roles)
-                  prose_opts[:align] = alignment
-                end
-                layout_prose child.content, prose_opts
+                layout_prose child.content, ((align = resolve_alignment_from_role child.roles) ? (prose_opts.merge align: align) : prose_opts.dup)
                 prose_opts.delete :first_line_options
-                prose_opts[:align] = initial_alignment
               else
                 # FIXME this could do strange things if the wrong kind of content shows up
                 convert_content_for_block child
               end
             end
           elsif node.content_model != :compound && (string = node.content)
-            if (alignment = resolve_alignment_from_role node.roles)
-              prose_opts[:align] = alignment
+            if (align = resolve_alignment_from_role node.roles)
+              prose_opts[:align] = align
             end
             layout_prose string, prose_opts
           end
@@ -651,13 +666,13 @@ class Converter < ::Prawn::Document
 
   def convert_paragraph node
     add_dest_for_block node if node.id
-    prose_opts = { margin_bottom: 0 }
+    prose_opts = { margin_bottom: 0, hyphenate: true }
     lead = (roles = node.roles).include? 'lead'
     if (align = resolve_alignment_from_role roles)
       prose_opts[:align] = align
     end
 
-    if (text_indent = @theme.prose_text_indent)
+    if (text_indent = @theme.prose_text_indent || 0) > 0
       prose_opts[:indent_paragraphs] = text_indent
     end
 
@@ -675,11 +690,10 @@ class Converter < ::Prawn::Document
 
     if (margin_inner_val = @theme.prose_margin_inner) &&
         (next_block = (siblings = node.parent.blocks)[(siblings.index node) + 1]) && next_block.context == :paragraph
-      margin_bottom_val = margin_inner_val
+      margin_bottom margin_inner_val
     else
-      margin_bottom_val = @theme.prose_margin_bottom
+      margin_bottom @theme.prose_margin_bottom
     end
-    margin_bottom margin_bottom_val
   end
 
   def convert_admonition node
@@ -752,7 +766,7 @@ class Converter < ::Prawn::Document
           float do
             bounding_box [0, cursor], width: label_width, height: box_height do
               if icons == 'font'
-                # FIXME we're assume icon is a square
+                # FIXME we assume icon is square
                 icon_size = fit_icon_to_bounds icon_size
                 # NOTE Prawn's vertical center is not reliable, so calculate it manually
                 if label_valign == :center
@@ -776,7 +790,8 @@ class Converter < ::Prawn::Document
                         height: box_height,
                         fallback_font_name: fallback_svg_font_name,
                         enable_web_requests: allow_uri_read,
-                        enable_file_requests_with_root: (::File.dirname icon_path)
+                        enable_file_requests_with_root: (::File.dirname icon_path),
+                        cache_images: cache_uri
                     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
@@ -829,7 +844,7 @@ class Converter < ::Prawn::Document
         end
         pad_box [cpad[0], 0, cpad[2], label_width + lpad[1] + cpad[3]] do
           move_down shift_top
-          layout_caption node.title if node.title?
+          layout_caption node.title, category: :admonition if node.title?
           theme_font :admonition do
             convert_content_for_block node
           end
@@ -941,7 +956,7 @@ class Converter < ::Prawn::Document
             convert_content_for_block node
           else # verse
             content = guard_indentation node.content
-            layout_prose content, normalize: false, align: :left
+            layout_prose content, normalize: false, align: :left, hyphenate: true
           end
         end
         if node.attr? 'attribution', nil, false
@@ -1134,7 +1149,7 @@ class Converter < ::Prawn::Document
         if (term_font_styles = font_styles).empty?
           term_inline_format = true
         else
-          term_inline_format = [normalize: false, inherited: { styles: term_font_styles }]
+          term_inline_format = [inherited: { styles: term_font_styles }]
         end
         term_line_metrics = calc_line_metrics @theme.description_list_term_line_height || @theme.base_line_height
         term_padding = [term_line_metrics.padding_top, 10, (@theme.prose_margin_bottom || 0) * 0.5 + term_line_metrics.padding_bottom, 10]
@@ -1408,14 +1423,14 @@ class Converter < ::Prawn::Document
       terms, desc = node
       [*terms].each {|term| layout_prose %(<em>#{term.text}</em>), (opts.merge margin_top: 0, margin_bottom: @theme.description_list_term_spacing) }
       if desc
-        layout_prose desc.text, opts if desc.text?
+        layout_prose desc.text, (opts.merge hyphenate: true) if desc.text?
         convert_content_for_block desc
       end
     else
       if (primary_text = node.text).nil_or_empty?
         layout_prose DummyText, opts unless node.blocks?
       else
-        layout_prose primary_text, opts
+        layout_prose primary_text, (opts.merge hyphenate: true)
       end
       convert_content_for_block node
     end
@@ -1495,7 +1510,8 @@ class Converter < ::Prawn::Document
               width: width,
               fallback_font_name: fallback_svg_font_name,
               enable_web_requests: allow_uri_read,
-              enable_file_requests_with_root: file_request_root
+              enable_file_requests_with_root: file_request_root,
+              cache_images: cache_uri
           rendered_w = (svg_size = svg_obj.document.sizing).output_width
           if !width && (svg_obj.document.root.attributes.key? 'width')
             # NOTE scale native width & height from px to pt and restrict width to available width
@@ -1565,7 +1581,7 @@ class Converter < ::Prawn::Document
       layout_caption node, category: :image, side: :bottom if node.title?
       theme_margin :block, :bottom unless pinned
     rescue
-      on_image_error :exception, node, target, (opts.merge message: %(could not embed image: #{image_path}; #{$!.message}))
+      on_image_error :exception, node, target, (opts.merge message: %(could not embed image: #{image_path}; #{$!.message}#{::Prawn::Errors::UnsupportedImageType === $! ? '; install prawn-gmagick gem to add support' : ''}))
     end
   ensure
     unlink_tmp_file image_path if image_path
@@ -1631,7 +1647,7 @@ class Converter < ::Prawn::Document
     when 'vimeo'
       video_path = %(https://vimeo.com/#{video_id = node.attr 'target'})
       if allow_uri_read
-        if node.document.attr? 'cache-uri'
+        if cache_uri
           Helpers.require_library 'open-uri/cached', 'open-uri-cached' unless defined? ::OpenURI::Cache
         else
           ::OpenURI
@@ -1950,8 +1966,10 @@ class Converter < ::Prawn::Document
       head_transform = resolve_text_transform :table_head_text_transform, nil
       row_data = []
       row.each do |cell|
+        cell_text = head_transform ? (transform_text cell.text.strip, head_transform) : cell.text.strip
+        cell_text = hyphenate_text cell_text, @hyphenator if defined? @hyphenator
         row_data << {
-          content: (head_transform ? (transform_text cell.text.strip, head_transform) : cell.text.strip),
+          content: cell_text,
           inline_format: [normalize: true],
           background_color: head_bg_color,
           text_color: (theme.table_head_font_color || theme.table_font_color || @font_color),
@@ -2023,7 +2041,8 @@ class Converter < ::Prawn::Document
           end
           cell_line_metrics = calc_line_metrics theme.base_line_height
         when :literal
-          cell_data[:content] = @capabilities[:honors_literal_cell_style] ? (guard_indentation cell.text) : (guard_indentation cell.instance_variable_get :@text)
+          # NOTE we want the raw AsciiDoc in this case
+          cell_data[:content] = guard_indentation cell.instance_variable_get :@text
           # NOTE the absence of the inline_format option implies it's disabled
           # QUESTION should we use literal_font_*, code_font_*, or introduce another category?
           cell_data[:font] = theme.code_font_family
@@ -2061,6 +2080,8 @@ class Converter < ::Prawn::Document
         unless cell_data.key? :content
           cell_text = cell.text.strip
           cell_text = transform_text cell_text if cell_transform
+          cell_text = hyphenate_text cell_text, @hyphenator if defined? @hyphenator
+          cell_text = cell_text.gsub CjkLineBreakRx, ZeroWidthSpace if @cjk_line_breaks
           if cell_text.include? LF
             # NOTE effectively the same as calling cell.content (should we use that instead?)
             # FIXME hard breaks not quite the same result as separate paragraphs; need custom cell impl here
@@ -2072,8 +2093,11 @@ class Converter < ::Prawn::Document
           end
         end
         if node.document.attr? 'cellbgcolor'
-          cell_bg_color = node.document.attr 'cellbgcolor'
-          cell_data[:background_color] = cell_bg_color == 'transparent' ? body_bg_color : (cell_bg_color.slice 1, cell_bg_color.length) 
+          if (cell_bg_color = node.document.attr 'cellbgcolor') == 'transparent'
+            cell_data[:background_color] = body_bg_color
+          elsif (cell_bg_color.start_with? '#') && (HexColorRx.match? cell_bg_color)
+            cell_data[:background_color] = cell_bg_color.slice 1, cell_bg_color.length
+          end
         end
         row_data << cell_data
       end
@@ -2134,7 +2158,7 @@ class Converter < ::Prawn::Document
       table_width = bounds.width * ((node.attr 'tablepcwidth') / 100.0)
       column_widths = node.columns.map {|col| ((col.attr 'colpcwidth') * table_width) / 100.0 }
       # NOTE until Asciidoctor 1.5.4, colpcwidth values didn't always add up to 100%; use last column to compensate
-      unless column_widths.empty? || (width_delta = table_width - column_widths.reduce(:+)) == 0
+      unless column_widths.empty? || (width_delta = table_width - column_widths.sum) == 0
         column_widths[-1] += width_delta
       end
     end
@@ -2276,6 +2300,7 @@ class Converter < ::Prawn::Document
         start_new_page unless at_page_top?
         start_new_page if @ppbook && verso_page? && !(node.option? 'nonfacing')
       end
+      add_dest_for_block node, (derive_anchor_from_id node.id, 'toc')
       allocate_toc doc, (doc.attr 'toclevels', 2).to_i, @y, (is_book || (doc.attr? 'title-page'))
     end
     nil
@@ -2340,8 +2365,7 @@ class Converter < ::Prawn::Document
       end
       text = %(#{text}, #{pagenums.join ', '})
     end
-    layout_prose text, align: :left, margin: 0, normalize_line_height: true
-
+    layout_prose text, align: :left, margin: 0, normalize_line_height: true, hanging_indent: @theme.description_list_description_indent * 2
     term.subterms.each do |subterm|
       indent @theme.description_list_description_indent do
         convert_index_list_item subterm
@@ -2442,11 +2466,14 @@ class Converter < ::Prawn::Document
     if node.document.attr? 'icons', 'font'
       if (icon_name = node.target).include? '@'
         icon_name, icon_set = icon_name.split '@', 2
+        explicit_icon_set = true
+      elsif (icon_set = node.attr 'set', nil, false)
+        explicit_icon_set = true
       else
-        icon_set = node.attr 'set', (node.document.attr 'icon-set', 'fa'), false
+        icon_set = node.document.attr 'icon-set', 'fa'
       end
-      icon_set = 'fa' unless IconSets.include? icon_set
-      if icon_set == 'fa'
+      if icon_set == 'fa' || !(IconSets.include? icon_set)
+        icon_set = 'fa'
         # legacy name from Font Awesome < 5
         if (remapped_icon_name = resolve_legacy_icon_name icon_name)
           requested_icon_name = icon_name
@@ -2465,6 +2492,10 @@ class Converter < ::Prawn::Document
       else
         glyph = (icon_font_data icon_set).unicode icon_name rescue nil
       end
+      unless glyph || explicit_icon_set || !icon_name.start_with?(*IconSetPrefixes)
+        icon_set, icon_name = icon_name.split '-', 2
+        glyph = (icon_font_data icon_set).unicode icon_name rescue nil
+      end
       if glyph
         if node.attr? 'size', nil, false
           case (size = node.attr 'size')
@@ -2637,34 +2668,22 @@ class Converter < ::Prawn::Document
       if (logo_align = [(logo_image_attrs.delete 'align'), @theme.title_page_logo_align, title_align.to_s].find {|val| (BlockAlignmentNames.include? val) })
         logo_image_attrs['align'] = logo_align
       end
-      # QUESTION should we allow theme to turn logo image off?
-      logo_image_top = logo_image_attrs['top'] || @theme.title_page_logo_top || '10%'
-      # FIXME delegate to method to convert page % to y value
-      if logo_image_top.end_with? 'vh'
-        logo_image_top = page_height - page_height * logo_image_top.to_f / 100.0
-      else
-        logo_image_top = bounds.absolute_top - effective_page_height * logo_image_top.to_f / 100.0
+      if (logo_image_top = logo_image_attrs['top'] || @theme.title_page_logo_top)
+        initial_y, @y = @y, (resolve_top logo_image_top)
       end
-      initial_y, @y = @y, logo_image_top
       # FIXME add API to Asciidoctor for creating blocks like this (extract from extensions module?)
       image_block = ::Asciidoctor::Block.new doc, :image, content_model: :empty, attributes: logo_image_attrs
       # NOTE pinned option keeps image on same page
       indent (@theme.title_page_logo_margin_left || 0), (@theme.title_page_logo_margin_right || 0) do
         convert_image image_block, relative_to_imagesdir: relative_to_imagesdir, pinned: true
       end
-      @y = initial_y
+      @y = initial_y if initial_y
     end
 
     # TODO prevent content from spilling to next page
     theme_font :title_page do
       if (title_top = @theme.title_page_title_top)
-        if title_top.end_with? 'vh'
-          title_top = page_height - page_height * title_top.to_f / 100.0
-        else
-          title_top = bounds.absolute_top - effective_page_height * title_top.to_f / 100.0
-        end
-        # FIXME delegate to method to convert page % to y value
-        @y = title_top
+        @y = resolve_top title_top
       end
       unless @theme.title_page_title_display == 'none'
         doctitle = doc.doctitle partition: true
@@ -2694,9 +2713,22 @@ class Converter < ::Prawn::Document
       if @theme.title_page_authors_display != 'none' && (doc.attr? 'authors')
         move_down(@theme.title_page_authors_margin_top || 0)
         indent (@theme.title_page_authors_margin_left || 0), (@theme.title_page_authors_margin_right || 0) do
+          authors_content = @theme.title_page_authors_content
+          authors_content = {
+            name_only: @theme.title_page_authors_content_name_only || authors_content,
+            with_email: @theme.title_page_authors_content_with_email || authors_content,
+            with_url: @theme.title_page_authors_content_with_url || authors_content,
+          }
           # TODO provide an API in core to get authors as an array
           authors = (1..(doc.attr 'authorcount', 1).to_i).map {|idx|
-            doc.attr(idx == 1 ? 'author' : %(author_#{idx}))
+            promote_author doc, idx do
+              author_content_key = (url = doc.attr 'url') ? ((url.start_with? 'mailto:') ? :with_email : :with_url) : :name_only
+              if (author_content = authors_content[author_content_key])
+                apply_subs_discretely doc, author_content
+              else
+                doc.attr 'author'
+              end
+            end
           }.join (@theme.title_page_authors_delimiter || ', ')
           theme_font :title_page_authors do
             layout_prose authors,
@@ -2806,9 +2838,15 @@ class Converter < ::Prawn::Document
     end
     outdent_section(opts.delete :outdent) do
       margin_top top_margin
+      # QUESTION should we move inherited styles to typeset_text?
+      if (inherited = apply_text_decoration ::Set.new, :heading, hlevel).empty?
+        inline_format_opts = true
+      else
+        inline_format_opts = [{ inherited: inherited }]
+      end
       typeset_text string, calc_line_metrics((opts.delete :line_height) || (hlevel ? @theme[%(heading_h#{hlevel}_line_height)] : nil) || @theme.heading_line_height || @theme.base_line_height), {
         color: @font_color,
-        inline_format: true,
+        inline_format: inline_format_opts,
         align: @base_align.to_sym
       }.merge(opts)
       margin_bottom bot_margin
@@ -2822,6 +2860,7 @@ class Converter < ::Prawn::Document
     if (transform = resolve_text_transform opts)
       string = transform_text string, transform
     end
+    string = hyphenate_text string, @hyphenator if (opts.delete :hyphenate) && (defined? @hyphenator)
     # NOTE used by extensions; ensures linked text gets formatted using the link styles
     if (anchor = opts.delete :anchor)
       string = %(<a anchor="#{anchor}">#{string}</a>)
@@ -2885,7 +2924,8 @@ class Converter < ::Prawn::Document
           margin_bottom: margin[:bottom],
           align: (@theme[%(#{category_caption}_align)] || @theme.caption_align || @base_align).to_sym,
           normalize: false,
-          normalize_line_height: true
+          normalize_line_height: true,
+          hyphenate: true,
         }.merge(opts)
         if side == :top && (bb_color = @theme[%(#{category_caption}_border_bottom_color)] || @theme.caption_border_bottom_color)
           stroke_horizontal_rule bb_color
@@ -2990,31 +3030,25 @@ class Converter < ::Prawn::Document
     sections.each do |sect|
       theme_font :toc, level: (sect.level + 1) do
         sect_title = ZeroWidthSpace + (@text_transform ? (transform_text sect.numbered_title, @text_transform) : sect.numbered_title)
+        hanging_indent = @theme.toc_hanging_indent || 0
         # NOTE only write section title (excluding dots and page number) if this is a dry run
         if scratch?
           # FIXME use layout_prose
           # NOTE must wrap title in empty anchor element in case links are styled with different font family / size
-          typeset_text %(<a>#{sect_title}</a>), line_metrics, inline_format: true
+          typeset_text %(<a>#{sect_title}</a>), line_metrics, inline_format: true, hanging_indent: hanging_indent
         else
           pgnum_label = ((sect.attr 'pdf-page-start') - num_front_matter_pages).to_s
           start_page_number = page_number
           start_cursor = cursor
           start_dots = nil
-          # NOTE use low-level text formatter to add anchor overlay without styling text as link & force color
-          sect_title_format_override = {
-            anchor: (sect_anchor = sect.attr 'pdf-anchor'),
-            color: @font_color,
-            styles: ((@theme[%(toc_h#{sect.level + 1}_text_decoration)] || @theme.toc_text_decoration) == 'underline' ?
-                (font_styles << :underline) : font_styles)
-          }
-          (sect_title_fragments = text_formatter.format sect_title).each do |fragment|
-            fragment.update(sect_title_format_override) {|k, oval, nval| k == :styles ? (oval.merge nval) : oval }
-          end
+          sect_title_inherited = (apply_text_decoration ::Set.new, :toc, sect.level.next).merge anchor: (sect_anchor = sect.attr 'pdf-anchor'), color: @font_color
+          # NOTE use text formatter to add anchor overlay to avoid using inline format with synthetic anchor tag
+          sect_title_fragments = text_formatter.format sect_title, inherited: sect_title_inherited
           pgnum_label_width = rendered_width_of_string pgnum_label
           indent 0, pgnum_label_width do
             sect_title_fragments[-1][:callback] = (last_fragment_pos = ::Asciidoctor::PDF::FormattedText::FragmentPositionRenderer.new)
-            typeset_formatted_text sect_title_fragments, line_metrics
-            start_dots = last_fragment_pos.right
+            typeset_formatted_text sect_title_fragments, line_metrics, hanging_indent: hanging_indent
+            start_dots = last_fragment_pos.right + hanging_indent
             last_fragment_cursor = last_fragment_pos.top + line_metrics.padding_top
             # NOTE this will be incorrect if wrapped line is all monospace
             start_cursor = last_fragment_cursor if start_cursor - last_fragment_cursor > line_metrics.height
@@ -3456,21 +3490,24 @@ class Converter < ::Prawn::Document
       pagenum_labels[n] = { P: (::PDF::Core::LiteralString.new %(#{i + 1})) }
     end
 
+    unless toc_page_nums.none? || (toc_title = doc.attr 'toc-title').nil_or_empty?
+      toc_section = insert_toc_section doc, toc_title, toc_page_nums
+    end
+
     outline.define do
       initial_pagenum = has_front_cover ? 2 : 1
       # FIXME use sanitize: :plain_text once available
       if document.page_count >= initial_pagenum && (doctitle = doc.header? ? doc.doctitle : (doc.attr 'untitled-label'))
         page title: (document.sanitize doctitle), destination: (document.dest_top has_front_cover ? 2 : 1)
       end
-      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 is there any way to get add_outline_level to invoke in the context of the outline?
       document.add_outline_level self, doc.sections, num_levels, expand_levels
     end
 
+    toc_section.parent.blocks.delete toc_section if toc_section
+
     catalog.data[:PageLabels] = state.store.ref Nums: pagenum_labels.flatten
-    catalog.data[:PageMode] = :UseOutlines
+    catalog.data[((doc.attr 'pdf-page-mode') || @theme.page_mode) == 'fullscreen' ? :NonFullScreenPageMode : :PageMode] = :UseOutlines
     nil
   end
 
@@ -3488,6 +3525,30 @@ class Converter < ::Prawn::Document
     end
   end
 
+  def insert_toc_section doc, toc_title, toc_page_nums
+    if (doc.attr? 'toc-placement', 'macro') && (toc_node = (doc.find_by context: :toc)[0])
+      if (parent_section = toc_node.parent).context == :section
+        grandparent_section = parent_section.parent
+        toc_level = parent_section.level
+        insert_idx = (grandparent_section.blocks.index parent_section) + 1
+      else
+        parent_section = grandparent_section = doc
+        toc_level = doc.sections[0].level
+        insert_idx = 0
+      end
+      toc_dest = toc_node.attr 'pdf-destination'
+    else
+      parent_section = grandparent_section = doc
+      toc_level = doc.sections[0].level
+      insert_idx = 0
+      toc_dest = dest_top toc_page_nums.first
+    end
+    toc_section = Section.new grandparent_section, toc_level, false, { attributes: { 'pdf-destination' => toc_dest } }
+    toc_section.title = toc_title
+    grandparent_section.blocks.insert insert_idx, toc_section
+    toc_section
+  end
+
   def write pdf_doc, target
     if target.respond_to? :write
       require_relative 'ext/core/quantifiable_stdout' unless defined? ::QuantifiableStdout
@@ -3537,6 +3598,19 @@ class Converter < ::Prawn::Document
   end
 
   attr_reader :allow_uri_read
+  attr_reader :cache_uri
+
+  def apply_text_decoration styles, category, level = nil
+    if (text_decoration_style = TextDecorationStyleTable[(level && @theme[%(#{category}_h#{level}_text_decoration)]) || @theme[%(#{category}_text_decoration)]])
+      {
+        styles: (styles << text_decoration_style),
+        text_decoration_color: (level && @theme[%(#{category}_h#{level}_text_decoration_color)]) || @theme[%(#{category}_text_decoration_color)],
+        text_decoration_width: (level && @theme[%(#{category}_h#{level}_text_decoration_width)]) || @theme[%(#{category}_text_decoration_width)],
+      }.compact
+    else
+      styles.empty? ? {} : { styles: styles }
+    end
+  end
 
   def resolve_text_transform key, use_fallback = true
     if (transform = ::Hash === key ? (key.delete :text_transform) : @theme[key.to_s])
@@ -3708,7 +3782,7 @@ class Converter < ::Prawn::Document
       width_of_string str, opts
     else
       char_widths = chars.map {|char| rendered_width_of_char char, opts }
-      char_widths.reduce(&:+) + (char_widths.length * character_spacing)
+      char_widths.sum + (char_widths.length * character_spacing)
     end
   end
 
@@ -3731,7 +3805,11 @@ class Converter < ::Prawn::Document
     move_down line_metrics.padding_top
     opts = { leading: line_metrics.leading, final_gap: line_metrics.final_gap }.merge opts
     string = string.gsub CjkLineBreakRx, ZeroWidthSpace if @cjk_line_breaks
-    if (first_line_opts = opts.delete :first_line_options)
+    if (hanging_indent = (opts.delete :hanging_indent) || 0) > 0
+      indent hanging_indent do
+        text string, (opts.merge indent_paragraphs: -hanging_indent)
+      end
+    elsif (first_line_opts = opts.delete :first_line_options)
       # TODO good candidate for Prawn enhancement!
       text_with_formatted_first_line string, first_line_opts, opts
     else
@@ -3743,7 +3821,14 @@ class Converter < ::Prawn::Document
   # QUESTION combine with typeset_text?
   def typeset_formatted_text fragments, line_metrics, opts = {}
     move_down line_metrics.padding_top
-    formatted_text fragments, { leading: line_metrics.leading, final_gap: line_metrics.final_gap }.merge(opts)
+    opts = { leading: line_metrics.leading, final_gap: line_metrics.final_gap }.merge opts
+    if (hanging_indent = (opts.delete :hanging_indent) || 0) > 0
+      indent hanging_indent do
+        formatted_text fragments, (opts.merge indent_paragraphs: -hanging_indent)
+      end
+    else
+      formatted_text fragments, opts
+    end
     move_down line_metrics.padding_bottom
   end
 
@@ -3915,7 +4000,7 @@ class Converter < ::Prawn::Document
         logger.warn %(allow-uri-read is not enabled; cannot embed remote image: #{image_path}) unless scratch?
         return
       end
-      if doc.attr? 'cache-uri'
+      if cache_uri
         Helpers.require_library 'open-uri/cached', 'open-uri-cached' unless defined? ::OpenURI::Cache
       else
         ::OpenURI
@@ -3926,6 +4011,7 @@ class Converter < ::Prawn::Document
         open(image_path, (binary ? 'rb' : 'r')) {|fd| tmp_image.write fd.read }
         tmp_image.path.extend TemporaryPath
       rescue
+        logger.warn %(could not retrieve remote image: #{image_path}; #{$!.message}) unless scratch?
         nil
       ensure
         tmp_image.close
@@ -3976,6 +4062,7 @@ class Converter < ::Prawn::Document
       image_opts = {
         enable_file_requests_with_root: (::File.dirname image_path),
         enable_web_requests: allow_uri_read,
+        cache_images: cache_uri,
         fallback_font_name: fallback_svg_font_name,
         format: 'svg',
       }
@@ -4122,6 +4209,16 @@ class Converter < ::Prawn::Document
     end
   end
 
+  def resolve_top val
+    if val.end_with? 'vh'
+      page_height * (1 - (val.to_f / 100))
+    elsif val.end_with? '%'
+      @y - effective_page_height * (val.to_f / 100)
+    else
+      @y - (str_to_pt val)
+    end
+  end
+
   def add_link_to_image uri, image_info, image_opts
     image_width = image_info[:width]
     image_height = image_info[:height]
@@ -4173,8 +4270,7 @@ class Converter < ::Prawn::Document
     if imagesdir
       doc.set_attr 'imagesdir', imagesdir
     else
-      # NOTE remove_attr not defined until Asciidoctor 1.5.6
-      doc.attributes.delete 'imagesdir'
+      doc.remove_attr 'imagesdir'
     end
     value
   end
@@ -4186,6 +4282,44 @@ class Converter < ::Prawn::Document
     value
   end
 
+  def promote_author doc, idx = 1
+    doc.remove_attr 'url' if (original_url = doc.attr 'url')
+    email = nil
+    if idx > 1
+      original_attrs = AuthorAttributeNames.reduce({}) do |accum, name|
+        accum[name] = doc.attr name
+        if (val = doc.attr %(#{name}_#{idx}))
+          doc.set_attr name, val
+          # NOTE email holds url as well
+          email = val if name == 'email'
+        else
+          doc.remove_attr name
+        end
+        accum
+      end
+      doc.set_attr 'url', ((email.include? '@') ? %(mailto:#{email}) : email) if email
+      result = yield
+      original_attrs.each do |name, val|
+        if val
+          doc.set_attr name, val
+        else
+          doc.remove_attr name
+        end
+      end
+    else
+      if (email = doc.attr 'email')
+        doc.set_attr 'url', ((email.include? '@') ? %(mailto:#{email}) : email)
+      end
+      result = yield
+    end
+    if original_url
+      doc.set_attr 'url', original_url
+    elsif email
+      doc.remove_attr 'url'
+    end
+    result
+  end
+
   # NOTE assume URL is escaped (i.e., contains character references such as &amp;)
   def breakable_uri uri
     scheme, address = uri.split UriSchemeBoundaryRx, 2