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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcb6c79a944028551c1ec56650df511a0f4be9984d379de22c891031ce743fe2
-  data.tar.gz: d75bce156557910b7aa82c703b97fd266a5035cd4b37707756ca2f3e29359363
+  metadata.gz: fed971e3655c6b460cdf90ba7205802ad7060710287123a36df56b1e75dd8257
+  data.tar.gz: 888b1ef50e7e690bab7661ee0b10d35671376e85352389ccc8f1bf6b11798cfc
 SHA512:
-  metadata.gz: be77878203c03b479682a80f50baf8278599b6c9d5d24e3dba46e2ad798f26641f223a6b620cff240d6e893eed4d12804b0693f5dbbd926b79e65c40c704e4cc
-  data.tar.gz: 2c3d80e93665b076bda8c1c6b4d6dd59225eb6437d9ad679ebed6995ad1523cadf215a0d6dbe3bab461a089ecf1433bab259cc8bdab519737029659acc175355
+  metadata.gz: e29597fcbbb5c7cc2b822ad5844f0d656fc5890a1b6fb062511f9fb88a68204d5cde0f98b897b9f448c24897c53a9b221328a53ec8ef2f922f769d9f707153ed
+  data.tar.gz: a0275c1a8cee51ccbcf69102d47508f892784637ed0727a4c507c7d3f538b632aa2e87430e23146c7b93a295a95e4057f794f3b7693a1891517106f16c20b563

data/CHANGELOG.adoc

@@ -5,6 +5,33 @@
 This document provides a high-level view of the changes to the {project-name} by release.
 For a detailed view of what has changed, refer to the {uri-repo}/commits/master[commit history] on GitHub.
 
