resolves #778, rewrite converter API; resolves #638, integrate thread_safe gem

- rewrite converter API
- separate built-in converters from template converter
- rename renderer/render to converter/convert
- make converter an extension point (resolves #778)
- base built-in converters on the converter API
- rename template_name property to node_name on AbstractNode
- make block_ prefix on file name of block-level templates optional
- use thread_safe gem for template and converter caches (resolves #638)
- introduce Stylesheets API to manage stylesheets
- move file write logic to Document
- delegate file write logic to converter that implements Writer
- remove compact logic, deprecate related options
- duplicate options and attributes passed to APIs, add tests
- assign doctype / backend attributes correctly when document is loaded, add tests
- report proper error if nil is passed to load_file and convert_file
- use span tag to group kbd combination in html5 backend
- setup toc in preamble if toc attribute is preamble
- Opal compatibility fixes, use built-in HTML5 converter
- make the outline method accessible to all html converters
- document the converter APIs along with some minor cleanups in terminology
- load stylesheets from data directory
- rename ruler block to thematic_break
- add inline? and block? query methods to AbstractNode
- use Timings class to measure and report timings from processor steps
- fix cucumber tests
- upgrade tilt dependency to 2.0.0
- minor optimizations

9 files changed, 501 insertions, 268 deletions

diff --git a/test/attributes_test.rb b/test/attributes_test.rb
index 087bb8de..f6b588a8 100644
--- a/test/attributes_test.rb
+++ b/test/attributes_test.rb
@@ -149,12 +149,94 @@ endif::holygrail[]
       assert_equal nil, doc.attributes['cash']
     end
 
+    test 'backend and doctype attributes are set by default in default configuration' do
+      input = <<-EOS
+= Document Title
+Author Name
+
+content
+      EOS
+
+      doc = document_from_string input
+      expect = {
+        'backend' => 'html5',
+        'backend-html5' => '',
+        'backend-html5-doctype-article' => '',
+        'basebackend' => 'html',
+        'basebackend-html' => '',
+        'basebackend-html-doctype-article' => '',
+        'doctype' => 'article',
+        'doctype-article' => '',
+        'filetype' => 'html',
+        'filetype-html' => ''
+      }
+      expect.each do |key, val|
+        assert doc.attributes.key? key
+        assert_equal val, doc.attributes[key]
+      end
+    end
+
+    test 'backend and doctype attributes are set by default in custom configuration' do
+      input = <<-EOS
+= Document Title
+Author Name
+
+content
+      EOS
+
+      doc = document_from_string input, :doctype => 'book', :backend => 'docbook'
+      expect = {
+        'backend' => 'docbook5',
+        'backend-docbook5' => '',
+        'backend-docbook5-doctype-book' => '',
+        'basebackend' => 'docbook',
+        'basebackend-docbook' => '',
+        'basebackend-docbook-doctype-book' => '',
+        'doctype' => 'book',
+        'doctype-book' => '',
+        'filetype' => 'xml',
+        'filetype-xml' => ''
+      }
+      expect.each do |key, val|
+        assert doc.attributes.key? key
+        assert_equal val, doc.attributes[key]
+      end
+    end
+
     test 'backend attributes are updated if backend attribute is defined in document and safe mode is less than SERVER' do
-      doc = document_from_string(':backend: docbook45', :safe => Asciidoctor::SafeMode::SAFE)
-      assert_equal 'docbook45', doc.attributes['backend']
-      assert doc.attributes.has_key? 'backend-docbook45'
-      assert_equal 'docbook', doc.attributes['basebackend']
-      assert doc.attributes.has_key? 'basebackend-docbook'
+      input = <<-EOS
+= Document Title
+Author Name
+:backend: docbook
+:doctype: book
+
+content
+      EOS
+
+      doc = document_from_string input, :safe => Asciidoctor::SafeMode::SAFE
+      expect = {
+        'backend' => 'docbook5',
+        'backend-docbook5' => '',
+        'backend-docbook5-doctype-book' => '',
+        'basebackend' => 'docbook',
+        'basebackend-docbook' => '',
+        'basebackend-docbook-doctype-book' => '',
+        'doctype' => 'book',
+        'doctype-book' => '',
+        'filetype' => 'xml',
+        'filetype-xml' => ''
+      }
+      expect.each do |key, val|
+        assert doc.attributes.key?(key)
+        assert_equal val, doc.attributes[key]
+      end
+
+      assert !doc.attributes.key?('backend-html5')
+      assert !doc.attributes.key?('backend-html5-doctype-article')
+      assert !doc.attributes.key?('basebackend-html')
+      assert !doc.attributes.key?('basebackend-html-doctype-article')
+      assert !doc.attributes.key?('doctype-article')
+      assert !doc.attributes.key?('filetype-html')
     end
 
     test 'backend attributes defined in document options overrides backend attribute in document' do
diff --git a/test/blocks_test.rb b/test/blocks_test.rb
index bbe94140..1003ed5c 100644
--- a/test/blocks_test.rb
+++ b/test/blocks_test.rb
@@ -692,8 +692,8 @@ line two
 line three
 ....
 EOS
-      [[true, true], [true, false], [false, true], [false, false]].each {|compact, header_footer|
-        output = render_string input, :header_footer => header_footer, :compact => compact
+      [true, false].each {|header_footer|
+        output = render_string input, :header_footer => header_footer
         assert_xpath '//pre', output, 1
         assert_xpath '//pre/text()', output, 1
         text = xmlnodes_at_xpath('//pre/text()', output, 1).text
@@ -702,11 +702,7 @@ EOS
         expected = "line one\n\nline two\n\nline three".lines.entries
         assert_equal expected, lines
         blank_lines = output.scan(/\n[ \t]*\n/).size
-        if compact
-          assert_equal 2, blank_lines
-        else
-          assert blank_lines >= 2
-        end
+        assert blank_lines >= 2
       }
     end
 
@@ -721,8 +717,8 @@ line two
 line three
 ----
 EOS
-      [[true, true], [true, false], [false, true], [false, false]].each {|(compact,header_footer)|
-        output = render_string input, header_footer => header_footer, :compact => compact
+      [true, false].each {|header_footer|
+        output = render_string input, header_footer => header_footer
         assert_xpath '//pre/code', output, 1
         assert_xpath '//pre/code/text()', output, 1
         text = xmlnodes_at_xpath('//pre/code/text()', output, 1).text
@@ -731,11 +727,7 @@ EOS
         expected = "line one\n\nline two\n\nline three".lines.entries
         assert_equal expected, lines
         blank_lines = output.scan(/\n[ \t]*\n/).size
-        if compact
-          assert_equal 2, blank_lines
-        else
-          assert blank_lines >= 2
-        end
+        assert blank_lines >= 2
       }
     end
 
@@ -752,8 +744,8 @@ line three
 ____
 --
 EOS
-      [[true, true], [true, false], [false, true], [false, false]].each {|compact, header_footer|
-        output = render_string input, :header_footer => header_footer, :compact => compact
+      [true, false].each {|header_footer|
+        output = render_string input, :header_footer => header_footer
         assert_xpath '//*[@class="verseblock"]/pre', output, 1
         assert_xpath '//*[@class="verseblock"]/pre/text()', output, 1
         text = xmlnodes_at_xpath('//*[@class="verseblock"]/pre/text()', output, 1).text
@@ -762,11 +754,7 @@ EOS
         expected = "line one\n\nline two\n\nline three".lines.entries
         assert_equal expected, lines
         blank_lines = output.scan(/\n[ \t]*\n/).size
-        if compact
-          assert_equal 2, blank_lines
-        else
-          assert blank_lines >= 2
-        end
+        assert blank_lines >= 2
       }
     end
 
@@ -792,23 +780,6 @@ last line
       assert_xpath %(//pre[text()="  first line\n\nlast line"]), result, 1
     end
 
-    test 'should not compact nested document twice' do
-      input = <<-EOS
-|===
-a|....
-line one
-
-line two
-
-line three
-....
-|===
-      EOS
-
-      output = render_string input, :compact => true
-      assert_xpath %(//pre[text() = "line one\n\nline two\n\nline three"]), output, 1
-    end
-
     test 'should process block with CRLF endlines' do
       input = <<-EOS
 [source]\r
@@ -2098,7 +2069,7 @@ html = CodeRay.scan("puts 'Hello, world!'", :ruby).div(:line_numbers => :table)
       EOS
       output = render_string input, :safe => Asciidoctor::SafeMode::SAFE, :attributes => {'linkcss' => ''}
       assert_xpath '//pre[@class="CodeRay"]/code[@class="ruby language-ruby"]//span[@class = "constant"][text() = "CodeRay"]', output, 1
-      assert_css 'link[rel="stylesheet"][href="./asciidoctor-coderay.css"]', output, 1
+      assert_css 'link[rel="stylesheet"][href="./coderay-asciidoctor.css"]', output, 1
     end
 
     test 'should highlight source inline if source-highlighter attribute is coderay and coderay-css is style' do
diff --git a/test/converter_test.rb b/test/converter_test.rb
new file mode 100644
index 00000000..2ab1562f
--- /dev/null
+++ b/test/converter_test.rb
@@ -0,0 +1,304 @@
+# encoding: UTF-8
+unless defined? ASCIIDOCTOR_PROJECT_DIR
+  $: << File.dirname(__FILE__); $:.uniq!
+  require 'test_helper'
+end
+require 'tilt' unless defined? ::Tilt
+
+context 'Converter' do
+
+  context 'View options' do
+    test 'should set Haml format to html5 for html5 backend' do
+      doc = Asciidoctor::Document.new [], :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'haml'), :template_cache => false
+      assert doc.converter.is_a?(Asciidoctor::Converter::CompositeConverter)
+      selected = doc.converter.find_converter('paragraph')
+      assert selected.is_a? Asciidoctor::Converter::TemplateConverter
+      assert selected.templates['paragraph'].is_a? Tilt::HamlTemplate
+      assert_equal :html5, selected.templates['paragraph'].options[:format]
+    end
+
+    test 'should set Haml format to xhtml for docbook backend' do
+      doc = Asciidoctor::Document.new [], :backend => 'docbook45', :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'haml'), :template_cache => false
+      assert doc.converter.is_a?(Asciidoctor::Converter::CompositeConverter)
+      selected = doc.converter.find_converter('paragraph')
+      assert selected.is_a? Asciidoctor::Converter::TemplateConverter
+      assert selected.templates['paragraph'].is_a? Tilt::HamlTemplate
+      assert_equal :xhtml, selected.templates['paragraph'].options[:format]
+    end
+
+    test 'should set Slim format to html5 for html5 backend' do
+      doc = Asciidoctor::Document.new [], :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'slim'), :template_cache => false
+      assert doc.converter.is_a?(Asciidoctor::Converter::CompositeConverter)
+      selected = doc.converter.find_converter('paragraph')
+      assert selected.is_a? Asciidoctor::Converter::TemplateConverter
+      assert selected.templates['paragraph'].is_a? Slim::Template
+      assert_equal :html5, selected.templates['paragraph'].options[:format]
+    end
+
+    test 'should set Slim format to nil for docbook backend' do
+      doc = Asciidoctor::Document.new [], :backend => 'docbook45', :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'slim'), :template_cache => false
+      assert doc.converter.is_a?(Asciidoctor::Converter::CompositeConverter)
+      selected = doc.converter.find_converter('paragraph')
+      assert selected.is_a? Asciidoctor::Converter::TemplateConverter
+      assert selected.templates['paragraph'].is_a? Slim::Template
+      assert_nil selected.templates['paragraph'].options[:format]
+    end
+
+    test 'should support custom template engine options for known engine' do
+      doc = Asciidoctor::Document.new [], :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'slim'), :template_cache => false, :template_engine_options => { :slim => { :pretty => true } }
+      assert doc.converter.is_a?(Asciidoctor::Converter::CompositeConverter)
+      selected = doc.converter.find_converter('paragraph')
+      assert selected.is_a? Asciidoctor::Converter::TemplateConverter
+      assert selected.templates['paragraph'].is_a? Slim::Template
+      assert_equal true, selected.templates['paragraph'].options[:pretty]
+    end
+
+    test 'should support custom template engine options' do
+      doc = Asciidoctor::Document.new [], :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'slim'), :template_cache => false, :template_engine_options => { :slim => { :pretty => true } }
+      assert doc.converter.is_a?(Asciidoctor::Converter::CompositeConverter)
+      selected = doc.converter.find_converter('paragraph')
+      assert selected.is_a? Asciidoctor::Converter::TemplateConverter
+      assert selected.templates['paragraph'].is_a? Slim::Template
+      assert_equal false, selected.templates['paragraph'].options[:sort_attrs]
+      assert_equal true, selected.templates['paragraph'].options[:pretty]
+    end
+  end
+
+  context 'Custom backends' do
+    test 'should load Haml templates for default backend' do
+      doc = Asciidoctor::Document.new [], :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'haml'), :template_cache => false
+      assert doc.converter.is_a?(Asciidoctor::Converter::CompositeConverter)
+      ['paragraph', 'sidebar'].each do |node_name|
+        selected = doc.converter.find_converter node_name
+        assert selected.is_a? Asciidoctor::Converter::TemplateConverter
+        assert selected.templates[node_name].is_a? Tilt::HamlTemplate
+        assert_equal %(block_#{node_name}.html.haml), File.basename(selected.templates[node_name].file)
+      end
+    end
+
+    test 'should load Haml templates for docbook45 backend' do
+      doc = Asciidoctor::Document.new [], :backend => 'docbook45', :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'haml'), :template_cache => false
+      assert doc.converter.is_a?(Asciidoctor::Converter::CompositeConverter)
+      ['paragraph'].each do |node_name|
+        selected = doc.converter.find_converter node_name
+        assert selected.is_a? Asciidoctor::Converter::TemplateConverter
+        assert selected.templates[node_name].is_a? Tilt::HamlTemplate
+        assert_equal %(block_#{node_name}.xml.haml), File.basename(selected.templates[node_name].file)
+      end
+    end
+
+    test 'should use Haml templates in place of built-in templates' do
+      input = <<-EOS
+= Document Title
+Author Name
+
+== Section One
+
+Sample paragraph
+
+.Related
+****
+Sidebar content
+****
+      EOS
+
+      output = render_embedded_string input, :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'haml'), :template_cache => false
+      assert_xpath '/*[@class="sect1"]/*[@class="sectionbody"]/p', output, 1
+      assert_xpath '//aside', output, 1
+      assert_xpath '/*[@class="sect1"]/*[@class="sectionbody"]/p/following-sibling::aside', output, 1
+      assert_xpath '//aside/header/h1[text()="Related"]', output, 1
+      assert_xpath '//aside/header/following-sibling::p[text()="Sidebar content"]', output, 1
+    end
+
+    test 'should use built-in global cache to cache templates' do
+      begin
+        # clear out any cache, just to be sure
+        Asciidoctor::Converter::TemplateConverter.clear_caches if defined? Asciidoctor::Converter::TemplateConverter
+
+        template_dir = File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'haml')
+        doc = Asciidoctor::Document.new [], :template_dir => template_dir
+        doc.converter
+        caches = Asciidoctor::Converter::TemplateConverter.caches
+        if defined? ::ThreadSafe::Cache
+          assert caches[:templates].is_a?(::ThreadSafe::Cache)
+          assert !caches[:templates].empty?
+          paragraph_template_before = caches[:templates].values.find {|t| File.basename(t.file) == 'block_paragraph.html.haml' }
+          assert !paragraph_template_before.nil?
+
+          # should use cache
+          doc = Asciidoctor::Document.new [], :template_dir => template_dir
+          template_converter = doc.converter.find_converter('paragraph')
+          paragraph_template_after = template_converter.templates['paragraph']
+          assert !paragraph_template_after.nil?
+          assert paragraph_template_before.eql?(paragraph_template_after)
+
+          # should not use cache
+          doc = Asciidoctor::Document.new [], :template_dir => template_dir, :template_cache => false
+          template_converter = doc.converter.find_converter('paragraph')
+          paragraph_template_after = template_converter.templates['paragraph']
+          assert !paragraph_template_after.nil?
+          assert !paragraph_template_before.eql?(paragraph_template_after)
+        else
+          assert caches.empty?
+        end
+      ensure
+        # clean up
+        Asciidoctor::Converter::TemplateConverter.clear_caches if defined? Asciidoctor::Converter::TemplateConverter
+      end
+    end
+
+    test 'should use custom cache to cache templates' do
+      template_dir = File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'haml')
+      Asciidoctor::PathResolver.new.system_path(File.join(template_dir, 'html5', 'block_paragraph.html.haml'), nil)
+      caches = { :scans => {}, :templates => {} }
+      doc = Asciidoctor::Document.new [], :template_dir => template_dir, :template_cache => caches
+      doc.converter
+      assert !caches[:scans].empty?
+      assert !caches[:templates].empty?
+      paragraph_template = caches[:templates].values.find {|t| File.basename(t.file) == 'block_paragraph.html.haml' }
+      assert !paragraph_template.nil?
+      assert paragraph_template.is_a? ::Tilt::HamlTemplate
+    end
+
+    test 'should be able to disable template cache' do
+      begin
+        # clear out any cache, just to be sure
+        Asciidoctor::Converter::TemplateConverter.clear_caches if defined? Asciidoctor::Converter::TemplateConverter
+
+        doc = Asciidoctor::Document.new [], :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'haml'),
+            :template_cache => false
+        doc.converter
+        caches = Asciidoctor::Converter::TemplateConverter.caches
+        assert caches.empty? || caches[:scans].empty?
+        assert caches.empty? || caches[:templates].empty?
+      ensure
+        # clean up
+        Asciidoctor::Converter::TemplateConverter.clear_caches if defined? Asciidoctor::Converter::TemplateConverter
+      end
+    end
+
+    test 'should load Slim templates for default backend' do
+      doc = Asciidoctor::Document.new [], :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'slim'), :template_cache => false
+      assert doc.converter.is_a?(Asciidoctor::Converter::CompositeConverter)
+      ['paragraph', 'sidebar'].each do |node_name|
+        selected = doc.converter.find_converter node_name
+        assert selected.is_a? Asciidoctor::Converter::TemplateConverter
+        assert selected.templates[node_name].is_a? Slim::Template
+        assert_equal %(block_#{node_name}.html.slim), File.basename(selected.templates[node_name].file)
+      end
+    end
+
+    test 'should load Slim templates for docbook45 backend' do
+      doc = Asciidoctor::Document.new [], :backend => 'docbook45', :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'slim'), :template_cache => false
+      assert doc.converter.is_a?(Asciidoctor::Converter::CompositeConverter)
+      ['paragraph'].each do |node_name|
+        selected = doc.converter.find_converter node_name
+        assert selected.is_a? Asciidoctor::Converter::TemplateConverter
+        assert selected.templates[node_name].is_a? Slim::Template
+        assert_equal %(block_#{node_name}.xml.slim), File.basename(selected.templates[node_name].file)
+      end
+    end
+
+    test 'should use Slim templates in place of built-in templates' do
+      input = <<-EOS
+= Document Title
+Author Name
+
+== Section One
+
+Sample paragraph
+
+.Related
+****
+Sidebar content
+****
+      EOS
+
+      output = render_embedded_string input, :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'slim'), :template_cache => false
+      assert_xpath '/*[@class="sect1"]/*[@class="sectionbody"]/p', output, 1
+      assert_xpath '//aside', output, 1
+      assert_xpath '/*[@class="sect1"]/*[@class="sectionbody"]/p/following-sibling::aside', output, 1
+      assert_xpath '//aside/header/h1[text()="Related"]', output, 1
+      assert_xpath '//aside/header/following-sibling::p[text()="Sidebar content"]', output, 1
+    end
+
+    test 'should use custom converter if specified' do
+      input = <<-EOS
+= Document Title
+
+preamble
+
+== Section
+
+content
+      EOS
+
+      class CustomConverterA
+        def initialize backend, opts = {}
+        end
+
+        def convert node, name = nil
+          'document'
+        end
+
+        def self.converts? backend
+          true
+        end
+      end
+
+      output = render_string input, :converter => CustomConverterA
+      assert 'document', output
+    end
+
+    test 'should use converter registered for backend' do
+      input = <<-EOS
+content
+      EOS
+
+      begin
+        Asciidoctor::Converter::Factory.unregister_all 
+
+        class CustomConverterB
+          include Asciidoctor::Converter
+          register_for 'foobar'
+          def convert node, name = nil
+            'foobar content'
+          end
+        end
+
+        converters = Asciidoctor::Converter::Factory.converters
+        assert converters.size == 1
+        assert converters['foobar'] == CustomConverterB
+        output = render_string input, :backend => 'foobar'
+        assert 'foobar content', output
+      ensure
+        Asciidoctor::Converter::Factory.unregister_all 
+      end
+    end
+
+    test 'should fall back to catch all converter' do
+      input = <<-EOS
+content
+      EOS
+
+      begin
+        Asciidoctor::Converter::Factory.unregister_all 
+
+        class CustomConverterC
+          include Asciidoctor::Converter
+          register_for '*'
+          def convert node, name = nil
+            'foobaz content'
+          end
+        end
+
+        converters = Asciidoctor::Converter::Factory.converters
+        assert converters['*'] == CustomConverterC
+        output = render_string input, :backend => 'foobaz'
+        assert 'foobaz content', output
+      ensure
+        Asciidoctor::Converter::Factory.unregister_all 
+      end
+    end
+  end
+end
diff --git a/test/document_test.rb b/test/document_test.rb
index a9fc6023..f0a01168 100644
--- a/test/document_test.rb
+++ b/test/document_test.rb
@@ -4,6 +4,8 @@ unless defined? ASCIIDOCTOR_PROJECT_DIR
   require 'test_helper'
 end
 
