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

data/lib/asciidoctor/pdf/converter.rb

@@ -185,7 +185,7 @@ class Converter < ::Prawn::Document
       blk_0 = blk_1 = preface = nil
     end
 
-    on_page_create &(method :init_page)
+    on_page_create(&(method :init_page))
 
     marked_page_number = page_number
     # NOTE a new page will already be started (page_number = 2) if the front cover image is a PDF
@@ -207,58 +207,62 @@ class Converter < ::Prawn::Document
       end if doc.header? && !doc.notitle
     end
 
-    toc_num_levels = (doc.attr 'toclevels', 2).to_i
-    if (insert_toc = (doc.attr? 'toc') && !(doc.attr? 'toc-placement', 'macro') && doc.sections?)
-      start_new_page if @ppbook && verso_page?
-      allocate_toc doc, toc_num_levels, @y, use_title_page
-    else
-      @toc_extent = nil
-    end
+    num_front_matter_pages = toc_page_nums = toc_num_levels = nil
 
-    start_new_page if @ppbook && verso_page?
+    indent_section do
+      toc_num_levels = (doc.attr 'toclevels', 2).to_i
+      if (insert_toc = (doc.attr? 'toc') && !(doc.attr? 'toc-placement', 'macro') && doc.sections?)
+        start_new_page if @ppbook && verso_page?
+        allocate_toc doc, toc_num_levels, @y, use_title_page
+      else
+        @toc_extent = nil
+      end
 
-    if use_title_page
-      zero_page_offset = has_front_cover ? 1 : 0
-      first_page_offset = has_title_page ? zero_page_offset.next : zero_page_offset
-      body_offset = (body_start_page_number = page_number) - 1
-      running_content_start_at = @theme.running_content_start_at || 'body'
-      running_content_start_at = 'toc' if running_content_start_at == 'title' && !has_title_page
-      running_content_start_at = 'body' if running_content_start_at == 'toc' && !insert_toc
-      page_numbering_start_at = @theme.page_numbering_start_at || 'body'
-      page_numbering_start_at = 'toc' if page_numbering_start_at == 'title' && !has_title_page
-      page_numbering_start_at = 'body' if page_numbering_start_at == 'toc' && !insert_toc
-      front_matter_sig = [running_content_start_at, page_numbering_start_at]
-      # table values are number of pages to skip before starting running content and page numbering, respectively
-      num_front_matter_pages = {
-        ['title', 'title'] => [zero_page_offset, zero_page_offset],
-        ['title', 'toc'] => [zero_page_offset, first_page_offset],
-        ['title', 'body'] => [zero_page_offset, body_offset],
-        ['toc', 'title'] => [first_page_offset, zero_page_offset],
-        ['toc', 'toc'] => [first_page_offset, first_page_offset],
-        ['toc', 'body'] => [first_page_offset, body_offset],
-        ['body', 'title'] => [body_offset, zero_page_offset],
-        ['body', 'toc'] => [body_offset, first_page_offset],
-      }[front_matter_sig] || [body_offset, body_offset]
-    else
-      num_front_matter_pages = [body_start_page_number - 1] * 2
-    end
+      start_new_page if @ppbook && verso_page?
 
-    @index.start_page_number = num_front_matter_pages[1] + 1
-    doc.set_attr 'pdf-anchor', (doc_anchor = derive_anchor_from_id doc.id, 'top')
-    add_dest_for_block doc, doc_anchor
+      if use_title_page
+        zero_page_offset = has_front_cover ? 1 : 0
+        first_page_offset = has_title_page ? zero_page_offset.next : zero_page_offset
+        body_offset = (body_start_page_number = page_number) - 1
+        running_content_start_at = @theme.running_content_start_at || 'body'
+        running_content_start_at = 'toc' if running_content_start_at == 'title' && !has_title_page
+        running_content_start_at = 'body' if running_content_start_at == 'toc' && !insert_toc
+        page_numbering_start_at = @theme.page_numbering_start_at || 'body'
+        page_numbering_start_at = 'toc' if page_numbering_start_at == 'title' && !has_title_page
+        page_numbering_start_at = 'body' if page_numbering_start_at == 'toc' && !insert_toc
+        front_matter_sig = [running_content_start_at, page_numbering_start_at]
+        # table values are number of pages to skip before starting running content and page numbering, respectively
+        num_front_matter_pages = {
+          ['title', 'title'] => [zero_page_offset, zero_page_offset],
+          ['title', 'toc'] => [zero_page_offset, first_page_offset],
+          ['title', 'body'] => [zero_page_offset, body_offset],
+          ['toc', 'title'] => [first_page_offset, zero_page_offset],
+          ['toc', 'toc'] => [first_page_offset, first_page_offset],
+          ['toc', 'body'] => [first_page_offset, body_offset],
+          ['body', 'title'] => [body_offset, zero_page_offset],
+          ['body', 'toc'] => [body_offset, first_page_offset],
+        }[front_matter_sig] || [body_offset, body_offset]
+      else
+        num_front_matter_pages = [body_start_page_number - 1] * 2
+      end
 