+== 1.5.0.alpha.18 (2019-06-01) - @mojavelinux
+
+* restore compatibility with Asciidoctor back to 1.5.3 and add verification to test matrix (#1038)
+* allow theme to set text indent for paragraphs using prose_text_indent (#191)
+* allow theme to set spacing between adjacent paragraphs using prose_margin_inner (#191)
+* show parts in toc when toclevels=0 (#783)
+* add support for autonumbered callouts in source blocks (#1076)
+* fix duplication of footnotes in keep together regions (#1047)
+* display standalone preamble in book normally (#1051)
+* allow outline depth to be set using outlinelevels attribute independent of toclevels (#1054)
+* fix compounding cell padding (#1053)
+* add support for qanda list (#1013)
+* fix parsing of bibref and link inside footnote text (#1061)
+* restore square brackets around ID of bibliography entry with custom ID (#1065)
+* add page_numbering_start_at key to theme to control start page for page numbering (#1041)
+* don't allow running_content_start_at key to affect page numbering (#1041)
+* substitute \{chapter-title} property on front matter pages (replace with doctitle and toc-title, respectively, when running content starts before first page of body) (#1040)
+* allow side margins to be set on elements on title page (#824)
+* don't promote preamble to preface if preface-title attribute is empty
+* expand padding value for running content (header and footer) to array
+* add support for unnumbered (and no-bullet) style on ordered list (#1073)
+* add visual regression capability to test suite (@beatchristen)
+* ensure index section doesn't get numbered when using Asciidoctor < 1.5.7
+* add part signifier and part number to part title if partnums is set; allow signifier to be customized using part-signifier attribute (#597)
+* add support for the chapter-signifier attribute as the prefered alternative to chapter-label
+* warn if the image referenced in the running content cannot be found (#731)
+
 == 1.5.0.alpha.17 (2019-04-23) - @mojavelinux
 
 * drop support for Ruby < 2.3 (and installation will fail for Ruby < 2.1)
@@ -34,8 +61,8 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/master[
 * handle case when uri to make breakable is empty (#936)
 * add support for frame=ends as alternative to frame=topbot on table
 * allow table frame and grid to be set globally using the table-frame and table-grid attributes (#822)
-* disable table stripes by default
-* allow table stripes to be enabled globally using table-stripes attribute
+* disable table stripes by default (#1049)
+* allow table stripes to be enabled globally using table-stripes attribute (#1049)
 * use new logging subsystem, if available; otherwise, use shim (#905)
 * allow alignment of list text to be controlled using roles (#182)
 * allow text alignment to be set for abstract (#893)
@@ -56,6 +83,7 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/master[
 * guard against pygments returning nil (#884)
 * encode quotes in alt text of inline image (#977)
 * fix crash when menu macro is used in a section or block title (#934)
+* remove duplicate message when syntax highlighter is unavailable; don't crash processor (#1078)
 * only look for the start attribute on the code block itself when highlighting with rouge
 * apply block styling to background for line-oriented tokens in rouge by default
 * detect pagenum ranges in index when media is print or prepress (#906)

data/README.adoc

@@ -1,6 +1,6 @@
 = Asciidoctor PDF: A native PDF converter for AsciiDoc
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
-v1.5.0.alpha.17, 2019-04-23
+v1.5.0.alpha.18, 2019-06-01
 // Settings:
 :experimental:
 :idprefix:
@@ -24,7 +24,7 @@ endif::[]
 :project-name: Asciidoctor PDF
 :project-handle: asciidoctor-pdf
 // Variables:
-:release-version: 1.5.0.alpha.17
+:release-version: 1.5.0.alpha.18
 // URIs:
 :uri-asciidoctor: http://asciidoctor.org
 :uri-gem: http://rubygems.org/gems/asciidoctor-pdf
@@ -41,6 +41,7 @@ endif::[]
 
 ifdef::status[]
 image:https://img.shields.io/travis/asciidoctor/asciidoctor-pdf/master.svg[Build Status (Travis CI),link=https://travis-ci.org/asciidoctor/asciidoctor-pdf]
+image:https://ci.appveyor.com/api/projects/status/524bhoms3j2dp1o3/branch/master?svg=true[Build Status (AppVeyor),link=https://ci.appveyor.com/project/asciidoctor/asciidoctor-pdf]
 image:https://img.shields.io/gem/v/asciidoctor-pdf.svg[Latest Release, link={uri-gem}]
 image:https://img.shields.io/badge/license-MIT-blue.svg[MIT License, link=#copyright]
 endif::[]
@@ -118,7 +119,7 @@ endif::[]
 
 == Prerequisites
 
-All that's needed is Ruby 2.3 or better and a few Ruby gems, which we explain how to install in the next section.
+All that's needed is Ruby 2.3 or better and a few Ruby gems (including at least Asciidoctor 1.5.3), which we explain how to install in the next section.
 
 To check if you have Ruby available, use the `ruby` command to query the version installed:
 
@@ -756,7 +757,11 @@ To run the tests, simply invoke rspec via bundler.
 
  $ bundle exec rspec
 
-If you want to see the name of each test that is run, add the `-fd` option:
+To disable the visual integration tests, pass the `` option:
+
+ $ bundle exec rspec -t ~integration
+
+If you want to see the name of each test as it is run, add the `-fd` option:
 
  $ bundle exec rspec -fd
 
@@ -790,6 +795,28 @@ You can use the application to convert a document as follows:
 
  $ bundle exec asciidoctor-pdf /path/to/sample.adoc
 
+=== Install the Application (optional)
+
+If you want to install the application globally so you can run it anywhere, use the following `rake` task:
+
+ $ bundle exec rake install
+
+This task will package the gem and install it into your system gems.
+
+If you want to install the gem using a separate command, first use the following `rake` task to build it:
+
+ $ rm -rf pkg
+   bundle exec rake build
+
+This task packages the application as a gem and writes it to the [.path]_pkg_ directory.
+A message will be printed to the console telling you the exact filename.
+You can now use the `gem install` command to install it.
+
+ $ gem install pkg/*.gem
+
+You'll want to pay attention to which Ruby installation you are installing the gem into.
+If successful, the `asciidoctor-pdf` executable will be available on your PATH.
+
 endif::[]
 
 === Test a Pull Request

data/asciidoctor-pdf.gemspec

@@ -35,7 +35,7 @@ Gem::Specification.new do |s|
   s.require_paths = ['lib']
   #s.test_files = files.grep %r/^(?:test|spec|feature)\/.*$/
 
-  s.add_runtime_dependency 'asciidoctor', '>= 1.5.0', '< 3.0.0'
+  s.add_runtime_dependency 'asciidoctor', '>= 1.5.3', '< 3.0.0'
   s.add_runtime_dependency 'prawn', '~> 2.2.0'
   s.add_runtime_dependency 'prawn-table', '~> 0.2.0'
   s.add_runtime_dependency 'prawn-templates', '~> 0.1.0'
@@ -50,4 +50,5 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'rake', '~> 12.3.0'
   s.add_development_dependency 'rspec', '~> 3.8.0'
   s.add_development_dependency 'pdf-inspector', '~> 1.3.0'
+  s.add_development_dependency 'chunky_png', '~> 1.3.0'
 end

data/docs/theming-guide.adoc

@@ -96,12 +96,33 @@ link:
   font_color: #002FA7
 outline_list:
   indent: $base_font_size * 1.5
+footer:
+  height: $base_line_height_length * 2.5
+  line_height: 1
+  recto:
+    right:
+      content: '{page-number}'
+  verso:
+    left:
+      content: $footer_recto_right_content
 ----
 
 When creating a new theme, you only have to define the keys you want to override from the base theme, which is loaded prior to loading your custom theme.
 All the available keys are documented in <<Keys>>.
 The converter uses the information from the theme map to help construct the PDF.
 
+Instead of writing a theme from scratch, you can extend the default theme using the `extends` key as follows:
+
+[source,yaml]
+----
+extends: default
+base:
+  color: #ff0000
+----
+
+You can also point the extends key at another custom theme to extend from it.
+Currently, the base theme is always loaded first.
+
 WARNING: If you start a new theme from scratch, we strongly recommend defining TrueType fonts and specifying them in the `base` and `literal` categories.
 Otherwise, Asciidoctor PDF will use built-in AFM fonts, which can result in missing functionality and warnings.
 
@@ -876,6 +897,34 @@ When creating a theme, all keys are optional.
 Required keys are provided by the base theme.
 Therefore, you only have to declare keys that you want to override.
 
+[#keys-extends]
+=== Extends
+
+A theme can extend another theme using the `extends` key.
+The extends key accepts either a single value or an array of values.
+Each value is interpreted as a filename.
+If the filename equals `default`, it resolves to the location of the default (built-in) theme.
+If the filename is absolute, it's used as is.
+If the filename begins with `./`, it's resolved as a theme file relative to the current theme file.
+Otherwise, the filename is resolved as a theme file in the normal way (relative to the value of the `pdf-stylesdir` attribute).
+
+Currently, the base theme is always loaded first.
+Then, the files referenced by the extends key are loaded in order.
+Finally, the keys in the current file are loaded.
+Each time a theme is loaded, the keys are overlaid onto the keys from the previous theme.
+
+[cols="3,4,5l"]
+|===
+|Key |Value Type |Example
+
+|extends
+|String or Array
+(default: [])
+|extends:
+- default
+- ./brand-theme.yml
+|===
+
 [#keys-page]
 === Page
 
@@ -932,6 +981,12 @@ See <<Title Page>> for details.
 (default: A4)
 |page:
   size: Letter
+
+|numbering_start_at
+|title {vbar} toc {vbar} body +
+(default: body)
+|page:
+  numbering_start_at: toc
 |===
 
 . Page background images are automatically scaled to fit within the bounds of the page.
@@ -1615,8 +1670,23 @@ Typically, all the margin is placed on the bottom.
 (default: 12)
 |prose:
   margin_bottom: $vertical_spacing
+
+|margin_inner^[1]^
+|<<measurement-units,Measurement>> +
+(default: $prose_margin_bottom)
+|prose:
+  margin_inner: 0
+
+|text_indent
+|<<measurement-units,Measurement>> +
+(default: _not set_)
+|prose:
+  text_indent: 18
 |===
 
+. Controls the margin between adjacent paragraphs.
+Useful when using indented paragraphs.
+
 [#keys-block]
 === Block
 
@@ -2955,6 +3025,56 @@ The keys in this category control the arrangement and style of tables and table
 . Applied to even rows by default; controlled using `stripes` attribute (even, odd, all, none) on table.
 //. `<parity>` can be `odd` (odd rows) or `even` (even rows).
 
+[#keys-footnotes]
+=== Footnotes
+
+The keys in this catagory control the style the list of footnotes at the end of the chapter (book) or document (otherwise).
+If the `footnotes-title` attribute is specified, it is styled as a block caption.
+The styling of the links is controlled by the global link styles.
+
+[cols="3,4,5l"]
+|===
+|Key |Value Type |Example
+
+3+|[#key-prefix-footnotes]*Key Prefix:* <<key-prefix-footnotes,footnotes>>
+
+|font_color
+|<<colors,Color>> +
+(default: $base_font_color)
+|footnotes:
+  font_color: #cccccc
+
+|font_size
+|<<values,Number>> +
+(default: 8)
+|footnotes:
+  font_size: 6
+
+|font_style
+|<<font-styles,Font style>> +
+(default: $base_font_style)
+|footnotes:
+  font_style: italic
+
+|item_spacing
+|<<measurement-units,Measurement>> +
+(default: 3)
+|footnotes:
+  item_spacing: 5
+
+|margin_top
+|<<measurement-units,Measurement>> +
+(default: 0)
+|footnotes:
+  margin_top: 10
+
+|text_transform
+|<<text-transforms,Text transform>> +
+(default: _inherit_)
+|footnotes:
+  text_transform: lowercase
+|===
+
 [#keys-table-of-contents]
 === Table of Contents (TOC)
 
@@ -3144,6 +3264,7 @@ If value is not specified, dot leaders are shown for all levels.
 === Running Content (Header & Footer)
 
 The keys in this category control the arrangement and style of running header and footer content.
+Please note that the running content will _not_ be used unless a) the periphery (header or footer) is configured and b) the height key for the periphery is assigned a value.
 
 [cols="3,4,5l"]
 |===
@@ -3347,7 +3468,7 @@ The keys in this category control the arrangement and style of running header an
       content: '\{page-number}'
 |===
 . The background color spans the width of the page, as does the border when a background color is specified.
-. If the height is not set, the running content at this periphery is disabled.
+. *If the height is not set, the running content at this periphery is disabled.*
 . If the side padding is negative, the content will bleed into the margin of the page.
 . `<side>` can be `recto` (right-hand, odd-numbered pages) or `verso` (left-hand, even-numbered pages).
 Where the page sides fall in relation to the physical or printed page number is controlled using the `pdf-folio-placement` attribute (except when `media=prepress`, which implies `physical`).
@@ -3540,6 +3661,10 @@ These settings override equivalent keys defined in the theme file, where applica
 |screen {vbar} print {vbar} prepress
 |:media: prepress
 
+|outlinelevels
+|number (default: same as _toclevels_)
+|:outlinelevels: 2
+
 |page-background-image^[4]^
 |path^[2]^ {vbar} image macro^[3]^
 |:page-background-image: image:bg.jpg[]

data/lib/asciidoctor-pdf/asciidoctor_ext.rb

@@ -1,4 +1,6 @@
-# NOTE these are all candidates for inclusion in Asciidoctor core
+# NOTE these are either candidates for inclusion in Asciidoctor core or backports
+require_relative 'asciidoctor_ext/abstract_block'
+require_relative 'asciidoctor_ext/document'
 require_relative 'asciidoctor_ext/section'
 require_relative 'asciidoctor_ext/list'
 require_relative 'asciidoctor_ext/list_item'

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

@@ -0,0 +1,5 @@
+class Asciidoctor::AbstractBlock
+  def sections?
+    !sections.empty?
+  end unless method_defined? :sections?
+end

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

@@ -0,0 +1,3 @@
+class Asciidoctor::Document
+  alias catalog references unless method_defined? :catalog
+end

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

@@ -1,11 +1,17 @@
 module Asciidoctor
   class StubLogger
     class << self
-      def warn message
+      def info message = nil
+        # ignore since this isn't a real logger
+      end
+
+      def warn message = nil
+        message = block_given? ? yield : message unless message
         ::Kernel.warn %(asciidoctor: WARNING: #{message})
       end
 
-      def error message
+      def error message = nil
+        message = block_given? ? yield : message unless message
         ::Kernel.warn %(asciidoctor: ERROR: #{message})
       end
     end

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

@@ -1,17 +1,25 @@
 class Asciidoctor::Section
   def numbered_title opts = {}
     unless (@cached_numbered_title ||= nil)
-      if (slevel = (@level == 0 && @special ? 1 : @level)) == 0
-        @is_numbered = false
-        @cached_numbered_title = @cached_formal_numbered_title = title
-      elsif @numbered && !@caption && slevel <= (@document.attr 'sectnumlevels', 3).to_i
+      slevel = @level == 0 && @special ? 1 : @level
+      if @numbered && !@caption && slevel <= (@document.attr 'sectnumlevels', 3).to_i
         @is_numbered = true
-        @cached_numbered_title = %(#{sectnum} #{title})
-        @cached_formal_numbered_title = if slevel == 1 && @document.doctype == 'book'
-          %(#{@document.attr 'chapter-label', 'Chapter'} #{@cached_numbered_title}).lstrip
+        @cached_formal_numbered_title = if @document.doctype == 'book'
+          if slevel == 0
+            @cached_numbered_title = %(#{sectnum nil, ':'} #{title})
+            %(#{@document.attr 'part-signifier', 'Part'} #{@cached_numbered_title}).lstrip
+          elsif slevel == 1
+            @cached_numbered_title = %(#{sectnum} #{title})
+            %(#{@document.attr 'chapter-signifier', (@document.attr 'chapter-label', 'Chapter')} #{@cached_numbered_title}).lstrip
+          else
+            @cached_numbered_title = %(#{sectnum} #{title})
+          end
         else
-          @cached_numbered_title
+          @cached_numbered_title = %(#{sectnum} #{title})
         end
+      elsif slevel == 0
+        @is_numbered = false
+        @cached_numbered_title = @cached_formal_numbered_title = title
       else
         @is_numbered = false
         @cached_numbered_title = @cached_formal_numbered_title = captioned_title

data/lib/asciidoctor-pdf/converter.rb

@@ -90,8 +90,7 @@ class Converter < ::Prawn::Document
   MeasurementRxt = '\\d+(?:\\.\\d+)?(?:in|cm|mm|p[txc])?'
   MeasurementPartsRx = /^(\d+(?:\.\d+)?)(in|mm|cm|p[txc])?$/
   PageSizeRx = /^(?:\[(#{MeasurementRxt}), ?(#{MeasurementRxt})\]|(#{MeasurementRxt})(?: x |x)(#{MeasurementRxt})|\S+)$/
-  # CalloutExtractRx synced from /lib/asciidoctor.rb of Asciidoctor core
-  CalloutExtractRx = /(?:(?:\/\/|#|--|;;) ?)?(\\)?<!?(--|)(\d+)\2> ?(?=(?:\\?<!?\2\d+\2> ?)*$)/
+  CalloutExtractRx = /(?:(?:\/\/|#|--|;;) ?)?(\\)?<!?(|--)(\d+|\.)\2> ?(?=(?:\\?<!?\2(?:\d+|\.)\2>)*$)/
   ImageAttributeValueRx = /^image:{1,2}(.*?)\[(.*?)\]$/
   UriBreakCharsRx = /(?:\/|\?|&amp;|#)(?!$)/
   UriBreakCharRepl = %(\\&#{ZeroWidthSpace})
@@ -113,10 +112,10 @@ class Converter < ::Prawn::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 = {
-      expands_tabs: (::Asciidoctor::VERSION.start_with? '1.5.3.') || AsciidoctorVersion >= (::Gem::Version.create '1.5.3')
+      expands_tabs: (::Asciidoctor::VERSION.start_with? '1.5.3.') || AsciidoctorVersion >= (::Gem::Version.create '1.5.3'),
+      special_sectnums: AsciidoctorVersion >= (::Gem::Version.create '1.5.7'),
+      syntax_highlighter: AsciidoctorVersion >= (::Gem::Version.create '2.0.0'),
     }
   end
 
@@ -155,16 +154,19 @@ class Converter < ::Prawn::Document
     unless (doc.attribute_locked? 'pagenums') || ((doc.instance_variable_get :@attributes_modified).include? 'pagenums')
       doc.attributes['pagenums'] = ''
     end
+    if (idx_sect = doc.sections.find {|candidate| candidate.sectname == 'index' }) && idx_sect.numbered
+      idx_sect.numbered = false
+    end unless @capabilities[:special_sectnums]
     #assign_missing_section_ids doc
 
     # promote anonymous preface (defined using preamble block) to preface section
     # FIXME this should be done in core
-    if doc.doctype == 'book' && (blk_0 = doc.blocks[0]) && blk_0.context == :preamble &&
-        blk_0.title? && blk_0.blocks[0].style != 'abstract' && (blk_1 = doc.blocks[1]) && blk_1.context == :section
+    if doc.doctype == 'book' && (blk_0 = doc.blocks[0]) && blk_0.context == :preamble && blk_0.title? &&
+        !blk_0.title.nil_or_empty? && blk_0.blocks[0].style != 'abstract' && (blk_1 = doc.blocks[1]) && blk_1.context == :section
       preface = Section.new doc, blk_1.level, false, attributes: { 1 => 'preface', 'style' => 'preface' }
       preface.special = true
       preface.sectname = 'preface'
-      preface.title = doc.attr 'preface-title', 'Preface'
+      preface.title = blk_0.instance_variable_get :@title
       # QUESTION should ID be generated from raw or converted title? core is not clear about this
       preface.id = preface.generate_id
       preface.blocks.replace blk_0.blocks.map {|b| b.parent = preface; b }
@@ -233,20 +235,31 @@ class Converter < ::Prawn::Document
     start_new_page if @media == 'prepress' && verso_page?
 
     if insert_title_page
-      body_start_page_number = page_number
+      body_offset = (body_start_page_number = page_number) - 1
+      front_matter_sig = [@theme.running_content_start_at || 'body', @theme.page_numbering_start_at || 'body', insert_toc]
       # 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
+      num_front_matter_pages = {
+        ['title', 'title', true] => [0, 0],
+        ['title', 'title', false] => [0, 0],
+        ['title', 'toc', true] => [0, 1],
+        ['title', 'toc', false] => [0, 1],
+        ['title', 'body', true] => [0, body_offset],
+        ['title', 'body', false] => [0, 1],
+        ['toc', 'title', true] => [1, 0],
+        ['toc', 'title', false] => [1, 0],
+        ['toc', 'toc', true] => [1, 1],
+        ['toc', 'toc', false] => [1, 1],
+        ['toc', 'body', true] => [1, body_offset],
+        ['body', 'title', true] => [body_offset, 0],
+        ['body', 'title', false] => [1, 0],
+        ['body', 'toc', true] => [body_offset, 1],
+      }[front_matter_sig] || [body_offset, body_offset]
     else
-      num_front_matter_pages = body_start_page_number - 1
+      # Q: what if there's only a toc page, but not title?
+      num_front_matter_pages = [body_start_page_number - 1] * 2
     end
 
-    @index.start_page_number = num_front_matter_pages + 1
+    @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
 
@@ -261,18 +274,18 @@ class Converter < ::Prawn::Document
     # 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_start) : []
+    toc_page_nums = insert_toc ? (layout_toc doc, num_toc_levels, toc_page_nums.first, num_front_matter_pages[1], toc_start) : []
 
     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
+        layout_running_content :header, doc, skip: num_front_matter_pages, body_start_page_number: body_start_page_number
       end
       unless doc.nofooter || @theme.footer_height.to_f.zero?
-        layout_running_content :footer, doc, skip: num_front_matter_pages
+        layout_running_content :footer, doc, skip: num_front_matter_pages, body_start_page_number: body_start_page_number
       end
     end
 
-    add_outline doc, num_toc_levels, toc_page_nums, num_front_matter_pages
+    add_outline doc, (doc.attr 'outlinelevels', num_toc_levels).to_i, toc_page_nums, num_front_matter_pages[1]
     # TODO allow document (or theme) to override initial view magnification
     # NOTE add 1 to page height to force initial scroll to 0; a nil value also seems to work
     catalog.data[:OpenAction] = dest_fit_horizontally((page_height + 1), state.pages[0]) if state.pages.size > 0
@@ -321,6 +334,8 @@ 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
+    @list_numerals = []
+    @list_bullets = []
     @footnotes = []
     @index = IndexCatalog.new
     # NOTE we have to init Pdfmark class here while we have reference to the doc
@@ -359,19 +374,19 @@ class Converter < ::Prawn::Document
       page_margin = nil
     end
 
-    page_size = if (doc.attr? 'pdf-page-size') && (m = PageSizeRx.match(doc.attr 'pdf-page-size'))
+    if (doc.attr? 'pdf-page-size') && PageSizeRx =~ (doc.attr 'pdf-page-size')
       # e.g, [8.5in, 11in]
-      if m[1]
-        [m[1], m[2]]
+      if $1
+        page_size = [$1, $2]
       # e.g, 8.5in x 11in
-      elsif m[3]
-        [m[3], m[4]]
+      elsif $3
+        page_size = [$3, $4]
       # e.g, A4
       else
-        m[0]
+        page_size = $&
       end
     else
-      theme.page_size
+      page_size = theme.page_size
     end
 
     page_size = case page_size
@@ -388,9 +403,9 @@ class Converter < ::Prawn::Document
         if ::Numeric === dim
           # dimension cannot be less than 0
           dim > 0 ? dim : break
-        elsif ::String === dim && (m = (MeasurementPartsRx.match dim))
+        elsif ::String === dim && MeasurementPartsRx =~ dim
           # NOTE truncate to max precision retained by PDF::Core
-          (to_pt m[1].to_f, m[2]).truncate 4
+          (to_pt $1.to_f, $2).truncate 4
         else
           break
         end
@@ -519,6 +534,9 @@ class Converter < ::Prawn::Document
       end
       theme_font :abstract do
         prose_opts = { line_height: @theme.abstract_line_height, align: (@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] }
@@ -547,21 +565,25 @@ class Converter < ::Prawn::Document
 
   def convert_preamble node
     # TODO find_by needs to support a depth argument
-    if (first_p = (node.find_by context: :paragraph)[0]) && first_p.parent == node
+    # 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'
     end
     convert_content_for_block node
   end
 
-  # 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
-    prose_opts = {}
+    prose_opts = { margin_bottom: 0 }
     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)
+      prose_opts[:indent_paragraphs] = text_indent
+    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?
@@ -573,6 +595,14 @@ class Converter < ::Prawn::Document
     else
       layout_prose node.content, prose_opts
     end
+
+    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
+    else
+      margin_bottom_val = @theme.prose_margin_bottom
+    end
+    margin_bottom margin_bottom_val
   end
 
   def convert_admonition node
@@ -627,6 +657,7 @@ class Converter < ::Prawn::Document
     shift_top = shift_base / 3.0
     shift_bottom = (shift_base * 2) / 3.0
     keep_together do |box_height = nil|
+      push_scratch doc if scratch?
       pad_box [0, cpad[1], 0, lpad[3]] do
         if box_height
           if (rule_color = @theme.admonition_column_rule_color) &&
@@ -634,7 +665,7 @@ class Converter < ::Prawn::Document
             float do
               bounding_box [0, cursor], width: label_width + lpad[1], height: box_height do
                 stroke_vertical_rule rule_color,
-                    at: bounds.width,
+                    at: bounds.right,
                     line_style: (@theme.admonition_column_rule_style || :solid).to_sym,
                     line_width: rule_width
               end
@@ -728,6 +759,7 @@ class Converter < ::Prawn::Document
           move_up shift_bottom unless at_page_top?
         end
       end
+      pop_scratch doc if scratch?
     end
     theme_margin :block, :bottom
   end
@@ -736,6 +768,7 @@ class Converter < ::Prawn::Document
     add_dest_for_block node if node.id
     theme_margin :block, :top
     keep_together do |box_height = nil|
+      push_scratch node.document if scratch?
       caption_height = node.title? ? (layout_caption node) : 0
       if box_height
         float do
@@ -749,6 +782,7 @@ class Converter < ::Prawn::Document
           convert_content_for_block node
         end
       end
+      pop_scratch node.document if scratch?
     end
     theme_margin :block, :bottom
   end
@@ -773,6 +807,7 @@ class Converter < ::Prawn::Document
     b_width = @theme.blockquote_border_width
     b_color = @theme.blockquote_border_color
     keep_together do |box_height = nil|
+      push_scratch node.document if scratch?
       start_page_number = page_number
       start_cursor = cursor
       caption_height = node.title? ? (layout_caption node) : 0
@@ -823,6 +858,7 @@ class Converter < ::Prawn::Document
           end unless b_height == 0
         end
       end
+      pop_scratch node.document if scratch?
     end
     theme_margin :block, :bottom
   end
@@ -834,6 +870,7 @@ class Converter < ::Prawn::Document
     add_dest_for_block node if node.id
     theme_margin :block, :top
     keep_together do |box_height = nil|
+      push_scratch node.document if scratch?
       if box_height
         # FIXME due to the calculation error logged in #789, we must advance page even when content is split across pages
         advance_page if box_height > cursor && !at_page_top?
@@ -890,6 +927,7 @@ class Converter < ::Prawn::Document
           convert_content_for_block node
         end
       end
+      pop_scratch node.document if scratch?
     end
     theme_margin :block, :bottom
   end
@@ -908,10 +946,10 @@ class Converter < ::Prawn::Document
       end
     end
     add_dest_for_block node if node.id
-    @list_numbers ||= []
+    @list_numerals ||= []
     # FIXME move \u2460 to constant (or theme setting)
     # \u2460 = circled one, \u24f5 = double circled one, \u278b = negative circled one
-    @list_numbers << %(\u2460)
+    @list_numerals << %(\u2460)
     #stroke_horizontal_rule @theme.caption_border_bottom_color
     line_metrics = calc_line_metrics @theme.base_line_height
     node.items.each_with_index do |item, idx|
@@ -919,7 +957,7 @@ class Converter < ::Prawn::Document
       advance_page if cursor < (line_metrics.height + line_metrics.leading + line_metrics.padding_top) + 1
       convert_colist_item item
     end
-    @list_numbers.pop
+    @list_numerals.pop
     # correct bottom margin of last item
     list_margin_bottom = @theme.prose_margin_bottom
     margin_bottom list_margin_bottom - @theme.outline_list_item_spacing
@@ -931,7 +969,7 @@ class Converter < ::Prawn::Document
       marker_width = rendered_width_of_string %(#{conum_glyph 1}x)
       float do
         bounding_box [0, cursor], width: marker_width do
-          @list_numbers << (index = @list_numbers.pop).next
+          @list_numerals << (index = @list_numerals.pop).next
           theme_font :conum do
             layout_prose index, align: :center, line_height: @theme.conum_line_height, inline_format: false, margin: 0
           end
@@ -940,39 +978,46 @@ class Converter < ::Prawn::Document
     end
 
     indent marker_width do
-      convert_content_for_list_item node, margin_bottom: @theme.outline_list_item_spacing
+      convert_content_for_list_item node, :colist, margin_bottom: @theme.outline_list_item_spacing
     end
   end
 
   def convert_dlist node
     add_dest_for_block node if node.id
 
-    # 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?
+    case node.style
+    when 'qanda'
+      (@list_numerals ||= []) << '1'
+      convert_outline_list node
+      @list_numerals.pop
+    else
+      # 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?
 
-    node.items.each do |terms, desc|
-      terms = [*terms]
-      # NOTE don't orphan the terms, allow for at least one line of content
-      # FIXME extract ensure_space (or similar) method
-      advance_page if cursor < @theme.base_line_height_length * (terms.size + 1)
-      terms.each do |term|
-        # FIXME layout_prose should pass style downward when parsing formatted text
-        #layout_prose term.text, style: @theme.description_list_term_font_style.to_sym, margin_top: 0, margin_bottom: @theme.description_list_term_spacing, align: :left
-        term_text = term.text
-        case @theme.description_list_term_font_style.to_sym
-        when :bold
-          term_text = %(<strong>#{term_text}</strong>)
-        when :italic
-          term_text = %(<em>#{term_text}</em>)
-        when :bold_italic
-          term_text = %(<strong><em>#{term_text}</em></strong>)
-        end
-        layout_prose term_text, margin_top: 0, margin_bottom: @theme.description_list_term_spacing, align: :left
-      end
-      if desc
-        indent @theme.description_list_description_indent do
-          convert_content_for_list_item desc
+      node.items.each do |terms, desc|
+        terms = [*terms]
+        # NOTE don't orphan the terms, allow for at least one line of content
+        # FIXME extract ensure_space (or similar) method
+        advance_page if cursor < @theme.base_line_height_length * (terms.size + 1)
+        terms.each do |term|
+          # FIXME layout_prose should pass style downward when parsing formatted text
+          #layout_prose term.text, style: @theme.description_list_term_font_style.to_sym, margin_top: 0, margin_bottom: @theme.description_list_term_spacing, align: :left
+          term_text = term.text
+          case @theme.description_list_term_font_style.to_sym
+          when :bold
+            term_text = %(<strong>#{term_text}</strong>)
+          when :italic
+            term_text = %(<em>#{term_text}</em>)
+          when :bold_italic
+            term_text = %(<strong><em>#{term_text}</em></strong>)
+          end
+          layout_prose term_text, margin_top: 0, margin_bottom: @theme.description_list_term_spacing, align: :left
+        end
+        if desc
+          indent @theme.description_list_description_indent do
+            convert_content_for_list_item desc, :dlist_desc
+          end
         end
       end
     end
@@ -980,7 +1025,7 @@ class Converter < ::Prawn::Document
 
   def convert_olist node
     add_dest_for_block node if node.id
-    @list_numbers ||= []
+    @list_numerals ||= []
     # TODO move list_number resolve to a method
     list_number = case node.style
     when 'arabic'
@@ -997,16 +1042,20 @@ class Converter < ::Prawn::Document
       RomanNumeral.new 'I'
     when 'lowergreek'
       LowercaseGreekA
+    when 'unstyled', 'unnumbered', 'no-bullet'
+      nil
+    when 'none'
+      ''
     else
       '1'
     end
     # TODO support start values < 1 (issue #498)
     if (start = ((node.attr 'start', nil, false) || ((node.option? 'reversed') ? node.items.size : 1)).to_i) > 1
-      (start - 1).times { list_number = list_number.next  }
+      (start - 1).times { list_number = list_number.next }
     end
-    @list_numbers << list_number
+    @list_numerals << list_number
     convert_outline_list node
-    @list_numbers.pop
+    @list_numerals.pop
   end
 
   def convert_ulist node
@@ -1064,13 +1113,13 @@ class Converter < ::Prawn::Document
     complex = false
     # ...or if we want to give all items in the list the same treatment
     #complex = node.items.find(&:complex?) ? true : false
-    if node.context == :ulist && !@list_bullets[-1]
+    if (node.context == :ulist && !@list_bullets[-1]) || (node.context == :olist && !@list_numerals[-1])
       if node.style == 'unstyled'
         # unstyled takes away all indentation
         list_indent = 0
       elsif (list_indent = @theme.outline_list_indent) > 0
         # no-bullet aligns text with left-hand side of bullet position (as though there's no bullet)
-        list_indent = [list_indent - (rendered_width_of_string %(\u2022x)), 0].max
+        list_indent = [list_indent - (rendered_width_of_string %(#{node.context == :ulist ? "\u2022" : '1.'}x)), 0].max
       end
     else
       list_indent = @theme.outline_list_indent
@@ -1079,7 +1128,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?, opts
+        convert_outline_list_item item, node, opts
       end
     end
     # NOTE Children will provide the necessary bottom margin if last item is complex.
@@ -1091,33 +1140,48 @@ class Converter < ::Prawn::Document
     end
   end
 
-  def convert_outline_list_item node, complex = false, opts = {}
+  def convert_outline_list_item node, list, 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)
+    case (list_type = list.context)
     when :ulist
-      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_type = (node.attr? 'checked', nil, false) ? :checked : :unchecked
-          marker = @theme[%(ulist_marker_#{marker_type}_content)] || BallotBox[marker_type]
+      complex = node.complex?
+      if (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_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
-      else
-        marker = @theme[%(ulist_marker_#{marker_type}_content)] || Bullets[marker_type]
+        [: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
       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)
+      complex = node.complex?
+      if (index = @list_numerals.pop)
+        if index.empty?
+          marker = ''
+        else
+          marker = %(#{index}.)
+          dir = (node.parent.option? 'reversed') ? :pred : :next
+          @list_numerals << (index = index.public_send dir)
+        end
+      end
+    when :dlist
+      # NOTE list.style is 'qanda'
+      complex = node[1] && node[1].complex?
+      @list_numerals << (index = @list_numerals.pop).next
       marker = %(#{index}.)
     else
+      complex = node.complex?
       logger.warn %(unknown list type #{list_type.inspect})
       marker = @theme.ulist_marker_disc_content || Bullets[:disc]
     end
@@ -1148,15 +1212,24 @@ class Converter < ::Prawn::Document
     end
 
     if complex
-      convert_content_for_list_item node, opts
+      convert_content_for_list_item node, list_type, opts
     else
-      convert_content_for_list_item node, (opts.merge margin_bottom: @theme.outline_list_item_spacing)
+      convert_content_for_list_item node, list_type, (opts.merge margin_bottom: @theme.outline_list_item_spacing)
     end
   end
 
-  def convert_content_for_list_item node, opts = {}
-    layout_prose node.text, opts if node.text?
-    convert_content_for_block node
+  def convert_content_for_list_item node, list_type, opts = {}
+    if list_type == :dlist # qanda
+      terms, desc = node
+      [*terms].each {|term| layout_prose %(<em>#{term.text}</em>), opts }
+      if desc
+        layout_prose desc.text, opts if desc.text?
+        convert_content_for_block desc
+      end
+    else
+      layout_prose node.text, opts if node.text?
+      convert_content_for_block node
+    end
   end
 
   def convert_image node, opts = {}
@@ -1330,10 +1403,8 @@ class Converter < ::Prawn::Document
           ::OpenURI
         end
         poster = open(%(http://vimeo.com/api/v2/video/#{video_id}.xml), 'r') do |f|
-          (/<thumbnail_large>(.*?)<\/thumbnail_large>/.match f.read)[1]
+          /<thumbnail_large>(.*?)<\/thumbnail_large>/ =~ f.read && $1
         end
-      else
-        poster = nil
       end
       type = 'Vimeo video'
     else
@@ -1366,13 +1437,27 @@ class Converter < ::Prawn::Document
 
     # HACK disable built-in syntax highlighter; must be done before calling node.content!
     if node.style == 'source' && node.attributes['language'] &&
-        (highlighter = node.document.attributes['source-highlighter']) &&
-        (SourceHighlighters.include? highlighter)
+        (highlighter = node.document.attributes['source-highlighter']) && (SourceHighlighters.include? highlighter) &&
+        (@capabilities[:syntax_highlighter] ? node.document.syntax_highlighter.highlight? : true)
+      case highlighter
+      when 'coderay'
+        unless defined? ::Asciidoctor::Prawn::CodeRayEncoder
+          highlighter = nil if (Helpers.require_library CodeRayRequirePath, 'coderay', :warn).nil?
+        end
+      when 'pygments'
+        unless defined? ::Pygments
+          highlighter = nil if (Helpers.require_library 'pygments', 'pygments.rb', :warn).nil?
+        end
+      when 'rouge'
+        unless defined? ::Rouge::Formatters::Prawn
+          highlighter = nil if (Helpers.require_library RougeRequirePath, 'rouge', :warn).nil?
+        end
+      end
       prev_subs = (subs = node.subs).dup
-      # NOTE the highlight sub is only set for coderay and pygments atm
+      # NOTE the highlight sub is only set for coderay, rouge, and pygments atm
       highlight_idx = subs.index :highlight
       # NOTE scratch? here only applies if listing block is nested inside another block
-      if scratch?
+      if !highlighter || scratch?
         highlighter = nil
         if highlight_idx
           # switch the :highlight sub back to :specialcharacters
@@ -1401,7 +1486,6 @@ class Converter < ::Prawn::Document
 
     source_chunks = case highlighter
     when 'coderay'
-      Helpers.require_library CodeRayRequirePath, 'coderay' unless defined? ::Asciidoctor::Prawn::CodeRayEncoder
       source_string, conum_mapping = extract_conums source_string
       srclang = node.attr 'language', 'text', false
       begin
@@ -1412,7 +1496,6 @@ class Converter < ::Prawn::Document
       fragments = (::CodeRay.scan source_string, srclang).to_prawn
       conum_mapping ? (restore_conums fragments, conum_mapping) : fragments
     when 'pygments'
-      Helpers.require_library 'pygments', 'pygments.rb' unless defined? ::Pygments
       lexer = ::Pygments::Lexer.find_by_alias(node.attr 'language', 'text', false) || ::Pygments::Lexer.find_by_mimetype('text/plain')
       lexer_opts = {
         nowrap: true,
@@ -1451,7 +1534,6 @@ class Converter < ::Prawn::Document
       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)
@@ -1533,15 +1615,16 @@ class Converter < ::Prawn::Document
   # and the mapping of lines to conums as the second.
   def extract_conums string
     conum_mapping = {}
+    auto_num = 0
     string = string.split(LF).map.with_index {|line, line_num|
       # FIXME we get extra spaces before numbers if more than one on a line
       if line.include? '<'
         line.gsub(CalloutExtractRx) {
           # honor the escape
-          if $1 == '\\'
-            $&.sub '\\', ''
+          if $1 == ?\\
+            $&.sub $1, ''
           else
-            (conum_mapping[line_num] ||= []) << $3.to_i
+            (conum_mapping[line_num] ||= []) << ($3 == '.' ? (auto_num += 1) : $3.to_i)
             ''
           end
         }
@@ -1748,7 +1831,9 @@ class Converter < ::Prawn::Document
           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
+          if ::Array === (cell_padding = cell_data[:padding]) && cell_padding.size == 4
+            cell_padding = cell_padding.dup
+          else
             cell_padding = cell_data[:padding] = inflate_padding cell_padding
           end
           cell_padding[0] += cell_line_metrics.padding_top
@@ -2026,7 +2111,7 @@ class Converter < ::Prawn::Document
       elsif (@media ||= node.document.attr 'media', 'screen') != 'screen' || (node.document.attr? 'show-link-uri')
         # QUESTION should we insert breakable chars into URI when building fragment instead?
         # TODO allow style of printed link to be controlled by theme
-        %(<a href="#{target = node.target}"#{attrs.join}>#{node.text}</a> [<font size="0.85em">#{breakable_uri target}</font>])
+        %(<a href="#{target = node.target}"#{attrs.join}>#{node.text}</a> [<font size="0.85em">#{breakable_uri target}</font>&#93;)
       else
         %(<a href="#{node.target}"#{attrs.join}>#{node.text}</a>)
       end
@@ -2038,18 +2123,18 @@ class Converter < ::Prawn::Document
         %(<a href="#{node.target}">#{node.text || path}</a>)
       elsif (refid = node.attributes['refid'])
         unless (text = node.text)
-          if (refs = node.document.references[:refs])
+          if (refs = node.document.catalog[:refs])
             if ::Asciidoctor::AbstractNode === (ref = refs[refid])
               text = ref.xreftext((@xrefstyle ||= (node.document.attr 'xrefstyle')))
             end
           else
             # Asciidoctor < 1.5.6
-            text = node.document.references[:ids][refid]
+            text = node.document.catalog[:ids][refid]
           end
         end
-        %(<a anchor="#{derive_anchor_from_id refid}">#{text || "[#{refid}]"}</a>)
+        %(<a anchor="#{derive_anchor_from_id refid}">#{text || "[#{refid}]"}</a>).gsub ']', '&#93;'
       else
-        %(<a anchor="#{node.document.attr 'pdf-anchor'}">#{node.text || '[^top]'}</a>)
+        %(<a anchor="#{node.document.attr 'pdf-anchor'}">#{node.text || '[^top&#93;'}</a>)
       end
     when :ref
       # NOTE destination is created inside callback registered by FormattedTextTransform#build_fragment
@@ -2058,9 +2143,14 @@ class Converter < ::Prawn::Document
     when :bibref
       # NOTE destination is created inside callback registered by FormattedTextTransform#build_fragment
       # 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 reftext is no longer enclosed in [] starting in Asciidoctor 2.0.0
       # 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}]"})
+      if (reftext = node.reftext)
+        reftext = %([#{reftext}]) unless reftext.start_with? '['
+      else
+        reftext = %([#{node.target || node.id}])
+      end
+      %(<a name="#{node.target || node.id}">#{DummyText}</a>#{reftext})
     else
       logger.warn %(unknown anchor type: #{node.type.inspect})
     end
@@ -2166,7 +2256,7 @@ class Converter < ::Prawn::Document
       node.type == :visible ? node.text : ''
     else
       dest = {
-        anchor: (anchor_name = %(__indexterm-#{node.object_id}))
+        anchor: (anchor_name = @index.next_anchor_name)
         # NOTE page number is added in InlineDestinationMarker
       }
       anchor = %(<a name="#{anchor_name}" type="indexterm">#{DummyText}</a>)
@@ -2270,9 +2360,7 @@ class Converter < ::Prawn::Document
         relative_to_imagesdir = false
       end
       # HACK quick fix to resolve image path relative to theme
-      unless doc.attr? 'title-logo-image'
-        logo_image_path = ThemeLoader.resolve_theme_asset logo_image_path, (doc.attr 'pdf-stylesdir')
-      end
+      logo_image_path = ThemeLoader.resolve_theme_asset logo_image_path, (doc.attr 'pdf-stylesdir') unless doc.attr? 'title-logo-image'
       logo_image_attrs['target'] = logo_image_path
       logo_image_attrs['align'] ||= (@theme.title_page_logo_align || title_align.to_s)
       # QUESTION should we allow theme to turn logo image off?
@@ -2287,7 +2375,9 @@ class Converter < ::Prawn::Document
       # 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
-      convert_image image_block, relative_to_imagesdir: relative_to_imagesdir, pinned: true
+      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
     end
 
@@ -2304,34 +2394,40 @@ class Converter < ::Prawn::Document
         @y = title_top
       end
       move_down(@theme.title_page_title_margin_top || 0)
-      theme_font :title_page_title do
-        layout_heading doctitle.main,
-          align: title_align,
-          margin: 0,
-          line_height: @theme.title_page_title_line_height
+      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
+        end
       end
       move_down(@theme.title_page_title_margin_bottom || 0)
       if doctitle.subtitle
         move_down(@theme.title_page_subtitle_margin_top || 0)
-        theme_font :title_page_subtitle do
-          layout_heading doctitle.subtitle,
-            align: title_align,
-            margin: 0,
-            line_height: @theme.title_page_subtitle_line_height
+        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,
+              align: title_align,
+              margin: 0,
+              line_height: @theme.title_page_subtitle_line_height
+          end
         end
         move_down(@theme.title_page_subtitle_margin_bottom || 0)
       end
       if doc.attr? 'authors'
         move_down(@theme.title_page_authors_margin_top || 0)
-        # TODO provide an API in core to get authors as an array
-        authors = (1..(doc.attr 'authorcount', 1).to_i).map {|idx|
-          doc.attr(idx == 1 ? 'author' : %(author_#{idx}))
-        } * (@theme.title_page_authors_delimiter || ', ')
-        theme_font :title_page_authors do
-          layout_prose authors,
-            align: title_align,
-            margin: 0,
-            normalize: false
+        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
+          authors = (1..(doc.attr 'authorcount', 1).to_i).map {|idx|
+            doc.attr(idx == 1 ? 'author' : %(author_#{idx}))
+          } * (@theme.title_page_authors_delimiter || ', ')
+          theme_font :title_page_authors do
+            layout_prose authors,
+              align: title_align,
+              margin: 0,
+              normalize: false
+          end
         end
         move_down(@theme.title_page_authors_margin_bottom || 0)
       end
@@ -2339,11 +2435,13 @@ class Converter < ::Prawn::Document
       unless revision_info.empty?
         move_down(@theme.title_page_revision_margin_top || 0)
         revision_text = revision_info * (@theme.title_page_revision_delimiter || ', ')
-        theme_font :title_page_revision do
-          layout_prose revision_text,
-            align: title_align,
-            margin: 0,
-            normalize: false
+        indent (@theme.title_page_revision_margin_left || 0), (@theme.title_page_revision_margin_right || 0) do
+          theme_font :title_page_revision do
+            layout_prose revision_text,
+              align: title_align,
+              margin: 0,
+              normalize: false
+          end
         end
         move_down(@theme.title_page_revision_margin_bottom || 0)
       end
@@ -2505,8 +2603,8 @@ class Converter < ::Prawn::Document
         layout_heading((doc.attr 'toc-title'), align: toc_title_align)
       end
     end
-    # QUESTION should we skip this whole method if num_levels == 0?
-    if num_levels > 0
+    # QUESTION should we skip this whole method if num_levels < 0?
+    unless num_levels < 0
       dot_leader = theme_font :toc do
         # TODO we could simplify by using nested theme_font :toc_dot_leader
         if (dot_leader_font_style = (@theme.toc_dot_leader_font_style || :normal).to_sym) != font_style
@@ -2618,7 +2716,8 @@ class Converter < ::Prawn::Document
 
   # TODO delegate to layout_page_header and layout_page_footer per page
   def layout_running_content periphery, doc, opts = {}
-    skip = opts[:skip] || 1
+    skip, skip_pagenums, body_start_page_number = 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 {|p| !p.imported_page? })
     content_start_page += (skip + 1)
@@ -2640,7 +2739,7 @@ class Converter < ::Prawn::Document
     section_start_pages = {}
     trailing_section_start_pages = {}
     sections.each do |sect|
-      page_num = (sect.attr 'pdf-page-start').to_i - skip
+      page_num = (sect.attr 'pdf-page-start').to_i - skip_pagenums
       if is_book && ((sect_is_part = sect.part?) || sect.chapter?)
         if sect_is_part
           part_start_pages[page_num] ||= (sect.numbered_title formal: true)
@@ -2663,8 +2762,8 @@ class Converter < ::Prawn::Document
     sections_by_page = {}
     # QUESTION should the default part be the doctitle?
     last_part = nil
-    # QUESTION should we enforce that the preamble is preface?
-    last_chap = is_book ? (doc.attr 'preface-title', 'Preface') : nil
+    # QUESTION should we enforce that the preamble is a preface?
+    last_chap = is_book ? :pre : nil
     last_sect = nil
     sect_search_threshold = 1
     (1..num_pages).each do |num|
@@ -2691,7 +2790,17 @@ class Converter < ::Prawn::Document
         end
       end
       parts_by_page[num] = last_part
-      chapters_by_page[num] = last_chap
+      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
+        else
+          chapters_by_page[num] = doc.attr 'toc-title'
+        end
+      else
+        chapters_by_page[num] = last_chap
+      end
       sections_by_page[num] = last_sect
     end
 
@@ -2709,7 +2818,7 @@ class Converter < ::Prawn::Document
       trim_top = page_height
       # NOTE height is required atm
       trim_height = @theme.header_height || page_margin_top
-      trim_padding = @theme.header_padding || [0, 0, 0, 0]
+      trim_padding = inflate_padding @theme.header_padding || 0
       trim_bg_color = resolve_theme_color :header_background_color
       trim_border_width = @theme.header_border_width || @theme.base_border_width
       trim_border_style = (@theme.header_border_style || :solid).to_sym
@@ -2720,7 +2829,7 @@ class Converter < ::Prawn::Document
       trim_line_metrics = calc_line_metrics(@theme.footer_line_height || @theme.base_line_height)
       # NOTE height is required atm
       trim_top = trim_height = @theme.footer_height || page_margin_bottom
-      trim_padding = @theme.footer_padding || [0, 0, 0, 0]
+      trim_padding = inflate_padding @theme.footer_padding || 0
       trim_bg_color = resolve_theme_color :footer_background_color
       trim_border_width = @theme.footer_border_width || @theme.base_border_width
       trim_border_style = (@theme.footer_border_style || :solid).to_sym
@@ -2804,21 +2913,25 @@ class Converter < ::Prawn::Document
       ColumnPositions.each do |position|
         unless (val = @theme[%(#{periphery}_#{side}_#{position}_content)]).nil_or_empty?
           # TODO support image URL (using resolve_image_path)
-          if (val.include? ':') && val =~ ImageAttributeValueRx &&
-              ::File.readable?(path = (ThemeLoader.resolve_theme_asset $1, (doc.attr 'pdf-stylesdir')))
-            attrs = (AttributeList.new $2).parse
-            col_width = colspec_dict[side][position][:width]
-            if (fit = attrs['fit']) == 'contain'
-              width = col_width
-            else
-              unless (width = resolve_explicit_width attrs, col_width)
-                # QUESTION should we lookup and scale intrinsic width if explicit width is not given?
-                # NOTE failure message will be reported later when image is rendered
-                width = (to_pt intrinsic_image_dimensions(path)[:width], :px) rescue 0
+          if (val.include? ':') && val =~ ImageAttributeValueRx
+            if ::File.readable?(path = (ThemeLoader.resolve_theme_asset $1, (doc.attr 'pdf-stylesdir')))
+              attrs = (AttributeList.new $2).parse
+              col_width = colspec_dict[side][position][:width]
+              if (fit = attrs['fit']) == 'contain'
+                width = col_width
+              else
+                unless (width = resolve_explicit_width attrs, col_width)
+                  # QUESTION should we lookup and scale intrinsic width if explicit width is not given?
+                  # NOTE failure message will be reported later when image is rendered
+                  width = (to_pt intrinsic_image_dimensions(path)[:width], :px) rescue 0
+                end
+                width = col_width if fit == 'scale-down' && width > col_width
               end
-              width = col_width if fit == 'scale-down' && width > col_width
+              side_content[position] = { path: path, width: width, fit: !!fit }
+            else
+              logger.warn %(image to embed not found or not readable: #{path})
+              side_content[position] = val
             end
-            side_content[position] = { path: path, width: width, fit: !!fit }
           else
             side_content[position] = val
           end
@@ -2875,7 +2988,8 @@ class Converter < ::Prawn::Document
     repeat((content_start_page..page_count), 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
+      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)
       # FIXME we need to have a content setting for chapter pages
       content_by_position, colspec_by_position = content_dict[side], colspec_dict[side]
@@ -2943,13 +3057,13 @@ class Converter < ::Prawn::Document
                   doc.set_attr 'attribute-missing', 'skip' unless attribute_missing_doc == 'skip'
                   if (content = doc.apply_subs content).include? '{'
                     # NOTE must use &#123; in place of {, not \{, to escape attribute reference
-                    content = content.split(LF).delete_if {|line| SimpleAttributeRefRx =~ line } * LF
+                    content = content.split(LF).delete_if {|line| SimpleAttributeRefRx.match? line } * LF
                   end
                   doc.set_attr 'attribute-missing', attribute_missing_doc unless attribute_missing_doc == 'skip'
                 end
                 theme_font %(#{periphery}_#{side}_#{position}) do
                   formatted_text_box parse_text(content, color: @font_color, inline_format: [normalize: true]),
-                    at: [colspec[:x], trim_content_height + trim_padding[2] + trim_line_metrics.padding_bottom],
+                    at: [colspec[:x], trim_top - trim_padding[0] + (trim_valign == :center ? font.descender * 0.5 : 0)],
                     width: colspec[:width],
                     height: trim_content_height,
                     align: colspec[:align],
@@ -3540,6 +3654,8 @@ class Converter < ::Prawn::Document
 
   # QUESTION move to prawn/extensions.rb?
   def init_scratch_prototype
+    @save_state = nil
+    @scratch_depth = 0
     # IMPORTANT don't set font before using Marshal, it causes serialization to fail
     @prototype = ::Marshal.load ::Marshal.dump self
     @prototype.state.store.info.data[:Scratch] = true
@@ -3547,6 +3663,23 @@ class Converter < ::Prawn::Document
     #@prototype.start_new_page if @prototype.page_number == 0
   end
 
+  def push_scratch doc
+    if (@scratch_depth += 1) == 1
+      @save_state = {
+        catalog: {}.tap {|accum| doc.catalog.each {|k, v| accum[k] = v.dup } },
+        attributes: doc.attributes.dup,
+      }
+    end
+  end
+
+  def pop_scratch doc
+    if (@scratch_depth -= 1) == 0
+      doc.catalog.replace @save_state[:catalog]
+      doc.attributes.replace @save_state[:attributes]
+      @save_state = nil
+    end
+  end
+
 =begin
   # TODO could assign pdf-anchor attributes here too
   def assign_missing_section_ids doc