+BUILT_IN_ELEMENTS = %w(admonition audio colist dlist document embedded example floating_title image inline_anchor inline_break inline_button inline_callout inline_footnote inline_image inline_indexterm inline_kbd inline_menu inline_quoted listing literal math olist open page_break paragraph pass preamble quote section sidebar table thematic_break toc ulist verse video)
+
 context 'Document' do
 
   context 'Example document' do
@@ -223,6 +225,34 @@ preamble
       assert doc.attributes.is_a?(Hash)
       assert doc.attributes.has_key?('toc')
     end
+
+    test 'should not modify options argument' do
+      options = {
+        :safe => Asciidoctor::SafeMode::SAFE
+      }
+      options.freeze
+      sample_input_path = fixture_path('sample.asciidoc')
+      begin
+        Asciidoctor.load_file sample_input_path, options
+      rescue
+        flunk %(options argument should not be modified)
+      end
+    end
+
+    test 'should not modify attributes Hash argument' do
+      attributes = {}
+      attributes.freeze
+      options = {
+        :safe => Asciidoctor::SafeMode::SAFE,
+        :attributes => attributes
+      }
+      sample_input_path = fixture_path('sample.asciidoc')
+      begin
+        Asciidoctor.load_file sample_input_path, options
+      rescue
+        flunk %(attributes argument should not be modified)
+      end
+    end
   end
 
   context 'Render APIs' do