-    convert_section generate_manname_section doc if doc.doctype == 'manpage' && (doc.attr? 'manpurpose')
+      @index.start_page_number = num_front_matter_pages[1] + 1
+      doc.set_attr 'pdf-anchor', (doc_anchor = derive_anchor_from_id doc.id, 'top')
+      add_dest_for_block doc, doc_anchor
 
-    convert_content_for_block doc
+      convert_section generate_manname_section doc if doc.doctype == 'manpage' && (doc.attr? 'manpurpose')
 
-    # NOTE for a book, these are leftover footnotes; for an article this is everything
-    layout_footnotes doc
+      convert_content_for_block 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.empty? && page_count > 1
+      # NOTE for a book, these are leftover footnotes; for an article this is everything
+      outdent_section { layout_footnotes doc }
 
-    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]) : []
+      # 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
+
+      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
 
     unless page_count < body_start_page_number
       unless doc.noheader || @theme.header_height.to_f.zero?
@@ -343,6 +347,7 @@ class Converter < ::Prawn::Document
       from, to = r.rstrip.split '-', 2
       to ? ((get_char from)..(get_char to)).to_a : [(get_char from)]
     }.flatten
+    @section_indent = (val = @theme.section_indent) && (inflate_indent val)
     @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
@@ -458,7 +463,9 @@ class Converter < ::Prawn::Document
   def build_pdf_info doc
     info = {}
     # FIXME use sanitize: :plain_text once available
-    info[:Title] = sanitize(doc.doctitle use_fallback: true).as_pdf
+    if (doctitle = doc.header? ? doc.doctitle : (doc.attr 'untitled-label'))
+      info[:Title] = (sanitize doctitle).as_pdf
+    end
     info[:Author] = (doc.attr 'authors').as_pdf if doc.attr? 'authors'
     info[:Subject] = (doc.attr 'subject').as_pdf if doc.attr? 'subject'
     info[:Keywords] = (doc.attr 'keywords').as_pdf if doc.attr? 'keywords'
@@ -536,22 +543,35 @@ class Converter < ::Prawn::Document
       elsif type == :chapter
         layout_chapter_title sect, title, align: align, level: hlevel
       else
-        layout_heading title, align: align, level: hlevel
+        layout_heading title, align: align, level: hlevel, outdent: true
       end
     end
 
-    if (section_indent = @theme.section_indent)
-      indent_l, indent_r = inflate_indent section_indent
-      indent indent_l, indent_r do
-        sect.sectname == 'index' ? (convert_index_section sect) : (convert_content_for_block sect)
-      end
+    if sect.sectname == 'index'
+      outdent_section { convert_index_section sect }
     else
-      sect.sectname == 'index' ? (convert_index_section sect) : (convert_content_for_block sect)
+      convert_content_for_block sect
     end
-    layout_footnotes sect if type == :chapter
+    outdent_section { layout_footnotes sect } if type == :chapter
     sect.set_attr 'pdf-page-end', page_number
   end
 