@@ -472,6 +502,19 @@ text
         FileUtils.rmdir output_dir
       end
     end
+
+    test 'should not modify options argument' do
+      options = {
+        :safe => Asciidoctor::SafeMode::SAFE
+      }
+      options.freeze
+      sample_input_path = fixture_path('sample.asciidoc')
+      begin
+        Asciidoctor.render_file sample_input_path, options
+      rescue
+        flunk %(options argument should not be modified)
+      end
+    end
   end
 
   context 'Docinfo files' do
@@ -642,63 +685,56 @@ text
     end
   end
 
-  context 'Renderer' do
+  context 'Converter' do
     test 'built-in HTML5 views are registered by default' do
       doc = document_from_string ''
       assert_equal 'html5', doc.attributes['backend']
       assert doc.attributes.has_key? 'backend-html5'
       assert_equal 'html', doc.attributes['basebackend']
       assert doc.attributes.has_key? 'basebackend-html'
-      renderer = doc.renderer
-      assert !renderer.nil?
-      views = renderer.views
-      assert !views.nil?
-      assert_equal 37, views.size
-      assert views.has_key? 'document'
-      assert Asciidoctor.const_defined?(:HTML5)
-      assert Asciidoctor::HTML5.const_defined?(:DocumentTemplate)
+      converter = doc.converter
+      assert converter.is_a? Asciidoctor::Converter::Html5Converter
+      BUILT_IN_ELEMENTS.each do |element|
+        assert converter.respond_to? element
+      end
     end
 
     test 'built-in DocBook45 views are registered when backend is docbook45' do
       doc = document_from_string '', :attributes => {'backend' => 'docbook45'}
-      renderer = doc.renderer
+      converter = doc.converter
       assert_equal 'docbook45', doc.attributes['backend']
       assert doc.attributes.has_key? 'backend-docbook45'
       assert_equal 'docbook', doc.attributes['basebackend']
       assert doc.attributes.has_key? 'basebackend-docbook'
-      assert !renderer.nil?
-      views = renderer.views
-      assert !views.nil?
-      assert_equal 37, views.size
-      assert views.has_key? 'document'
-      assert Asciidoctor.const_defined?(:DocBook45)
-      assert Asciidoctor::DocBook45.const_defined?(:DocumentTemplate)
+      converter = doc.converter
+      assert converter.is_a? Asciidoctor::Converter::DocBook45Converter
+      BUILT_IN_ELEMENTS.each do |element|
+        assert converter.respond_to? element
+      end
     end
 
     test 'built-in DocBook5 views are registered when backend is docbook5' do
       doc = document_from_string '', :attributes => {'backend' => 'docbook5'}
-      renderer = doc.renderer
+      converter = doc.converter
       assert_equal 'docbook5', doc.attributes['backend']
       assert doc.attributes.has_key? 'backend-docbook5'
       assert_equal 'docbook', doc.attributes['basebackend']
       assert doc.attributes.has_key? 'basebackend-docbook'