+  def indent_section
+    if (values = @section_indent)
+      indent(values[0], values[1]) { yield }
+    else
+      yield
+    end
+  end
+
+  def outdent_section enabled = true
+    if enabled && (values = @section_indent)
+      indent(-values[0], -values[1]) { yield }
+    else
+      yield
+    end
+  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?
@@ -571,59 +591,60 @@ class Converter < ::Prawn::Document
     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, level: hlevel
+      layout_heading node.title, align: (@theme[%(heading_h#{hlevel}_align)] || @theme.heading_align || @base_align).to_sym, level: hlevel, outdent: (node.parent.context == :section)
     end
   end
 
   def convert_abstract node
     add_dest_for_block node if node.id
-    pad_box @theme.abstract_padding do
-      theme_font :abstract_title do
-        layout_heading node.title, align: (@theme.abstract_title_align || @base_align).to_sym, margin_top: (@theme.heading_margin_top || 0), margin_bottom: (@theme.heading_margin_bottom || 0)
-      end if node.title?
-      theme_font :abstract do
-        prose_opts = { line_height: @theme.abstract_line_height, align: (initial_alignment = (@theme.abstract_align || @base_align).to_sym) }
-        if (text_indent = @theme.prose_text_indent)
-          prose_opts[:indent_paragraphs] = text_indent
-        end
-        # 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] }
-        end
-        # FIXME make this cleaner!!
-        if node.blocks?
-          node.blocks.each do |child|
-            # 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
+    outdent_section do
+      pad_box @theme.abstract_padding do
+        theme_font :abstract_title do
+          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[:indent_paragraphs] = text_indent
+          end
+          # 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] }
+          end
+          # FIXME make this cleaner!!
+          if node.blocks?
+            node.blocks.each do |child|
+              # FIXME is playback necessary here?
+              child.document.playback_attributes child.attributes
+              if child.context == :paragraph
+                if (alignment = resolve_alignment_from_role child.roles)
+                  prose_opts[:align] = alignment
+                end
+                layout_prose child.content, prose_opts
+                prose_opts.delete :first_line_options
+                prose_opts[:align] = initial_alignment
+              else
+                # FIXME this could do strange things if the wrong kind of content shows up
+                convert_content_for_block child
               end
-              layout_prose child.content, prose_opts
-              prose_opts.delete :first_line_options
-              prose_opts[:align] = initial_alignment
-            else
-              # FIXME this could do strange things if the wrong kind of content shows up
-              convert_content_for_block child
             end
+          elsif node.content_model != :compound && (string = node.content)
+            if (alignment = resolve_alignment_from_role node.roles)
+              prose_opts[:align] = alignment
+            end
+            layout_prose string, prose_opts
           end
-        elsif node.content_model != :compound && (string = node.content)
-          if (alignment = resolve_alignment_from_role node.roles)
-            prose_opts[:align] = alignment
-          end
-          layout_prose string, prose_opts
         end
       end
+      # QUESTION should we be adding margin below the abstract??
+      #theme_margin :block, :bottom
     end
-    # QUESTION should we be adding margin below the abstract??
-    #theme_margin :block, :bottom
   end
 
   def convert_preamble node
-    # TODO find_by needs to support a depth argument
     # FIXME core should not be promoting paragraph to preamble if there are no sections
-    if (first_p = (node.find_by context: :paragraph)[0]) && first_p.parent == node && node.document.sections?
-      first_p.add_role 'lead'
+    if node.blocks? && (first_block = node.blocks[0]).context == :paragraph && node.document.sections?
+      first_block.add_role 'lead' unless first_block.role?
     end
     convert_content_for_block node
   end
@@ -1024,7 +1045,7 @@ class Converter < ::Prawn::Document
       pad_box @theme.sidebar_padding do
         theme_font :sidebar_title do
           # QUESTION should we allow margins of sidebar title to be customized?
-          layout_heading node.title, align: (@theme.sidebar_title_align || @base_align).to_sym, margin_top: 0, margin_bottom: (@theme.heading_margin_bottom || 0)
+          layout_prose node.title, align: (@theme.sidebar_title_align || @base_align).to_sym, margin_top: 0, margin_bottom: (@theme.heading_margin_bottom || 0), line_height: @theme.heading_line_height
         end if node.title?
         theme_font :sidebar do
           convert_content_for_block node
@@ -1418,7 +1439,13 @@ class Converter < ::Prawn::Document
         if ::File.readable? image_path
           # NOTE import_page automatically advances to next page afterwards
           # QUESTION should we add destination to top of imported page?
-          import_page image_path, page: [(node.attr 'page').to_i, 1].max, replace: page.empty?
+          if (pgnums = node.attr 'pages', nil, false)
+            (resolve_pagenums pgnums).each_with_index do |pgnum, idx|
+              import_page image_path, page: pgnum, replace: (idx == 0 ? page.empty? : true)
+            end
+          else
+            import_page image_path, page: [(node.attr 'page', nil, 1).to_i, 1].max, replace: page.empty?
+          end
         else
           # QUESTION should we use alt text in this case?
           logger.warn %(pdf to insert not found or not readable: #{image_path})
@@ -1545,7 +1572,7 @@ class Converter < ::Prawn::Document
   end
 
   def draw_image_border top, w, h, alignment
-    if (b_width = @theme.image_border_width || 0) > 0 && @theme.image_border_color
+    if (@theme.image_border_width || 0) > 0 && @theme.image_border_color
       if (@theme.image_border_fit || 'content') == 'auto'
         bb_width = bounds.width
       elsif alignment == :center
@@ -1953,7 +1980,7 @@ class Converter < ::Prawn::Document
           rowspan: cell.rowspan || 1,
           align: (cell.attr 'halign', nil, false).to_sym,
           valign: (val = cell.attr 'valign', nil, false) == 'middle' ? :center : val.to_sym,
-          padding: theme.table_cell_padding
+          padding: theme.table_cell_padding,
         }
         cell_transform = nil
         case cell.style
@@ -2490,7 +2517,7 @@ class Converter < ::Prawn::Document
 
   def convert_inline_indexterm node
     # NOTE indexterms not supported if text gets substituted before PDF is initialized
-    return '' unless instance_variable_defined? :@index
+    return '' unless defined? @index
     if scratch?
       node.type == :visible ? node.text : ''
     else
@@ -2596,7 +2623,7 @@ class Converter < ::Prawn::Document
     title_align = (@theme.title_page_align || @base_align).to_sym
 
     # TODO disallow .pdf as image type
-    if (logo_image_path = (doc.attr 'title-logo-image') || (logo_image_from_theme = @theme.title_page_logo_image))
+    if @theme.title_page_logo_display != 'none' && (logo_image_path = (doc.attr 'title-logo-image') || (logo_image_from_theme = @theme.title_page_logo_image))
       if (logo_image_path.include? ':') && logo_image_path =~ ImageAttributeValueRx
         logo_image_attrs = (AttributeList.new $2).parse ['alt', 'width', 'height']
         relative_to_imagesdir = true
@@ -2607,7 +2634,9 @@ class Converter < ::Prawn::Document
         logo_image_path = ThemeLoader.resolve_theme_asset (sub_attributes_discretely doc, logo_image_path), @themesdir if logo_image_from_theme
       end
       logo_image_attrs['target'] = logo_image_path
-      logo_image_attrs['align'] ||= (@theme.title_page_logo_align || title_align.to_s)
+      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
@@ -2628,7 +2657,6 @@ class Converter < ::Prawn::Document
 
     # TODO prevent content from spilling to next page
     theme_font :title_page do
-      doctitle = doc.doctitle partition: true
       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
@@ -2638,21 +2666,24 @@ class Converter < ::Prawn::Document
         # FIXME delegate to method to convert page % to y value
         @y = title_top
       end
-      move_down(@theme.title_page_title_margin_top || 0)
-      indent (@theme.title_page_title_margin_left || 0), (@theme.title_page_title_margin_right || 0) do
-        theme_font :title_page_title do
-          layout_heading doctitle.main,
-            align: title_align,
-            margin: 0,
-            line_height: @theme.title_page_title_line_height
+      unless @theme.title_page_title_display == 'none'
+        doctitle = doc.doctitle partition: true
+        move_down(@theme.title_page_title_margin_top || 0)
+        indent (@theme.title_page_title_margin_left || 0), (@theme.title_page_title_margin_right || 0) do
+          theme_font :title_page_title do
+            layout_prose doctitle.main,
+              align: title_align,
+              margin: 0,
+              line_height: @theme.title_page_title_line_height
+          end
         end
+        move_down(@theme.title_page_title_margin_bottom || 0)
       end
-      move_down(@theme.title_page_title_margin_bottom || 0)
-      if doctitle.subtitle
+      if @theme.title_page_subtitle_display != 'none' && (subtitle = (doctitle || (doc.doctitle partition: true)).subtitle)
         move_down(@theme.title_page_subtitle_margin_top || 0)
         indent (@theme.title_page_subtitle_margin_left || 0), (@theme.title_page_subtitle_margin_right || 0) do
           theme_font :title_page_subtitle do
-            layout_heading doctitle.subtitle,
+            layout_prose subtitle,
               align: title_align,
               margin: 0,
               line_height: @theme.title_page_subtitle_line_height
@@ -2660,7 +2691,7 @@ class Converter < ::Prawn::Document
         end
         move_down(@theme.title_page_subtitle_margin_bottom || 0)
       end
-      if doc.attr? 'authors'
+      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
           # TODO provide an API in core to get authors as an array
@@ -2676,8 +2707,7 @@ class Converter < ::Prawn::Document
         end
         move_down(@theme.title_page_authors_margin_bottom || 0)
       end
-      revision_info = [(doc.attr? 'revnumber') ? %(#{doc.attr 'version-label'} #{doc.attr 'revnumber'}) : nil, (doc.attr 'revdate')].compact
-      unless revision_info.empty?
+      unless @theme.title_page_revision_display == 'none' || (revision_info = [(doc.attr? 'revnumber') ? %(#{doc.attr 'version-label'} #{doc.attr 'revnumber'}) : nil, (doc.attr 'revdate')].compact).empty?
         move_down(@theme.title_page_revision_margin_top || 0)
         revision_text = revision_info.join (@theme.title_page_revision_delimiter || ', ')
         if (revremark = doc.attr 'revremark')
@@ -2694,6 +2724,8 @@ class Converter < ::Prawn::Document
         move_down(@theme.title_page_revision_margin_bottom || 0)
       end
     end
+
+    layout_prose DummyText, margin: 0, line_height: 1, normalize: false if page.empty?
   end
 
   def layout_cover_page doc, face
@@ -2748,7 +2780,7 @@ class Converter < ::Prawn::Document
   end
 
   def layout_chapter_title node, title, opts = {}
-    layout_heading title, opts
+    layout_heading title, (opts.merge outdent: true)
   end
 
   alias start_new_part start_new_chapter
@@ -2772,13 +2804,15 @@ class Converter < ::Prawn::Document
     if (transform = resolve_text_transform opts)
       string = transform_text string, transform
     end
-    margin_top top_margin
-    typeset_text string, calc_line_metrics((opts.delete :line_height) || (hlevel ? @theme[%(heading_h#{hlevel}_line_height)] : nil) || @theme.heading_line_height || @theme.base_line_height), {
-      color: @font_color,
-      inline_format: true,
-      align: @base_align.to_sym
-    }.merge(opts)
-    margin_bottom bot_margin
+    outdent_section(opts.delete :outdent) do
+      margin_top top_margin
+      typeset_text string, calc_line_metrics((opts.delete :line_height) || (hlevel ? @theme[%(heading_h#{hlevel}_line_height)] : nil) || @theme.heading_line_height || @theme.base_line_height), {
+        color: @font_color,
+        inline_format: true,
+        align: @base_align.to_sym
+      }.merge(opts)
+      margin_bottom bot_margin
+    end
   end
 
   # NOTE inline_format is true by default
@@ -2915,7 +2949,7 @@ class Converter < ::Prawn::Document
       theme_font :heading, level: 2 do
         theme_font :toc_title do
           toc_title_align = (@theme.toc_title_align || @theme.heading_h2_align || @theme.heading_align || @base_align).to_sym
-          layout_heading toc_title, align: toc_title_align, level: 2
+          layout_heading toc_title, align: toc_title_align, level: 2, outdent: true
         end
       end
     end
@@ -3040,12 +3074,12 @@ class Converter < ::Prawn::Document
 
   # TODO delegate to layout_page_header and layout_page_footer per page
   def layout_running_content periphery, doc, opts = {}
-    skip, skip_pagenums, body_start_page_number = opts[:skip] || [1, 1]
+    skip, skip_pagenums = opts[:skip] || [1, 1]
     body_start_page_number = opts[:body_start_page_number] || 1
     # NOTE find and advance to first non-imported content page to use as model page
     return unless (content_start_page = state.pages[skip..-1].index {|it| !it.imported_page? })
     content_start_page += (skip + 1)
-    num_pages = page_count - skip
+    num_pages = page_count
     prev_page_number = page_number
     go_to_page content_start_page
 
@@ -3054,34 +3088,37 @@ class Converter < ::Prawn::Document
     header = doc.header? ? doc.header : nil
     sectlevels = (@theme[%(#{periphery}_sectlevels)] || 2).to_i
     sections = doc.find_by(context: :section) {|sect| sect.level <= sectlevels && sect != header } || []
+    if (toc_page_nums = @toc_extent && @toc_extent[:page_nums])
+      toc_title = (doc.attr 'toc-title') || ''
+    end
 
     title_method = TitleStyles[@theme[%(#{periphery}_title_style)]]
     # FIXME we need a proper model for all this page counting
     # FIXME we make a big assumption that part & chapter start on new pages
-    # index parts, chapters and sections by the visual page number on which they start
+    # index parts, chapters and sections by the physical page number on which they start
     part_start_pages = {}
     chapter_start_pages = {}
     section_start_pages = {}
     trailing_section_start_pages = {}
     sections.each do |sect|
-      page_num = (sect.attr 'pdf-page-start').to_i - skip_pagenums
+      pgnum = (sect.attr 'pdf-page-start').to_i
       if is_book && ((sect_is_part = sect.part?) || sect.chapter?)
         if sect_is_part
-          part_start_pages[page_num] ||= sect.send(*title_method)
+          part_start_pages[pgnum] ||= sect.send(*title_method)
         else
-          chapter_start_pages[page_num] ||= sect.send(*title_method)
+          chapter_start_pages[pgnum] ||= sect.send(*title_method)
           if sect.sectname == 'appendix' && !part_start_pages.empty?
             # FIXME need a better way to indicate that part has ended
-            part_start_pages[page_num] = ''
+            part_start_pages[pgnum] = ''
           end
         end
       else
-        sect_title = trailing_section_start_pages[page_num] = sect.send(*title_method)
-        section_start_pages[page_num] ||= sect_title
+        sect_title = trailing_section_start_pages[pgnum] = sect.send(*title_method)
+        section_start_pages[pgnum] ||= sect_title
       end
     end
 
-    # index parts, chapters, and sections by the visual page number on which they appear
+    # index parts, chapters, and sections by the physical page number on which they appear
     parts_by_page = {}
     chapters_by_page = {}
     sections_by_page = {}
@@ -3091,42 +3128,42 @@ class Converter < ::Prawn::Document
     last_chap = is_book ? :pre : nil
     last_sect = nil
     sect_search_threshold = 1
-    (1..num_pages).each do |num|
-      if (part = part_start_pages[num])
+    (1..num_pages).each do |pgnum|
+      if (part = part_start_pages[pgnum])
         last_part = part
         last_chap = nil
         last_sect = nil
       end
-      if (chap = chapter_start_pages[num])
+      if (chap = chapter_start_pages[pgnum])
         last_chap = chap
         last_sect = nil
       end
-      if (sect = section_start_pages[num])
+      if (sect = section_start_pages[pgnum])
         last_sect = sect
       elsif part || chap
-        sect_search_threshold = num
+        sect_search_threshold = pgnum
       # 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|
+        ((sect_search_threshold)..(pgnum - 1)).reverse_each do |prev|
           if (sect = trailing_section_start_pages[prev])
             last_sect = sect
             break
           end
         end
       end
-      parts_by_page[num] = last_part
+      parts_by_page[pgnum] = last_part
       if last_chap == :pre
-        if num == 1
-          chapters_by_page[num] = doc.doctitle
-        elsif num >= body_start_page_number
-          chapters_by_page[num] = is_book ? (doc.attr 'preface-title', 'Preface') : nil
+        if pgnum >= body_start_page_number
+          chapters_by_page[pgnum] = is_book ? (doc.attr 'preface-title', 'Preface') : nil
+        elsif toc_page_nums && (toc_page_nums.cover? pgnum)
+          chapters_by_page[pgnum] = toc_title
         else
-          chapters_by_page[num] = doc.attr 'toc-title'
+          chapters_by_page[pgnum] = doc.doctitle
         end
       else
-        chapters_by_page[num] = last_chap
+        chapters_by_page[pgnum] = last_chap
       end
-      sections_by_page[num] = last_sect
+      sections_by_page[pgnum] = last_sect
     end
 
     doctitle = doc.doctitle partition: true, use_fallback: true
@@ -3134,7 +3171,7 @@ class Converter < ::Prawn::Document
     doc.set_attr 'doctitle', doctitle.combined
     doc.set_attr 'document-title', doctitle.main
     doc.set_attr 'document-subtitle', doctitle.subtitle
-    doc.set_attr 'page-count', num_pages
+    doc.set_attr 'page-count', (num_pages - skip_pagenums)
 
     pagenums_enabled = doc.attr? 'pagenums'
     case @media == 'prepress' ? 'physical' : (doc.attr 'pdf-folio-placement')
@@ -3148,24 +3185,36 @@ class Converter < ::Prawn::Document
       folio_basis, invert_folio = :virtual, false
     end
     periphery_layout_cache = {}
-    repeat((content_start_page..page_count), dynamic: true) do
+    repeat((content_start_page..num_pages), dynamic: true) do
       # NOTE don't write on pages which are imported / inserts (otherwise we can get a corrupt PDF)
       next if page.imported_page?
-      pgnum_label = page_number - skip_pagenums
-      pgnum_label = (RomanNumeral.new page_number, :lower) if pgnum_label < 1
-      side = page_side((folio_basis == :physical ? page_number : pgnum_label), invert_folio)
+      virtual_pgnum = (pgnum = page_number) - skip_pagenums
+      pgnum_label = (virtual_pgnum < 1 ? (RomanNumeral.new pgnum, :lower) : virtual_pgnum).to_s
+      side = page_side((folio_basis == :physical ? pgnum : virtual_pgnum), invert_folio)
       # QUESTION should allocation be per side?
       trim_styles, colspec_dict, content_dict, stamp_names = allocate_running_content_layout page, periphery, periphery_layout_cache
       # FIXME we need to have a content setting for chapter pages
       content_by_position, colspec_by_position = content_dict[side], colspec_dict[side]
       # TODO populate chapter-number
       # TODO populate numbered and unnumbered chapter and section titles
-      doc.set_attr 'page-number', pgnum_label.to_s if pagenums_enabled
+      doc.set_attr 'page-number', pgnum_label if pagenums_enabled
       # QUESTION should the fallback value be nil instead of empty string? or should we remove attribute if no value?
-      doc.set_attr 'part-title', (parts_by_page[pgnum_label] || '')
-      doc.set_attr 'chapter-title', (chapters_by_page[pgnum_label] || '')
-      doc.set_attr 'section-title', (sections_by_page[pgnum_label] || '')
-      doc.set_attr 'section-or-chapter-title', (sections_by_page[pgnum_label] || chapters_by_page[pgnum_label] || '')
+      doc.set_attr 'part-title', (parts_by_page[pgnum] || '')
+      if toc_page_nums && (toc_page_nums.cover? pgnum)
+        if is_book
+          doc.set_attr 'chapter-title', (sect_or_chap_title = toc_title)
+          doc.set_attr 'section-title', ''
+        else
+          doc.set_attr 'chapter-title', ''
+          doc.set_attr 'section-title', (sect_or_chap_title = section_start_pages[pgnum] ? sections_by_page[pgnum] : toc_title)
+        end
+        doc.set_attr 'section-or-chapter-title', sect_or_chap_title
+        toc_page_nums = nil if toc_page_nums.end == pgnum
+      else
+        doc.set_attr 'chapter-title', (chapters_by_page[pgnum] || '')
+        doc.set_attr 'section-title', (sections_by_page[pgnum] || '')
+        doc.set_attr 'section-or-chapter-title', (sections_by_page[pgnum] || chapters_by_page[pgnum] || '')
+      end
 
       stamp stamp_names[side] if stamp_names
 
@@ -3214,7 +3263,7 @@ class Converter < ::Prawn::Document
                 theme_font %(#{periphery}_#{side}_#{position}) do
                   # NOTE minor optimization
                   if content == '{page-number}'
-                    content = pagenums_enabled ? pgnum_label.to_s : nil
+                    content = pagenums_enabled ? pgnum_label : nil
                   else
                     content = apply_subs_discretely doc, content, drop_lines_with_unresolved_attributes: true
                     content = transform_text content, @text_transform if @text_transform
@@ -3245,8 +3294,7 @@ class Converter < ::Prawn::Document
   end
 
   def allocate_running_content_layout page, periphery, cache
-    layout = page.layout
-    cache[layout] ||= begin
+    cache[layout = page.layout] ||= begin
       trim_styles = {
         line_metrics: (trim_line_metrics = calc_line_metrics @theme[%(#{periphery}_line_height)] || @theme.base_line_height),
         # NOTE we've already verified this property is set
@@ -3260,7 +3308,7 @@ class Converter < ::Prawn::Document
         column_rule_color: (trim_column_rule_color = resolve_theme_color %(#{periphery}_column_rule_color).to_sym),
         column_rule_style: (@theme[%(#{periphery}_column_rule_style)] || :solid).to_sym,
         column_rule_width: (trim_column_rule_color ? @theme[%(#{periphery}_column_rule_width)] || 0 : 0),
-        column_rule_spacing: (trim_column_rule_spacing = @theme[%(#{periphery}_column_rule_spacing)] || 0),
+        column_rule_spacing: (@theme[%(#{periphery}_column_rule_spacing)] || 0),
         valign: (val = (@theme[%(#{periphery}_vertical_align)] || :middle).to_sym) == :middle ? :center : val,
         img_valign: @theme[%(#{periphery}_image_vertical_align)],
         left: {
@@ -3349,10 +3397,6 @@ class Converter < ::Prawn::Document
             end
           end
         end
-        # NOTE set fallbacks if not explicitly disabled
-        if side_content.empty? && periphery == :footer && @theme[%(footer_#{side}_content)] != 'none'
-          side_content = { side == :recto ? :right : :left => '{page-number}' }
-        end
 
         acc[side] = side_content
         acc
@@ -3413,14 +3457,15 @@ class Converter < ::Prawn::Document
     end
 
     outline.define do
+      initial_pagenum = has_front_cover ? 2 : 1
       # FIXME use sanitize: :plain_text once available
-      if (doctitle = document.sanitize(doc.doctitle use_fallback: true)) && document.page_count > (has_front_cover ? 2 : 1)
-        page title: doctitle, destination: (document.dest_top has_front_cover ? 2 : 1)
+      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 any way to get add_outline_level to invoke in the context of the outline?
+      # 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
 
@@ -4107,7 +4152,6 @@ class Converter < ::Prawn::Document
   # QUESTION is there a better way to do this?
   # I suppose we could have @tmp_files as an instance variable on converter instead
   # It might be sufficient to delete temporary files once per conversion
-  # 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
@@ -4171,6 +4215,20 @@ class Converter < ::Prawn::Document
     end
   end
 
+  def resolve_pagenums val
+    pgnums = []
+    ((val.include? ',') ? (val.split ',') : (val.split ';')).each do |entry|
+      if entry.include? '..'
+        from, _, to = entry.partition '..'
+        pgnums += ([from.to_i, 1].max..[to.to_i, 1].max).to_a
+      else
+        pgnums << entry.to_i
+      end
+    end
+
+    pgnums
+  end
+
   def get_char code
     (code.start_with? '\u') ? ([((code.slice 2, code.length).to_i 16)].pack 'U1') : code
   end