-      assert !renderer.nil?
-      views = renderer.views
-      assert !views.nil?
-      assert_equal 37, views.size
-      assert views.has_key? 'document'
-      assert Asciidoctor.const_defined?(:DocBook5)
-      assert Asciidoctor::DocBook5.const_defined?(:DocumentTemplate)
+      converter = doc.converter
+      assert converter.is_a? Asciidoctor::Converter::DocBook5Converter
+      BUILT_IN_ELEMENTS.each do |element|
+        assert converter.respond_to? element
+      end
     end
 
 # NOTE The eruby tests are no longer relevant as we no longer use ERB internally
-# These should be rewritten to test the selection of ERB for use with the template renderer
+# These should be rewritten to test the selection of ERB for use with the template converter
 =begin
     test 'eRuby implementation should default to ERB' do
       # intentionally use built-in templates for this test
       doc = Asciidoctor::Document.new [], :backend => 'docbook', :header_footer => true
-      renderer = doc.renderer
-      views = renderer.views
+      converter = doc.converter
+      views = converter.views
       assert !views.nil?
       assert views.has_key? 'document'
       assert views['document'].is_a?(Asciidoctor::DocBook45::DocumentTemplate)
@@ -710,9 +746,9 @@ text
       # intentionally use built-in templates for this test
       doc = Asciidoctor::Document.new [], :backend => 'docbook', :eruby => 'erubis', :header_footer => true
       assert $LOADED_FEATURES.detect {|p| p == 'erubis.rb' || p.end_with?('/erubis.rb') }.nil?
-      renderer = doc.renderer
+      converter = doc.converter
       assert $LOADED_FEATURES.detect {|p| p == 'erubis.rb' || p.end_with?('/erubis.rb') }
-      views = renderer.views
+      views = converter.views
       assert !views.nil?
       assert views.has_key? 'document'
       assert views['document'].is_a?(Asciidoctor::DocBook45::DocumentTemplate)
diff --git a/test/invoker_test.rb b/test/invoker_test.rb
index 7a99fba1..daa8745e 100644
--- a/test/invoker_test.rb
+++ b/test/invoker_test.rb
@@ -198,7 +198,7 @@ context 'Invoker' do
   test 'should copy default stylesheet to target directory if linkcss is specified' do
     sample_outpath = File.expand_path(File.join(File.dirname(__FILE__), 'fixtures', 'sample-output.html'))
     asciidoctor_stylesheet = File.expand_path(File.join(File.dirname(__FILE__), 'fixtures', 'asciidoctor.css'))
-    coderay_stylesheet = File.expand_path(File.join(File.dirname(__FILE__), 'fixtures', 'asciidoctor-coderay.css'))
+    coderay_stylesheet = File.expand_path(File.join(File.dirname(__FILE__), 'fixtures', 'coderay-asciidoctor.css'))
     begin
       invoker = invoke_cli %W(-o #{sample_outpath} -a linkcss -a source-highlighter=coderay)
       invoker.document
@@ -308,24 +308,6 @@ context 'Invoker' do
     assert_xpath '/*[@id="preamble"]', output, 1
   end
 
-  # no longer relevant
-  #test 'should not compact output by default' do
-  #  # NOTE we are relying on the fact that the template leaves blank lines
-  #  # this will always fail when using a template engine which strips blank lines by default
-  #  invoker = invoke_cli_to_buffer(%w(-o -), '-') { '* content' }
-  #  output = invoker.read_output
-  #  puts output
-  #  assert_match(/\n[ \t]*\n/, output)
-  #end
-
-  test 'should compact output if specified' do
-    # NOTE we are relying on the fact that the template leaves blank lines
-    # this will always succeed when using a template engine which strips blank lines by default
-    invoker = invoke_cli_to_buffer(%w(-C -s -o -), '-') { '* content' }
-    output = invoker.read_output
-    assert_no_match(/\n[ \t]*\n/, output)
-  end
-
   test 'should output a trailing endline to stdout' do
     invoker = nil
     output = nil
@@ -376,7 +358,10 @@ context 'Invoker' do
     custom_backend_root = File.expand_path(File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends'))
     invoker = invoke_cli_to_buffer %W(-E haml -T #{custom_backend_root} -o -)
     doc = invoker.document
-    assert doc.renderer.views['block_paragraph'].is_a? Tilt::HamlTemplate
+    assert doc.converter.is_a? Asciidoctor::Converter::CompositeConverter
+    selected = doc.converter.find_converter 'paragraph'
+    assert selected.is_a? Asciidoctor::Converter::TemplateConverter
+    assert selected.templates['paragraph'].is_a? Tilt::HamlTemplate
   end
 
   test 'should load custom templates from multiple template directories' do
diff --git a/test/renderer_test.rb b/test/renderer_test.rb
deleted file mode 100644
index 6af3a572..00000000
--- a/test/renderer_test.rb
+++ /dev/null
@@ -1,166 +0,0 @@
-# encoding: UTF-8
-unless defined? ASCIIDOCTOR_PROJECT_DIR
-  $: << File.dirname(__FILE__); $:.uniq!
-  require 'test_helper'
-end
-require 'tilt'
-
-context 'Renderer' do
-
-  context 'View mapping' do
-    test 'should extract view mapping from built-in template with one segment and backend' do
-      view_name, view_backend = Asciidoctor::Renderer.extract_view_mapping('Asciidoctor::HTML5::DocumentTemplate') 
-      assert_equal 'document', view_name
-      assert_equal 'html5', view_backend
-    end
-
-    test 'should extract view mapping from built-in template with two segments and backend' do
-      view_name, view_backend = Asciidoctor::Renderer.extract_view_mapping('Asciidoctor::DocBook45::BlockSidebarTemplate') 
-      assert_equal 'block_sidebar', view_name
-      assert_equal 'docbook45', view_backend
-    end
-
-    test 'should extract view mapping from built-in template without backend' do
-      view_name, view_backend = Asciidoctor::Renderer.extract_view_mapping('Asciidoctor::DocumentTemplate') 
-      assert_equal 'document', view_name
-      assert view_backend.nil?
-    end
-  end
-
-  context 'View options' do
-    test 'should set Haml format to html5 for html5 backend' do
-      doc = Asciidoctor::Document.new [], :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'haml'), :template_cache => false
-      assert doc.renderer.views['block_paragraph'].is_a? Tilt::HamlTemplate
-      assert_equal :html5, doc.renderer.views['block_paragraph'].options[:format]
-    end
-
-    test 'should set Haml format to xhtml for docbook backend' do
-      doc = Asciidoctor::Document.new [], :backend => 'docbook45', :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'haml'), :template_cache => false
-      assert doc.renderer.views['block_paragraph'].is_a? Tilt::HamlTemplate
-      assert_equal :xhtml, doc.renderer.views['block_paragraph'].options[:format]
-    end
-  end
-
-  context 'Custom backends' do
-    test 'should load Haml templates for default backend' do
-      doc = Asciidoctor::Document.new [], :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'haml'), :template_cache => false
-      assert doc.renderer.views['block_paragraph'].is_a? Tilt::HamlTemplate
-      assert doc.renderer.views['block_paragraph'].file.end_with? 'block_paragraph.html.haml'
-      assert doc.renderer.views['block_sidebar'].is_a? Tilt::HamlTemplate
-      assert doc.renderer.views['block_sidebar'].file.end_with? 'block_sidebar.html.haml'
-    end
-
-    test 'should load Haml templates for docbook45 backend' do
-      doc = Asciidoctor::Document.new [], :backend => 'docbook45', :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'haml'), :template_cache => false
-      assert doc.renderer.views['block_paragraph'].is_a? Tilt::HamlTemplate
-      assert doc.renderer.views['block_paragraph'].file.end_with? 'block_paragraph.xml.haml'
-    end
-
-    test 'should use Haml templates in place of built-in templates' do
-      input = <<-EOS
-= Document Title
-Author Name
-
-== Section One
-
-Sample paragraph
-
-.Related
-****
-Sidebar content
-****
-      EOS
-
-      output = render_embedded_string input, :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'haml'), :template_cache => false
-      assert_xpath '/*[@class="sect1"]/*[@class="sectionbody"]/p', output, 1
-      assert_xpath '//aside', output, 1
-      assert_xpath '/*[@class="sect1"]/*[@class="sectionbody"]/p/following-sibling::aside', output, 1
-      assert_xpath '//aside/header/h1[text()="Related"]', output, 1
-      assert_xpath '//aside/header/following-sibling::p[text()="Sidebar content"]', output, 1
-    end
-
-    test 'should use built-in global cache to cache templates' do
-      # clear out any cache, just to be sure
-      Asciidoctor::Renderer.reset_global_cache
-
-      template_dir = File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'haml')
-      doc = Asciidoctor::Document.new [], :template_dir => template_dir
-      doc.renderer
-      template_cache = Asciidoctor::Renderer.global_cache
-      assert template_cache.is_a? Asciidoctor::TemplateCache
-      cache = template_cache.cache
-      assert_not_nil cache
-      assert cache.size > 0
-
-      # ensure we don't scan a second time (using the view option hash to mark the cached view object)
-      template_path = Asciidoctor::PathResolver.new.system_path(File.join(template_dir, 'html5', 'block_paragraph.html.haml'), nil)
-      view = template_cache.fetch(:view, template_path)
-      view.options[:foo] = 'bar'
-      doc = Asciidoctor::Document.new [], :template_dir => template_dir
-      doc.renderer
-      template_cache = Asciidoctor::Renderer.global_cache
-      view = template_cache.fetch(:view, template_path)
-      assert_equal 'bar', view.options[:foo]
-
-      # clean up
-      Asciidoctor::Renderer.reset_global_cache
-    end
-
-    test 'should use custom cache to cache templates' do
-      template_dir = File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'haml')
-      template_path = Asciidoctor::PathResolver.new.system_path(File.join(template_dir, 'html5', 'block_paragraph.html.haml'), nil)
-      doc = Asciidoctor::Document.new [], :template_dir => template_dir,
-          :template_cache => Asciidoctor::TemplateCache.new
-      template_cache = doc.renderer.cache
-      assert_not_nil template_cache
-      cache = template_cache.cache
-      assert_not_nil cache
-      assert cache.size > 0
-      view = template_cache.fetch(:view, template_path)
-      assert view.is_a? Tilt::HamlTemplate
-    end
-
-    test 'should be able to disable template cache' do
-      doc = Asciidoctor::Document.new [], :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'haml'),
-          :template_cache => false
-      assert_nil doc.renderer.cache
-    end
-
-    test 'should load Slim templates for default backend' do
-      doc = Asciidoctor::Document.new [], :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'slim'), :template_cache => false
-      assert doc.renderer.views['block_paragraph'].is_a? Slim::Template
-      assert doc.renderer.views['block_paragraph'].file.end_with? 'block_paragraph.html.slim'
-      assert doc.renderer.views['block_sidebar'].is_a? Slim::Template
-      assert doc.renderer.views['block_sidebar'].file.end_with? 'block_sidebar.html.slim'
-    end
-
-    test 'should load Slim templates for docbook45 backend' do
-      doc = Asciidoctor::Document.new [], :backend => 'docbook45', :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'slim'), :template_cache => false
-      assert doc.renderer.views['block_paragraph'].is_a? Slim::Template
-      assert doc.renderer.views['block_paragraph'].file.end_with? 'block_paragraph.xml.slim'
-    end
-
-    test 'should use Slim templates in place of built-in templates' do
-      input = <<-EOS
-= Document Title
-Author Name
-
-== Section One
-
-Sample paragraph
-
-.Related
-****
-Sidebar content
-****
-      EOS
-
-      output = render_embedded_string input, :template_dir => File.join(File.dirname(__FILE__), 'fixtures', 'custom-backends', 'slim'), :template_cache => false
-      assert_xpath '/*[@class="sect1"]/*[@class="sectionbody"]/p', output, 1
-      assert_xpath '//aside', output, 1
-      assert_xpath '/*[@class="sect1"]/*[@class="sectionbody"]/p/following-sibling::aside', output, 1
-      assert_xpath '//aside/header/h1[text()="Related"]', output, 1
-      assert_xpath '//aside/header/following-sibling::p[text()="Sidebar content"]', output, 1
-    end
-  end
-end
diff --git a/test/sections_test.rb b/test/sections_test.rb
index 0583df61..2975c20f 100644
--- a/test/sections_test.rb
+++ b/test/sections_test.rb
@@ -1849,6 +1849,27 @@ They couldn't believe their eyes when...
       assert_xpath '//*[@id="header"]//*[@id="toc"]/ul/li[1]/a[@href="#_section_one"][text()="1. Section One"]', output, 1
     end
 
+    test 'should set toc placement to preamble if toc attribute is set to preamble' do
+      input = <<-EOS
+= Article
+:toc: preamble
+
+Yada yada
+
+== Section One
+
+It was a dark and stormy night...
+
+== Section Two
+
+They couldn't believe their eyes when...
+      EOS
+
+      output = render_string input
+      assert_css '#preamble #toc', output, 1
+      assert_css '#preamble .sectionbody + #toc', output, 1
+    end
+
     test 'should use document attributes toc-class, toc-title and toclevels to create toc' do
       input = <<-EOS
 = Article
diff --git a/test/substitutions_test.rb b/test/substitutions_test.rb
index 92a317d4..ef04f0e3 100644
--- a/test/substitutions_test.rb
+++ b/test/substitutions_test.rb
@@ -898,37 +898,37 @@ EOS
   
       test 'kbd macro with key combination' do
         para = block_from_string('kbd:[Ctrl+Shift+T]', :attributes => {'experimental' => ''})
-        assert_equal %q{<kbd class="keyseq"><kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>T</kbd></kbd>}, para.sub_macros(para.source)
+        assert_equal %q{<span class="keyseq"><kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>T</kbd></span>}, para.sub_macros(para.source)
       end
   
       test 'kbd macro with key combination with spaces' do
         para = block_from_string('kbd:[Ctrl + Shift + T]', :attributes => {'experimental' => ''})
-        assert_equal %q{<kbd class="keyseq"><kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>T</kbd></kbd>}, para.sub_macros(para.source)
+        assert_equal %q{<span class="keyseq"><kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>T</kbd></span>}, para.sub_macros(para.source)
       end
   
       test 'kbd macro with key combination delimited by commas' do
         para = block_from_string('kbd:[Ctrl,Shift,T]', :attributes => {'experimental' => ''})
-        assert_equal %q{<kbd class="keyseq"><kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>T</kbd></kbd>}, para.sub_macros(para.source)
+        assert_equal %q{<span class="keyseq"><kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>T</kbd></span>}, para.sub_macros(para.source)
       end
   
       test 'kbd macro with key combination containing a plus key no spaces' do
         para = block_from_string('kbd:[Ctrl++]', :attributes => {'experimental' => ''})
-        assert_equal %q{<kbd class="keyseq"><kbd>Ctrl</kbd>+<kbd>+</kbd></kbd>}, para.sub_macros(para.source)
+        assert_equal %q{<span class="keyseq"><kbd>Ctrl</kbd>+<kbd>+</kbd></span>}, para.sub_macros(para.source)
       end
   
       test 'kbd macro with key combination delimited by commands containing a comma key' do
         para = block_from_string('kbd:[Ctrl,,]', :attributes => {'experimental' => ''})
-        assert_equal %q{<kbd class="keyseq"><kbd>Ctrl</kbd>+<kbd>,</kbd></kbd>}, para.sub_macros(para.source)
+        assert_equal %q{<span class="keyseq"><kbd>Ctrl</kbd>+<kbd>,</kbd></span>}, para.sub_macros(para.source)
       end
   
       test 'kbd macro with key combination containing a plus key with spaces' do
         para = block_from_string('kbd:[Ctrl + +]', :attributes => {'experimental' => ''})
-        assert_equal %q{<kbd class="keyseq"><kbd>Ctrl</kbd>+<kbd>+</kbd></kbd>}, para.sub_macros(para.source)
+        assert_equal %q{<span class="keyseq"><kbd>Ctrl</kbd>+<kbd>+</kbd></span>}, para.sub_macros(para.source)
       end
   
       test 'kbd macro with key combination containing escaped bracket' do
         para = block_from_string('kbd:[Ctrl + \]]', :attributes => {'experimental' => ''})
-        assert_equal %q{<kbd class="keyseq"><kbd>Ctrl</kbd>+<kbd>]</kbd></kbd>}, para.sub_macros(para.source)
+        assert_equal %q{<span class="keyseq"><kbd>Ctrl</kbd>+<kbd>]</kbd></span>}, para.sub_macros(para.source)
       end
   
       test 'kbd macro with key combination, docbook backend' do
diff --git a/test/tables_test.rb b/test/tables_test.rb
index 14962dd3..192b9788 100644
--- a/test/tables_test.rb
+++ b/test/tables_test.rb
@@ -636,7 +636,7 @@ output file name is used.
       assert !body_cell_1_3.inner_document.nil?
       assert body_cell_1_3.inner_document.nested?
       assert_equal doc, body_cell_1_3.inner_document.parent_document
-      assert_equal doc.renderer, body_cell_1_3.inner_document.renderer
+      assert_equal doc.converter, body_cell_1_3.inner_document.converter
       output = doc.render
 
       assert_css 'table > tbody > tr', output, 2